Metadata-Version: 2.4
Name: forktex-core
Version: 0.2.3
Summary: Shared async PostgreSQL (asyncpg + SQLAlchemy 2) and Redis primitives for the ForkTex ecosystem
License-Expression: AGPL-3.0-only
License-File: LICENSE
License-File: NOTICE
Author: FORKTEX
Author-email: info@forktex.com
Requires-Python: >=3.12
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Database
Classifier: Topic :: Database :: Database Engines/Servers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Dist: asyncpg (>=0.29)
Requires-Dist: pydantic (>=2.0)
Requires-Dist: redis[hiredis] (>=5.0)
Requires-Dist: sqlalchemy[asyncio] (>=2.0)
Project-URL: Bug Tracker, https://github.com/forktex/core-py/issues
Project-URL: Homepage, https://forktex.com
Project-URL: Repository, https://github.com/forktex/core-py
Description-Content-Type: text/markdown

# forktex-core

[![PyPI](https://img.shields.io/pypi/v/forktex-core.svg)](https://pypi.org/project/forktex-core/)
[![Python](https://img.shields.io/pypi/pyversions/forktex-core.svg)](https://pypi.org/project/forktex-core/)
[![License](https://img.shields.io/pypi/l/forktex-core.svg)](https://github.com/forktex/core-py/blob/master/LICENSE)

Shared async PostgreSQL (asyncpg + SQLAlchemy 2) and Redis primitives for the [ForkTex](https://forktex.com) ecosystem.

`forktex-core` is the foundation library every ForkTex Python service depends on. It owns the async SQLAlchemy engine, session helpers, ORM mixins, and Redis caching primitives, so individual services don't reinvent connection management.

## Install

```bash
pip install forktex-core
```

PostgreSQL (asyncpg + SQLAlchemy 2) and Redis (hiredis) are both included by default — no optional extras to remember. **Requires Python 3.12+.**

## Quick Start

### PostgreSQL

```python
from forktex_core.psql import (
    init_engine, close_engine, get_session,
    BaseDBModel, TimestampMixin, AuditMixin,
)

# Initialize once in your app's lifespan
init_engine("postgresql+asyncpg://user:pass@localhost/db")

# Use a session anywhere
async with get_session() as session:
    user = await session.get(User, user_id)
```

Tunable engine kwargs are passed straight through to `create_async_engine`:

```python
init_engine(
    "postgresql+asyncpg://user:pass@host/db",
    pool_size=20,
    max_overflow=10,
    pool_pre_ping=True,
)
```

### Redis

```python
from forktex_core.redis import init, close, cached

await init("redis://localhost:6379/0")

@cached(ttl=300)
async def get_profile(user_id: str):
    ...
```

## What's in the package

| Module | Responsibility |
|--------|---------------|
| `forktex_core.psql.connection` | `init_engine` / `close_engine` / `get_session` lifecycle |
| `forktex_core.psql.models` | `BaseDBModel`, `TimestampMixin`, `AuditMixin` |
| `forktex_core.psql.crud` | Generic async CRUD helpers over SQLAlchemy 2 |
| `forktex_core.redis.connection` | `init` / `close` / `get_client` for the shared Redis pool |
| `forktex_core.redis.ops` | Typed get / set / delete / incr / mget operations |
| `forktex_core.redis.decorators` | `@cached(ttl=...)` for transparent function caching |
| `forktex_core.redis.namespaces` | Key namespacing helpers |

Consumed as a runtime dependency by `forktex-cloud-api`, `forktex-intelligence-api`, and any future ForkTex Python service that needs PostgreSQL or Redis.

## Configuration

Connection strings and pool settings are passed in by the host service at `init_engine` / `init` time — `forktex-core` does not read environment variables directly. Each consuming service decides its own configuration source (env vars, secrets manager, manifest, etc.).

## Development

The root [`Makefile`](Makefile) is generated by `forktex fsd makefile sync` from [`forktex.json`](forktex.json) — do not hand-edit.

```bash
make help              # list every available target
make deps              # editable install
make format            # ruff format
make lint              # ruff check
make test              # pytest tests/
make build             # python3 -m build → dist/
make ci                # format-check + lint + license-check + audit + test + build
make clean             # remove caches and dist/
```

`make ci` is the single command that gates a publish: it format-checks, lints, verifies dual-license headers across every source file, audits dependencies for known CVEs, runs the test suite, and builds the wheel + sdist with `twine check`.

`make start` / `make stop` / `make logs` are intentional no-ops — `forktex-core` is a library, there is nothing to run.

### License headers

Every source file carries the AGPL-3.0 + Commercial dual-license SPDX header, applied idempotently via:

```bash
make license-check    # CI gate — fails if any source file is missing the header
make license-fix      # add or refresh headers across src/, tests/, scripts/
make license-strip    # remove headers (used before license-model changes)
```

## FSD Self-Description

This repo follows the [ForkTex Standard Delivery (FSD)](https://github.com/forktex/forktex-python) shape:

- root manifest: [`forktex.json`](forktex.json)
- profile: `workspace/python-monorepo`
- target maturity: `L3`
- single publishable package: `forktex-core` at path `.`

Re-validate locally with:

```bash
forktex fsd --project-dir . check
forktex arch discover --project-dir . --output-dir /tmp/arch-corepy
```

## License

Dual-licensed — **AGPL-3.0-or-later** for open-source use, **commercial** for everything else (proprietary products, SaaS without source release, redistribution in closed-source form). See [`LICENSE`](LICENSE) and [`NOTICE`](NOTICE) for the full terms.

Commercial licensing inquiries: info@forktex.com.

The 1.0.0 release on PyPI remains under MIT; from **0.2.3** onwards the package ships AGPL-3.0+Commercial.

