python-ppa 0.1.6__py3-none-any.whl → 0.1.8__py3-none-any.whl

ppa/__init__.py

@@ -1,2 +1,3 @@
 from ppa import mongo
-from ppa import config
+from ppa import postgres
+from ppa import config

ppa/config.py

@@ -96,16 +96,33 @@ class ConfigSettings:
 
         self._config_data = _load_and_interpolate_yaml(profile_config_path)
         mongodb_config = _as_dict(self._config_data.get("mongodb"), context=f"{profile_filename}.mongodb")
+        postgres_config = _as_dict(
+            self._config_data.get("postgresql", self._config_data.get("postgres")),
+            context=f"{profile_filename}.postgresql",
+        )
 
         # 3. Expose parameters to the framework
         self.mongo_uri = mongodb_config.get("uri")
         self.database_name = mongodb_config.get("database")
+        self.postgres_dsn = self._resolve_postgres_dsn(postgres_config)
+        self.postgres_database_name = postgres_config.get("database") or postgres_config.get("dbname")
 
-        if not isinstance(self.mongo_uri, str) or not self.mongo_uri or not isinstance(self.database_name,
-                                                                                       str) or not self.database_name:
+        has_mongo_config = bool(self.mongo_uri and self.database_name)
+        has_postgres_config = bool(self.postgres_dsn)
+
+        if mongodb_config and not has_mongo_config:
             raise KeyError(
                 f"Invalid configuration format in {profile_filename}. Missing 'mongodb.uri' or 'mongodb.database'.")
 
+        if postgres_config and not has_postgres_config:
+            raise KeyError(
+                f"Invalid configuration format in {profile_filename}. Provide 'postgresql.dsn' or "
+                "'postgresql.host', 'postgresql.database', and 'postgresql.user'.")
+
+        if not has_mongo_config and not has_postgres_config:
+            raise KeyError(
+                f"Invalid configuration format in {profile_filename}. Configure either 'mongodb' or 'postgresql'.")
+
         framework_config = _as_dict(self._config_data.get("framework"), context=f"{profile_filename}.framework")
         framework_logging_config = _as_dict(framework_config.get("logging"),
                                             context=f"{profile_filename}.framework.logging")
@@ -115,6 +132,32 @@ class ConfigSettings:
         self.framework_log_date_format = str(
             framework_logging_config.get("date_format", DEFAULT_FRAMEWORK_LOG_DATE_FORMAT))
 
+    @staticmethod
+    def _resolve_postgres_dsn(postgres_config: dict[str, Any]) -> str | None:
+        dsn = postgres_config.get("dsn") or postgres_config.get("uri") or postgres_config.get("url")
+        if isinstance(dsn, str) and dsn:
+            return dsn
+
+        host = postgres_config.get("host")
+        database = postgres_config.get("database") or postgres_config.get("dbname")
+        user = postgres_config.get("user") or postgres_config.get("username")
+        if not host or not database or not user:
+            return None
+
+        parts = [
+            f"host={host}",
+            f"dbname={database}",
+            f"user={user}",
+        ]
+        optional_fields = {
+            "password": postgres_config.get("password"),
+            "port": postgres_config.get("port"),
+            "sslmode": postgres_config.get("sslmode"),
+            "connect_timeout": postgres_config.get("connect_timeout"),
+        }
+        parts.extend(f"{key}={value}" for key, value in optional_fields.items() if value not in (None, ""))
+        return " ".join(parts)
+
 
 def _configure_framework_logger() -> logging.Logger:
     logger = logging.getLogger(FRAMEWORK_LOGGER_NAME)
@@ -144,11 +187,23 @@ def get_framework_logger(name: str | None = None) -> logging.Logger:
 settings = ConfigSettings()
 framework_logger = _configure_framework_logger()
 framework_logger.info("Bootstrapping framework with active profile [%s]", settings.profile)
-_mongo_client = MongoClient(settings.mongo_uri)
-if not settings or not settings.database_name and not isinstance(settings.database_name, str):
-    raise ValueError("Database name must be provided and it must be a string")
-db = _mongo_client[settings.database_name]
-framework_logger.debug("Mongo client initialized for database [%s]", settings.database_name)
+_mongo_client: MongoClient | None = None
+db = None
+
+
+def _get_mongo_client() -> MongoClient:
+    global _mongo_client, db
+    if not isinstance(settings.mongo_uri, str) or not settings.mongo_uri:
+        raise ValueError("MongoDB URI must be provided before using Mongo repositories")
+    if not isinstance(settings.database_name, str) or not settings.database_name:
+        raise ValueError("MongoDB database name must be provided before using Mongo repositories")
+
+    if _mongo_client is None:
+        _mongo_client = MongoClient(settings.mongo_uri)
+        db = _mongo_client[settings.database_name]
+        framework_logger.debug("Mongo client initialized for database [%s]", settings.database_name)
+
+    return _mongo_client
 
 
 def value(place_holder: str) -> Any:
