python-ppa 0.1.5__tar.gz → 0.1.7__tar.gz

{python_ppa-0.1.5 → python_ppa-0.1.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-ppa
-Version: 0.1.5
+Version: 0.1.7
 Summary: JPA-like ORM for Python
 Author: Pratyush Kumar
 License-Expression: MIT
@@ -13,6 +13,7 @@ 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
@@ -20,9 +21,9 @@ Requires-Dist: typing-inspection==0.4.2
 Requires-Dist: typing_extensions==4.15.0
 Dynamic: license-file
 
-# python-jpa
+# python-ppa
 
-`python-jpa` is a lightweight, Spring Data JPA-inspired Object-Document Mapper (ODM) for MongoDB built on top of **Python 3.13+**, **Pydantic v2**, and **PyMongo**. 
+`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.
 
@@ -30,9 +31,9 @@ It uses advanced Python metaprogramming (`metaclass`) to dynamically generate Mo
 
 ## 🚀 Features
 
-* **JPA-Like Repository Pattern:** Declare an interface, and let the metaclass handle query assembly dynamically.
+* **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.
+* **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.
@@ -44,44 +45,88 @@ It uses advanced Python metaprogramming (`metaclass`) to dynamically generate Mo
 ```text
 .
 ├── README.md
-├── jpa
+├── ppa
 │   ├── __init__.py
 │   ├── config.py         # App bootstrapping, YAML parsing & environment mapping
-│   └── mongo
+│   ├── 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
 
-🛠️ Getting Started
-Prerequisites
-• Python 3.13 or higher
-Installation & Virtual Env Setup
-1. Clone the repository and navigate to its root: cd python-jpa
-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)
+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)
+2. Environment Profile Configuration (`resources/settings-dev.yml`)
+
+```yaml
 mongodb:
   uri: ${MONGO_URI:mongodb://localhost:27017}
-  database: ${MONGO_DB_NAME:jpa_database}
+  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"
+```
+
+## 📖 Usage Example
 
-📖 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 jpa.mongo.interface import DocumentModel, document
+from ppa.mongo.interface import DocumentModel, document
 
 @document(name="users")
 class User(DocumentModel):
@@ -89,10 +134,14 @@ class User(DocumentModel):
     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 jpa.mongo.interface import IRepository, query
+
+```python
+from ppa.mongo.interface import IRepository, query
 from typing import List, Optional
 
 class UserRepository(IRepository[User]):
@@ -105,9 +154,12 @@ class UserRepository(IRepository[User]):
     # 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 jpa.config import close_db_connection
+
+```python
+from ppa.config import close_db_connection
 
 # Initialize repository instance
 user_repo = UserRepository()
@@ -122,6 +174,28 @@ print(f"Found User: {user.email if user else 'Not Found'}")
 
 # Clean up connections on process termination
 close_db_connection()
+```
+
+PostgreSQL repositories follow the same naming conventions with SQL-backed models:
+
+```python
+from pydantic import EmailStr
+from ppa.postgres.interface import EntityModel, IRepository, query, table
+
+@table(name="users")
+class User(EntityModel):
+    username: str
+    email: EmailStr
+    age: int
+
+class UserRepository(IRepository[User]):
+    def find_by_username(self, username: str) -> User | None: ...
+    def count_by_age(self, age: int) -> int: ...
+
+    @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]: ...
+```
+
+## 📜 License
 
-📜 License
 This project is open-source software licensed under the MIT License.

{python_ppa-0.1.5 → python_ppa-0.1.7}/README.md

@@ -1,6 +1,6 @@
-# python-jpa
+# python-ppa
 
-`python-jpa` is a lightweight, Spring Data JPA-inspired Object-Document Mapper (ODM) for MongoDB built on top of **Python 3.13+**, **Pydantic v2**, and **PyMongo**. 
+`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.
 
@@ -8,9 +8,9 @@ It uses advanced Python metaprogramming (`metaclass`) to dynamically generate Mo
 
 ## 🚀 Features
 
