| Name | nemoria JSON |
| Version |
1.0.0
JSON |
| download |
| home_page | None |
| Summary | Async TCP in-memory datastore with secure client-server protocol, supporting real-time multi-client CRUD operations. |
| upload_time | 2025-09-12 22:51:17 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | MIT License
Copyright (c) 2025 Moh-Dehghan
Email: M.Dehghan.2003@outlook.com
GitHub: https://github.com/Moh-Dehghan/Nemoria
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE. |
| keywords |
asyncio
client
crud
memory
protocol
server
store
tcp
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Nemoria
**Nemoria** is a lightweight, asynchronous, in-memory datastore with secure client-server protocol, supporting real-time multi-client CRUD operations.
It is designed for **fast prototyping, experiments, and educational use cases** where a minimal and hackable data layer is needed.
✨ With Nemoria, you can **read and write data in real time** from **any process, thread, or program**, using multiple clients simultaneously.
Think of it as a tiny Redis-like system built entirely in Python/asyncio.
---
## Features
- 🚀 **Asynchronous I/O** powered by `asyncio`
- 🔑 **Password-based authentication**
- 🧩 **Nested routes** with hierarchical `Route` objects
- ⚡ **Simple CRUD API** (`get`, `all`, `set`, `delete`, `drop`, `purge`, `ping`)
- 🔄 **Multi-client access** – read and write data in real time across any process, thread, or external program
- 🛠 **Minimalistic & extensible design** for custom protocols
---
## Installation
### A) Install from PyPI
```bash
pip install nemoria
```
---
### B) Local source install
```bash
git clone https://github.com/moh-dehghan/nemoria.git
cd nemoria
pip install -e .
```
---
### C) Install from built distributions (dist/)
**Wheel (recommended)**
```bash
pip install dist/nemoria-1.0.0-py3-none-any.whl
```
**Or Source tarball**
```bash
pip install dist/nemoria-1.0.0.tar.gz
```
---
### Verification
Check if the package is installed correctly:
```bash
python -c "import nemoria; print(nemoria.__version__)"
```
Or:
```python
import nemoria
print(nemoria.__version__)
```
---
## Quick Start
### 1. Run the Server
```python
# server.py
import asyncio
from nemoria import Server
async def main():
server = Server(host="localhost", port=1234, namespace="TEST", password="12345678")
# Run server
await server.run_forever(raise_on_error=False)
if __name__ == "__main__":
try:
asyncio.run(main())
except KeyboardInterrupt:
pass
```
Run it in one terminal:
```bash
python server.py
```
---
### 2. Connect a Client
```python
# client.py
import asyncio
from nemoria import Client, Route
async def main():
client = Client(host="localhost", port=1234, password="12345678")
# Connect
if not await client.connect():
return
# Create data
await client.set(Route("user", "profile", "name"), "Alice")
await client.set(Route("user", "profile", "age"), 30)
# Read data
print(await client.get(Route("user", "profile", "name"))) # -> "Alice"
print(await client.all()) # -> {'user': {'profile': {'name': 'Alice', 'age': 30}}}
# Update data
await client.set(Route("user", "profile", "age"), 31)
print(await client.get(Route("user", "profile", "age"))) # -> 31
# Delete part of a route
await client.delete(Route("user", "profile", "age"))
print(await client.all())
# Drop the entire top-level route
await client.drop(Route("user"))
print(await client.all()) # -> {}
await asyncio.Future()
if __name__ == "__main__":
try:
asyncio.run(main())
except KeyboardInterrupt:
pass
```
Run it in another terminal:
```bash
python client.py
```
---
## More Examples
### Storing Nested Data
```python
await client.set(Route("blog", "posts", "1", "title"), "Hello World")
await client.set(Route("blog", "posts", "1", "tags"), ["intro", "nemoria"])
await client.set(Route("blog", "posts", "2", "title"), "Async Rocks")
print(await client.all())
# {
# "blog": {
# "posts": {
# "1": {"title": "Hello World", "tags": ["intro", "nemoria"]},
# "2": {"title": "Async Rocks"}
# }
# }
# }
```
### Deleting & Dropping & Purging
```python
# Delete just one nested field
await client.delete(Route("blog", "posts", "1", "tags"))
# Drop entire "posts" subtree
await client.drop(Route("blog", "posts"))
# Clear entire datastore
await client.purge()
```
### Ping & Healthcheck
```python
# Ping
print(await client.ping()) # -> Latency in milliseconds, or `None` on timeout/connection error.
# Healthcheck
print(await client.is_alive()) # -> True or False
```
---
## Development Notes
Nemoria is intentionally designed to be **minimalistic yet extensible**, with a focus on clarity, hackability, and serving as an educational reference.
- 🧩 **Architecture**:
The system follows a clear client–server separation.
- `Server`: manages connections, authentication, and route-based storage.
- `Client`: provides a high-level API for CRUD operations and route traversal.
- `Route`: represents nested hierarchical keys for structured data access.
- ⚙️ **Technology Stack**:
- Implemented in **Python 3.10+** using `asyncio` for fully asynchronous I/O.
- Built around standard Python libraries to keep dependencies minimal.
- Supports multiple concurrent clients with real-time access guarantees.
- 🎯 **Design Goals**:
- Prioritize **readability** and **hackability** over heavy optimizations.
- Provide a safe playground for learning about async networking and protocol design.
- Allow easy extension for advanced features like persistence, clustering, and pub/sub.
- 🛠 **Intended Use**:
- Great for **fast prototyping** when you need a lightweight datastore.
- Suitable for **experiments** in distributed systems and protocol design.
- Serves as a **teaching tool** for learning asyncio, client-server patterns, and hierarchical data structures.
---
## Roadmap
- [ ] Persistent storage (save/load to disk)
- [ ] Pub/Sub messaging
- [ ] Cluster mode (multi-server)
- [ ] Advanced query language
---
## Educational Use
Nemoria is not only a functional datastore, but also an **educational resource**.
It is particularly valuable for:
- 📚 **Students & Learners**: Understanding how asynchronous servers and clients communicate.
- 🧑💻 **Developers**: Experimenting with custom protocols, networking, and route-based data models.
- 🏫 **Educators**: Demonstrating practical concepts of `asyncio`, event loops, and concurrency in Python.
---
## License
This project is licensed under the MIT License – see the [LICENSE](LICENSE) file for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "nemoria",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "asyncio, client, crud, memory, protocol, server, store, tcp",
"author": null,
"author_email": "Moh-Dehghan <m.dehghan.2003@outlook.com>",
"download_url": "https://files.pythonhosted.org/packages/7f/03/64355c8214ceb62a199820d440db75cb6a8bfa184fdda51db3848c6e57cf/nemoria-1.0.0.tar.gz",
"platform": null,
"description": "# Nemoria\n\n**Nemoria** is a lightweight, asynchronous, in-memory datastore with secure client-server protocol, supporting real-time multi-client CRUD operations. \nIt is designed for **fast prototyping, experiments, and educational use cases** where a minimal and hackable data layer is needed. \n\n\u2728 With Nemoria, you can **read and write data in real time** from **any process, thread, or program**, using multiple clients simultaneously.\n\nThink of it as a tiny Redis-like system built entirely in Python/asyncio.\n\n---\n\n## Features\n\n- \ud83d\ude80 **Asynchronous I/O** powered by `asyncio`\n- \ud83d\udd11 **Password-based authentication**\n- \ud83e\udde9 **Nested routes** with hierarchical `Route` objects\n- \u26a1 **Simple CRUD API** (`get`, `all`, `set`, `delete`, `drop`, `purge`, `ping`)\n- \ud83d\udd04 **Multi-client access** \u2013 read and write data in real time across any process, thread, or external program\n- \ud83d\udee0 **Minimalistic & extensible design** for custom protocols\n\n---\n\n## Installation\n\n### A) Install from PyPI\n```bash\npip install nemoria\n```\n\n---\n\n### B) Local source install\n```bash\ngit clone https://github.com/moh-dehghan/nemoria.git\ncd nemoria\npip install -e .\n```\n\n---\n\n### C) Install from built distributions (dist/)\n\n**Wheel (recommended)**\n```bash\npip install dist/nemoria-1.0.0-py3-none-any.whl\n```\n\n**Or Source tarball**\n```bash\npip install dist/nemoria-1.0.0.tar.gz\n```\n\n---\n\n### Verification\nCheck if the package is installed correctly:\n```bash\npython -c \"import nemoria; print(nemoria.__version__)\"\n```\nOr:\n```python\nimport nemoria\nprint(nemoria.__version__)\n```\n\n---\n\n## Quick Start\n\n### 1. Run the Server\n\n```python\n# server.py\nimport asyncio\nfrom nemoria import Server\n\nasync def main():\n server = Server(host=\"localhost\", port=1234, namespace=\"TEST\", password=\"12345678\")\n\n # Run server\n await server.run_forever(raise_on_error=False)\n\nif __name__ == \"__main__\":\n try:\n asyncio.run(main())\n except KeyboardInterrupt:\n pass\n```\n\nRun it in one terminal:\n\n```bash\npython server.py\n```\n\n---\n\n### 2. Connect a Client\n\n```python\n# client.py\nimport asyncio\nfrom nemoria import Client, Route\n\nasync def main():\n client = Client(host=\"localhost\", port=1234, password=\"12345678\")\n \n # Connect\n if not await client.connect():\n return\n\n # Create data\n await client.set(Route(\"user\", \"profile\", \"name\"), \"Alice\")\n await client.set(Route(\"user\", \"profile\", \"age\"), 30)\n\n # Read data\n print(await client.get(Route(\"user\", \"profile\", \"name\"))) # -> \"Alice\"\n print(await client.all()) # -> {'user': {'profile': {'name': 'Alice', 'age': 30}}}\n\n # Update data\n await client.set(Route(\"user\", \"profile\", \"age\"), 31)\n print(await client.get(Route(\"user\", \"profile\", \"age\"))) # -> 31\n\n # Delete part of a route\n await client.delete(Route(\"user\", \"profile\", \"age\"))\n print(await client.all())\n\n # Drop the entire top-level route\n await client.drop(Route(\"user\"))\n print(await client.all()) # -> {}\n\n await asyncio.Future()\n\nif __name__ == \"__main__\":\n try:\n asyncio.run(main())\n except KeyboardInterrupt:\n pass\n```\n\nRun it in another terminal:\n\n```bash\npython client.py\n```\n\n---\n\n## More Examples\n\n### Storing Nested Data\n\n```python\nawait client.set(Route(\"blog\", \"posts\", \"1\", \"title\"), \"Hello World\")\nawait client.set(Route(\"blog\", \"posts\", \"1\", \"tags\"), [\"intro\", \"nemoria\"])\nawait client.set(Route(\"blog\", \"posts\", \"2\", \"title\"), \"Async Rocks\")\n\nprint(await client.all())\n# {\n# \"blog\": {\n# \"posts\": {\n# \"1\": {\"title\": \"Hello World\", \"tags\": [\"intro\", \"nemoria\"]},\n# \"2\": {\"title\": \"Async Rocks\"}\n# }\n# }\n# }\n```\n\n### Deleting & Dropping & Purging\n\n```python\n# Delete just one nested field\nawait client.delete(Route(\"blog\", \"posts\", \"1\", \"tags\"))\n\n# Drop entire \"posts\" subtree\nawait client.drop(Route(\"blog\", \"posts\"))\n\n# Clear entire datastore\nawait client.purge()\n```\n\n### Ping & Healthcheck\n\n```python\n# Ping\nprint(await client.ping()) # -> Latency in milliseconds, or `None` on timeout/connection error.\n\n# Healthcheck\nprint(await client.is_alive()) # -> True or False\n\n```\n\n---\n\n## Development Notes\n\nNemoria is intentionally designed to be **minimalistic yet extensible**, with a focus on clarity, hackability, and serving as an educational reference. \n\n- \ud83e\udde9 **Architecture**: \n The system follows a clear client\u2013server separation. \n - `Server`: manages connections, authentication, and route-based storage. \n - `Client`: provides a high-level API for CRUD operations and route traversal. \n - `Route`: represents nested hierarchical keys for structured data access. \n\n- \u2699\ufe0f **Technology Stack**: \n - Implemented in **Python 3.10+** using `asyncio` for fully asynchronous I/O. \n - Built around standard Python libraries to keep dependencies minimal. \n - Supports multiple concurrent clients with real-time access guarantees. \n\n- \ud83c\udfaf **Design Goals**: \n - Prioritize **readability** and **hackability** over heavy optimizations. \n - Provide a safe playground for learning about async networking and protocol design. \n - Allow easy extension for advanced features like persistence, clustering, and pub/sub. \n\n- \ud83d\udee0 **Intended Use**: \n - Great for **fast prototyping** when you need a lightweight datastore. \n - Suitable for **experiments** in distributed systems and protocol design. \n - Serves as a **teaching tool** for learning asyncio, client-server patterns, and hierarchical data structures. \n\n---\n\n## Roadmap\n\n- [ ] Persistent storage (save/load to disk) \n- [ ] Pub/Sub messaging \n- [ ] Cluster mode (multi-server) \n- [ ] Advanced query language \n\n---\n\n## Educational Use\n\nNemoria is not only a functional datastore, but also an **educational resource**. \nIt is particularly valuable for: \n\n- \ud83d\udcda **Students & Learners**: Understanding how asynchronous servers and clients communicate. \n- \ud83e\uddd1\u200d\ud83d\udcbb **Developers**: Experimenting with custom protocols, networking, and route-based data models. \n- \ud83c\udfeb **Educators**: Demonstrating practical concepts of `asyncio`, event loops, and concurrency in Python. \n\n---\n\n## License\n\nThis project is licensed under the MIT License \u2013 see the [LICENSE](LICENSE) file for details.\n",
"bugtrack_url": null,
"license": "MIT License\n \n Copyright (c) 2025 Moh-Dehghan\n Email: M.Dehghan.2003@outlook.com\n GitHub: https://github.com/Moh-Dehghan/Nemoria\n \n Permission is hereby granted, free of charge, to any person obtaining a copy\n of this software and associated documentation files (the \"Software\"), to deal\n in the Software without restriction, including without limitation the rights\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n copies of the Software, and to permit persons to whom the Software is\n furnished to do so, subject to the following conditions:\n \n The above copyright notice and this permission notice shall be included in all\n copies or substantial portions of the Software.\n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n SOFTWARE.",
"summary": "Async TCP in-memory datastore with secure client-server protocol, supporting real-time multi-client CRUD operations.",
"version": "1.0.0",
"project_urls": {
"Homepage": "https://github.com/moh-dehghan/nemoria",
"Issues": "https://github.com/moh-dehghan/nemoria/issues",
"Repository": "https://github.com/moh-dehghan/nemoria"
},
"split_keywords": [
"asyncio",
" client",
" crud",
" memory",
" protocol",
" server",
" store",
" tcp"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "207bab406cc74394368da495a3e4d73732897cbe978a2bcc7471e9d20d809d00",
"md5": "e480ad8b76374f05a5f13077cf090f4e",
"sha256": "a45bf39a6e3cd59093e56b027c8ee5d9e301ceb64f143b2b8834485148f473ca"
},
"downloads": -1,
"filename": "nemoria-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e480ad8b76374f05a5f13077cf090f4e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 27699,
"upload_time": "2025-09-12T22:51:15",
"upload_time_iso_8601": "2025-09-12T22:51:15.527820Z",
"url": "https://files.pythonhosted.org/packages/20/7b/ab406cc74394368da495a3e4d73732897cbe978a2bcc7471e9d20d809d00/nemoria-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "7f0364355c8214ceb62a199820d440db75cb6a8bfa184fdda51db3848c6e57cf",
"md5": "654767c36fe80147fdec511698416991",
"sha256": "17d7be4b0e520696f49617bd8abe1a65ed8b23660d9c6b2de42f0b6e0fdef27c"
},
"downloads": -1,
"filename": "nemoria-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "654767c36fe80147fdec511698416991",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 22549,
"upload_time": "2025-09-12T22:51:17",
"upload_time_iso_8601": "2025-09-12T22:51:17.448955Z",
"url": "https://files.pythonhosted.org/packages/7f/03/64355c8214ceb62a199820d440db75cb6a8bfa184fdda51db3848c6e57cf/nemoria-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-12 22:51:17",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "moh-dehghan",
"github_project": "nemoria",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "nemoria"
}
