forktex-core 0.2.3

Shared async PostgreSQL (asyncpg + SQLAlchemy 2) and Redis primitives for the ForkTex ecosystem

forktex-core

Shared async PostgreSQL (asyncpg + SQLAlchemy 2) and Redis primitives for the ForkTex 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

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

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:

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

Redis

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 is generated by forktex fsd makefile sync from forktex.json — do not hand-edit.

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:

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) shape:

• root manifest: forktex.json
• profile: workspace/python-monorepo
• target maturity: L3
• single publishable package: forktex-core at path .

Re-validate locally with:

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 and NOTICE for the full terms.

Commercial licensing inquiries: [e-mail].

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