{"id":29656531,"url":"https://github.com/zincware/znsocket","last_synced_at":"2025-12-16T11:44:53.661Z","repository":{"id":240956706,"uuid":"803899175","full_name":"zincware/ZnSocket","owner":"zincware","description":"Python implementation of a Redis-compatible API using websockets.","archived":false,"fork":false,"pushed_at":"2025-07-15T14:41:20.000Z","size":627,"stargazers_count":4,"open_issues_count":21,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-07-16T03:58:56.014Z","etag":null,"topics":["cache","database","key-value","low-latency","nosql","redis","socketio","websocket"],"latest_commit_sha":null,"homepage":"https://zincware.github.io/ZnSocket/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zincware.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-05-21T15:16:07.000Z","updated_at":"2025-07-15T14:41:24.000Z","dependencies_parsed_at":"2024-05-28T21:50:37.541Z","dependency_job_id":"b1e29e02-a029-4a26-9991-892be4583aa7","html_url":"https://github.com/zincware/ZnSocket","commit_stats":null,"previous_names":["zincware/znsocket"],"tags_count":22,"template":false,"template_full_name":null,"purl":"pkg:github/zincware/ZnSocket","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zincware%2FZnSocket","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zincware%2FZnSocket/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zincware%2FZnSocket/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zincware%2FZnSocket/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zincware","download_url":"https://codeload.github.com/zincware/ZnSocket/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zincware%2FZnSocket/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266456421,"owners_count":23931407,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-22T02:00:09.085Z","response_time":66,"last_error":null,"robots_txt_status":null,"robots_txt_updated_at":null,"robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cache","database","key-value","low-latency","nosql","redis","socketio","websocket"],"created_at":"2025-07-22T08:35:50.748Z","updated_at":"2025-12-16T11:44:53.561Z","avatar_url":"https://github.com/zincware.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![PyPI version](https://badge.fury.io/py/znsocket.svg)](https://badge.fury.io/py/znsocket)\n[![npm version](https://badge.fury.io/js/znsocket.svg)](https://badge.fury.io/js/znsocket)\n[![Coverage Status](https://coveralls.io/repos/github/zincware/ZnSocket/badge.svg?branch=main)](https://coveralls.io/github/zincware/ZnSocket?branch=main)\n![PyTest](https://github.com/zincware/ZnSocket/actions/workflows/pytest.yaml/badge.svg)\n[![zincware](https://img.shields.io/badge/Powered%20by-zincware-darkcyan)](https://github.com/zincware)\n\n# ZnSocket - Redis-like Key-Value Store in Python\n\nZnSocket provides a [Redis](https://redis.io/)-compatible API using [python-socketio](https://python-socketio.readthedocs.io/en/stable/) and Python objects for storage. It is designed for testing and applications requiring key-value storage while being easily installable via `pip`. For production, consider using [redis-py](https://redis-py.readthedocs.io/) and a Redis instance.\n\n\u003e [!IMPORTANT]\n\u003e ZnSocket automatically handles large data transfers through message chunking.\n\u003e Messages larger than the configured size limit (default: 1MB or server limit) are automatically split into smaller chunks and transmitted seamlessly.\n\u003e For extremely large data transfers, consider using dedicated file transfer mechanisms or databases.\n\n## Installation\n\nTo install ZnSocket, use:\n\n```bash\npip install znsocket\n```\n\n## Example\n\nStart the ZnSocket server using the CLI:\n\n```bash\nznsocket --port 5000\n```\n\nFor additional options, run:\n\n```bash\nznsocket --help\n```\n\nHere's a simple example of how to use the ZnSocket client:\n\n```python\nfrom znsocket import Client\n\n# Connect to the ZnSocket server\nc = Client.from_url(\"znsocket://127.0.0.1:5000\")\n\n# Set and get a value\nc.set(\"name\", \"Fabian\")\nassert c.get(\"name\") == \"Fabian\"\n```\n\n\u003e [!NOTE]\n\u003e ZnSocket does not encode/decode strings. Using it is equivalent to using `Redis.from_url(storage, decode_responses=True)` in the Redis client.\n\n## Lists\n\nZnSocket provides a synchronized version of the Python `list` implementation. Unlike a regular Python list, the data in `znsocket.List` is not stored locally; instead, it is dynamically pushed to and pulled from the server.\n\nBelow is a step-by-step example of how to use `znsocket.List` to interact with a ZnSocket server.\n\n```python\nfrom znsocket import Client, List\n\n# Connect to the ZnSocket server using the provided URL\nclient = Client.from_url(\"znsocket://127.0.0.1:5000\")\n\n# Create a synchronized list associated with the specified key\nsync_list = List(r=client, key=\"list:1\")\n\n# Extend the list with multiple elements\nsync_list.extend([\"a\", \"b\", \"c\", \"d\"])\n\n# Print every second element from the list\nprint(sync_list[::2])\n```\n\n## Dicts\n\nZnSocket provides a synchronized version of the Python `dict` implementation similar to the `list` implementation.\n\nBelow is a step-by-step example of how to use `znsocket.Dict` to interact with a ZnSocket server.\n\n```python\nfrom znsocket import Client, Dict\n\n# Connect to the ZnSocket server using the provided URL\nclient = Client.from_url(\"znsocket://127.0.0.1:5000\")\n\n# Create a synchronized dict associated with the specified key\nsync_dict = Dict(r=client, key=\"dict:1\")\n\n# Add an item to the synchronized dict\nsync_dict[\"Hello\"] = \"World\"\n\n# Print the added item\nprint(sync_dict[\"Hello\"])\n```\n\n## Adapters\n\nZnSocket provides adapter classes that allow you to expose existing Python objects through the ZnSocket interface. This enables real-time access to your data structures from both Python and JavaScript clients without copying or modifying the original data.\n\n### ListAdapter\n\nThe `ListAdapter` exposes any list-like Python object through the ZnSocket `List` interface:\n\n```python\nfrom znsocket import Client, List, ListAdapter\nimport numpy as np\n\n# Connect to the ZnSocket server\nclient = Client.from_url(\"znsocket://127.0.0.1:5000\")\n\n# Create some data (can be any list-like object)\ndata = [1, 2, 3, 4, 5]\n# Or numpy array: data = np.array([1, 2, 3, 4, 5])\n\n# Expose the data through an adapter\nadapter = ListAdapter(socket=client, key=\"data\", object=data)\n\n# Access the data through a List interface\nshared_list = List(r=client, key=\"data\")\nprint(len(shared_list))  # 5\nprint(shared_list[0])    # 1\nprint(shared_list[1:3])  # [2, 3] - supports slicing!\n\n# Changes to the original data are immediately visible\ndata.append(6)\nprint(len(shared_list))  # 6\nprint(shared_list[-1])   # 6\n```\n\n### DictAdapter\n\nThe `DictAdapter` exposes any dict-like Python object through the ZnSocket `Dict` interface:\n\n```python\nfrom znsocket import Client, Dict, DictAdapter\n\n# Connect to the ZnSocket server\nclient = Client.from_url(\"znsocket://127.0.0.1:5000\")\n\n# Create some data (can be any dict-like object)\ndata = {\"name\": \"John\", \"age\": 30, \"city\": \"Berlin\"}\n\n# Expose the data through an adapter\nadapter = DictAdapter(socket=client, key=\"user_data\", object=data)\n\n# Access the data through a Dict interface\nshared_dict = Dict(r=client, key=\"user_data\")\nprint(shared_dict[\"name\"])           # \"John\"\nprint(list(shared_dict.keys()))      # [\"name\", \"age\", \"city\"]\nprint(\"age\" in shared_dict)          # True\n\n# Changes to the original data are immediately visible\ndata[\"country\"] = \"Germany\"\nprint(shared_dict[\"country\"])        # \"Germany\"\nprint(len(shared_dict))              # 4\n```\n\n### Key Features of Adapters\n\n- **Real-time synchronization**: Changes to the underlying object are immediately visible through the adapter\n- **Cross-language support**: Access your Python data from JavaScript clients\n- **Efficient slicing**: ListAdapter supports efficient slicing operations (e.g., `list[1:5:2]`)\n- **Read-only access**: Adapters provide read-only access to prevent accidental modifications\n- **Nested data**: Adapters work with complex nested data structures\n- **No data copying**: Adapters reference the original data directly\n\n### JavaScript Access\n\nBoth adapters can be accessed from JavaScript clients:\n\n```javascript\nimport { createClient, List, Dict } from 'znsocket';\n\n// Connect to the server\nconst client = createClient({ url: 'znsocket://127.0.0.1:5000' });\nawait client.connect();\n\n// Access Python data through adapters\nconst sharedList = new List({ client, key: 'data' });\nconst sharedDict = new Dict({ client, key: 'user_data' });\n\n// All operations work seamlessly\nconsole.log(await sharedList.length());     // Real-time length\nconsole.log(await sharedList.slice(1, 3));  // Efficient slicing\nconsole.log(await sharedDict.get('name'));  // Access dict values\n```\n\n## Automatic Message Chunking\n\nZnSocket automatically handles large data transfers by splitting messages into smaller chunks when they exceed the configured size limit. This feature is transparent to users and works seamlessly with all ZnSocket operations.\n\n### How It Works\n\n- **Automatic Detection**: When a message exceeds the size limit, ZnSocket automatically splits it into chunks\n- **Transparent Transmission**: Chunks are sent sequentially and reassembled on the server\n- **Compression Support**: Large messages are automatically compressed using gzip to reduce transfer size\n- **Error Handling**: If any chunk fails to transmit, the entire message transmission is retried\n\n### Configuration\n\nThe chunking behavior can be configured when creating a client:\n\n```python\nfrom znsocket import Client\n\n# Configure chunking parameters\nclient = Client.from_url(\n    \"znsocket://127.0.0.1:5000\",\n    max_message_size_bytes=500000,  # 500KB limit (default: 1MB or server limit)\n    enable_compression=True,        # Enable gzip compression (default: True)\n    compression_threshold=1024      # Compress messages larger than 1KB (default: 1KB)\n)\n```\n\n### Example with Large Data\n\n```python\nimport numpy as np\nfrom znsocket import Client, Dict\n\n# Connect with chunking enabled\nclient = Client.from_url(\"znsocket://127.0.0.1:5000\")\n\n# Create a large dataset\nlarge_data = np.random.rand(1000, 1000)  # ~8MB array\n\n# Store the data - chunking happens automatically\ndata_dict = Dict(r=client, key=\"large_dataset\")\ndata_dict[\"array\"] = large_data  # Automatically chunked and compressed\n\n# Retrieve the data - chunks are automatically reassembled\nretrieved_data = data_dict[\"array\"]\n```\n\n### Key Features\n\n- **Seamless Operation**: No changes needed to existing code\n- **Automatic Compression**: Large messages are compressed to reduce bandwidth\n- **Configurable Limits**: Customize chunk size based on your network conditions\n- **Error Recovery**: Built-in retry mechanism for failed transmissions\n- **Performance Optimization**: Efficient binary serialization and compression\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzincware%2Fznsocket","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzincware%2Fznsocket","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzincware%2Fznsocket/lists"}