Sipora Server Catchers

A lightweight, Python-based distributed in-memory caching server and client library.

Sipora Server Catchers is designed to provide fast key-value caching for Python applications without requiring Redis as a dependency.

Features

• 🚀 Fast in-memory caching
• 🌐 Remote cache server
• 🐍 Native Python client
• ⏱️ Key expiration with TTL
• 🔢 Increment and decrement counters
• 🗑️ Delete cached values
• 🔍 Check whether a key exists
• 🔌 TCP-based client/server communication
• 📦 Easy installation through PyPI
• ⚡ Designed for FastAPI and Python applications
• 🧩 Lightweight architecture
• 🔒 Authentication support can be added
• 📊 Memory eviction support

Architecture

                    Python Application
                           │
                           │
                           ▼
                ┌─────────────────────┐
                │    Sipora Client    │
                │                     │
                │  set()              │
                │  get()              │
                │  delete()           │
                │  exists()           │
                │  expire()           │
                │  increment()        │
                └──────────┬──────────┘
                           │
                           │ TCP
                           ▼
                ┌─────────────────────┐
                │ Sipora Cache Server │
                │                     │
                │    Memory Storage   │
                │                     │
                │    TTL Manager      │
                │                     │
                │    Eviction         │
                └──────────┬──────────┘
                           │
                           │ Cache MISS
                           ▼
                ┌─────────────────────┐
                │     SQL / MongoDB   │
                │      / Database     │
                └─────────────────────┘

Installation

Install from PyPI:

pip install sipora-server-catchers

Quick Start

Start the Server

After installation, start the Sipora cache server:

sipora-cache-server

By default, the server will listen on:

127.0.0.1:6380

You can specify a custom host and port:

sipora-cache-server --host 0.0.0.0 --port 6380

Python Client

Connect to the cache server:

from sipora_server_catchers import CacheClient

cache = CacheClient(
    host="127.0.0.1",
    port=6380
)

Set a Value

cache.set("name", "Mahesh")

Get a Value

name = cache.get("name")

print(name)

Output:

Mahesh

Delete a Value

cache.delete("name")

Check if a Key Exists

if cache.exists("name"):
    print("Key exists")

TTL

You can automatically expire cached data.

cache.set(
    "otp:12345",
    "987654",
    ttl=60
)

The key will automatically expire after 60 seconds.

You can check the remaining TTL:

remaining = cache.ttl("otp:12345")

print(remaining)

Counters

Increment a numeric value:

cache.increment("page_views")

Increment by a specific amount:

cache.increment(
    "page_views",
    amount=10
)

Get the value:

views = cache.get("page_views")

print(views)

Using With FastAPI

Sipora Server Catchers can be used as a caching layer in FastAPI applications.

from fastapi import FastAPI
from sipora_server_catchers import CacheClient

app = FastAPI()

cache = CacheClient(
    host="127.0.0.1",
    port=6380
)


@app.get("/product/{product_id}")
def get_product(product_id: int):

    cache_key = f"product:{product_id}"

    cached_product = cache.get(cache_key)

    if cached_product is not None:
        return {
            "source": "cache",
            "data": cached_product
        }

    # Query your database here
    product = {
        "id": product_id,
        "name": "Example Product",
        "price": 100
    }

    cache.set(
        cache_key,
        product,
        ttl=300
    )

    return {
        "source": "database",
        "data": product
    }

Cache-Aside Pattern

Sipora is designed to work well with the cache-aside pattern.

             Request
                │
                ▼
          ┌───────────┐
          │  FastAPI  │
          └─────┬─────┘
                │
                ▼
          ┌───────────┐
          │  Sipora   │
          │   Cache   │
          └─────┬─────┘
                │
          ┌─────┴─────┐
          │           │
        HIT          MISS
          │           │
          ▼           ▼
       Return      Database
       cached         │
       data           ▼
                  Store in
                    cache
                      │
                      ▼
                   Return

This prevents frequently requested data from repeatedly hitting the database.

