zodiac-core 0.2.0__tar.gz

zodiac_core-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Legolas Bloom
+
+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.

zodiac_core-0.2.0/PKG-INFO

@@ -0,0 +1,127 @@
+Metadata-Version: 2.4
+Name: zodiac-core
+Version: 0.2.0
+Summary: ZodiacCore-Py: A high-performance core library for modern Python web services.
+License-Expression: MIT
+Keywords: fastapi,async,web,logging,middleware,sqlalchemy,pydantic
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
+Requires-Python: <3.15,>=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi>=0.128.0
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: loguru>=0.7.2
+Requires-Dist: httpx>=0.28.1
+Provides-Extra: zodiac
+Requires-Dist: click>=8.0; extra == "zodiac"
+Requires-Dist: jinja2>=3.0; extra == "zodiac"
+Provides-Extra: sql
+Requires-Dist: sqlmodel>=0.0.31; extra == "sql"
+Provides-Extra: mongo
+Requires-Dist: motor>=3.3.0; extra == "mongo"
+Dynamic: license-file
+
+# ZodiacCore-Py
+
+<p align="center">
+  <img src="https://img.shields.io/badge/Python-3.12+-blue.svg?style=for-the-badge&logo=python&logoColor=white" alt="Python 3.12+">
+  <img src="https://img.shields.io/badge/FastAPI-0.109+-009688.svg?style=for-the-badge&logo=fastapi&logoColor=white" alt="FastAPI">
+  <img src="https://img.shields.io/badge/Pydantic-v2-e92063.svg?style=for-the-badge&logo=pydantic&logoColor=white" alt="Pydantic v2">
+  <img src="https://img.shields.io/badge/Async-First-purple.svg?style=for-the-badge" alt="Async First">
+  <img src="https://img.shields.io/badge/License-MIT-green.svg?style=for-the-badge" alt="MIT License">
+</p>
+
+> **The opinionated, async-first core library for modern Python web services.**
+
+## 🎯 Mission
+
+**Stop copy-pasting your infrastructure code.**
+
+Every new FastAPI project starts the same way: setting up logging, error handling, database sessions, pagination... It's tedious, error-prone, and inconsistent across teams.
+
+**ZodiacCore** solves this in two ways: a **library** you drop into any FastAPI app, and a **CLI** that scaffolds a full project so you can start coding in seconds.
+
+## ✨ Key Features
+
+*   **🔍 Observability First**: Built-in JSON structured logging with **Trace ID** injection across the entire request lifecycle (Middleware → Context → Log).
+*   **🛡️ Robust Error Handling**: Centralized exception handlers that map `ZodiacException` to standard HTTP 4xx/5xx JSON responses.
+*   **💾 Database Abstraction**: Async SQLAlchemy session management and `BaseSQLRepository` with pagination helpers (`paginate_query`).
+*   **🎁 Standard Response Wrapper**: Automatic wrapping of API responses into `code` / `data` / `message` via `APIRouter`.
+*   **📄 Standard Pagination**: `PageParams` and `PagedResponse[T]` with repository integration.
+*   **⚡ Async Ready**: Python 3.12+ async/await from the ground up.
+*   **⌨️ zodiac CLI**: Scaffold a 3-tier FastAPI project (DI, routers, config) with one command.
+
+## 📦 Quick Install
+
+| Use case | Install |
+|----------|--------|
+| **Library only** (use in your app) | `uv add zodiac-core` |
+| **Library + CLI** (scaffold new projects) | `uv add "zodiac-core[zodiac]"` |
+
+Extras (combinable): `zodiac-core[sql]` (SQLModel), `zodiac-core[mongo]` (Motor, helpers planned), `zodiac-core[zodiac]` (CLI). See the [Installation Guide](https://ttwshell.github.io/ZodiacCore-Py/user-guide/installation/) for details.
+
+---
+
+## 🚀 Two ways to use ZodiacCore
+
+### 1. Scaffolding (fastest start)
+
+Use the **zodiac** CLI to generate a full project: 3-tier architecture, dependency injection, config, and tests.
+
+```bash
+uv add "zodiac-core[zodiac]"
+zodiac new my_app --tpl standard-3tier -o ./projects
+cd projects/my_app
+uv sync --extra dev && uv run fastapi run --reload
+```
+
+Open `http://127.0.0.1:8000/docs` and `http://127.0.0.1:8000/api/v1/health`. See [Getting started](https://ttwshell.github.io/ZodiacCore-Py/user-guide/getting-started/) and [CLI docs](https://ttwshell.github.io/ZodiacCore-Py/user-guide/cli/).
+
+### 2. Library (use in your own app)
+
+Add **zodiac-core** to an existing FastAPI project and wire up logging, middleware, and response wrapping.
+
+```python
+from fastapi import FastAPI
+from zodiac_core.routing import APIRouter
+from zodiac_core.logging import setup_loguru
+from zodiac_core.middleware import register_middleware
+from zodiac_core.exception_handlers import register_exception_handlers
+from zodiac_core.exceptions import NotFoundException
+from loguru import logger
+
+setup_loguru(level="INFO", json_format=True)
+app = FastAPI()
+register_middleware(app)
+register_exception_handlers(app)
+
+router = APIRouter()
+@router.get("/items/{item_id}")
+async def read_item(item_id: int):
+    logger.info(f"request: item_id={item_id}")
+    if item_id == 0:
+        raise NotFoundException(message="Item not found")
+    return {"item_id": item_id}
+app.include_router(router)
+```
+
+## 📚 Documentation
+
+- **Online**: [https://ttwshell.github.io/ZodiacCore-Py/](https://ttwshell.github.io/ZodiacCore-Py/) (multiple versions via release).
+- **Local**: `make docs-serve` (sources in `docs/`).
+
+## 🤝 Contributing
+
+Contributions are welcome. Please read [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and workflow.
+
+## 📄 License
+
+This project is licensed under the [MIT License](LICENSE).

zodiac_core-0.2.0/README.md

@@ -0,0 +1,96 @@
+# ZodiacCore-Py
+
+<p align="center">
+  <img src="https://img.shields.io/badge/Python-3.12+-blue.svg?style=for-the-badge&logo=python&logoColor=white" alt="Python 3.12+">
+  <img src="https://img.shields.io/badge/FastAPI-0.109+-009688.svg?style=for-the-badge&logo=fastapi&logoColor=white" alt="FastAPI">
+  <img src="https://img.shields.io/badge/Pydantic-v2-e92063.svg?style=for-the-badge&logo=pydantic&logoColor=white" alt="Pydantic v2">
+  <img src="https://img.shields.io/badge/Async-First-purple.svg?style=for-the-badge" alt="Async First">
+  <img src="https://img.shields.io/badge/License-MIT-green.svg?style=for-the-badge" alt="MIT License">
+</p>
+
+> **The opinionated, async-first core library for modern Python web services.**
+
+## 🎯 Mission
+
+**Stop copy-pasting your infrastructure code.**
+
+Every new FastAPI project starts the same way: setting up logging, error handling, database sessions, pagination... It's tedious, error-prone, and inconsistent across teams.
+
+**ZodiacCore** solves this in two ways: a **library** you drop into any FastAPI app, and a **CLI** that scaffolds a full project so you can start coding in seconds.
+
+## ✨ Key Features
+
+*   **🔍 Observability First**: Built-in JSON structured logging with **Trace ID** injection across the entire request lifecycle (Middleware → Context → Log).
+*   **🛡️ Robust Error Handling**: Centralized exception handlers that map `ZodiacException` to standard HTTP 4xx/5xx JSON responses.
+*   **💾 Database Abstraction**: Async SQLAlchemy session management and `BaseSQLRepository` with pagination helpers (`paginate_query`).
+*   **🎁 Standard Response Wrapper**: Automatic wrapping of API responses into `code` / `data` / `message` via `APIRouter`.
+*   **📄 Standard Pagination**: `PageParams` and `PagedResponse[T]` with repository integration.
+*   **⚡ Async Ready**: Python 3.12+ async/await from the ground up.
+*   **⌨️ zodiac CLI**: Scaffold a 3-tier FastAPI project (DI, routers, config) with one command.
+
+## 📦 Quick Install
+
+| Use case | Install |
+|----------|--------|
+| **Library only** (use in your app) | `uv add zodiac-core` |
+| **Library + CLI** (scaffold new projects) | `uv add "zodiac-core[zodiac]"` |
+
+Extras (combinable): `zodiac-core[sql]` (SQLModel), `zodiac-core[mongo]` (Motor, helpers planned), `zodiac-core[zodiac]` (CLI). See the [Installation Guide](https://ttwshell.github.io/ZodiacCore-Py/user-guide/installation/) for details.
+
+---
+
+## 🚀 Two ways to use ZodiacCore
+
+### 1. Scaffolding (fastest start)
+
+Use the **zodiac** CLI to generate a full project: 3-tier architecture, dependency injection, config, and tests.
+
+```bash
+uv add "zodiac-core[zodiac]"
+zodiac new my_app --tpl standard-3tier -o ./projects
+cd projects/my_app
+uv sync --extra dev && uv run fastapi run --reload
+```
+
+Open `http://127.0.0.1:8000/docs` and `http://127.0.0.1:8000/api/v1/health`. See [Getting started](https://ttwshell.github.io/ZodiacCore-Py/user-guide/getting-started/) and [CLI docs](https://ttwshell.github.io/ZodiacCore-Py/user-guide/cli/).
+
+### 2. Library (use in your own app)
+
+Add **zodiac-core** to an existing FastAPI project and wire up logging, middleware, and response wrapping.
+
+```python
+from fastapi import FastAPI
+from zodiac_core.routing import APIRouter
+from zodiac_core.logging import setup_loguru
+from zodiac_core.middleware import register_middleware
+from zodiac_core.exception_handlers import register_exception_handlers
+from zodiac_core.exceptions import NotFoundException
+from loguru import logger
+
+setup_loguru(level="INFO", json_format=True)
+app = FastAPI()
+register_middleware(app)
+register_exception_handlers(app)
+
+router = APIRouter()
+@router.get("/items/{item_id}")
+async def read_item(item_id: int):
+    logger.info(f"request: item_id={item_id}")
+    if item_id == 0:
+        raise NotFoundException(message="Item not found")
+    return {"item_id": item_id}
+app.include_router(router)
+```
+
+## 📚 Documentation
+
+- **Online**: [https://ttwshell.github.io/ZodiacCore-Py/](https://ttwshell.github.io/ZodiacCore-Py/) (multiple versions via release).
+- **Local**: `make docs-serve` (sources in `docs/`).
+
+## 🤝 Contributing
+
+Contributions are welcome. Please read [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and workflow.
+
+## 📄 License
+
+This project is licensed under the [MIT License](LICENSE).

zodiac_core-0.2.0/pyproject.toml

@@ -0,0 +1,120 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "zodiac-core"
+version = "0.2.0"
+description = "ZodiacCore-Py: A high-performance core library for modern Python web services."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.12,<3.15"
+keywords = [
+    "fastapi",
+    "async",
+    "web",
+    "logging",
+    "middleware",
+    "sqlalchemy",
+    "pydantic",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Framework :: FastAPI",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Internet :: WWW/HTTP :: HTTP Servers",
+]
+dependencies = [
+    "fastapi>=0.128.0",
+    "pydantic>=2.12.5",
+    "loguru>=0.7.2",
+    "httpx>=0.28.1",
+]
+
+[project.optional-dependencies]
+zodiac = ["click>=8.0", "jinja2>=3.0"]
+sql = ["sqlmodel>=0.0.31"]
+mongo = ["motor>=3.3.0"]
+
+[project.scripts]
+zodiac = "zodiac.main:main"
+
+[tool.setuptools.packages.find]
+include = ["zodiac*", "zodiac_core*"]
+exclude = ["tests*", "benchmarks*"]
+
+[tool.setuptools.package-data]
+zodiac = ["templates/**/*.jinja"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py312"
+extend-exclude = [".venv", ".tox", "demo*"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B"]
+ignore = []
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+
+[tool.pytest.ini_options]
+testpaths = ["tests", "benchmarks"]
+addopts = """
+    --cov=zodiac_core
+    --cov=zodiac
+    --cov-report=term-missing
+    --no-cov-on-fail
+    -s -vv
+    -p no:warnings
+    --benchmark-warmup=on
+    --benchmark-warmup-iterations=10
+    --benchmark-min-rounds=5
+"""
+log_cli = true
+markers = ["serial: marks tests that must run serially (e.g., database tests)"]
+
+[tool.coverage.run]
+source = ["zodiac_core", "zodiac"]
+omit = [
+    "*/tests/*",
+    "*/test_*.py",
+    "*/__pycache__/*",
+    "*/.*",
+    "*/benchmarks/*",
+    "*/templates/*",
+    "*/*.jinja",
+]
+
+[dependency-groups]
+dev = [
+    "ruff>=0.9.3",
+    "ipython>=9.9.0",
+    "pytest>=9.0.2",
+    "pytest-asyncio>=1.3.0",
+    "pytest-cov>=7.0.0",
+    "pytest-env>=1.2.0",
+    "pytest-benchmark>=5.1.0",
+    "py-cpuinfo>=9.0.0",
+    "respx>=0.22.0",
+    "psycopg2-binary>=2.9.9",
+    "pymysql>=1.1.0",
+    "aiomysql>=0.2.0",
+    "cryptography>=42.0.0",
+    "asyncpg>=0.31.0",
+    "aiosqlite>=0.22.1",
+    "uvicorn>=0.40.0",
+]
+
+docs = [
+    "mkdocs>=1.6.0",
+    "mkdocs-material>=9.5.0",
+    "mkdocstrings[python]>=0.24.0",
+    "mike>=2.0.0",
+]

zodiac_core-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

zodiac_core-0.2.0/tests/test_build.py

@@ -0,0 +1,71 @@
+"""Tests for verifying package build includes all required files."""
+
+import subprocess
+import zipfile
+from pathlib import Path
+
+
+class TestPackageBuild:
+    """Tests for verifying package build completeness."""
+
+    # Manually verified expected file counts
+    EXPECTED_ZODIAC_FILES = 33  # Python files + template files (.jinja)
+    EXPECTED_ZODIAC_CORE_FILES = 16  # Python files only
+
+    def test_build_includes_all_files(self, tmp_path):
+        """Verify that built package includes all required files from zodiac and zodiac_core."""
+        project_root = Path(__file__).parent.parent
+
+        # 1. Build the package
+        dist_dir = tmp_path / "dist"
+        dist_dir.mkdir()
+
+        result = subprocess.run(
+            ["uv", "build", "--out-dir", str(dist_dir)],
+            cwd=project_root,
+            capture_output=True,
+            text=True,
+        )
+
+        assert result.returncode == 0, f"Build failed: {result.stderr}"
+
+        # 2. Find the built wheel
+        wheel_files = list(dist_dir.glob("*.whl"))
+        assert len(wheel_files) == 1, f"Expected 1 wheel file, found {len(wheel_files)}"
+
+        wheel_path = wheel_files[0]
+
+        # 3. Extract and count files in the wheel (separately for each package)
+        actual_zodiac_files = self._count_wheel_files(wheel_path, "zodiac")
+        actual_zodiac_core_files = self._count_wheel_files(wheel_path, "zodiac_core")
+
+        # 4. Verify counts match manually verified expectations
+        assert actual_zodiac_files == self.EXPECTED_ZODIAC_FILES, (
+            f"zodiac file count mismatch: "
+            f"expected={self.EXPECTED_ZODIAC_FILES} (manually verified), "
+            f"actual={actual_zodiac_files}"
+        )
+        assert actual_zodiac_core_files == self.EXPECTED_ZODIAC_CORE_FILES, (
+            f"zodiac_core file count mismatch: "
+            f"expected={self.EXPECTED_ZODIAC_CORE_FILES} (manually verified), "
+            f"actual={actual_zodiac_core_files}"
+        )
+
+    def _count_wheel_files(self, wheel_path: Path, package_name: str) -> int:
+        """Count files for a specific package in the wheel."""
+        count = 0
+        with zipfile.ZipFile(wheel_path, "r") as wheel:
+            for name in wheel.namelist():
+                # Count files in the package directory
+                if name.startswith(f"{package_name}/") and not name.endswith("/"):
+                    # Exclude metadata files and dist-info
+                    if not any(
+                        excluded in name
+                        for excluded in (
+                            ".egg-info/",
+                            ".dist-info/",
+                            "__pycache__/",
+                        )
+                    ):
+                        count += 1
+        return count

zodiac_core-0.2.0/tests/test_config.py

@@ -0,0 +1,146 @@
+import os
+from types import SimpleNamespace
+
+from loguru import logger
+from pydantic import BaseModel
+
+from zodiac_core import ConfigManagement, Environment
+
+
+def test_get_config_files_base_only(tmp_path):
+    (tmp_path / "app.ini").touch()
+    (tmp_path / "settings.ini").touch()
+
+    # Use 'develop' as target_env
+    files = ConfigManagement.get_config_files([tmp_path], env_var="TEST_ENV", default_env="develop")
+    filenames = [os.path.basename(f) for f in files]
+    assert sorted(filenames) == ["app.ini", "settings.ini"]
+
+
+def test_get_config_files_with_env_override(tmp_path):
+    (tmp_path / "app.ini").touch()
+    (tmp_path / "app.develop.ini").touch()
+    (tmp_path / "app.production.ini").touch()  # Known env, should be skipped silently
+
+    # target_env is 'develop'
+    files = ConfigManagement.get_config_files([tmp_path], env_var="TEST_ENV_2", default_env="develop")
+
+    filenames = [os.path.basename(f) for f in files]
+    assert "app.ini" in filenames
+    assert "app.develop.ini" in filenames
+    assert "app.production.ini" not in filenames
+    assert filenames.index("app.ini") < filenames.index("app.develop.ini")
+
+
+def test_get_config_files_logging_strict_env(tmp_path):
+    # Setup
+    (tmp_path / "app.production.ini").touch()
+    (tmp_path / "app.dev.ini").touch()
+    (tmp_path / "app.test.ini").touch()
+    (tmp_path / "app.weirdo.ini").touch()
+
+    logs = []
+    handler_id = logger.add(logs.append, format="{message}")
+
+    try:
+        # target_env is 'production'
+        ConfigManagement.get_config_files([tmp_path], env_var="TEST_ENV_LOG", default_env="production")
+    finally:
+        logger.remove(handler_id)
+
+    log_messages = [str(log) for log in logs]
+
+    # Check strict matches are NOT logged
+    assert not any("app.production.ini" in m for m in log_messages)
+
+    # Check non-strict or unknown aliases ARE logged
+    assert any("app.dev.ini" in m for m in log_messages)
+    assert any("app.test.ini" in m for m in log_messages)
+    assert any("app.weirdo.ini" in m for m in log_messages)
+
+
+def test_environment_enum_values():
+    assert Environment.DEVELOP == "develop"
+    assert Environment.TESTING == "testing"
+    assert Environment.STAGING == "staging"
+    assert Environment.PRODUCTION == "production"
+    assert len(Environment) == 4
+
+
+def test_provide_config_recursive_list():
+    config_dict = {
+        "services": [
+            {"name": "auth", "port": 8080},
+            {"name": "gateway", "port": 80},
+        ],
+        "meta": {"tags": ["api", "v1"]},
+    }
+    config_obj = ConfigManagement.provide_config(config_dict)
+
+    assert isinstance(config_obj.services[0], SimpleNamespace)
+    assert config_obj.services[0].name == "auth"
+    assert config_obj.services[1].port == 80
+    assert config_obj.meta.tags == ["api", "v1"]
+
+
+def test_get_config_files_complex_filename(tmp_path):
+    # Test file with multiple dots
+    (tmp_path / "my.app.service.develop.ini").touch()
+
+    files = ConfigManagement.get_config_files([tmp_path], env_var="TEST_ENV_COMPLEX", default_env="develop")
+    filenames = [os.path.basename(f) for f in files]
+    assert "my.app.service.develop.ini" in filenames
+
+
+def test_get_config_files_invalid_paths(tmp_path):
+    # Test with non-existent directory
+    invalid_path = tmp_path / "ghost_dir"
+
+    # Should not raise exception, just return empty list or skip
+    files = ConfigManagement.get_config_files([invalid_path], default_env="develop")
+    assert len(files) == 0
+
+
+class DbConfig(BaseModel):
+    host: str
+    port: int = 5432
+
+
+class AppConfig(BaseModel):
+    db: DbConfig
+    debug: bool = False
+
+
+def test_provide_config_with_pydantic_model():
+    """Test provide_config with Pydantic model for type-safe config."""
+    config_dict = {"db": {"host": "localhost", "port": 3306}, "debug": True}
+
+    config = ConfigManagement.provide_config(config_dict, AppConfig)
+
+    assert isinstance(config, AppConfig)
+    assert isinstance(config.db, DbConfig)
+    assert config.db.host == "localhost"
+    assert config.db.port == 3306
+    assert config.debug is True
+
+
+def test_provide_config_pydantic_model_with_defaults():
+    """Test that Pydantic model defaults are applied."""
+    config_dict = {"db": {"host": "localhost"}}  # port and debug use defaults
+
+    config = ConfigManagement.provide_config(config_dict, AppConfig)
+
+    assert config.db.port == 5432  # default
+    assert config.debug is False  # default
+
+
+def test_provide_config_empty_with_model():
+    """Test provide_config with empty dict and model that has all defaults."""
+
+    class AllDefaultConfig(BaseModel):
+        name: str = "app"
+        version: str = "1.0.0"
+
+    config = ConfigManagement.provide_config({}, AllDefaultConfig)
+    assert config.name == "app"
+    assert config.version == "1.0.0"