python-ppa 0.0.1__tar.gz

python_ppa-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pratyush Kumar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

python_ppa-0.0.1/PKG-INFO

@@ -0,0 +1,127 @@
+Metadata-Version: 2.4
+Name: python-ppa
+Version: 0.0.1
+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-jpa
+
+`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**. 
+
+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
+
+* **JPA-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
+├── jpa
+│   ├── __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-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)
+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:jpa_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 jpa.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 jpa.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 jpa.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.0.1/README.md

@@ -0,0 +1,105 @@
+# python-jpa
+
+`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**. 
+
+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
+
+* **JPA-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
+├── jpa
+│   ├── __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-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)
+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:jpa_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 jpa.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 jpa.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 jpa.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.0.1/jpa/__init__.py

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

python_ppa-0.0.1/jpa/config.py

@@ -0,0 +1,205 @@
+import logging
+import os
+import re
+from pathlib import Path
+from typing import Any
+
+import yaml
+from pymongo import MongoClient
+from dotenv import load_dotenv
+
+# Load local .env variables into system memory at the very beginning
+load_dotenv()
+
+
+def _detect_resources_dir() -> Path:
+    """
+    Implicitly finds the resources directory by checking the execution context (CWD).
+    Falls back to environment variables or the file location if not found.
+    """
+    # 1. Honor explicit override if provided
+    if env_root := os.getenv("PROJECT_ROOT"):
+        return Path(env_root) / "resources"
+
+    # 2. Implicit Discovery: Look at where the application is being executed from
+    cwd = Path.cwd()
+    for parent in [cwd, *cwd.parents]:
+        candidate_dir = parent / "resources"
+        # Verify this directory exists and contains your master settings file
+        if candidate_dir.is_dir() and (candidate_dir / "settings.yml").exists():
+            return candidate_dir
+
+    # 3. Fallback to package-relative directory if all else fails
+    return Path(__file__).resolve().parent / "resources"
+
+
+# Establish dynamic path routing based on runtime context
+RESOURCES_DIR = _detect_resources_dir()
+BASE_DIR = RESOURCES_DIR.parent
+FRAMEWORK_LOGGER_NAME = "framework"
+DEFAULT_FRAMEWORK_LOG_FORMAT = "%(asctime)s | %(levelname)s | %(name)s | %(message)s"
+DEFAULT_FRAMEWORK_LOG_DATE_FORMAT = "%Y-%m-%d %H:%M:%S"
+
+# Regular expression pattern to match ${VAR_NAME} or ${VAR_NAME:fallback_value}
+ENV_VAR_PATTERN = re.compile(r"\$\{(\w+)(?::([^}]+))?}")
+
+
+def _parse_log_level(level_name: str) -> int:
+    normalized_level = str(level_name).upper()
+    level = getattr(logging, normalized_level, None)
+    if not isinstance(level, int):
+        raise ValueError(f"Invalid logging level configured for framework.logging.level: {level_name}")
+    return level
+
+
+def _as_dict(value: Any, *, context: str) -> dict[str, Any]:
+    if value is None:
+        return {}
+    if not isinstance(value, dict):
+        raise TypeError(f"Expected a mapping for {context}, but got {type(value).__name__}.")
+    return value
+
+
+def _load_and_interpolate_yaml(file_path: Path) -> dict[str, Any]:
+    """Reads a configuration file as raw text, swaps environment placeholders, and parses YAML."""
+    if not file_path.exists():
+        raise FileNotFoundError(f"Configuration file missing at: {file_path}")
+
+    with open(file_path, "r", encoding="utf-8") as f:
+        raw_content = f.read()
+
+    def match_replacer(match: re.Match[str]) -> str:
+        env_var_name = match.group(1)
+        fallback_value = match.group(2) or ""
+        # Pull from live environment parameters; defer to fallback if empty
+        return os.getenv(env_var_name, fallback_value)
+
+    # Perform a global substitution across the text body
+    interpolated_content = ENV_VAR_PATTERN.sub(match_replacer, raw_content)
+    loaded = yaml.safe_load(interpolated_content)
+    return _as_dict(loaded, context=str(file_path))
+
+
+class ConfigSettings:
+    def __init__(self):
+        # 1. Bootstrap: Read the master settings.yml to find the active profile
+        master_config_path = RESOURCES_DIR / "settings.yml"
+        master_data = _load_and_interpolate_yaml(master_config_path)
+        app_config = _as_dict(master_data.get("app"), context="settings.app")
+
+        # Safely extract app.profile, defaulting to 'dev' if missing
+        self.profile = str(app_config.get("profile", "dev"))
+
+        # 2. Profile Loading: Read the target profile file (e.g., settings-dev.yml)
+        profile_filename = f"settings-{self.profile}.yml" if self.profile != "prod" else "settings-prod.yml"
+        profile_config_path = RESOURCES_DIR / profile_filename
+
+        self._config_data = _load_and_interpolate_yaml(profile_config_path)
+        mongodb_config = _as_dict(self._config_data.get("mongodb"), context=f"{profile_filename}.mongodb")
+
+        # 3. Expose parameters to the framework
+        self.mongo_uri = mongodb_config.get("uri")
+        self.database_name = mongodb_config.get("database")
+
+        if not isinstance(self.mongo_uri, str) or not self.mongo_uri or not isinstance(self.database_name,
+                                                                                       str) or not self.database_name:
+            raise KeyError(
+                f"Invalid configuration format in {profile_filename}. Missing 'mongodb.uri' or 'mongodb.database'.")
+
+        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")
+        self.framework_logs_enabled = bool(framework_logging_config.get("enabled", False))
+        self.framework_log_level = _parse_log_level(str(framework_logging_config.get("level", "INFO")))
+        self.framework_log_format = str(framework_logging_config.get("format", DEFAULT_FRAMEWORK_LOG_FORMAT))
+        self.framework_log_date_format = str(
+            framework_logging_config.get("date_format", DEFAULT_FRAMEWORK_LOG_DATE_FORMAT))
+
+
+def _configure_framework_logger() -> logging.Logger:
+    logger = logging.getLogger(FRAMEWORK_LOGGER_NAME)
+    logger.handlers.clear()
+    logger.propagate = False
+
+    if settings.framework_logs_enabled:
+        handler = logging.StreamHandler()
+        handler.setFormatter(logging.Formatter(settings.framework_log_format, settings.framework_log_date_format))
+        logger.addHandler(handler)
+        logger.setLevel(settings.framework_log_level)
+    else:
+        logger.addHandler(logging.NullHandler())
+        logger.setLevel(logging.CRITICAL + 1)
+
+    return logger
+
+
+def get_framework_logger(name: str | None = None) -> logging.Logger:
+    if not name:
+        return logging.getLogger(FRAMEWORK_LOGGER_NAME)
+    return logging.getLogger(f"{FRAMEWORK_LOGGER_NAME}.{name}")
+
+
+# --- SINGLETON INITIALIZATION LAYER ---
+# This block triggers exactly once when the app imports this file
+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)
+
+
+def value(place_holder: str) -> Any:
+    """
+    Spring Boot-inspired property extraction tool.
+    Always extracts and returns the raw value immediately from the active configuration sheet.
+    """
+    # 1. Enforce your validation constraint
+    if place_holder.startswith("${") and not place_holder.endswith("}"):
+        raise ValueError(f"Invalid place holder: {place_holder}")
+
+    # 2. Extract key path and optional fallback default value
+    if place_holder.startswith("${") and place_holder.endswith("}"):
+        raw_content = place_holder[2:-1]  # Strip '${' and '}'
+
+        # Support default fallbacks split by a colon (e.g., ${mongodb.uri:mongodb://localhost})
+        if ":" in raw_content:
+            path, default_val = raw_content.split(":", 1)
+            # Basic primitive type-casting
+            if default_val.isdigit():
+                default_val = int(default_val)
+            elif default_val.lower() == "true":
+                default_val = True
+            elif default_val.lower() == "false":
+                default_val = False
+        else:
+            path = raw_content
+            default_val = None
+    else:
+        path = place_holder
+        default_val = None
+
+    # 3. Direct, eager lookup against the live dictionary
+    keys = path.split(".")
+    current_node = settings._config_data
+
+    for key in keys:
+        if isinstance(current_node, dict) and key in current_node:
+            current_node = current_node[key]
+        else:
+            return default_val
+
+    return current_node
+
+
+def get_collection(collection_name: str):
+    """Provides repositories access to the shared single client pool."""
+    return db[collection_name]
+
+
+def close_db_connection():
+    """Gracefully terminates connection pool sockets on shutdown."""
+    framework_logger.debug("Closing MongoDB client connection pool")
+    _mongo_client.close()

