| Name | znsocket JSON |
| Version |
0.2.12
JSON |
| download |
| home_page | None |
| Summary | Python implementation of a Redis-compatible API using websockets. |
| upload_time | 2025-07-15 14:40:56 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | None |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
[](https://badge.fury.io/py/znsocket)
[](https://badge.fury.io/js/znsocket)
[](https://coveralls.io/github/zincware/ZnSocket?branch=main)
[](https://github.com/zincware)
# ZnSocket - Redis-like Key-Value Store in Python
ZnSocket 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.
> [!IMPORTANT]
> ZnSocket automatically handles large data transfers through message chunking.
> Messages larger than the configured size limit (default: 1MB or server limit) are automatically split into smaller chunks and transmitted seamlessly.
> For extremely large data transfers, consider using dedicated file transfer mechanisms or databases.
## Installation
To install ZnSocket, use:
```bash
pip install znsocket
```
## Example
Start the ZnSocket server using the CLI:
```bash
znsocket --port 5000
```
For additional options, run:
```bash
znsocket --help
```
Here's a simple example of how to use the ZnSocket client:
```python
from znsocket import Client
# Connect to the ZnSocket server
c = Client.from_url("znsocket://127.0.0.1:5000")
# Set and get a value
c.set("name", "Fabian")
assert c.get("name") == "Fabian"
```
> [!NOTE]
> ZnSocket does not encode/decode strings. Using it is equivalent to using `Redis.from_url(storage, decode_responses=True)` in the Redis client.
## Lists
ZnSocket 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.
Below is a step-by-step example of how to use `znsocket.List` to interact with a ZnSocket server.
```python
from znsocket import Client, List
# Connect to the ZnSocket server using the provided URL
client = Client.from_url("znsocket://127.0.0.1:5000")
# Create a synchronized list associated with the specified key
sync_list = List(r=client, key="list:1")
# Extend the list with multiple elements
sync_list.extend(["a", "b", "c", "d"])
# Print every second element from the list
print(sync_list[::2])
```
## Dicts
ZnSocket provides a synchronized version of the Python `dict` implementation similar to the `list` implementation.
Below is a step-by-step example of how to use `znsocket.Dict` to interact with a ZnSocket server.
```python
from znsocket import Client, Dict
# Connect to the ZnSocket server using the provided URL
client = Client.from_url("znsocket://127.0.0.1:5000")
# Create a synchronized dict associated with the specified key
sync_dict = Dict(r=client, key="dict:1")
# Add an item to the synchronized dict
sync_dict["Hello"] = "World"
# Print the added item
print(sync_dict["Hello"])
```
## Adapters
ZnSocket 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.
### ListAdapter
The `ListAdapter` exposes any list-like Python object through the ZnSocket `List` interface:
```python
from znsocket import Client, List, ListAdapter
import numpy as np
# Connect to the ZnSocket server
client = Client.from_url("znsocket://127.0.0.1:5000")
# Create some data (can be any list-like object)
data = [1, 2, 3, 4, 5]
# Or numpy array: data = np.array([1, 2, 3, 4, 5])
# Expose the data through an adapter
adapter = ListAdapter(socket=client, key="data", object=data)
# Access the data through a List interface
shared_list = List(r=client, key="data")
print(len(shared_list)) # 5
print(shared_list[0]) # 1
print(shared_list[1:3]) # [2, 3] - supports slicing!
# Changes to the original data are immediately visible
data.append(6)
print(len(shared_list)) # 6
print(shared_list[-1]) # 6
```
### DictAdapter
The `DictAdapter` exposes any dict-like Python object through the ZnSocket `Dict` interface:
```python
from znsocket import Client, Dict, DictAdapter
# Connect to the ZnSocket server
client = Client.from_url("znsocket://127.0.0.1:5000")
# Create some data (can be any dict-like object)
data = {"name": "John", "age": 30, "city": "Berlin"}
# Expose the data through an adapter
adapter = DictAdapter(socket=client, key="user_data", object=data)
# Access the data through a Dict interface
shared_dict = Dict(r=client, key="user_data")
print(shared_dict["name"]) # "John"
print(list(shared_dict.keys())) # ["name", "age", "city"]
print("age" in shared_dict) # True
# Changes to the original data are immediately visible
data["country"] = "Germany"
print(shared_dict["country"]) # "Germany"
print(len(shared_dict)) # 4
```
### Key Features of Adapters
- **Real-time synchronization**: Changes to the underlying object are immediately visible through the adapter
- **Cross-language support**: Access your Python data from JavaScript clients
- **Efficient slicing**: ListAdapter supports efficient slicing operations (e.g., `list[1:5:2]`)
- **Read-only access**: Adapters provide read-only access to prevent accidental modifications
- **Nested data**: Adapters work with complex nested data structures
- **No data copying**: Adapters reference the original data directly
### JavaScript Access
Both adapters can be accessed from JavaScript clients:
```javascript
import { createClient, List, Dict } from 'znsocket';
// Connect to the server
const client = createClient({ url: 'znsocket://127.0.0.1:5000' });
await client.connect();
// Access Python data through adapters
const sharedList = new List({ client, key: 'data' });
const sharedDict = new Dict({ client, key: 'user_data' });
// All operations work seamlessly
console.log(await sharedList.length()); // Real-time length
console.log(await sharedList.slice(1, 3)); // Efficient slicing
console.log(await sharedDict.get('name')); // Access dict values
```
## Automatic Message Chunking
ZnSocket 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.
### How It Works
- **Automatic Detection**: When a message exceeds the size limit, ZnSocket automatically splits it into chunks
- **Transparent Transmission**: Chunks are sent sequentially and reassembled on the server
- **Compression Support**: Large messages are automatically compressed using gzip to reduce transfer size
- **Error Handling**: If any chunk fails to transmit, the entire message transmission is retried
### Configuration
The chunking behavior can be configured when creating a client:
```python
from znsocket import Client
# Configure chunking parameters
client = Client.from_url(
"znsocket://127.0.0.1:5000",
max_message_size_bytes=500000, # 500KB limit (default: 1MB or server limit)
enable_compression=True, # Enable gzip compression (default: True)
compression_threshold=1024 # Compress messages larger than 1KB (default: 1KB)
)
```
### Example with Large Data
```python
import numpy as np
from znsocket import Client, Dict
# Connect with chunking enabled
client = Client.from_url("znsocket://127.0.0.1:5000")
# Create a large dataset
large_data = np.random.rand(1000, 1000) # ~8MB array
# Store the data - chunking happens automatically
data_dict = Dict(r=client, key="large_dataset")
data_dict["array"] = large_data # Automatically chunked and compressed
# Retrieve the data - chunks are automatically reassembled
retrieved_data = data_dict["array"]
```
### Key Features
- **Seamless Operation**: No changes needed to existing code
- **Automatic Compression**: Large messages are compressed to reduce bandwidth
- **Configurable Limits**: Customize chunk size based on your network conditions
- **Error Recovery**: Built-in retry mechanism for failed transmissions
- **Performance Optimization**: Efficient binary serialization and compression
Raw data
{
"_id": null,
"home_page": null,
"name": "znsocket",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": null,
"author": null,
"author_email": "Fabian Zills <fzills@icp.uni-stuttgart.de>",
"download_url": "https://files.pythonhosted.org/packages/f1/d5/d64eb7a719a9649cc3c8cc52ca70063387728a9b3d28e4f291296e922511/znsocket-0.2.12.tar.gz",
"platform": null,
"description": "[](https://badge.fury.io/py/znsocket)\n[](https://badge.fury.io/js/znsocket)\n[](https://coveralls.io/github/zincware/ZnSocket?branch=main)\n\n[](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> [!IMPORTANT]\n> ZnSocket automatically handles large data transfers through message chunking.\n> Messages larger than the configured size limit (default: 1MB or server limit) are automatically split into smaller chunks and transmitted seamlessly.\n> 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> [!NOTE]\n> 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",
"bugtrack_url": null,
"license": null,
"summary": "Python implementation of a Redis-compatible API using websockets.",
"version": "0.2.12",
"project_urls": {
"Releases": "https://github.com/zincware/ZnSocket/releases",
"Repository": "https://github.com/zincware/ZnSocket"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "cb7e221263b7ee3b7724ccf2c28ee4df096c27fcd646681cf13d6748d31f2acf",
"md5": "16deb7caa943c82495c4cdf2f6f258b8",
"sha256": "e6f42c9e311bf252a873399af621514809cb0e794650291dce4a54c8870b7e79"
},
"downloads": -1,
"filename": "znsocket-0.2.12-py3-none-any.whl",
"has_sig": false,
"md5_digest": "16deb7caa943c82495c4cdf2f6f258b8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 39797,
"upload_time": "2025-07-15T14:40:55",
"upload_time_iso_8601": "2025-07-15T14:40:55.784837Z",
"url": "https://files.pythonhosted.org/packages/cb/7e/221263b7ee3b7724ccf2c28ee4df096c27fcd646681cf13d6748d31f2acf/znsocket-0.2.12-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "f1d5d64eb7a719a9649cc3c8cc52ca70063387728a9b3d28e4f291296e922511",
"md5": "623e7c16e11e6740feb67d718e341e5d",
"sha256": "14cd0813d19586d816e7d2e67ccf3b57f0fc99e6b1c04d89f810ef796734eedf"
},
"downloads": -1,
"filename": "znsocket-0.2.12.tar.gz",
"has_sig": false,
"md5_digest": "623e7c16e11e6740feb67d718e341e5d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 236789,
"upload_time": "2025-07-15T14:40:56",
"upload_time_iso_8601": "2025-07-15T14:40:56.670991Z",
"url": "https://files.pythonhosted.org/packages/f1/d5/d64eb7a719a9649cc3c8cc52ca70063387728a9b3d28e4f291296e922511/znsocket-0.2.12.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-15 14:40:56",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "zincware",
"github_project": "ZnSocket",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "znsocket"
}
