{"id":43610387,"url":"https://github.com/ttwshell/zodiaccore-py","last_synced_at":"2026-03-06T12:04:21.098Z","repository":{"id":336413889,"uuid":"1149535762","full_name":"TTWShell/ZodiacCore-Py","owner":"TTWShell","description":null,"archived":false,"fork":false,"pushed_at":"2026-03-03T02:55:29.000Z","size":1500,"stargazers_count":3,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-03-03T06:22:39.960Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://ttwshell.github.io/ZodiacCore-Py/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/TTWShell.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-04T08:19:00.000Z","updated_at":"2026-03-03T02:54:20.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/TTWShell/ZodiacCore-Py","commit_stats":null,"previous_names":["ttwshell/zodiaccore-py"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/TTWShell/ZodiacCore-Py","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TTWShell%2FZodiacCore-Py","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TTWShell%2FZodiacCore-Py/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TTWShell%2FZodiacCore-Py/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TTWShell%2FZodiacCore-Py/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TTWShell","download_url":"https://codeload.github.com/TTWShell/ZodiacCore-Py/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TTWShell%2FZodiacCore-Py/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30175918,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-06T11:48:51.886Z","status":"ssl_error","status_checked_at":"2026-03-06T11:48:51.460Z","response_time":250,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":[],"created_at":"2026-02-04T11:44:41.263Z","updated_at":"2026-03-06T12:04:21.054Z","avatar_url":"https://github.com/TTWShell.png","language":"Python","readme":"# ZodiacCore-Py\n\n[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/)\n[![FastAPI](https://img.shields.io/badge/FastAPI-0.109+-009688.svg)](https://fastapi.tiangolo.com/)\n[![Pydantic v2](https://img.shields.io/badge/Pydantic-v2-e92063.svg)](https://docs.pydantic.dev/)\n[![Async First](https://img.shields.io/badge/Async-First-purple.svg)](https://docs.python.org/3/library/asyncio.html)\n[![Documentation](https://img.shields.io/badge/docs-latest-brightgreen)](https://ttwshell.github.io/ZodiacCore-Py/)\n[![PyPI version](https://img.shields.io/pypi/v/zodiac-core.svg)](https://pypi.org/project/zodiac-core/)\n[![codecov](https://codecov.io/github/TTWShell/ZodiacCore-Py/graph/badge.svg?token=ZVSMW38NIA)](https://codecov.io/github/TTWShell/ZodiacCore-Py)\n[![License](https://img.shields.io/:license-mit-blue.svg)](https://opensource.org/licenses/MIT)\n\n\u003e **The opinionated, async-first core library for modern Python web services.**\n\n## 🎯 Mission\n\n**Stop copy-pasting your infrastructure code.**\n\nEvery new FastAPI project starts the same way: setting up logging, error handling, database sessions, pagination... It's tedious, error-prone, and inconsistent across teams.\n\n**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.\n\n## ✨ Key Features\n\n*   **🔍 Observability First**: Built-in JSON structured logging with **Trace ID** injection across the entire request lifecycle (Middleware → Context → Log).\n*   **🛡️ Robust Error Handling**: Centralized exception handlers that map `ZodiacException` to standard HTTP 4xx/5xx JSON responses.\n*   **💾 Database Abstraction**: Async SQLAlchemy session management and `BaseSQLRepository` with pagination helpers (`paginate_query`).\n*   **🎁 Standard Response Wrapper**: Automatic wrapping of API responses into `code` / `data` / `message` via `APIRouter`.\n*   **📄 Standard Pagination**: `PageParams` and `PagedResponse[T]` with repository integration.\n*   **⚡ Async Ready**: Python 3.12+ async/await from the ground up.\n*   **⌨️ zodiac CLI**: Scaffold a 3-tier FastAPI project (DI, routers, config) with one command.\n\n## 📦 Quick Install\n\n| Use case | Install |\n|----------|--------|\n| **Library only** (use in your app) | `uv add zodiac-core` |\n| **Library + CLI** (scaffold new projects) | `uv add \"zodiac-core[zodiac]\"` |\n\nExtras (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.\n\n---\n\n## 🚀 Two ways to use ZodiacCore\n\n### 1. Scaffolding (fastest start)\n\nUse the **zodiac** CLI to generate a full project: 3-tier architecture, dependency injection, config, and tests.\n\n\u003e **Note**: `dfd-service` below is the name of the new project you want to create; replace it with your own.\n\n```bash\nmkdir dfd-service\ncd dfd-service\nuv init --python 3.12\n\nuv add \"zodiac-core[zodiac,sql]\"\nzodiac new dfd-service --tpl standard-3tier -o .. --force\n\nuv add \"fastapi[standard]\" --dev\nuv run fastapi run --reload\n```\n\nOpen `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/).\n\n### 2. Library (use in your own app)\n\nAdd **zodiac-core** to an existing FastAPI project and wire up logging, middleware, and response wrapping.\n\n```python\nfrom fastapi import FastAPI\nfrom zodiac_core.routing import APIRouter\nfrom zodiac_core.logging import setup_loguru\nfrom zodiac_core.middleware import register_middleware\nfrom zodiac_core.exception_handlers import register_exception_handlers\nfrom zodiac_core.exceptions import NotFoundException\nfrom loguru import logger\n\nsetup_loguru(level=\"INFO\", json_format=True)\napp = FastAPI()\nregister_middleware(app)\nregister_exception_handlers(app)\n\nrouter = APIRouter()\n@router.get(\"/items/{item_id}\")\nasync def read_item(item_id: int):\n    logger.info(f\"request: item_id={item_id}\")\n    if item_id == 0:\n        raise NotFoundException(message=\"Item not found\")\n    return {\"item_id\": item_id}\napp.include_router(router)\n```\n\n## 📚 Documentation\n\n- **Online**: [https://ttwshell.github.io/ZodiacCore-Py/](https://ttwshell.github.io/ZodiacCore-Py/) (multiple versions via release).\n- **Local**: `make docs-serve` (sources in `docs/`).\n\n## 🤝 Contributing\n\nContributions are welcome. Please read [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and workflow.\n\n## 📄 License\n\nThis project is licensed under the [MIT License](LICENSE).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fttwshell%2Fzodiaccore-py","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fttwshell%2Fzodiaccore-py","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fttwshell%2Fzodiaccore-py/lists"}