-* **JPA-Like Repository Pattern:** Declare an interface, and let the metaclass handle query assembly dynamically.
+* **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.
+* **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.
@@ -22,44 +22,88 @@ It uses advanced Python metaprogramming (`metaclass`) to dynamically generate Mo
 ```text
 .
 ├── README.md
-├── jpa
+├── ppa
 │   ├── __init__.py
 │   ├── config.py         # App bootstrapping, YAML parsing & environment mapping
-│   └── mongo
+│   ├── 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
 
-🛠️ Getting Started
-Prerequisites
-• Python 3.13 or higher
-Installation & Virtual Env Setup
-1. Clone the repository and navigate to its root: cd python-jpa
-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)
+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)
+2. Environment Profile Configuration (`resources/settings-dev.yml`)
+
+```yaml
 mongodb:
   uri: ${MONGO_URI:mongodb://localhost:27017}
-  database: ${MONGO_DB_NAME:jpa_database}
+  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"
+```
+
+## 📖 Usage Example
 
-📖 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 jpa.mongo.interface import DocumentModel, document
+from ppa.mongo.interface import DocumentModel, document
 
 @document(name="users")
 class User(DocumentModel):
@@ -67,10 +111,14 @@ class User(DocumentModel):
     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 jpa.mongo.interface import IRepository, query
+
+```python
+from ppa.mongo.interface import IRepository, query
 from typing import List, Optional
 
 class UserRepository(IRepository[User]):
@@ -83,9 +131,12 @@ class UserRepository(IRepository[User]):
     # 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 jpa.config import close_db_connection
+
+```python
+from ppa.config import close_db_connection
 
 # Initialize repository instance
 user_repo = UserRepository()
@@ -100,6 +151,28 @@ print(f"Found User: {user.email if user else 'Not Found'}")
 
 # Clean up connections on process termination
 close_db_connection()
+```
+
+PostgreSQL repositories follow the same naming conventions with SQL-backed models:
+
+```python
+from pydantic import EmailStr
+from ppa.postgres.interface import EntityModel, IRepository, query, table
+
+@table(name="users")
+class User(EntityModel):
+    username: str
+    email: EmailStr
+    age: int
+
+class UserRepository(IRepository[User]):
+    def find_by_username(self, username: str) -> User | None: ...
+    def count_by_age(self, age: int) -> int: ...
+
+    @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]: ...
+```
+
+## 📜 License
 
-📜 License
-This project is open-source software licensed under the MIT License.
+This project is open-source software licensed under the MIT License.

python_ppa-0.1.7/ppa/__init__.py

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

{python_ppa-0.1.5 → python_ppa-0.1.7}/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()

python_ppa-0.1.7/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

python_ppa-0.1.7/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.5 → python_ppa-0.1.7}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-ppa"
-version = "0.1.5"
+version = "0.1.7"
 description = "JPA-like ORM for Python"
 readme = "README.md"
 requires-python = ">=3.13"
