python-ppa 0.1.4__tar.gz → 0.1.6__tar.gz

{python_ppa-0.1.4 → python_ppa-0.1.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-ppa
-Version: 0.1.4
+Version: 0.1.6
 Summary: JPA-like ORM for Python
 Author: Pratyush Kumar
 License-Expression: MIT
@@ -20,9 +20,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 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.
 
@@ -30,7 +30,7 @@ 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.
 * **Data Validation:** Fully powered by Pydantic v2 for robust runtime type checking and parsing.
@@ -44,7 +44,7 @@ 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
@@ -57,7 +57,7 @@ It uses advanced Python metaprogramming (`metaclass`) to dynamically generate Mo
 Prerequisites
 • Python 3.13 or higher
 Installation & Virtual Env Setup
-1. Clone the repository and navigate to its root: cd python-jpa
+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
@@ -70,7 +70,7 @@ app:
 2. Environment Profile Configuration (resources/settings-dev.yml)
 mongodb:
   uri: ${MONGO_URI:mongodb://localhost:27017}
-  database: ${MONGO_DB_NAME:jpa_database}
+  database: ${MONGO_DB_NAME:ppa_database}
 
 framework:
   logging:
@@ -81,7 +81,7 @@ framework:
 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
+from ppa.mongo.interface import DocumentModel, document
 
 @document(name="users")
 class User(DocumentModel):
@@ -92,7 +92,7 @@ class User(DocumentModel):
 
 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 ppa.mongo.interface import IRepository, query
 from typing import List, Optional
 
 class UserRepository(IRepository[User]):
@@ -107,7 +107,7 @@ class UserRepository(IRepository[User]):
     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
+from ppa.config import close_db_connection
 
 # Initialize repository instance
 user_repo = UserRepository()

{python_ppa-0.1.4 → python_ppa-0.1.6}/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 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.
 
@@ -8,7 +8,7 @@ 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.
 * **Data Validation:** Fully powered by Pydantic v2 for robust runtime type checking and parsing.
@@ -22,7 +22,7 @@ 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
@@ -35,7 +35,7 @@ It uses advanced Python metaprogramming (`metaclass`) to dynamically generate Mo
 Prerequisites
 • Python 3.13 or higher
 Installation & Virtual Env Setup
-1. Clone the repository and navigate to its root: cd python-jpa
+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
@@ -48,7 +48,7 @@ app:
 2. Environment Profile Configuration (resources/settings-dev.yml)
 mongodb:
   uri: ${MONGO_URI:mongodb://localhost:27017}
-  database: ${MONGO_DB_NAME:jpa_database}
+  database: ${MONGO_DB_NAME:ppa_database}
 
 framework:
   logging:
@@ -59,7 +59,7 @@ framework:
 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
+from ppa.mongo.interface import DocumentModel, document
 
 @document(name="users")
 class User(DocumentModel):
@@ -70,7 +70,7 @@ class User(DocumentModel):
 
 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 ppa.mongo.interface import IRepository, query
 from typing import List, Optional
 
 class UserRepository(IRepository[User]):
@@ -85,7 +85,7 @@ class UserRepository(IRepository[User]):
     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
+from ppa.config import close_db_connection
 
 # Initialize repository instance
 user_repo = UserRepository()

python_ppa-0.1.6/ppa/mongo/__init__.py

@@ -0,0 +1,4 @@
+from ppa.mongo.interface import IRepository
+from ppa.mongo.interface import query
+from ppa.mongo.interface import document
+from ppa.mongo.interface import DocumentModel

{python_ppa-0.1.4 → python_ppa-0.1.6}/ppa/mongo/interface.py

@@ -1,27 +1,64 @@
 import inspect
 import re
-from typing import Any, Callable, ClassVar, Generic, TypeVar, cast, get_args, get_origin, get_type_hints, List
-from unittest import result
+from typing import Any, Callable, ClassVar, Generic, Optional, TypeVar, cast, get_args, get_origin, get_type_hints, List
 
-from pydantic import BaseModel, ConfigDict
+from pydantic import BaseModel, ConfigDict, Field
 from bson import ObjectId, errors
 
 from ppa.config import get_collection, get_framework_logger
 
-T = TypeVar("T", bound=BaseModel)
+T = TypeVar("T", bound='DocumentModel')
 F = TypeVar("F", bound=Callable[..., Any])
 framework_logger = get_framework_logger("repository")
 
-DEFAULT_DOCUMENT_CONFIG = dict[str, Any] = {
-    "populate_by_name": True,
-    "arbitrary_types_allowed": True,
-    "json_encoders": {ObjectId: str}
-}
-
 
 class DocumentModel(BaseModel):
+    """
+    Base class for all MongoDB models.
+    Inherits default configurations and the standard MongoDB _id mapping.
+    """
     __collection_name__: ClassVar[str]
 
+    # Automatically inherited and merged by child models
+    model_config = ConfigDict(
+        populate_by_name=True,
+        arbitrary_types_allowed=True,
+        json_encoders={ObjectId: str}
+    )
+
+    # Universal MongoDB _id mapping
+    id: Optional[ObjectId] = Field(default=None, alias="_id")
+
+    def model_dump(self, **kwargs: Any) -> dict[str, Any]:
+        """
+        Overrides default Pydantic dump to ensure MongoDB compatibility.
+        Defaults to excluding None values and using aliases (id -> _id).
+        """
+        kwargs.setdefault("exclude_none", True)
+        kwargs.setdefault("by_alias", True)
+        return super().model_dump(**kwargs)
+
+
+# Inherit from list[T] so we can use DocumentList[User], DocumentList[Booking], etc.
+class DocumentList(list[T]):
+    """
+    List of documents that can be used to perform bulk operations.
+    Inherits default configurations
+    """
+
+    def model_dump(self, **kwargs: Any) -> list[dict[str, Any]]:
+        return [doc.model_dump(**kwargs) for doc in self]
+
+    @classmethod
+    def model_validate(cls, obj: list[Any], entity_cls: type[T]) -> 'DocumentList[T]':
+        """
+        Validates a list of raw dictionaries and returns a populated DocumentList.
+        We pass `entity_cls` because generic type T is erased at runtime.
+        """
+        if not isinstance(obj, list) and not hasattr(obj, "__iter__"):
+            raise ValueError("Data provided to DocumentList.model_validate must be iterable.")
+
+        return cls([entity_cls.model_validate(item) for item in obj])
 
 def query(definition: dict[str, Any]) -> Callable[[F], F]:
     """Annotation to specify a custom MongoDB query template."""
@@ -38,20 +75,6 @@ def document(name: str) -> Callable[[type[DocumentModel]], type[DocumentModel]]:
 
     def decorator(cls):
         cls.__collection_name__ = name
-        current_cfs = dict(getattr(cls, "model_config", {}) or {})
-        current_encoders = dict(current_cfs.get("json_encoders", {}) or {})
-        merged_encoders = {
-            **DEFAULT_DOCUMENT_CONFIG["json_encoders"],
-            **current_encoders
-        }
-        merged_cfs = {
-            **DEFAULT_DOCUMENT_CONFIG["model_config"],
-            **current_cfs,
-            "json_encoders": merged_encoders,
-        }
-        cls.model_config = ConfigDict(**merged_cfs)
-        if hasattr(cls, "model_rebuild"):
-            cls.model_rebuild(force=True)
         return cls
 
     return decorator
@@ -86,8 +109,8 @@ class RepositoryMeta(type):
                 is_convention = re.match(r"(find_by|find_all_by|exists_by|count_by)_(.*)", attr_name)
 
                 if not is_convention:
-                    framework_logger.info("Convention does not exists, relying on user implementation")
-                    return cls
+                    framework_logger.info("Convention does not exist, relying on user implementation")
+                    continue
 
                 if query_template or is_convention is not None:
                     hints = get_type_hints(attr_value)
@@ -139,12 +162,11 @@ class RepositoryMeta(type):
                 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
+                        return ordered_args[idx]
                     except (ValueError, IndexError):
                         return node
                 elif isinstance(node, dict):
@@ -193,6 +215,13 @@ class RepositoryMeta(type):
             bound.apply_defaults()
             actual_value = bound.arguments.get(param_names[0]) if param_names else None
 
+            # Convert string IDs to ObjectId if querying against _id
+            if mongo_field == "_id" and isinstance(actual_value, str):
+                try:
+                    actual_value = ObjectId(actual_value)
+                except errors.InvalidId:
+                    pass
+
             query_dict: dict[str, Any] = {mongo_field: actual_value}
 
             framework_logger.debug(
@@ -235,7 +264,6 @@ def execute_dynamic_query(
         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(
@@ -253,18 +281,15 @@ def execute_dynamic_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:
+    # UPDATE: Support both standard lists and our new DocumentList
+    if origin_type in (list, DocumentList):
         cursor = collection.find(processed_query)
-        return [entity_cls.model_validate(sanitize_output(doc)) for doc in cursor]
+        results = [entity_cls.model_validate(doc) for doc in cursor]
+        # Return the specific list type requested
+        return DocumentList(results) if origin_type is DocumentList else results
 
     doc = collection.find_one(processed_query)
-    return entity_cls.model_validate(sanitize_output(doc)) if doc else None
+    return entity_cls.model_validate(doc) if doc else None
 
 
 class IRepository(Generic[T], metaclass=RepositoryMeta):
@@ -284,43 +309,31 @@ class IRepository(Generic[T], metaclass=RepositoryMeta):
         )
 
     def save(self, pyd_model: T) -> str:
-        data = pyd_model.model_dump(exclude_none=True)
+        # Base model override handles exclude_none and by_alias automatically
+        data = pyd_model.model_dump()
         inserted_data = self.collection.insert_one(data)
-        return inserted_data.inserted_id
+        return str(inserted_data.inserted_id)
 
     def save_all(self, pyd_models: List[T]) -> List[str]:
-        data = [pyd_model for pyd_model in pyd_models]
+        data = [pyd_model.model_dump() for pyd_model in pyd_models]
         inserted_data = self.collection.insert_many(data)
-        return inserted_data.inserted_ids
+        return [str(obj_id) for obj_id in 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
+    def find_all(self) -> DocumentList[T]:
         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(**dict(data_dict)) for data_dict in cursor]
+        # UPDATE: Wrap the list comprehension in DocumentList
+        return DocumentList([self._entity_cls.model_validate(doc) for doc in cursor])
 
     def find(self, query_dict: dict) -> T:
-        data = self.collection.find(query_dict)
+        data = self.collection.find_one(query_dict)
         if not data:
             raise ValueError("No data found")
-        return dict(data)
+        return self._entity_cls.model_validate(data)
 
     def delete(self, resource_id: str) -> bool:
         query_result = self.collection.delete_one({"_id": ObjectId(resource_id)})
         return query_result.deleted_count > 0
 
-    def update(self, resource_id: str, data:dict):
+    def update(self, resource_id: str, data: dict) -> bool:
         query_result = self.collection.update_one({"_id": ObjectId(resource_id)}, {"$set": data})
         return query_result.modified_count > 0

{python_ppa-0.1.4 → python_ppa-0.1.6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-ppa"
-version = "0.1.4"
+version = "0.1.6"
 description = "JPA-like ORM for Python"
 readme = "README.md"
 requires-python = ">=3.13"

{python_ppa-0.1.4 → python_ppa-0.1.6}/python_ppa.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-ppa
-Version: 0.1.4
+Version: 0.1.6
 Summary: JPA-like ORM for Python
 Author: Pratyush Kumar
 License-Expression: MIT
@@ -20,9 +20,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 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.
 
@@ -30,7 +30,7 @@ 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.
 * **Data Validation:** Fully powered by Pydantic v2 for robust runtime type checking and parsing.
@@ -44,7 +44,7 @@ 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
@@ -57,7 +57,7 @@ It uses advanced Python metaprogramming (`metaclass`) to dynamically generate Mo
 Prerequisites
 • Python 3.13 or higher
 Installation & Virtual Env Setup
-1. Clone the repository and navigate to its root: cd python-jpa
+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
@@ -70,7 +70,7 @@ app:
 2. Environment Profile Configuration (resources/settings-dev.yml)
 mongodb:
   uri: ${MONGO_URI:mongodb://localhost:27017}
-  database: ${MONGO_DB_NAME:jpa_database}
+  database: ${MONGO_DB_NAME:ppa_database}
 
 framework:
   logging:
@@ -81,7 +81,7 @@ framework:
 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
+from ppa.mongo.interface import DocumentModel, document
 
 @document(name="users")
 class User(DocumentModel):
@@ -92,7 +92,7 @@ class User(DocumentModel):
 
 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 ppa.mongo.interface import IRepository, query
 from typing import List, Optional
 
 class UserRepository(IRepository[User]):
@@ -107,7 +107,7 @@ class UserRepository(IRepository[User]):
     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
+from ppa.config import close_db_connection
 
 # Initialize repository instance
 user_repo = UserRepository()

python_ppa-0.1.4/ppa/mongo/__init__.py

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