pgsqlasync2fast-fastapi 0.3.0__tar.gz → 0.3.1__tar.gz

{pgsqlasync2fast_fastapi-0.3.0/src/pgsqlasync2fast_fastapi.egg-info → pgsqlasync2fast_fastapi-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pgsqlasync2fast-fastapi
-Version: 0.3.0
+Version: 0.3.1
 Summary: Simple and fast PostgreSQL async module for FastAPI with multi-database support
 Author-email: Angel Daniel Sanchez Castillo <angeldaniel.sanchezcastillo@gmail.com>
 License: MIT License
@@ -56,6 +56,8 @@ Dynamic: license-file
 
 Simple and fast PostgreSQL async module for FastAPI with multi-database support and automatic database creation.
 
+> 📖 **Conventions reference**: this package follows the [2fast-handbook](https://github.com/AngelDanielSanchezCastillo/2fast-handbook) for ecosystem conventions (structure, versioning, README, commits, release).
+
 ## Features
 
 - ✅ **Multiple Database Connections**: Configure and manage multiple PostgreSQL databases

{pgsqlasync2fast_fastapi-0.3.0 → pgsqlasync2fast_fastapi-0.3.1}/README.md

@@ -2,6 +2,8 @@
 
 Simple and fast PostgreSQL async module for FastAPI with multi-database support and automatic database creation.
 
+> 📖 **Conventions reference**: this package follows the [2fast-handbook](https://github.com/AngelDanielSanchezCastillo/2fast-handbook) for ecosystem conventions (structure, versioning, README, commits, release).
+
 ## Features
 
 - ✅ **Multiple Database Connections**: Configure and manage multiple PostgreSQL databases

{pgsqlasync2fast_fastapi-0.3.0 → pgsqlasync2fast_fastapi-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pgsqlasync2fast-fastapi"
-version = "0.3.0"
+dynamic = ["version"]
 description = "Simple and fast PostgreSQL async module for FastAPI with multi-database support"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -64,6 +64,15 @@ package-dir = {"" = "src"}
 where = ["src"]
 include = ["pgsqlasync2fast_fastapi*"]
 
+# Single source of truth for the version: __version__.py
+[tool.setuptools.dynamic]
+version = {attr = "pgsqlasync2fast_fastapi.__version__.__version__"}
+
+[tool.setuptools.package-data]
+pgsqlasync2fast_fastapi = [
+    "skills/*.md",
+]
+
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 python_files = ["test_*.py"]

pgsqlasync2fast_fastapi-0.3.1/src/pgsqlasync2fast_fastapi/__version__.py

@@ -0,0 +1 @@
+__version__ = "0.3.1"

pgsqlasync2fast_fastapi-0.3.1/src/pgsqlasync2fast_fastapi/skills/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: pgsqlasync2fast-fastapi
+description: "Trigger: working on or with pgsqlasync2fast-fastapi. Multi-database async engine manager for FastAPI: DB_CONNECTIONS config, get_db_session deps, seeder orchestrator, tenant engines. Prevails over the 2fast-handbook base skill for this package."
+license: MIT
+metadata:
+  author: AngelDanielSanchezCastillo
+  version: "1.0"
+---
+
+## Purpose
+
+Connection-management foundation of the 2fast stack: multiple PostgreSQL
+engines/session factories keyed by connection name (`default`, `auth`,
+`business`, `tenant_{id}`), lifecycle, and the generic seeder orchestrator.
+
+## Import quirk
+
+- Dist `pgsqlasync2fast-fastapi` → import `pgsqlasync2fast_fastapi` (dash→underscore only).
+- Two "default connection" paths DISAGREE: `get_db_session`/`get_db_engine` default `connection_name="default"` (literal string), while `DatabaseManager.get_engine`/`get_connection` fall back `None → config.default_connection`. Never rely on `"default"`: name your primary `default` or always pass an explicit name via `functools.partial` (oauth2fast pattern: `get_auth_session = partial(get_db_session, connection_name="auth")`).
+
+## Public API
+
+- `get_manager(config=None)` — **global singleton**; honors a custom config only on its FIRST call. `get_db_manager` (FastAPI dep) always injects the module `settings`, so per-app config via the dep path is impossible.
+- `get_db_engine(connection_name="default")`, `get_db_session(connection_name="default")` (yields session; commits on success, rolls back on exception, closes in finally).
+- `startup_database()` — **NOT lazy**: eagerly creates and health-checks EVERY configured connection. README's "lazy loading" is wrong.
+- `shutdown_database()` → `manager.close_all()` (disposes all engines).
+- DB ops `database_exists/create_database/drop_database/list_databases` — ALL require a superuser connection (`is_superuser=True`; first configured one wins); use AUTOCOMMIT isolation.
+- Seeder: `SeederConfig`, `register_seeder`, `seed_all`, `get_registered_seeders`, `SeederConflictError`.
+
+## Architecture
+
+- `DatabaseSettings.connections: dict[str, DatabaseConnectionSettings]` — any lowercase name is a legal key (env `DB_CONNECTIONS__{NAME}__*`).
+- Engine: `create_async_engine(url, echo, pool_size=5, max_overflow=10, pool_timeout=30, pool_recycle=3600, pool_pre_ping=True)` (pre_ping hard-coded). URL: `postgresql+asyncpg://user:pass@host:port/db`.
+- Each engine has a parallel `async_sessionmaker(engine, class_=AsyncSession, expire_on_commit=False)` (SQLModel session — supports BOTH `session.execute` and `session.exec`).
+- `echo` resolution QUIRK: `conn.echo if conn.echo else global echo` — a connection-level `echo=False` cannot override a global `echo=True`.
+
+## Dynamic/tenant engines (private contract)
+
+- There is **no public API to register an engine at runtime**. tenants2fast writes the manager's PRIVATE (`manager._engines`, `manager._session_makers`, `manager.config.connections`) directly. No LRU, no cap — dynamic engines accumulate unboundedly (N tenants × up to 15 connections each). Dispose idle tenant engines explicitly.
+- `get_manager(config)` honors custom config only once; the FastAPI dep always passes module settings.
+
+## Wiring
+
+```python
+from pgsqlasync2fast_fastapi import get_db_session, startup_database, shutdown_database
+# startup(shutdown) events: await startup_database() / await shutdown_database()
+session: AsyncSession = Depends(get_db_session)  # or partial with connection_name
+```
+
+Downstream imports (stable contracts): oauth2fast `get_db_session`→`partial(..., connection_name="auth")`; permissions2fast `SeederConfig, register_seeder`; tenants2fast `create_database, drop_database`, `connection.get_manager`, `settings.settings, DatabaseConnectionSettings`.
+
+## Seeder orchestrator
+
+- `register_seeder` does registration-time **table-conflict detection** per connection (`SeederConflictError` if two seeders on the same connection share a manifest `tables` key).
+- `seed_all(profile, package_filter=None)` sorts by `priority` (LOWER first). **Skips** registered seeders with `is_tenant_seeder=True` and no `seed_fn` (warns — tenant seeding must be driven by `seed_all_tenants`/the tenant package itself).
+- Generic path: topological sort of `depends_on` (cycle → `SeedValidationError`), FK resolution `fk_field_mapping`/`fk_fields`/`rstrip('s')+'_id'`, insert **per row** with explicit `id` → idempotent (SELECT by id, skip if exists, commit per row).
+
+## Settings
+
+`DatabaseSettings`, prefix `DB_`, nested `__`, `.env` from **process CWD**. Top: `DB_DEFAULT_CONNECTION` (default "default"), `DB_ECHO` (False). Per connection: `HOST, USERNAME, PASSWORD, DATABASE` (**all required** — import crashes otherwise), `PORT` (5432), `IS_SUPERUSER` (False), `POOL_SIZE` (5), `MAX_OVERFLOW` (10), `POOL_TIMEOUT` (30), `POOL_RECYCLE` (3600), `ECHO` (False). Missing `.env` does NOT crash at import — it yields an empty manager that fails on first `get_engine` (plus a Spanish warning).
+
+## Gotchas
+
+- `create_database`/`drop_database` require a configured superuser connection.
+- Engines are disposed only by `shutdown_database`/`close_all` — or by tenants2fast's `dispose_tenant_engine` for individual tenant engines; dropping a tenant DB without disposing first leaks connections.
+
+## Golden rule (inherited)
+
+Follow the 2fast-handbook base skill for layout/versioning/naming/README/commits/release.
+Local edits are fine; NEVER bump/publish on your own — prepare the exact command and hand it to the developer.

{pgsqlasync2fast_fastapi-0.3.0 → pgsqlasync2fast_fastapi-0.3.1/src/pgsqlasync2fast_fastapi.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pgsqlasync2fast-fastapi
-Version: 0.3.0
+Version: 0.3.1
 Summary: Simple and fast PostgreSQL async module for FastAPI with multi-database support
 Author-email: Angel Daniel Sanchez Castillo <angeldaniel.sanchezcastillo@gmail.com>
 License: MIT License
@@ -56,6 +56,8 @@ Dynamic: license-file
 
 Simple and fast PostgreSQL async module for FastAPI with multi-database support and automatic database creation.
 
+> 📖 **Conventions reference**: this package follows the [2fast-handbook](https://github.com/AngelDanielSanchezCastillo/2fast-handbook) for ecosystem conventions (structure, versioning, README, commits, release).
+
 ## Features
 
 - ✅ **Multiple Database Connections**: Configure and manage multiple PostgreSQL databases

{pgsqlasync2fast_fastapi-0.3.0 → pgsqlasync2fast_fastapi-0.3.1}/src/pgsqlasync2fast_fastapi.egg-info/SOURCES.txt

@@ -2,7 +2,6 @@ LICENSE
 MANIFEST.in
 README.md
 pyproject.toml
-docs/.env.example
 docs/seeder-format.md
 examples/seeders/manifest.json
 examples/seeders/dev/categories.json
@@ -23,5 +22,6 @@ src/pgsqlasync2fast_fastapi.egg-info/SOURCES.txt
 src/pgsqlasync2fast_fastapi.egg-info/dependency_links.txt
 src/pgsqlasync2fast_fastapi.egg-info/requires.txt
 src/pgsqlasync2fast_fastapi.egg-info/top_level.txt
+src/pgsqlasync2fast_fastapi/skills/SKILL.md
 tests/test_completo.py
 tests/test_seeder.py

pgsqlasync2fast_fastapi-0.3.0/docs/.env.example

@@ -1,50 +0,0 @@
-# ============================================
-# PostgreSQL Database Configuration
-# ============================================
-
-# ===== Connection DEFAULT (principal) =====
-# Esta es la conexión por defecto que se usará cuando no especifiques ninguna
-DB_CONNECTIONS__DEFAULT__HOST=localhost
-DB_CONNECTIONS__DEFAULT__PORT=5432
-DB_CONNECTIONS__DEFAULT__USERNAME=myuser
-DB_CONNECTIONS__DEFAULT__PASSWORD=mypassword
-DB_CONNECTIONS__DEFAULT__DATABASE=mydb
-DB_CONNECTIONS__DEFAULT__IS_SUPERUSER=false
-
-# Pool settings (opcional, estos son los valores por defecto)
-DB_CONNECTIONS__DEFAULT__POOL_SIZE=5
-DB_CONNECTIONS__DEFAULT__MAX_OVERFLOW=10
-DB_CONNECTIONS__DEFAULT__POOL_TIMEOUT=30
-DB_CONNECTIONS__DEFAULT__POOL_RECYCLE=3600
-
-# Echo mode para esta conexión (opcional)
-DB_CONNECTIONS__DEFAULT__ECHO=false
-
-# ===== Connection BUSINESS (ejemplo de segunda conexión) =====
-# Para usar esta conexión, especifica connection_name="business" en tus dependencias
-DB_CONNECTIONS__BUSINESS__HOST=localhost
-DB_CONNECTIONS__BUSINESS__PORT=5432
-DB_CONNECTIONS__BUSINESS__USERNAME=business_user
-DB_CONNECTIONS__BUSINESS__PASSWORD=business_password
-DB_CONNECTIONS__BUSINESS__DATABASE=business_db
-DB_CONNECTIONS__BUSINESS__IS_SUPERUSER=false
-
-# ===== Connection ADMIN (ejemplo con superusuario) =====
-# Esta conexión tiene privilegios de superusuario para crear/eliminar bases de datos
-DB_CONNECTIONS__ADMIN__HOST=localhost
-DB_CONNECTIONS__ADMIN__PORT=5432
-DB_CONNECTIONS__ADMIN__USERNAME=postgres
-DB_CONNECTIONS__ADMIN__PASSWORD=postgres_password
-DB_CONNECTIONS__ADMIN__DATABASE=postgres
-DB_CONNECTIONS__ADMIN__IS_SUPERUSER=true
-
-# ============================================
-# General Settings
-# ============================================
-
-# Conexión por defecto cuando no se especifica ninguna
-# Opciones: "default", "business", "admin", o cualquier otra que hayas configurado
-DB_DEFAULT_CONNECTION=default
-
-# Echo mode global (puede ser sobrescrito por cada conexión)
-DB_ECHO=false

pgsqlasync2fast_fastapi-0.3.0/src/pgsqlasync2fast_fastapi/__version__.py

@@ -1 +0,0 @@
-__version__ = "0.3.0"