@@ -20,6 +20,7 @@ dependencies = [
     "idna==3.18",
     "pydantic==2.13.4",
     "pydantic_core==2.46.4",
+    "psycopg[binary]>=3.2.0",
     "pymongo==4.17.0",
     "python-dotenv==1.2.2",
     "PyYAML==6.0.3",
@@ -29,4 +30,4 @@ dependencies = [
 
 [tool.setuptools.packages.find]
 # Automatically discover the 'ppa' package and its nested subpackages (like mongo)
-include = ["ppa*"]
+include = ["ppa*"]

{python_ppa-0.1.5 → python_ppa-0.1.7}/python_ppa.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-ppa
-Version: 0.1.5
+Version: 0.1.7
 Summary: JPA-like ORM for Python
 Author: Pratyush Kumar
 License-Expression: MIT
@@ -13,6 +13,7 @@ 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
@@ -20,9 +21,9 @@ Requires-Dist: typing-inspection==0.4.2
 Requires-Dist: typing_extensions==4.15.0
 Dynamic: license-file
 
-# python-jpa
+# python-ppa
 
-`python-jpa` is a lightweight, Spring Data JPA-inspired Object-Document Mapper (ODM) for MongoDB built on top of **Python 3.13+**, **Pydantic v2**, and **PyMongo**. 
+`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.
 
@@ -30,9 +31,9 @@ It uses advanced Python metaprogramming (`metaclass`) to dynamically generate Mo
 
 ## 🚀 Features
 
-* **JPA-Like Repository Pattern:** Declare an interface, and let the metaclass handle query assembly dynamically.
+* **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.
+* **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.
@@ -44,44 +45,88 @@ It uses advanced Python metaprogramming (`metaclass`) to dynamically generate Mo
 ```text
 .
 ├── README.md
-├── jpa
+├── ppa
 │   ├── __init__.py
 │   ├── config.py         # App bootstrapping, YAML parsing & environment mapping
-│   └── mongo
+│   ├── 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
 
-🛠️ Getting Started
-Prerequisites
-• Python 3.13 or higher
-Installation & Virtual Env Setup
-1. Clone the repository and navigate to its root: cd python-jpa
-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)
+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)
+2. Environment Profile Configuration (`resources/settings-dev.yml`)
+
+```yaml
 mongodb:
   uri: ${MONGO_URI:mongodb://localhost:27017}
-  database: ${MONGO_DB_NAME:jpa_database}
+  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"
+```
+
+## 📖 Usage Example
 
-📖 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 jpa.mongo.interface import DocumentModel, document
+from ppa.mongo.interface import DocumentModel, document
 
 @document(name="users")
 class User(DocumentModel):
@@ -89,10 +134,14 @@ class User(DocumentModel):
     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 jpa.mongo.interface import IRepository, query
+
+```python
+from ppa.mongo.interface import IRepository, query
 from typing import List, Optional
 
 class UserRepository(IRepository[User]):
@@ -105,9 +154,12 @@ class UserRepository(IRepository[User]):
     # 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 jpa.config import close_db_connection
+
+```python
+from ppa.config import close_db_connection
 
 # Initialize repository instance
 user_repo = UserRepository()
@@ -122,6 +174,28 @@ print(f"Found User: {user.email if user else 'Not Found'}")
 
 # Clean up connections on process termination
 close_db_connection()
+```
+
+PostgreSQL repositories follow the same naming conventions with SQL-backed models:
+
+```python
+from pydantic import EmailStr
+from ppa.postgres.interface import EntityModel, IRepository, query, table
+
+@table(name="users")
+class User(EntityModel):
+    username: str
+    email: EmailStr
+    age: int
+
+class UserRepository(IRepository[User]):
+    def find_by_username(self, username: str) -> User | None: ...
+    def count_by_age(self, age: int) -> int: ...
+
+    @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]: ...
+```
+
+## 📜 License
 
-📜 License
 This project is open-source software licensed under the MIT License.

{python_ppa-0.1.5 → python_ppa-0.1.7}/python_ppa.egg-info/SOURCES.txt

@@ -5,6 +5,8 @@ ppa/__init__.py
 ppa/config.py
 ppa/mongo/__init__.py
 ppa/mongo/interface.py
+ppa/postgres/__init__.py
+ppa/postgres/interface.py
 python_ppa.egg-info/PKG-INFO
 python_ppa.egg-info/SOURCES.txt
 python_ppa.egg-info/dependency_links.txt

{python_ppa-0.1.5 → python_ppa-0.1.7}/python_ppa.egg-info/requires.txt

@@ -4,6 +4,7 @@ email-validator==2.3.0
 idna==3.18
 pydantic==2.13.4
 pydantic_core==2.46.4
+psycopg[binary]>=3.2.0
 pymongo==4.17.0
 python-dotenv==1.2.2
 PyYAML==6.0.3

python_ppa-0.1.5/ppa/__init__.py

@@ -1,2 +0,0 @@
-from ppa import mongo
-from ppa import config