Metadata-Version: 2.4
Name: fastapi-zcore-framework
Version: 0.1.0b5
Summary: An opinionated architectural framework built on top of FastAPI that provides production-ready architecture, repository abstractions, scoped dependency injection, a secure dynamic query engine, and consistent transaction management.
Project-URL: Homepage, https://github.com/fastapi-zcore-framework/zcore
Project-URL: Repository, https://github.com/fastapi-zcore-framework/zcore
Project-URL: Documentation, https://fastapi-zcore-framework.github.io/zcore
Project-URL: Bug Tracker, https://github.com/fastapi-zcore-framework/zcore/issues
Author-email: Ali Alf Ostovar <240363843+alialfostovar@users.noreply.github.com>
License: Apache License 2.0
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: >=3.11
Requires-Dist: anyio>=4.3.0
Requires-Dist: fastapi>=0.110.0
Requires-Dist: jsonschema>=4.21.0
Requires-Dist: pydantic-settings>=2.2.0
Requires-Dist: pydantic>=2.6.0
Requires-Dist: python-multipart>=0.0.9
Requires-Dist: structlog>=24.1.0
Requires-Dist: uvicorn>=0.22.0
Provides-Extra: all
Requires-Dist: aiofiles>=23.2.1; extra == 'all'
Requires-Dist: aiosqlite>=0.20.0; extra == 'all'
Requires-Dist: argon2-cffi>=23.1.0; extra == 'all'
Requires-Dist: pyjwt>=2.8.0; extra == 'all'
Requires-Dist: redis>=5.0.3; extra == 'all'
Requires-Dist: sqlalchemy[asyncio]>=2.0.28; extra == 'all'
Provides-Extra: cache
Requires-Dist: redis>=5.0.3; extra == 'cache'
Provides-Extra: crypto
Requires-Dist: argon2-cffi>=23.1.0; extra == 'crypto'
Requires-Dist: pyjwt>=2.8.0; extra == 'crypto'
Provides-Extra: db
Requires-Dist: aiosqlite>=0.20.0; extra == 'db'
Requires-Dist: sqlalchemy[asyncio]>=2.0.28; extra == 'db'
Provides-Extra: docs
Requires-Dist: mkdocs-gen-files>=0.5.0; extra == 'docs'
Requires-Dist: mkdocs-literate-nav>=0.6.0; extra == 'docs'
Requires-Dist: mkdocs-material>=9.5.0; extra == 'docs'
Requires-Dist: mkdocs-section-index>=0.3.0; extra == 'docs'
Requires-Dist: mkdocs>=1.5.0; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.24.0; extra == 'docs'
Provides-Extra: redis
Requires-Dist: redis>=5.0.3; extra == 'redis'
Provides-Extra: storage
Requires-Dist: aiofiles>=23.2.1; extra == 'storage'
Description-Content-Type: text/markdown

<p align="center">
  <img src="https://raw.githubusercontent.com/fastapi-zcore-framework/zcore/master/docs/assets/banner.png" alt="ZCore Logo" width="600">
  <br>
  <strong>A modest and practical architectural layer built on top of FastAPI.</strong>
</p>

<p align="center">
  <a href="https://github.com/fastapi-zcore-framework/zcore/blob/master/LICENSE">
  <img src="https://img.shields.io/github/license/fastapi-zcore-framework/zcore" alt="License"></a>
  <a href="https://pypi.org/project/fastapi-zcore-framework/"><img src="https://img.shields.io/pypi/v/fastapi-zcore-framework" alt="PyPI"></a>
  <a href="https://github.com/fastapi-zcore-framework/zcore/actions"><img src="https://img.shields.io/github/actions/workflow/status/fastapi-zcore-framework/zcore/publish.yml" alt="Build Status"></a>
</p>

---

## What is ZCore?

ZCore is not a replacement for FastAPI; it is a modest and practical architectural layer built on top of it. While FastAPI provides the high-performance engine for handling HTTP requests, ZCore provides the "chassis"—a structured environment that solves common challenges in medium-to-large scale applications such as dependency management, transaction integrity, and data leakage prevention.

The framework focuses on **Engineered Simplicity**. It abstracts complex patterns like the *Unit of Work* and *Scoped Inversion of Control* into intuitive interfaces, allowing you to focus on your domain logic while the framework ensures that your database transactions are atomic and your sensitive data remains restricted based on the execution context.

---

## Why Choose ZCore?

ZCore was designed to bridge the gap between "writing an endpoint" and "building a maintainable system."

| Feature | Standard FastAPI Challenge | The ZCore Approach |
| :--- | :--- | :--- |
| **Dependency Injection** | Manual wiring and complex `Depends` chains. | Automated **Scoped IoC** with constructor injection. |
| **Data Security** | Manual filtering of Pydantic models for different users. | Context-aware **Response Pruning** via `ResponseProjector`. |
| **Transactions** | Scatterred `.commit()` calls leading to partial failures. | Centralized **Unit of Work** (UOW) for atomic operations. |
| **Project Structure** | Inconsistent layouts across different teams. | Modular **Plugin System** and standardized CLI scaffolding. |
| **Search & Filter** | Writing repetitive boilerplate for every query. | A secure, dynamic **Search Engine** with depth-limit protection. |

---

## The Request Lifecycle

Understanding how a request travels through ZCore is key to mastering its architecture. The following diagram illustrates the automated orchestration from the moment a request hits the server to the final pruned response.

<p align="center">
  <img src="https://raw.githubusercontent.com/fastapi-zcore-framework/zcore/master/docs/assets/request-lifecycle.png" alt="ZCore Request Lifecycle" width="700">
</p>

---

## ⚡ Quick Start

### 1. Installation
Set up a clean virtual environment and install ZCore with all optional dependencies:

```bash
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install fastapi-zcore-framework[all]
```

### 2. Scaffold a Project
Initialize your project and generate a structured domain module using our command-line utility:

```bash
# Initialize project workspace
zc init product_api
cd product_api

# Scaffold a domain app with boilerplate templates
zc startapp products -t
```

### 3. Run the Development Server
Launch the local Uvicorn development server:

```bash
zc run
```

---

## 📚 Core Pillars at a Glance

*   **⚡ Scoped IoC Container:** Manage object lifecycles (Singleton, Transient, or Scoped) with ease. Scoped dependencies are automatically cleared at the end of every HTTP request to prevent memory pollution.
*   **🛡️ Secure Search Engine:** A dynamic query builder that supports nested filters and eager-loading, while automatically blocking access to restricted database columns based on security policies.
*   **🔗 Unit of Work (UOW):** Ensures that business operations succeed or fail as a single unit. It coordinates database flushes and delays event dispatching until the transaction is successfully committed.
*   **🏗️ Modular Plugin System:** Organize your application into decoupled domains. Each plugin manages its own lifecycle hooks (`on_startup`, `on_shutdown`) and can declare dependencies on other plugins.

---

## 📖 Documentation & Learning

To explore the full capabilities of ZCore, please refer to our online documentation:

> ℹ️ **NOTE:** **[Getting Started Guide]** - Step-by-step tutorial to build your first service.

> 💡 **TIP:** **[Architectural Concepts]** - Understand the inner mechanics of our Scoped DI, UOW, and the Core Kernel.

> ⚠️ **IMPORTANT:** For production environments, remember to generate a secure secret key using the `zc gensecret` CLI command and update your `.env` configuration file.

---

<p align="center">
    <small>ZCore is licensed under the Apache License 2.0. Built with ☕ and architectural rigor.</small>
</p>
