getme-python-sdk 1.1.1

Python SDK for a High-Performance Key-Value Store

📑 Index

• Overview
• About getMe Core Engine
• Server Dependency & Docker
  • Running the Core Engine via Docker
  • Connecting the SDK to the Core Engine
  • Why manage the core engine separately?
• Other Available SDKs
• Links and Resources
• License

📖 Overview

The official Python client library for the getMe key-value store. This SDK abstracts the underlying API calls, providing Python developers with a simple, idiomatic interface to interact directly with the getMe runtime.

🧠 About getMe Core Engine

getMe is a persistent, embeddable key-value store written in Go. It is heavily inspired by the design of Bitcask and is optimized for high write throughput and low-latency reads.

The engine runs on a few core principles:

• Log-Structured Storage: All data is written to an append-only log file, maximizing write speed by avoiding slow, random disk I/O.
• In-Memory Hash Index: A hash table is maintained in memory mapping each key to its exact on-disk location, enabling single disk seek lookups.
• Compaction: A background process that periodically removes stale data to reclaim disk space.
• Batch Operations: A batch API amortizes the cost of writes, allowing for extremely high ingestion rates.

For a deep dive into the architecture, please refer to the Root README and the Server README.

🚀 Server Dependency & Docker

Important: This SDK acts merely as a client. The getMe core server engine must be running independently for this library to function. The SDK interacts with the Core Engine through a Unix Domain Socket (UDS).

Running the Core Engine via Docker

You can use the official Docker images mentioned in our DockerHub README.

For maximum performance, we recommend using the Core Server Only container (ContainerFile.server), which isolates the database engine:

docker build -t getme-core -f ../../ContainerFile.server ../../
docker run -d \
  --name getme-engine \
  -v getme_data:/var/lib/getMeStore \
  -v /tmp/getMeStore/sockDir:/tmp/getMeStore/sockDir \
  getme-core

Connecting the SDK to the Core Engine

The SDK communicates with the engine via the Unix Domain Socket (getMe.sock). Because the engine creates the socket in /tmp/getMeStore/sockDir, it is critical that this exact directory is bind-mounted when running the container so that your local Python application can reach it.

To connect your Python SDK to the core engine:

1. Ensure the getMe server is running (either locally or via Docker with the /tmp/getMeStore/sockDir volume mounted).
2. Point your SDK initialization to the socket file location (default: /tmp/getMeStore/sockDir/getMe.sock).

Why manage the core engine separately?

Decoupling the database engine from the Python logic provides several critical advantages:

• Performance & Isolation: The core engine heavily utilizes memory for its hash index and performs continuous background disk I/O for compaction. Running it separately prevents the storage engine from starving your Python application of memory or compute resources (and vice-versa).
• Independent Scaling: You can scale your Python applications dynamically while connecting to a centralized, standalone getMe instance.
• Polyglot Ecosystems: A decoupled server can serve multiple applications simultaneously, even if those applications are built across entirely different technology stacks.

📦 Other Available SDKs

While this is the Python client, getMe supports multiple languages. Detailed information on all available SDKs can be found in the Root README.

• Go SDK
• Java SDK
• JavaScript/TypeScript SDK
• Python SDK (This package)

🔗 Links and Resources

Below is a comprehensive list of resources and documentation linked throughout the getMe ecosystem:

• getMe Root Repository
• Root README
• DockerHub README
• Server Engine Source
• AGPLv3 License

Engineering Blog Series

• Building getMe - Part I
• Building getMe - Part II

📄 License

This project is licensed under the GNU Affero General Public License v3.0 (AGPLv3) - see the LICENSE file for details.