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

{pgsqlasync2fast_fastapi-0.2.0 → pgsqlasync2fast_fastapi-0.3.1}/MANIFEST.in

@@ -1,4 +1,4 @@
 include LICENSE
 include README.md
 recursive-include docs *.md
-include docs/.env.example
+recursive-include examples/seeders *.json

{pgsqlasync2fast_fastapi-0.2.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.2.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.2.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.1/docs/seeder-format.md

@@ -0,0 +1,199 @@
+# Seeder Format Documentation
+
+Multi-package JSON seeder format for `pgsqlasync2fast-fastapi`.
+
+## Overview
+
+The seeder system uses JSON files organized by profile (e.g., `dev`, `prod`) with a manifest.json defining table structure and dependencies.
+
+## Directory Structure
+
+```
+seeders/
+├── manifest.json           # Table definitions and load order
+├── dev/                    # Development profile
+│   ├── roles.json
+│   ├── categories.json
+│   └── permissions.json
+└── prod/                   # Production profile
+    ├── roles.json
+    ├── categories.json
+    └── permissions.json
+```
+
+## manifest.json
+
+The manifest defines which tables are seeded and their dependencies.
+
+```json
+{
+  "tables": {
+    "categories": {
+      "file": "categories.json"
+    },
+    "roles": {
+      "file": "roles.json"
+    },
+    "permissions": {
+      "file": "permissions.json",
+      "depends_on": ["categories"]
+    }
+  },
+  "load_order": ["categories", "roles", "permissions"]
+}
+```
+
+### Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `tables` | object | Yes | Dictionary of table configurations |
+| `tables.{name}` | object | Yes | Configuration for each table |
+| `tables.{name}.file` | string | Yes | JSON filename containing the data |
+| `tables.{name}.depends_on` | array | No | Array of table names this table depends on |
+| `load_order` | array | No | Explicit load order (overrides dependency-based sort) |
+
+## Table JSON Files
+
+Each table has its own JSON file containing an array of row objects.
+
+### Format
+
+```json
+[
+  {
+    "id": 1,
+    "name": "Admin",
+    "description": "Administrator role"
+  },
+  {
+    "id": 2,
+    "name": "User",
+    "description": "Regular user role"
+  }
+]
+```
+
+### Requirements
+
+- **Required fields**: Each row MUST have an `id` field (integer or string)
+- **Data types**: JSON primitives (string, number, boolean, null)
+- **Relationships**: Use explicit IDs to reference related entities
+
+## Profiles
+
+Profiles allow the same table structure with different data for different environments.
+
+### Common Profiles
+
+- `dev` - Development data (more records, test data)
+- `prod` - Production data (minimal, realistic data)
+
+### Profile Resolution
+
+When calling `seed_all("dev")`, the system looks for data in `{manifest_dir}/dev/` folder.
+
+## Foreign Key (FK) Validation
+
+Before any inserts, the system validates that FK references point to existing IDs.
+
+### FK Naming Convention
+
+The system uses a simple naming convention:
+- Table `categories` → FK field `category_id`
+- Table `roles` → FK field `role_id`
+- Table `permissions` → FK field `permission_id`
+
+### Example
+
+If `permissions.json` contains:
+```json
+[
+  {
+    "id": 1,
+    "name": "read:users",
+    "category_id": 1
+  }
+]
+```
+
+The system validates that a category with `id=1` exists in `categories.json` before inserting.
+
+### Validation Errors
+
+If validation fails, `SeedValidationError` is raised with details:
+```
+Table 'permissions' row id=1 references non-existent categories id=999
+```
+
+## Priority
+
+Packages have a `priority` value (default: 50) that determines execution order.
+
+- **Lower values** = seeds first
+- **Higher values** = seeds later
+
+This allows controlling which package's data takes precedence when multiple packages are registered.
+
+### Example
+
+```python
+register_seeder(SeederConfig(
+    connection_name="auth",
+    manifest_path="path/to/manifest.json",
+    package_name="my-package",
+    priority=50  # Seeds before packages with higher priority
+))
+```
+
+## Conflict Detection
+
+When registering a seeder, the system detects table conflicts.
+
+### Rule
+
+Two packages CANNOT seed the same table in the same connection.
+
+### Error
+
+If conflicts are detected, `SeederConflictError` is raised:
+```
+Tables {'roles'} conflict between 'pkg-a' and 'pkg-b' on connection 'auth'
+```
+
+## Idempotency
+
+The seeder is idempotent - running multiple times produces the same result.
+
+- Rows with existing IDs are skipped
+- Only new rows are inserted
+
+This allows safe re-runs without duplicating data.
+
+## Usage Example
+
+```python
+from pgsqlasync2fast_fastapi import seed_all, register_seeder, SeederConfig
+
+# Register a package's seeder
+register_seeder(SeederConfig(
+    connection_name="auth",
+    manifest_path="my_package/seeders/manifest.json",
+    package_name="my-package",
+    priority=50
+))
+
+# Execute all seeders with dev profile
+result = await seed_all("dev")
+
+print(f"Seeded {result.tables_seeded} tables, {result.rows_seeded} rows")
+```
+
+## Seed Flow
+
+1. **Register**: `register_seeder()` validates no conflicts
+2. **Resolve Order**: Tables sorted by `depends_on` + `priority`
+3. **Load Data**: Each table's JSON loaded from profile folder
+4. **Validate FKs**: All FK references verified before inserts
+5. **Seed**: Idempotent inserts (skip existing IDs)
+6. **Result**: Summary of seeded packages, tables, and rows

pgsqlasync2fast_fastapi-0.3.1/examples/seeders/dev/categories.json

@@ -0,0 +1,17 @@
+[
+  {
+    "id": 1,
+    "name": "User Management",
+    "description": "Permissions related to user management"
+  },
+  {
+    "id": 2,
+    "name": "Role Management",
+    "description": "Permissions related to role management"
+  },
+  {
+    "id": 3,
+    "name": "System Administration",
+    "description": "Permissions related to system administration"
+  }
+]

pgsqlasync2fast_fastapi-0.3.1/examples/seeders/dev/permissions.json

@@ -0,0 +1,62 @@
+[
+  {
+    "id": 1,
+    "name": "users:read",
+    "description": "View user information",
+    "category_id": 1
+  },
+  {
+    "id": 2,
+    "name": "users:create",
+    "description": "Create new users",
+    "category_id": 1
+  },
+  {
+    "id": 3,
+    "name": "users:update",
+    "description": "Update existing users",
+    "category_id": 1
+  },
+  {
+    "id": 4,
+    "name": "users:delete",
+    "description": "Delete users",
+    "category_id": 1
+  },
+  {
+    "id": 5,
+    "name": "roles:read",
+    "description": "View role information",
+    "category_id": 2
+  },
+  {
+    "id": 6,
+    "name": "roles:create",
+    "description": "Create new roles",
+    "category_id": 2
+  },
+  {
+    "id": 7,
+    "name": "roles:update",
+    "description": "Update existing roles",
+    "category_id": 2
+  },
+  {
+    "id": 8,
+    "name": "roles:delete",
+    "description": "Delete roles",
+    "category_id": 2
+  },
+  {
+    "id": 9,
+    "name": "system:config",
+    "description": "Modify system configuration",
+    "category_id": 3
+  },
+  {
+    "id": 10,
+    "name": "system:audit",
+    "description": "View audit logs",
+    "category_id": 3
+  }
+]

pgsqlasync2fast_fastapi-0.3.1/examples/seeders/dev/roles.json

@@ -0,0 +1,22 @@
+[
+  {
+    "id": 1,
+    "name": "Admin",
+    "description": "Full system administrator with all permissions"
+  },
+  {
+    "id": 2,
+    "name": "Manager",
+    "description": "Manager with elevated privileges but limited system config"
+  },
+  {
+    "id": 3,
+    "name": "User",
+    "description": "Standard user with basic access"
+  },
+  {
+    "id": 4,
+    "name": "Guest",
+    "description": "Guest user with read-only access"
+  }
+]

pgsqlasync2fast_fastapi-0.3.1/examples/seeders/manifest.json

@@ -0,0 +1,21 @@
+{
+  "fk_fields": {
+    "categories": "category_id",
+    "roles": "role_id",
+    "permissions": "permission_id"
+  },
+  "profile_folders": ["dev", "prod"],
+  "tables": {
+    "categories": {
+      "file": "categories.json"
+    },
+    "roles": {
+      "file": "roles.json"
+    },
+    "permissions": {
+      "file": "permissions.json",
+      "depends_on": ["categories"]
+    }
+  },
+  "load_order": ["categories", "roles", "permissions"]
+}

pgsqlasync2fast_fastapi-0.3.1/examples/seeders/prod/categories.json

@@ -0,0 +1,12 @@
+[
+  {
+    "id": 1,
+    "name": "User Management",
+    "description": "Permissions related to user management"
+  },
+  {
+    "id": 2,
+    "name": "Role Management",
+    "description": "Permissions related to role management"
+  }
+]

pgsqlasync2fast_fastapi-0.3.1/examples/seeders/prod/permissions.json

@@ -0,0 +1,38 @@
+[
+  {
+    "id": 1,
+    "name": "users:read",
+    "description": "View user information",
+    "category_id": 1
+  },
+  {
+    "id": 2,
+    "name": "users:create",
+    "description": "Create new users",
+    "category_id": 1
+  },
+  {
+    "id": 3,
+    "name": "users:update",
+    "description": "Update existing users",
+    "category_id": 1
+  },
+  {
+    "id": 4,
+    "name": "roles:read",
+    "description": "View role information",
+    "category_id": 2
+  },
+  {
+    "id": 5,
+    "name": "roles:create",
+    "description": "Create new roles",
+    "category_id": 2
+  },
+  {
+    "id": 6,
+    "name": "roles:update",
+    "description": "Update existing roles",
+    "category_id": 2
+  }
+]

pgsqlasync2fast_fastapi-0.3.1/examples/seeders/prod/roles.json

@@ -0,0 +1,12 @@
+[
+  {
+    "id": 1,
+    "name": "Admin",
+    "description": "System administrator"
+  },
+  {
+    "id": 2,
+    "name": "User",
+    "description": "Standard user"
+  }
+]

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pgsqlasync2fast-fastapi"
-version = "0.2.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/__init__.py

@@ -0,0 +1,89 @@
+"""
+pgsqlasync2fast-fastapi - PostgreSQL async extensions for FastAPI
+
+This package provides database management and seeding capabilities.
+
+The seeder module provides multi-package JSON seeder orchestration.
+
+Example:
+    from pgsqlasync2fast_fastapi import seed_all, register_seeder, SeederConfig
+
+    # Register a package's seeder
+    register_seeder(SeederConfig(
+        connection_name="auth",
+        manifest_path="path/to/manifest.json",
+        package_name="my-package",
+        priority=50
+    ))
+
+    # Execute all seeders
+    result = await seed_all("dev")
+"""
+
+from .__version__ import __version__
+from .connection import DatabaseManager, get_manager
+from .database import create_database, database_exists, drop_database, list_databases
+from .dependencies import (
+    get_db_engine,
+    get_db_manager,
+    get_db_session,
+    shutdown_database,
+    startup_database,
+)
+from .settings import DatabaseConnectionSettings, DatabaseSettings, settings
+
+# Import seeder module
+from pgsqlasync2fast_fastapi import seeder
+
+# Re-export seeder-specific exports
+from pgsqlasync2fast_fastapi.seeder import (
+    # Dataclasses
+    SeederConfig,
+    SeederResult,
+    # Exceptions
+    SeederException,
+    SeederConflictError,
+    SeedValidationError,
+    # Registry functions
+    register_seeder,
+    get_registered_seeders,
+    clear_registry,
+    # Main orchestrator
+    seed_all,
+)
+
+__all__ = [
+    # Version
+    "__version__",
+    # Main classes
+    "DatabaseManager",
+    "get_manager",
+    # Settings
+    "DatabaseSettings",
+    "DatabaseConnectionSettings",
+    "settings",
+    # FastAPI dependencies
+    "get_db_manager",
+    "get_db_engine",
+    "get_db_session",
+    "startup_database",
+    "shutdown_database",
+    # Database utilities
+    "database_exists",
+    "create_database",
+    "drop_database",
+    "list_databases",
+    # Dataclasses (seeder)
+    "SeederConfig",
+    "SeederResult",
+    # Exceptions (seeder)
+    "SeederException",
+    "SeederConflictError",
+    "SeedValidationError",
+    # Registry functions (seeder)
+    "register_seeder",
+    "get_registered_seeders",
+    "clear_registry",
+    # Main orchestrator (seeder)
+    "seed_all",
+]

pgsqlasync2fast_fastapi-0.3.1/src/pgsqlasync2fast_fastapi/__version__.py

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