@@ -196,10 +251,26 @@ def value(place_holder: str) -> Any:
 
 def get_collection(collection_name: str):
     """Provides repositories access to the shared single client pool."""
+    _get_mongo_client()
     return db[collection_name]
 
 
+def get_postgres_connection():
+    """Creates a PostgreSQL connection using the active profile settings."""
+    if not isinstance(settings.postgres_dsn, str) or not settings.postgres_dsn:
+        raise ValueError("PostgreSQL DSN must be provided before using Postgres repositories")
+
+    try:
+        import psycopg
+        from psycopg.rows import dict_row
+    except ImportError as exc:
+        raise ImportError("Install psycopg to use PostgreSQL repositories.") from exc
+
+    return psycopg.connect(settings.postgres_dsn, row_factory=dict_row)
+
+
 def close_db_connection():
-    """Gracefully terminates connection pool sockets on shutdown."""
-    framework_logger.debug("Closing MongoDB client connection pool")
-    _mongo_client.close()
+    """Gracefully terminates open framework connection pools."""
+    if _mongo_client is not None:
+        framework_logger.debug("Closing MongoDB client connection pool")
+        _mongo_client.close()

ppa/postgres/__init__.py

@@ -0,0 +1,5 @@
+from ppa.postgres.interface import EntityList
+from ppa.postgres.interface import EntityModel
+from ppa.postgres.interface import IRepository
+from ppa.postgres.interface import query
+from ppa.postgres.interface import table

ppa/postgres/interface.py

