# Zeeland
Zeeland's core infrastructure serves the following frameworks:
| Lib | Description |
|--------------------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| Cogit | LLM MultiAgent task inference and autonomous orchestration framework/Comming soon |
| [Promptulate](https://github.com/Undertone0809/promptulate) | A LLM application and Agent development framework. |
| [Gcop](https://github.com/Undertone0809/gcop) | Your git AI copilot. |
## TODO
The following libraries are under development and will be released soon:
| Lib | Description |
|--------------------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| [UACP](https://github.com/Undertone0809/UACP) | Universal Agent Communication Protocol. |
| [P3G](https://github.com/Undertone0809/P3G) | Python Package Project Generator. |
| [cushy-storage](https://github.com/Undertone0809/cushy-storage) | A lightweight ORM framework that provides disk caching for Python objects. |
| [omnius](https://github.com/Undertone0809/omnius) | A lightweight event bus framework. You can easily build a powerful event bus in your project. |
| [cushy-socket](https://github.com/Undertone0809/cushy-socket) | A Python socket library. You can create a TCP/UDP connection easily. |
| [imarkdown](https://github.com/Undertone0809/imarkdown) | A practical Markdown image URL converter. |
| [cushy-serial](https://github.com/Undertone0809/cushy-serial) | A lightweight Python serial library. You can create a serial program easily. |
| [ecjtu](https://github.com/Undertone0809/ecjtu) | ecjtu API SDK service, best practices for client SDK design. |
## Why build it?
There are two main challenges in Zeeland's Python library development:
1. **Reducing Circular Dependencies**: The framework provides a structured way to manage and minimize circular dependencies between components, making the codebase more maintainable and easier to reason about.
2. **Reusable Common Logic**: As the developer of multiple Python libraries, I found myself repeatedly implementing similar patterns and utilities. Zeeland extracts these common elements into a shared infrastructure, allowing better maintenance and consistency across different frameworks and libraries.
## Features
- **Logger**: A logger framework that can record exceptions and log messages to different files based on the framework.
- **Singleton**: A singleton pattern implementation.
- **Project Metadata**: A metadata framework that can record the project's metadata and save it to the default storage path.
## Quick start
Conda package manager is recommended. Create a conda environment.
```bash
conda create -n zeeland python==3.10
```
Activate conda environment and install poetry
```bash
conda activate zeeland
pip install poetry
```
### Basic Usage
Create a metadata file in the default storage path.
```python
import json
import os
from zeeland import get_default_storage_path
def main():
storage_path = get_default_storage_path("test")
metadata_path = os.path.join(storage_path, "metadata.json")
metadata = {"name": "test", "version": "1.0.0", "description": "Test metadata file"}
with open(metadata_path, "w") as f:
json.dump(metadata, f, indent=4)
print(f"Created metadata file at: {metadata_path}")
with open(metadata_path, "r") as f:
print("Content:")
print(json.dumps(json.load(f), indent=4))
if __name__ == "__main__":
main()
```
The metadata file will be saved in the default storage path, which is `~/.zeeland/test/metadata.json`.
Singleton usage
```python
from zeeland import Singleton, singleton
@singleton()
class TestSingleton:
pass
instance1 = TestSingleton()
instance2 = TestSingleton()
assert instance1 is instance2
class TestSingletonWithArgs(metaclass=Singleton):
def __init__(self, value):
self.value = value
instance1 = TestSingletonWithArgs("test1")
instance2 = TestSingletonWithArgs("test2")
assert instance1 is instance2
assert instance1.value == "test1"
```
Logger usage
```python
from zeeland import Logger
logger = Logger("test_framework")
logger.info("Hello, Zeeland!")
```
Then you can see the log file in the default storage path. In this case, it is `~/.zeeland/test_framework/logs/{current_date}.log`.
### Makefile usage
[`Makefile`](https://github.com/Undertone0809/zeeland/blob/main/Makefile) contains a lot of functions for faster development.
<details>
<summary>Install all dependencies and pre-commit hooks</summary>
<p>
Install requirements:
```bash
make install
```
Pre-commit hooks coulb be installed after `git init` via
```bash
make pre-commit-install
```
</p>
</details>
<details>
<summary>Codestyle and type checks</summary>
<p>
Automatic formatting uses `ruff`.
```bash
make format
```
Codestyle checks only, without rewriting files:
```bash
make check-codestyle
```
> Note: `check-codestyle` uses `ruff` and `darglint` library
</p>
</details>
<details>
<summary>Code security</summary>
<p>
> If this command is not selected during installation, it cannnot be used.
```bash
make check-safety
```
This command launches `Poetry` integrity checks as well as identifies security issues with `Safety` and `Bandit`.
```bash
make check-safety
```
</p>
</details>
<details>
<summary>Tests with coverage badges</summary>
<p>
Run `pytest`
```bash
make test
```
</p>
</details>
<details>
<summary>All linters</summary>
<p>
Of course there is a command to run all linters in one:
```bash
make lint
```
the same as:
```bash
make check-codestyle && make test && make check-safety
```
</p>
</details>
<details>
<summary>Docker</summary>
<p>
```bash
make docker-build
```
which is equivalent to:
```bash
make docker-build VERSION=latest
```
Remove docker image with
```bash
make docker-remove
```
More information [about docker](https://github.com/Undertone0809/python-package-template/tree/main/%7B%7B%20cookiecutter.project_name%20%7D%7D/docker).
</p>
</details>
<details>
<summary>Cleanup</summary>
<p>
Delete pycache files
```bash
make pycache-remove
```
Remove package build
```bash
make build-remove
```
Delete .DS_STORE files
```bash
make dsstore-remove
```
Remove .mypycache
```bash
make mypycache-remove
```
Or to remove all above run:
```bash
make cleanup
```
</p>
</details>
## 🛡 License
[](https://github.com/Undertone0809/zeeland/blob/main/LICENSE)
This project is licensed under the terms of the `MIT` license. See [LICENSE](https://github.com/Undertone0809/zeeland/blob/main/LICENSE) for more details.
## 📃 Citation
```bibtex
@misc{zeeland,
author = {zeeland},
title = {zeeland frameworks core infra},
year = {2024},
publisher = {GitHub},
journal = {GitHub repository},
howpublished = {\url{https://github.com/Undertone0809/zeeland}}
}
```
## Credits [](https://github.com/Undertone0809/python-package-template)
This project was generated with [P3G](https://github.com/Undertone0809/P3G)
Raw data
{
"_id": null,
"home_page": "https://github.com/Undertone0809/zeeland",
"name": "zeeland",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.8",
"maintainer_email": null,
"keywords": null,
"author": "zeeland",
"author_email": "zeeland4work@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/e8/09/c89a97de342dc3b7ce2e321f05fc654ba7f41dee74797365bfd1eb00381f/zeeland-0.3.0.tar.gz",
"platform": null,
"description": "# Zeeland\n\n\n\nZeeland's core infrastructure serves the following frameworks:\n\n| Lib | Description |\n|--------------------------------------------------------------|---------------------------------------------------------------------------------------------------------|\n| Cogit | LLM MultiAgent task inference and autonomous orchestration framework/Comming soon |\n| [Promptulate](https://github.com/Undertone0809/promptulate) | A LLM application and Agent development framework. |\n| [Gcop](https://github.com/Undertone0809/gcop) | Your git AI copilot. |\n\n## TODO\n\nThe following libraries are under development and will be released soon:\n\n| Lib | Description |\n|--------------------------------------------------------------|---------------------------------------------------------------------------------------------------------|\n| [UACP](https://github.com/Undertone0809/UACP) | Universal Agent Communication Protocol. |\n| [P3G](https://github.com/Undertone0809/P3G) | Python Package Project Generator. |\n| [cushy-storage](https://github.com/Undertone0809/cushy-storage) | A lightweight ORM framework that provides disk caching for Python objects. |\n| [omnius](https://github.com/Undertone0809/omnius) | A lightweight event bus framework. You can easily build a powerful event bus in your project. |\n| [cushy-socket](https://github.com/Undertone0809/cushy-socket) | A Python socket library. You can create a TCP/UDP connection easily. |\n| [imarkdown](https://github.com/Undertone0809/imarkdown) | A practical Markdown image URL converter. |\n| [cushy-serial](https://github.com/Undertone0809/cushy-serial) | A lightweight Python serial library. You can create a serial program easily. |\n| [ecjtu](https://github.com/Undertone0809/ecjtu) | ecjtu API SDK service, best practices for client SDK design. |\n\n## Why build it?\n\nThere are two main challenges in Zeeland's Python library development:\n\n1. **Reducing Circular Dependencies**: The framework provides a structured way to manage and minimize circular dependencies between components, making the codebase more maintainable and easier to reason about.\n\n2. **Reusable Common Logic**: As the developer of multiple Python libraries, I found myself repeatedly implementing similar patterns and utilities. Zeeland extracts these common elements into a shared infrastructure, allowing better maintenance and consistency across different frameworks and libraries.\n\n## Features\n\n- **Logger**: A logger framework that can record exceptions and log messages to different files based on the framework.\n- **Singleton**: A singleton pattern implementation.\n- **Project Metadata**: A metadata framework that can record the project's metadata and save it to the default storage path.\n\n## Quick start\n\nConda package manager is recommended. Create a conda environment.\n\n```bash\nconda create -n zeeland python==3.10\n```\n\nActivate conda environment and install poetry\n\n```bash\nconda activate zeeland\npip install poetry\n```\n\n### Basic Usage\n\nCreate a metadata file in the default storage path.\n\n```python\nimport json\nimport os\n\nfrom zeeland import get_default_storage_path\n\n\ndef main():\n storage_path = get_default_storage_path(\"test\")\n metadata_path = os.path.join(storage_path, \"metadata.json\")\n\n metadata = {\"name\": \"test\", \"version\": \"1.0.0\", \"description\": \"Test metadata file\"}\n\n with open(metadata_path, \"w\") as f:\n json.dump(metadata, f, indent=4)\n\n print(f\"Created metadata file at: {metadata_path}\")\n with open(metadata_path, \"r\") as f:\n print(\"Content:\")\n print(json.dumps(json.load(f), indent=4))\n\n\nif __name__ == \"__main__\":\n main()\n```\n\nThe metadata file will be saved in the default storage path, which is `~/.zeeland/test/metadata.json`.\n\nSingleton usage\n\n```python\nfrom zeeland import Singleton, singleton\n\n\n@singleton()\nclass TestSingleton:\n pass\n\n\ninstance1 = TestSingleton()\ninstance2 = TestSingleton()\n\nassert instance1 is instance2\n\n\nclass TestSingletonWithArgs(metaclass=Singleton):\n def __init__(self, value):\n self.value = value\n\n\ninstance1 = TestSingletonWithArgs(\"test1\")\ninstance2 = TestSingletonWithArgs(\"test2\")\n\nassert instance1 is instance2\nassert instance1.value == \"test1\"\n```\n\nLogger usage\n\n```python\nfrom zeeland import Logger\n\nlogger = Logger(\"test_framework\")\nlogger.info(\"Hello, Zeeland!\")\n```\n\nThen you can see the log file in the default storage path. In this case, it is `~/.zeeland/test_framework/logs/{current_date}.log`.\n\n### Makefile usage\n\n[`Makefile`](https://github.com/Undertone0809/zeeland/blob/main/Makefile) contains a lot of functions for faster development.\n\n<details>\n<summary>Install all dependencies and pre-commit hooks</summary>\n<p>\n\nInstall requirements:\n\n```bash\nmake install\n```\n\nPre-commit hooks coulb be installed after `git init` via\n\n```bash\nmake pre-commit-install\n```\n\n</p>\n</details>\n\n<details>\n<summary>Codestyle and type checks</summary>\n<p>\n\nAutomatic formatting uses `ruff`.\n\n```bash\nmake format\n```\n\nCodestyle checks only, without rewriting files:\n\n```bash\nmake check-codestyle\n```\n\n> Note: `check-codestyle` uses `ruff` and `darglint` library\n\n</p>\n</details>\n\n<details>\n<summary>Code security</summary>\n<p>\n\n> If this command is not selected during installation, it cannnot be used.\n\n```bash\nmake check-safety\n```\n\nThis command launches `Poetry` integrity checks as well as identifies security issues with `Safety` and `Bandit`.\n\n```bash\nmake check-safety\n```\n\n</p>\n</details>\n\n<details>\n<summary>Tests with coverage badges</summary>\n<p>\n\nRun `pytest`\n\n```bash\nmake test\n```\n\n</p>\n</details>\n\n<details>\n<summary>All linters</summary>\n<p>\n\nOf course there is a command to run all linters in one:\n\n```bash\nmake lint\n```\n\nthe same as:\n\n```bash\nmake check-codestyle && make test && make check-safety\n```\n\n</p>\n</details>\n\n<details>\n<summary>Docker</summary>\n<p>\n\n```bash\nmake docker-build\n```\n\nwhich is equivalent to:\n\n```bash\nmake docker-build VERSION=latest\n```\n\nRemove docker image with\n\n```bash\nmake docker-remove\n```\n\nMore information [about docker](https://github.com/Undertone0809/python-package-template/tree/main/%7B%7B%20cookiecutter.project_name%20%7D%7D/docker).\n\n</p>\n</details>\n\n<details>\n<summary>Cleanup</summary>\n<p>\nDelete pycache files\n\n```bash\nmake pycache-remove\n```\n\nRemove package build\n\n```bash\nmake build-remove\n```\n\nDelete .DS_STORE files\n\n```bash\nmake dsstore-remove\n```\n\nRemove .mypycache\n\n```bash\nmake mypycache-remove\n```\n\nOr to remove all above run:\n\n```bash\nmake cleanup\n```\n\n</p>\n</details>\n\n## \ud83d\udee1 License\n\n[](https://github.com/Undertone0809/zeeland/blob/main/LICENSE)\n\nThis project is licensed under the terms of the `MIT` license. See [LICENSE](https://github.com/Undertone0809/zeeland/blob/main/LICENSE) for more details.\n\n## \ud83d\udcc3 Citation\n\n```bibtex\n@misc{zeeland,\n author = {zeeland},\n title = {zeeland frameworks core infra},\n year = {2024},\n publisher = {GitHub},\n journal = {GitHub repository},\n howpublished = {\\url{https://github.com/Undertone0809/zeeland}}\n}\n```\n\n## Credits [](https://github.com/Undertone0809/python-package-template)\n\nThis project was generated with [P3G](https://github.com/Undertone0809/P3G)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "zeeland frameworks core infra",
"version": "0.3.0",
"project_urls": {
"Homepage": "https://github.com/Undertone0809/zeeland",
"Repository": "https://github.com/Undertone0809/zeeland"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "fe02a6c283c1839350714c442bf1a2e381dfef817bd3b842342cbeb93dc3e26d",
"md5": "473ecc998002098fc4353c8dfbcd1224",
"sha256": "32c4e5b0d2a088f1ef7845d986bf46074c5e67aab214e6c22cd812e91eb61d11"
},
"downloads": -1,
"filename": "zeeland-0.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "473ecc998002098fc4353c8dfbcd1224",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.8",
"size": 7106,
"upload_time": "2024-11-07T11:29:24",
"upload_time_iso_8601": "2024-11-07T11:29:24.107611Z",
"url": "https://files.pythonhosted.org/packages/fe/02/a6c283c1839350714c442bf1a2e381dfef817bd3b842342cbeb93dc3e26d/zeeland-0.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e809c89a97de342dc3b7ce2e321f05fc654ba7f41dee74797365bfd1eb00381f",
"md5": "6b885047bd6d57423bdae0542a524167",
"sha256": "0305a57caf61080de47b701eadf6eb6dd6f1175f394c8af422ed8040bee4930b"
},
"downloads": -1,
"filename": "zeeland-0.3.0.tar.gz",
"has_sig": false,
"md5_digest": "6b885047bd6d57423bdae0542a524167",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.8",
"size": 6689,
"upload_time": "2024-11-07T11:29:25",
"upload_time_iso_8601": "2024-11-07T11:29:25.718852Z",
"url": "https://files.pythonhosted.org/packages/e8/09/c89a97de342dc3b7ce2e321f05fc654ba7f41dee74797365bfd1eb00381f/zeeland-0.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-07 11:29:25",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Undertone0809",
"github_project": "zeeland",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "zeeland"
}
JSON