python_ppa-0.0.1/jpa/mongo/__init__.py

@@ -0,0 +1,3 @@
+from jpa.mongo.interface import IRepository
+from jpa.mongo.interface import query
+from jpa.mongo.interface import document

python_ppa-0.0.1/jpa/mongo/interface.py

@@ -0,0 +1,296 @@
+import inspect
+import re
+from typing import Any, Callable, ClassVar, Generic, TypeVar, cast, get_args, get_origin, get_type_hints, List
+
+from pydantic import BaseModel
+from bson import ObjectId, errors
+
+from jpa.config import get_collection, get_framework_logger
+
+T = TypeVar("T", bound=BaseModel)
+F = TypeVar("F", bound=Callable[..., Any])
+framework_logger = get_framework_logger("repository")
+
+
+class DocumentModel(BaseModel):
+    __collection_name__: ClassVar[str]
+
+
+def query(definition: dict[str, Any]) -> Callable[[F], F]:
+    """Annotation to specify a custom MongoDB query template."""
+
+    def decorator(func: F) -> F:
+        func.__query_template__ = definition
+        return func
+
+    return decorator
+
+
+def document(name: str) -> Callable[[type[DocumentModel]], type[DocumentModel]]:
+    """Class decorator to bind a Pydantic model to a MongoDB collection."""
+
+    def decorator(cls):
+        cls.__collection_name__ = name
+        return cls
+
+    return decorator
+
+
+class RepositoryMeta(type):
+    def __new__(mcs, name, bases, namespace):
+        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[DocumentModel], entity_cls)
+
+        if not hasattr(typed_entity_cls, "__collection_name__"):
+            raise TypeError(
+                f"RepositoryDefinitionError: The model '{entity_cls.__name__}' "
+                f"used by '{name}' must be annotated with @document(name='...')"
+            )
+
+        cls._entity_cls = typed_entity_cls
+        valid_fields = set(typed_entity_cls.model_fields.keys())
+
+        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:
+                    raise ValueError("Convention does not exists")
+
+                if query_template or is_convention is not None:
+                    hints = get_type_hints(attr_value)
+                    return_type = hints.get("return")
+
+                    if isinstance(query_template, dict):
+                        generated_method = mcs._build_annotated_method(attr_name, attr_value, query_template,
+                                                                       return_type, typed_entity_cls)
+                    else:
+                        generated_method = mcs._build_convention_method(
+                            attr_name,
+                            is_convention,
+                            attr_value,
+                            valid_fields,
+                            return_type,
+                            typed_entity_cls,
+                        )
+
+                    setattr(cls, attr_name, generated_method)
+
+        return cls
+
+    @staticmethod
+    def _extract_entity_cls(cls) -> 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: dict[str, Any],
+            return_type: Any,
+            entity_cls: type[DocumentModel],
+    ) -> 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: list[Any] = []
+            for p_name in param_names:
+                if p_name in bound.arguments:
+                    ordered_args.append(bound.arguments[p_name])
+
+            # Pure dictionary walk for placeholder substitution (no internal casting strings to dates)
+            def substitute_placeholders(node: Any) -> Any:
+                if isinstance(node, str) and node.startswith("?"):
+                    try:
+                        idx = int(node[1:])
+                        return ordered_args[idx]  # Inject whatever object type the user passed
+                    except (ValueError, IndexError):
+                        return node
+                elif isinstance(node, dict):
+                    return {k: substitute_placeholders(v) for k, v in node.items()}
+                elif isinstance(node, list):
+                    return [substitute_placeholders(item) for item in node]
+                return node
+
+            evaluated_query = cast(dict[str, Any], substitute_placeholders(template))
+
+            framework_logger.debug(
+                "Invoked custom query %s.%s with args=%s kwargs=%s",
+                self.__class__.__name__,
+                name,
+                args,
+                kwargs,
+            )
+
+            return execute_dynamic_query(self.collection, evaluated_query, "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[DocumentModel],
+    ) -> 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__}")
+
+        mongo_field = "_id" if field_name == "id" else field_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
+
+            query_dict: dict[str, Any] = {mongo_field: actual_value}
+
+            framework_logger.debug(
+                "Invoked convention query %s.%s using %s=%r",
+                self.__class__.__name__,
+                name,
+                mongo_field,
+                actual_value,
+            )
+
+            return execute_dynamic_query(self.collection, query_dict, prefix, return_type, entity_cls)
+
+        wrapper.__name__ = name
+        wrapper.__qualname__ = f"{entity_cls.__name__}Repository.{name}"
+        return wrapper
+
+
+def cast_primary_keys(node: Any, current_field: str | None = None) -> Any:
+    """Recursively walks a query structure to convert ID strings to native BSON ObjectIds."""
+    if isinstance(node, dict):
+        new_dict: dict[str, Any] = {}
+        for k, v in node.items():
+            next_field = current_field if isinstance(k, str) and k.startswith("$") else k
+            new_dict[k] = cast_primary_keys(v, next_field)
+        return new_dict
+    elif isinstance(node, list):
+        return [cast_primary_keys(item, current_field) for item in node]
+    elif isinstance(node, str) and current_field == "_id":
+        try:
+            return ObjectId(node)
+        except errors.InvalidId:
+            return node
+    return node
+
+
+def execute_dynamic_query(
+        collection: Any,
+        query_dict: dict[str, Any],
+        strategy: str,
+        return_type: Any,
+        entity_cls: type[DocumentModel],
+) -> Any:
+    # Only cast fields checking against the database's internal _id field
+    processed_query = cast_primary_keys(query_dict)
+
+    framework_logger.debug(
+        "Executing MongoDB query on collection [%s] with strategy [%s]: %s",
+        collection.name,
+        strategy,
+        processed_query,
+    )
+
+    origin_type = get_origin(return_type) or return_type
+
+    if strategy == "count_by" or origin_type is int:
+        return collection.count_documents(processed_query)
+
+    if strategy == "exists_by" or origin_type is bool:
+        return collection.count_documents(processed_query, limit=1) > 0
+
+    def sanitize_output(doc: Any) -> Any:
+        if doc and "_id" in doc:
+            doc = dict(doc)
+            doc["_id"] = str(doc["_id"])
+        return doc
+
+    if origin_type is list:
+        cursor = collection.find(processed_query)
+        return [entity_cls.model_validate(sanitize_output(doc)) for doc in cursor]
+
+    doc = collection.find_one(processed_query)
+    return entity_cls.model_validate(sanitize_output(doc)) if doc else None
+
+
+class IRepository(Generic[T], metaclass=RepositoryMeta):
+    def __init__(self):
+        """
+        Automated Framework Constructor.
+        Automatically resolves the target collection name from the
+        Pydantic model's @document decorator metadata.
+        """
+        entity_cls = cast(type[DocumentModel], self._entity_cls)
+        collection_name = entity_cls.__collection_name__
+        self.collection = get_collection(collection_name)
+        framework_logger.debug(
+            "Initialized repository [%s] for collection [%s]",
+            self.__class__.__name__,
+            collection_name,
+        )
+
+    def save(self, pyd_model: T) -> str:
+        data = pyd_model.model_dump(exclude_none=True)
+        inserted_data = self.collection.insert_one(data)
+        return inserted_data.inserted_id
+
+    def save_all(self, pyd_models: List[T]) -> List[str]:
+        data = [pyd_model for pyd_model in pyd_models]
+        inserted_data = self.collection.insert_many(data)
+        return inserted_data.inserted_ids
+
+    def find_all(self) -> list[T]:
+        """
+        Fetches all documents matching a query and maps them safely to
+        the repository's bound Pydantic model.
+        """
+        # 1. Fetch raw cursor streams from MongoDB
+        cursor = self.collection.find()
+
+        # 2. Local serialization helper to clean BSON primary keys
+        def sanitize(doc):
+            if doc and "_id" in doc:
+                doc = dict(doc)
+                doc["_id"] = str(doc["_id"])
+            return doc
+
+        # 3. Instantiate using self._entity_cls (which holds the real model at runtime)
+        return [self._entity_cls(**sanitize(data_dict)) for data_dict in cursor]
+
+    def find(self, query_dict: dict) -> T:
+        data = self.collection.find(query_dict)
+        if not data:
+            raise ValueError("No data found")
+        return dict(data)