@@ -0,0 +1,344 @@
+import inspect
+import re
+from typing import Any, Callable, ClassVar, Generic, List, Optional, TypeVar, cast, get_args, get_origin, get_type_hints
+
+from pydantic import BaseModel, ConfigDict
+
+from ppa.config import get_framework_logger, get_postgres_connection
+
+T = TypeVar("T", bound="EntityModel")
+F = TypeVar("F", bound=Callable[..., Any])
+framework_logger = get_framework_logger("postgres.repository")
+IDENTIFIER_PATTERN = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+
+
+class EntityModel(BaseModel):
+    """Base class for PostgreSQL-backed models."""
+
+    __table_name__: ClassVar[str]
+
+    model_config = ConfigDict(
+        populate_by_name=True,
+        arbitrary_types_allowed=True,
+    )
+
+    id: Optional[int] = None
+
+    def model_dump(self, **kwargs: Any) -> dict[str, Any]:
+        kwargs.setdefault("exclude_none", True)
+        return super().model_dump(**kwargs)
+
+
+class EntityList(list[T]):
+    """List of entities that can be used to perform bulk operations."""
+
+    def model_dump(self, **kwargs: Any) -> list[dict[str, Any]]:
+        return [entity.model_dump(**kwargs) for entity in self]
+
+    @classmethod
+    def model_validate(cls, obj: list[Any], entity_cls: type[T]) -> "EntityList[T]":
+        if not isinstance(obj, list) and not hasattr(obj, "__iter__"):
+            raise ValueError("Data provided to EntityList.model_validate must be iterable.")
+
+        return cls([entity_cls.model_validate(item) for item in obj])
+
+
+def query(definition: str) -> Callable[[F], F]:
+    """Annotation to specify a custom PostgreSQL query template with ?0 style placeholders."""
+
+    def decorator(func: F) -> F:
+        func.__query_template__ = definition
+        return func
+
+    return decorator
+
+
+def table(name: str) -> Callable[[type[EntityModel]], type[EntityModel]]:
+    """Class decorator to bind a Pydantic model to a PostgreSQL table."""
+
+    _quote_identifier(name)
+
+    def decorator(cls: type[EntityModel]) -> type[EntityModel]:
+        cls.__table_name__ = name
+        return cls
+
+    return decorator
+
+
+def _quote_identifier(identifier: str) -> str:
+    if not IDENTIFIER_PATTERN.match(identifier):
+        raise ValueError(f"Invalid SQL identifier: {identifier}")
+    return f'"{identifier}"'
+
+
+def _field_names(entity_cls: type[EntityModel]) -> set[str]:
+    return set(entity_cls.model_fields.keys())
+
+
+def _build_where_clause(field_name: str) -> str:
+    return f"{_quote_identifier(field_name)} = %s"
+
+
+def _custom_query_to_sql(template: str, ordered_args: list[Any]) -> tuple[str, list[Any]]:
+    values: list[Any] = []
+
+    def replace(match: re.Match[str]) -> str:
+        idx = int(match.group(1))
+        try:
+            values.append(ordered_args[idx])
+        except IndexError as exc:
+            raise ValueError(f"Missing argument for SQL placeholder ?{idx}") from exc
+        return "%s"
+
+    return re.sub(r"\?(\d+)", replace, template), values
+
+
+class RepositoryMeta(type):
+    def __new__(mcs, name: str, bases: tuple[type, ...], namespace: dict[str, Any]):
+        cls = super().__new__(mcs, name, bases, namespace)
+
+        if name == "IRepository":
+            return cls
+
+        entity_cls = mcs._extract_entity_cls(cls)
+        if not entity_cls:
+            return cls
+
+        typed_entity_cls = cast(type[EntityModel], entity_cls)
+
+        if not hasattr(typed_entity_cls, "__table_name__"):
+            raise TypeError(
+                f"RepositoryDefinitionError: The model '{entity_cls.__name__}' "
+                f"used by '{name}' must be annotated with @table(name='...')"
+            )
+
+        cls._entity_cls = typed_entity_cls
+        valid_fields = _field_names(typed_entity_cls)
+
+        for attr_name, attr_value in list(namespace.items()):
+            if inspect.isfunction(attr_value) and not attr_name.startswith("_"):
+                query_template = getattr(attr_value, "__query_template__", None)
+                is_convention = re.match(r"(find_by|find_all_by|exists_by|count_by)_(.*)", attr_name)
+
+                if not is_convention and not query_template:
+                    framework_logger.info("Convention does not exist, relying on user implementation")
+                    continue
+
+                hints = get_type_hints(attr_value)
+                return_type = hints.get("return")
+
+                if isinstance(query_template, str):
+                    generated_method = mcs._build_annotated_method(
+                        attr_name,
+                        attr_value,
+                        query_template,
+                        return_type,
+                        typed_entity_cls,
+                    )
+                elif is_convention is not None:
+                    generated_method = mcs._build_convention_method(
+                        attr_name,
+                        is_convention,
+                        attr_value,
+                        valid_fields,
+                        return_type,
+                        typed_entity_cls,
+                    )
+                else:
+                    continue
+
+                setattr(cls, attr_name, generated_method)
+
+        return cls
+
+    @staticmethod
+    def _extract_entity_cls(cls: type) -> type[BaseModel] | None:
+        for base in getattr(cls, "__orig_bases__", []):
+            if get_origin(base) is IRepository:
+                args = get_args(base)
+                if args and issubclass(args[0], BaseModel):
+                    return args[0]
+        return None
+
+    @staticmethod
+    def _build_annotated_method(
+        name: str,
+        func: Callable[..., Any],
+        template: str,
+        return_type: Any,
+        entity_cls: type[EntityModel],
+    ) -> Callable[..., Any]:
+        sig = inspect.signature(func)
+        param_names = [p for p in sig.parameters if p != "self"]
+
+        def wrapper(self, *args: Any, **kwargs: Any) -> Any:
+            bound = sig.bind(self, *args, **kwargs)
+            bound.apply_defaults()
+            ordered_args = [bound.arguments[p_name] for p_name in param_names if p_name in bound.arguments]
+            sql, params = _custom_query_to_sql(template, ordered_args)
+
+            framework_logger.debug(
+                "Invoked custom Postgres query %s.%s with args=%s kwargs=%s",
+                self.__class__.__name__,
+                name,
+                args,
+                kwargs,
+            )
+
+            return execute_dynamic_query(sql, params, "custom", return_type, entity_cls)
+
+        wrapper.__name__ = name
+        wrapper.__qualname__ = f"{entity_cls.__name__}Repository.{name}"
+        return wrapper
+
+    @staticmethod
+    def _build_convention_method(
+        name: str,
+        match: re.Match[str],
+        func: Callable[..., Any],
+        valid_fields: set[str],
+        return_type: Any,
+        entity_cls: type[EntityModel],
+    ) -> Callable[..., Any]:
+        prefix, field_name = match.groups()
+
+        if field_name not in valid_fields:
+            raise TypeError(
+                f"RepositoryDefinitionError: Field '{field_name}' does not exist on model {entity_cls.__name__}"
+            )
+
+        sql_field = _quote_identifier(field_name)
+        table_name = _quote_identifier(entity_cls.__table_name__)
+        sig = inspect.signature(func)
+        param_names = [p for p in sig.parameters if p != "self"]
+
+        def wrapper(self, *args: Any, **kwargs: Any) -> Any:
+            bound = sig.bind_partial(self, *args, **kwargs)
+            bound.apply_defaults()
+            actual_value = bound.arguments.get(param_names[0]) if param_names else None
+
+            if prefix == "count_by":
+                sql = f"SELECT COUNT(*) AS count FROM {table_name} WHERE {sql_field} = %s"
+            elif prefix == "exists_by":
+                sql = f"SELECT EXISTS(SELECT 1 FROM {table_name} WHERE {sql_field} = %s LIMIT 1) AS exists"
+            else:
+                sql = f"SELECT * FROM {table_name} WHERE {sql_field} = %s"
+
+            framework_logger.debug(
+                "Invoked convention Postgres query %s.%s using %s=%r",
+                self.__class__.__name__,
+                name,
+                field_name,
+                actual_value,
+            )
+
+            return execute_dynamic_query(sql, [actual_value], prefix, return_type, entity_cls)
+
+        wrapper.__name__ = name
+        wrapper.__qualname__ = f"{entity_cls.__name__}Repository.{name}"
+        return wrapper
+
+
+def execute_dynamic_query(
+    sql: str,
+    params: list[Any],
+    strategy: str,
+    return_type: Any,
+    entity_cls: type[EntityModel],
+) -> Any:
+    framework_logger.debug("Executing PostgreSQL query with strategy [%s]: %s", strategy, sql)
+    origin_type = get_origin(return_type) or return_type
+
+    with get_postgres_connection() as connection:
+        with connection.cursor() as cursor:
+            cursor.execute(sql, params)
+
+            if strategy == "count_by" or origin_type is int:
+                row = cursor.fetchone()
+                return int(row["count"]) if row else 0
+
+            if strategy == "exists_by" or origin_type is bool:
+                row = cursor.fetchone()
+                return bool(row["exists"]) if row else False
+
+            if origin_type in (list, EntityList):
+                rows = cursor.fetchall()
+                results = [entity_cls.model_validate(row) for row in rows]
+                return EntityList(results) if origin_type is EntityList else results
+
+            row = cursor.fetchone()
+            return entity_cls.model_validate(row) if row else None
+
+
+class IRepository(Generic[T], metaclass=RepositoryMeta):
+    def __init__(self):
+        entity_cls = cast(type[EntityModel], self._entity_cls)
+        self.table_name = entity_cls.__table_name__
+        framework_logger.debug(
+            "Initialized repository [%s] for table [%s]",
+            self.__class__.__name__,
+            self.table_name,
+        )
+
+    def save(self, pyd_model: T) -> str:
+        data = pyd_model.model_dump()
+        data.pop("id", None)
+        if not data:
+            raise ValueError("No data provided for insert")
+
+        columns = list(data.keys())
+        quoted_columns = ", ".join(_quote_identifier(column) for column in columns)
+        placeholders = ", ".join(["%s"] * len(columns))
+        sql = f"INSERT INTO {_quote_identifier(self.table_name)} ({quoted_columns}) VALUES ({placeholders}) RETURNING id"
+
+        with get_postgres_connection() as connection:
+            with connection.cursor() as cursor:
+                cursor.execute(sql, [data[column] for column in columns])
+                row = cursor.fetchone()
+                return str(row["id"]) if row and "id" in row else ""
+
+    def save_all(self, pyd_models: List[T]) -> List[str]:
+        return [self.save(pyd_model) for pyd_model in pyd_models]
+
+    def find_all(self) -> EntityList[T]:
+        sql = f"SELECT * FROM {_quote_identifier(self.table_name)}"
+        with get_postgres_connection() as connection:
+            with connection.cursor() as cursor:
+                cursor.execute(sql)
+                rows = cursor.fetchall()
+                return EntityList([self._entity_cls.model_validate(row) for row in rows])
+
+    def find(self, query_dict: dict[str, Any]) -> T:
+        if not query_dict:
+            raise ValueError("Query criteria must be provided")
+
+        clauses = [_build_where_clause(field_name) for field_name in query_dict]
+        sql = f"SELECT * FROM {_quote_identifier(self.table_name)} WHERE {' AND '.join(clauses)} LIMIT 1"
+
+        with get_postgres_connection() as connection:
+            with connection.cursor() as cursor:
+                cursor.execute(sql, list(query_dict.values()))
+                row = cursor.fetchone()
+                if not row:
+                    raise ValueError("No data found")
+                return self._entity_cls.model_validate(row)
+
+    def delete(self, resource_id: str) -> bool:
+        sql = f"DELETE FROM {_quote_identifier(self.table_name)} WHERE {_quote_identifier('id')} = %s"
+        with get_postgres_connection() as connection:
+            with connection.cursor() as cursor:
+                cursor.execute(sql, [resource_id])
+                return cursor.rowcount > 0
+
+    def update(self, resource_id: str, data: dict[str, Any]) -> bool:
+        update_data = {key: value for key, value in data.items() if key != "id"}
+        if not update_data:
+            raise ValueError("No data provided for update")
+
+        assignments = ", ".join(f"{_quote_identifier(field_name)} = %s" for field_name in update_data)
+        sql = f"UPDATE {_quote_identifier(self.table_name)} SET {assignments} WHERE {_quote_identifier('id')} = %s"
+
+        with get_postgres_connection() as connection:
+            with connection.cursor() as cursor:
+                cursor.execute(sql, [*update_data.values(), resource_id])
+                return cursor.rowcount > 0

