Metadata-Version: 2.4
Name: forktex-core
Version: 0.1.1
Summary: Shared database (PostgreSQL) and cache (Redis) primitives for the FORKTEX ecosystem
Project-URL: Homepage, https://forktex.com
Project-URL: Repository, https://github.com/forktex/core-py
Project-URL: Bug Tracker, https://github.com/forktex/core-py/issues
Author-email: ForkTex <info@forktex.com>
License: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Database
Classifier: Topic :: Database :: Database Engines/Servers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: asyncpg>=0.29
Requires-Dist: pydantic>=2.0
Requires-Dist: redis[hiredis]>=5.0
Requires-Dist: sqlalchemy[asyncio]>=2.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.7.0; extra == 'dev'
Description-Content-Type: text/markdown

# forktex-core

Shared PostgreSQL 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.

## What This Repo Ships

This repo ships exactly one package: **`forktex-core`** on PyPI.

It is consumed as a runtime dependency by:

- `forktex-cloud-api` (cloud platform server) — `from forktex_core.psql.connection import init_engine, get_session`
- `forktex-intelligence-api` (intelligence platform server) — same
- any future ForkTex Python service that needs PostgreSQL or Redis

## Install

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

PostgreSQL (asyncpg + SQLAlchemy 2) and Redis (hiredis) are both included by default — there are no optional extras you need to remember.

## 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):
    ...
```

## Operate

The root [`Makefile`](Makefile) is generated by `forktex fsd makefile sync`. Do not hand-edit it.

```bash
make help              # list every available target
make deps              # pip install -e .
make format            # ruff format
make lint              # ruff check
make test              # pytest tests/
make build             # python3 -m build → dist/
make publish           # twine upload dist/*
make clean             # remove caches and dist/
make ci                # format-check + lint + test
```

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

## FSD Self-Description

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

- root manifest: [`forktex.json`](forktex.json)
- manifest schema version: `manifestVersion = 1.0.0`
- FSD contract version: `fsd.version = 1.0.0`
- 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
```

## Repository Layout

```text
core-py/
├── forktex.json
├── Makefile
├── pyproject.toml
├── README.md
└── src/forktex_core/
    ├── psql/        # async SQLAlchemy engine, sessions, ORM mixins
    └── redis/       # connection, namespaces, ops, decorators
```

## License

MIT — see [`LICENSE`](LICENSE).