Remote Cache Server

The cache server can run on another machine.

For example:

Application Server
10.0.0.10
      │
      │ TCP
      ▼
Sipora Cache Server
10.0.0.20:6380

Connect remotely:

from sipora_server_catchers import CacheClient

cache = CacheClient(
    host="10.0.0.20",
    port=6380
)

This allows multiple application servers to share the same cache.

                ┌─────────────────┐
                │ Sipora Cache    │
                │ 10.0.0.20:6380  │
                └────────┬────────┘
                         │
              ┌──────────┼──────────┐
              │          │          │
              ▼          ▼          ▼
          Server 1    Server 2    Server 3

Supported Commands

Current commands:

Project Structure

sipora-server-catchers/
│
├── pyproject.toml
├── README.md
├── LICENSE
├── .gitignore
├── CHANGELOG.md
│
├── src/
│   └── sipora_server_catchers/
│       │
│       ├── __init__.py
│       ├── version.py
│       │
│       ├── client/
│       │   ├── __init__.py
│       │   ├── client.py
│       │   ├── connection.py
│       │   └── exceptions.py
│       │
│       ├── server/
│       │   ├── __init__.py
│       │   ├── server.py
│       │   ├── connection.py
│       │   ├── protocol.py
│       │   └── handlers.py
│       │
│       ├── storage/
│       │   ├── __init__.py
│       │   ├── memory.py
│       │   ├── item.py
│       │   └── eviction.py
│       │
│       ├── ttl/
│       │   ├── __init__.py
│       │   └── manager.py
│       │
│       ├── serialization/
│       │   ├── __init__.py
│       │   └── serializer.py
│       │
│       ├── commands/
│       │   ├── __init__.py
│       │   ├── get.py
│       │   ├── set.py
│       │   ├── delete.py
│       │   ├── exists.py
│       │   ├── expire.py
│       │   └── increment.py
│       │
│       ├── config/
│       │   ├── __init__.py
│       │   └── settings.py
│       │
│       └── utils/
│           ├── __init__.py
│           └── logger.py
│
├── tests/
│
└── examples/

Development

Clone the repository:

git clone https://github.com/YOUR_USERNAME/sipora-server-catchers.git

Enter the project:

cd sipora-server-catchers

Create a virtual environment:

python -m venv .venv

Activate it on Windows:

.venv\Scripts\Activate.ps1

Activate it on Linux/macOS:

source .venv/bin/activate

Install development dependencies:

pip install -e ".[dev]"

Run tests:

pytest

Build Package

Build the PyPI package:

python -m build

The generated files will be placed in:

dist/

You should see:

dist/
├── sipora_server_catchers-0.1.0-py3-none-any.whl
└── sipora_server_catchers-0.1.0.tar.gz

Check the package:

twine check dist/*

Publishing to TestPyPI

Upload to TestPyPI first:

twine upload --repository testpypi dist/*

Then test installation:

pip install \
    --index-url https://test.pypi.org/simple/ \
    sipora-server-catchers

Publishing to PyPI

After testing:

twine upload dist/*

Users will then be able to install the package with:

pip install sipora-server-catchers

Security

Do not expose the cache server directly to the public internet without authentication, encryption, and appropriate network restrictions.

For production deployments, use:

• Firewall rules
• Private networking
• Authentication
• TLS
• Access control
• Monitoring
• Resource limits

Roadmap

Version 0.1

• Project structure
• TCP server
• Python client
• GET
• SET
• DELETE
• EXISTS
• TTL
• INCREMENT

Version 0.2

• Async client
• Async server
• Connection pooling
• Authentication
• Better serialization
• Memory limits

Version 0.3

• LRU eviction
• Persistence
• Monitoring
• Metrics
• Health checks

Future

• Replication
• High availability
• Cluster support
• Pub/Sub
• Distributed locking

License

This project is licensed under the MIT License.

See the LICENSE file for details.

Author

Sipora

Project:

sipora-server-catchers

Python package:

sipora_server_catchers