python_ppa-0.1.8.dist-info/METADATA

@@ -0,0 +1,283 @@
+Metadata-Version: 2.4
+Name: python-ppa
+Version: 0.1.8
+Summary: JPA-like ORM for Python
+Author: Pratyush Kumar
+License-Expression: MIT
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: annotated-types==0.7.0
+Requires-Dist: dnspython==2.8.0
+Requires-Dist: email-validator==2.3.0
+Requires-Dist: idna==3.18
+Requires-Dist: pydantic==2.13.4
+Requires-Dist: pydantic_core==2.46.4
+Requires-Dist: psycopg[binary]>=3.2.0
+Requires-Dist: pymongo==4.17.0
+Requires-Dist: python-dotenv==1.2.2
+Requires-Dist: PyYAML==6.0.3
+Requires-Dist: typing-inspection==0.4.2
+Requires-Dist: typing_extensions==4.15.0
+Dynamic: license-file
+
+# python-ppa
+
+`python-ppa` is a lightweight, Spring Data ppa-inspired persistence framework for MongoDB and PostgreSQL built on top of **Python 3.13+**, **Pydantic v2**, **PyMongo**, and **psycopg**. 
+
+It uses advanced Python metaprogramming (`metaclass`) to dynamically generate MongoDB queries at runtime based on method naming conventions or explicit query declarations, drastically reducing boilerplate code.
+
+---
+
+## 🚀 Features
+
+* **ppa-Like Repository Pattern:** Declare an interface, and let the metaclass handle query assembly dynamically.
+* **Query Naming Conventions:** Instantly supports `find_by_*`, `find_all_by_*`, `exists_by_*`, and `count_by_*` pattern resolutions.
+* **Custom Query Annotations:** Bind complex MongoDB or PostgreSQL query templates with custom parameter injections using the `@query` decorator.
+* **Data Validation:** Fully powered by Pydantic v2 for robust runtime type checking and parsing.
+* **Zero-Boilerplate ID Mapping:** Automatically handles conversions between stringified hexadecimal keys and native BSON `ObjectId` footprints.
+* **Environment Profiles:** Flexible configurations handling multi-stage deployment environments (`dev`, `prod`, etc.) via YAML interpolation.
+
+---
+
+## 📁 Directory Structure
+
+```text
+.
+├── README.md
+├── ppa
+│   ├── __init__.py
+│   ├── config.py         # App bootstrapping, YAML parsing & environment mapping
+│   ├── mongo
+│       ├── __init__.py
+│       └── interface.py  # Repository core interface, custom metadata, and queries
+│   └── postgres
+│       ├── __init__.py
+│       └── interface.py  # PostgreSQL repository interface and SQL query conventions
+├── pyproject.toml
+└── requirements.txt
+```
+
+## 🛠️ Getting Started
+
+### Prerequisites
+
+* Python 3.13 or higher
+
+### Installation & Virtual Env Setup
+
+1. Clone the repository and navigate to its root: `cd python-ppa`
+2. Spin up a virtual environment and update your pip core dependencies:
+
+```bash
+python3 -m venv venv
+source venv/bin/activate
+pip install --upgrade pip
+```
+
+3. Install the project library dependencies:
+
+```bash
+pip install -r requirements.txt
+```
+
+## ⚙️ Configuration Management
+
+The framework supports multi-profile YAML configurations with real-time environment substitution syntax (e.g., ${ENV_VAR:default_value}).
+Create a `resources/` directory at the root of your execution workspace and include your application sheets.
+
+1. Master Configuration (`resources/settings.yml`)
+
+```yaml
+app:
+  profile: ${APP_PROFILE:dev} # Swaps profile to target environment configuration
+```
+
+2. Environment Profile Configuration (`resources/settings-dev.yml`)
+
+```yaml
+mongodb:
+  uri: ${MONGO_URI:mongodb://localhost:27017}
+  database: ${MONGO_DB_NAME:ppa_database}
+
+# Or configure PostgreSQL instead.
+postgresql:
+  dsn: ${POSTGRES_DSN:postgresql://postgres:postgres@localhost:5432/ppa_database}
+
+# Equivalent field-based PostgreSQL configuration:
+# postgresql:
+#   host: ${POSTGRES_HOST:localhost}
+#   port: ${POSTGRES_PORT:5432}
+#   database: ${POSTGRES_DB_NAME:ppa_database}
+#   user: ${POSTGRES_USER:postgres}
+#   password: ${POSTGRES_PASSWORD:postgres}
+
+framework:
+  logging:
+    enabled: true
+    level: "DEBUG"
+```
+
+## PostgreSQL Quickstart
+
+The `demo/` folder contains a complete local PostgreSQL verification app.
+
+1. Start PostgreSQL:
+
+```bash
+cd demo
+docker compose up -d
+```
+
+2. Run the demo from the repository root:
+
+```bash
+./venv/bin/python demo/main.py
+```
+
+The demo creates a `users` table and verifies insert, convention queries, a custom SQL query, update, and delete through `ppa.postgres`.
+
+For your own app, create `resources/settings.yml`:
+
+```yaml
+app:
+  profile: ${APP_PROFILE:dev}
+```
+
+Then create `resources/settings-dev.yml`:
+
+```yaml
+postgresql:
+  host: ${POSTGRES_HOST:localhost}
+  port: ${POSTGRES_PORT:5432}
+  database: ${POSTGRES_DB_NAME:ppa_demo}
+  user: ${POSTGRES_USER:ppa_user}
+  password: ${POSTGRES_PASSWORD:ppa_password}
+
+framework:
+  logging:
+    enabled: true
+    level: DEBUG
+```
+
+You can also use a single DSN:
+
+```yaml
+postgresql:
+  dsn: ${POSTGRES_DSN:postgresql://ppa_user:ppa_password@localhost:5432/ppa_demo}
+```
+
+Create the database table before using the repository. `python-ppa` currently maps models to existing tables; it does not run migrations for you.
+
+```sql
+CREATE TABLE IF NOT EXISTS users (
+    id SERIAL PRIMARY KEY,
+    username TEXT NOT NULL UNIQUE,
+    email TEXT NOT NULL,
+    age INTEGER NOT NULL
+);
+```
+
+Define a PostgreSQL-backed entity and repository:
+
+```python
+from ppa.postgres import EntityModel, IRepository, query, table
+
+@table(name="users")
+class User(EntityModel):
+    username: str
+    email: str
+    age: int
+
+class UserRepository(IRepository[User]):
+    def find_by_username(self, username: str) -> User | None: ...
+    def exists_by_username(self, username: str) -> bool: ...
+    def count_by_age(self, age: int) -> int: ...
+    def find_all_by_age(self, age: int) -> list[User]: ...
+
+    @query("SELECT * FROM users WHERE email = ?0 AND age >= ?1")
+    def find_by_email_and_min_age(self, email: str, min_age: int) -> list[User]: ...
+```
+
+Use the repository:
+
+```python
+from ppa.config import close_db_connection
+
+repo = UserRepository()
+
+user_id = repo.save(User(username="pratyush", email="pratyush@example.com", age=25))
+user = repo.find_by_username("pratyush")
+
+print(user.model_dump() if user else None)
+print(repo.exists_by_username("pratyush"))
+print(repo.count_by_age(25))
+print(repo.find_by_email_and_min_age("pratyush@example.com", 21))
+
+repo.update(user_id, {"age": 26})
+repo.delete(user_id)
+
+close_db_connection()
+```
+
+## MongoDB Usage Example
+
+Here is a quick overview of how you can configure a domain entity and generate auto-implemented interface pipelines:
+
+1. Define your Document Model
+
+```python
+from pydantic import Field
+from ppa.mongo.interface import DocumentModel, document
+
+@document(name="users")
+class User(DocumentModel):
+    id: str = Field(alias="_id", default=None)
+    username: str
+    email: str
+    age: int
+```
+
+2. Declare your Interface Repository
+
+By extending IRepository[T], method naming patterns are captured and converted into database interactions seamlessly.
+
+```python
+from ppa.mongo.interface import IRepository, query
+from typing import List, Optional
+
+class UserRepository(IRepository[User]):
+    
+    # 1. Query generation by structural method naming convention
+    def find_by_username(self, username: str) -> Optional[User]: ...
+    
+    def count_by_age(self, age: int) -> int: ...
+
+    # 2. Templated declaration using placeholder substitutions
+    @query(definition={"email": "?0", "age": {"$gte": "?1"}})
+    def find_by_email_and_min_age(self, email: str, min_age: int) -> List[User]: ...
+```
+
+3. Execute CRUD Actions
+
+```python
+from ppa.config import close_db_connection
+
+# Initialize repository instance
+user_repo = UserRepository()
+
+# Save a document
+new_user = User(username="pratyush", email="pratyush@example.com", age=25)
+user_id = user_repo.save(new_user)
+
+# Fetch using automatic query generation
+user = user_repo.find_by_username("pratyush")
+print(f"Found User: {user.email if user else 'Not Found'}")
+
+# Clean up connections on process termination
+close_db_connection()
+```
+
+## 📜 License
+
+This project is open-source software licensed under the MIT License.