python_ppa-0.0.1/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "python-ppa"
+version = "0.0.1"
+description = "JPA-like ORM for Python"
+readme = "README.md"
+requires-python = ">=3.13"
+license = "MIT"
+authors = [
+    { name = "Pratyush Kumar" }
+]
+# Add this block to auto-install your core library requirements
+dependencies = [
+    "annotated-types==0.7.0",
+    "dnspython==2.8.0",
+    "email-validator==2.3.0",
+    "idna==3.18",
+    "pydantic==2.13.4",
+    "pydantic_core==2.46.4",
+    "pymongo==4.17.0",
+    "python-dotenv==1.2.2",
+    "PyYAML==6.0.3",
+    "typing-inspection==0.4.2",
+    "typing_extensions==4.15.0"
+]
+
+[tool.setuptools.packages.find]
+# Automatically discover the 'jpa' package and its nested subpackages (like mongo)
+include = ["jpa*"]

python_ppa-0.0.1/python_ppa.egg-info/PKG-INFO

@@ -0,0 +1,127 @@
+Metadata-Version: 2.4
+Name: python-ppa
+Version: 0.0.1
+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-jpa
+
+`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**. 
+
+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
+
+* **JPA-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
+├── jpa
+│   ├── __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-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)
+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:jpa_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 jpa.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 jpa.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 jpa.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.0.1/python_ppa.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE
+README.md
+pyproject.toml
+jpa/__init__.py
+jpa/config.py
+jpa/mongo/__init__.py
+jpa/mongo/interface.py
+python_ppa.egg-info/PKG-INFO
+python_ppa.egg-info/SOURCES.txt
+python_ppa.egg-info/dependency_links.txt
+python_ppa.egg-info/requires.txt
+python_ppa.egg-info/top_level.txt

python_ppa-0.0.1/python_ppa.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

python_ppa-0.0.1/python_ppa.egg-info/requires.txt

@@ -0,0 +1,11 @@
+annotated-types==0.7.0
+dnspython==2.8.0
+email-validator==2.3.0
+idna==3.18
+pydantic==2.13.4
+pydantic_core==2.46.4
+pymongo==4.17.0
+python-dotenv==1.2.2
+PyYAML==6.0.3
+typing-inspection==0.4.2
+typing_extensions==4.15.0

python_ppa-0.0.1/python_ppa.egg-info/top_level.txt

@@ -0,0 +1 @@
+jpa

python_ppa-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+