python_ppa-0.1.8.dist-info/RECORD

@@ -0,0 +1,11 @@
+ppa/__init__.py,sha256=xcGgO7Le8ZRHedmoe8ftYmxOaq5Y013RGZxGU7QuogU,70
+ppa/config.py,sha256=U-0Db6i_tN9ji0JocOuNeSIz8RyxNIHo4FaUMNe5Pr4,11270
+ppa/mongo/__init__.py,sha256=tioeX330txLUWpEyAuj8rCO6C8DISjRkNFVDs8wGe54,168
+ppa/mongo/interface.py,sha256=lKDtd1KOXIjl9gKPGP_WVoKsE54_esJadNqKIHTadcw,12684
+ppa/postgres/__init__.py,sha256=6CsIXOIIANpCcLbDjQLvsatxcMwngmJagXtPzAznqc0,222
+ppa/postgres/interface.py,sha256=1wZqP1oChgI1m23zUQ8XXg79NQDXwaKX2JB53yYe8Tg,12829
+python_ppa-0.1.8.dist-info/licenses/LICENSE,sha256=J2MOuVHjIUNmdrDLa3O35gQz6E_wAJh9Ke3dod_ZDWc,1071
+python_ppa-0.1.8.dist-info/METADATA,sha256=bC5EmRgXG_h_ofUMz3U6Yyk33Tjsil6XTE-dr5qmC2A,8013
+python_ppa-0.1.8.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+python_ppa-0.1.8.dist-info/top_level.txt,sha256=43G6at2pfqB1LsMChCc2_K8WwSSt-LoYBAYN6Sf-krk,4
+python_ppa-0.1.8.dist-info/RECORD,,

{python_ppa-0.1.6.dist-info → python_ppa-0.1.8.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (82.0.1)
+Generator: setuptools (83.0.0)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

python_ppa-0.1.6.dist-info/METADATA

@@ -1,127 +0,0 @@
-Metadata-Version: 2.4
-Name: python-ppa
-Version: 0.1.6
-Summary: JPA-like ORM for Python
-Author: Pratyush Kumar
-License-Expression: MIT
-Requires-Python: >=3.13
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: annotated-types==0.7.0
-Requires-Dist: dnspython==2.8.0
-Requires-Dist: email-validator==2.3.0
-Requires-Dist: idna==3.18
-Requires-Dist: pydantic==2.13.4
-Requires-Dist: pydantic_core==2.46.4
-Requires-Dist: pymongo==4.17.0
-Requires-Dist: python-dotenv==1.2.2
-Requires-Dist: PyYAML==6.0.3
-Requires-Dist: typing-inspection==0.4.2
-Requires-Dist: typing_extensions==4.15.0
-Dynamic: license-file
-
-# python-ppa
-
-`python-ppa` is a lightweight, Spring Data ppa-inspired Object-Document Mapper (ODM) for MongoDB built on top of **Python 3.13+**, **Pydantic v2**, and **PyMongo**. 
-
-It uses advanced Python metaprogramming (`metaclass`) to dynamically generate MongoDB queries at runtime based on method naming conventions or explicit query declarations, drastically reducing boilerplate code.
-
----
-
-## 🚀 Features
-
-* **ppa-Like Repository Pattern:** Declare an interface, and let the metaclass handle query assembly dynamically.
-* **Query Naming Conventions:** Instantly supports `find_by_*`, `find_all_by_*`, `exists_by_*`, and `count_by_*` pattern resolutions.
-* **Custom Query Annotations:** Bind complex MongoDB query templates with custom parameter injections using the `@query` decorator.
-* **Data Validation:** Fully powered by Pydantic v2 for robust runtime type checking and parsing.
-* **Zero-Boilerplate ID Mapping:** Automatically handles conversions between stringified hexadecimal keys and native BSON `ObjectId` footprints.
-* **Environment Profiles:** Flexible configurations handling multi-stage deployment environments (`dev`, `prod`, etc.) via YAML interpolation.
-
----
-
-## 📁 Directory Structure
-
-```text
-.
-├── README.md
-├── ppa
-│   ├── __init__.py
-│   ├── config.py         # App bootstrapping, YAML parsing & environment mapping
-│   └── mongo
-│       ├── __init__.py
-│       └── interface.py  # Repository core interface, custom metadata, and queries
-├── pyproject.toml
-└── requirements.txt
-
-🛠️ Getting Started
-Prerequisites
-• Python 3.13 or higher
-Installation & Virtual Env Setup
-1. Clone the repository and navigate to its root: cd python-ppa
-2. Spin up a virtual environment and update your pip core dependencies: python3 -m venv venv source venv/bin/activate  # On Windows use: venv\Scripts\activate pip install --upgrade pip
-3. Install the project library dependencies: pip install -r requirements.txt
-⚙️ Configuration Management
-The framework supports multi-profile YAML configurations with real-time environment substitution syntax (e.g., ${ENV_VAR:default_value}).
-Create a resources/ directory at the root of your execution workspace and include your application sheets:
-1. Master Configuration (resources/settings.yml)
-app:
-  profile: ${APP_PROFILE:dev} # Swaps profile to target environment configuration
-
-2. Environment Profile Configuration (resources/settings-dev.yml)
-mongodb:
-  uri: ${MONGO_URI:mongodb://localhost:27017}
-  database: ${MONGO_DB_NAME:ppa_database}
-
-framework:
-  logging:
-    enabled: true
-    level: "DEBUG"
-
-📖 Usage Example
-Here is a quick overview of how you can configure a domain entity and generate auto-implemented interface pipelines:
-1. Define your Document Model
-from pydantic import Field
-from ppa.mongo.interface import DocumentModel, document
-
-@document(name="users")
-class User(DocumentModel):
-    id: str = Field(alias="_id", default=None)
-    username: str
-    email: str
-    age: int
-
-2. Declare your Interface Repository
-By extending IRepository[T], method naming patterns are captured and converted into database interactions seamlessly.
-from ppa.mongo.interface import IRepository, query
-from typing import List, Optional
-
-class UserRepository(IRepository[User]):
-    
-    # 1. Query generation by structural method naming convention
-    def find_by_username(self, username: str) -> Optional[User]: ...
-    
-    def count_by_age(self, age: int) -> int: ...
-
-    # 2. Templated declaration using placeholder substitutions
-    @query(definition={"email": "?0", "age": {"$gte": "?1"}})
-    def find_by_email_and_min_age(self, email: str, min_age: int) -> List[User]: ...
-
-3. Execute CRUD Actions
-from ppa.config import close_db_connection
-
-# Initialize repository instance
-user_repo = UserRepository()
-
-# Save a document
-new_user = User(username="pratyush", email="pratyush@example.com", age=25)
-user_id = user_repo.save(new_user)
-
-# Fetch using automatic query generation
-user = user_repo.find_by_username("pratyush")
-print(f"Found User: {user.email if user else 'Not Found'}")
-
-# Clean up connections on process termination
-close_db_connection()
-
-📜 License
-This project is open-source software licensed under the MIT License.

python_ppa-0.1.6.dist-info/RECORD

@@ -1,9 +0,0 @@
-ppa/__init__.py,sha256=hPJEX6p9ISqFn9oCk29_HIZYIFVUF_XLEk02dg5fl9c,44
-ppa/config.py,sha256=BpnjdXIYjKe7P8HGKFwZkkTbHf94734dhuT1ki4x0UM,8430
-ppa/mongo/__init__.py,sha256=tioeX330txLUWpEyAuj8rCO6C8DISjRkNFVDs8wGe54,168
-ppa/mongo/interface.py,sha256=lKDtd1KOXIjl9gKPGP_WVoKsE54_esJadNqKIHTadcw,12684
-python_ppa-0.1.6.dist-info/licenses/LICENSE,sha256=J2MOuVHjIUNmdrDLa3O35gQz6E_wAJh9Ke3dod_ZDWc,1071
-python_ppa-0.1.6.dist-info/METADATA,sha256=KJ2JYTZDnJMWAL24j0A28kDJlAHST4yKU3KxXHMAqgg,4903
-python_ppa-0.1.6.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-python_ppa-0.1.6.dist-info/top_level.txt,sha256=43G6at2pfqB1LsMChCc2_K8WwSSt-LoYBAYN6Sf-krk,4
-python_ppa-0.1.6.dist-info/RECORD,,