aws-python-helper 0.30.1__tar.gz → 0.31.0__tar.gz

{aws_python_helper-0.30.1 → aws_python_helper-0.31.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aws-python-helper
-Version: 0.30.1
+Version: 0.31.0
 Summary: AWS Python Helper Framework
 Author-email: Fabian Claros <neufabiae@gmail.com>
 License: MIT
@@ -60,6 +60,7 @@ All available classes and functions:
 | `FargateTask` | `aws_python_helper.fargate.task_base` | Base class for Fargate tasks |
 | `FargateExecutor` | `aws_python_helper.fargate.executor` | Launches Fargate tasks from Lambda |
 | `fargate_handler` | `aws_python_helper.fargate.handler` | Entry point handler for Fargate |
+| `Repository` | `aws_python_helper.repository.base` | Base class for MongoDB repositories |
 | `MongoJSONEncoder` | `aws_python_helper.utils.json_encoder` | JSON encoder for MongoDB types |
 | `mongo_json_dumps` | `aws_python_helper.utils.json_encoder` | Helper to serialize MongoDB types |
 | `serialize_mongo_types` | `aws_python_helper.utils.serializer` | Recursively serialize MongoDB types |
@@ -489,6 +490,143 @@ class AddressAPI(API):
 
 `self.external_db` is available in `API`, `SQSConsumer`, `Lambda`, and `FargateTask`.
 
+## 🗂️ Repository Pattern
+
+The framework provides a `Repository` base class that eliminates repetitive boilerplate in data access layers. Each repository only declares what collection it uses, whether it belongs to an external cluster, and what indexes to create. The base class handles the MongoDB connection and index creation automatically.
+
+### Properties to override
+
+| Property | Type | Default | Required |
+|----------|------|---------|----------|
+| `collection_name` | `str` | — | **Yes** |
+| `database_name` | `str` | `"core"` | No |
+| `is_external` | `bool` | `False` | No |
+| `cluster_name` | `str` | `None` | Only if `is_external=True` |
+| `indexes` | `list` | `[]` | No |
+
+### Index format
+
+```python
+@property
+def indexes(self):
+    return [
+        {"key": [("field", 1)]},                               # simple ASC
+        {"key": [("field", -1)]},                              # simple DESC
+        {"key": [("f1", 1), ("f2", -1)], "unique": True},     # compound + unique
+        {"key": [("expires_at", 1)], "expireAfterSeconds": 0}, # TTL index
+    ]
+```
+
+Indexes are created automatically in the background on first collection access — no need to call any initialization method.
+
+### Repository on the main cluster (`database_name` defaults to `"core"`)
+
+```python
+from aws_python_helper import Repository
+
+class TownsRepository(Repository):
+
+    @property
+    def collection_name(self):
+        return "towns"
+
+    @property
+    def indexes(self):
+        return [
+            {"key": [("name", 1)]},
+            {"key": [("platform", 1)]},
+        ]
+
+    async def get_available(self, platforms):
+        return await self.collection.find(
+            {"platform": {"$in": platforms}},
+            {"name": 1, "platform": 1}
+        ).to_list(length=None)
+
+    async def find_by_name(self, name):
+        return await self.collection.find_one({"name": name})
+```
+
+### Repository on a different database (not `"core"`)
+
+```python
+from aws_python_helper import Repository
+
+class LandRecordsRepository(Repository):
+
+    @property
+    def database_name(self):
+        return "land_data"
+
+    @property
+    def collection_name(self):
+        return "records"
+
+    @property
+    def indexes(self):
+        return [
+            {"key": [("unique_id", 1)]},
+            {"key": [("owner", 1), ("town", 1)]},
+        ]
+
+    async def bulk_upsert(self, records):
+        from pymongo import UpdateOne
+        operations = [
+            UpdateOne({"unique_id": r["unique_id"]}, {"$set": r}, upsert=True)
+            for r in records
+        ]
+        result = await self.collection.bulk_write(operations)
+        return {"upserted": result.upserted_count, "modified": result.modified_count}
+```
+
+### Repository on an external cluster
+
+```python
+from aws_python_helper import Repository
+
+class AddressRepository(Repository):
+
+    @property
+    def database_name(self):
+        return "smart_data"
+
+    @property
+    def collection_name(self):
+        return "address"
+
+    @property
+    def is_external(self):
+        return True
+
+    @property
+    def cluster_name(self):
+        return "ClusterDockets"  # Must match a name in EXTERNAL_MONGODB_CONNECTIONS
+
+    async def find_by_query(self, query, limit=None):
+        cursor = self.collection.find(query)
+        if limit:
+            cursor = cursor.limit(limit)
+        return await cursor.to_list(length=None)
+```
+
+### Instantiation — no `db` argument needed
+
+```python
+class MyAPI(API):
+
+    @property
+    def towns_repository(self):
+        if not self._towns_repository:
+            self._towns_repository = TownsRepository()  # no args!
+        return self._towns_repository
+
+    async def process(self):
+        towns = await self.towns_repository.get_available(["platform_a", "platform_b"])
+        self.set_body({"towns": towns})
+```
+
+The repository connects itself using the already-initialized `MongoManager` singleton — the same one used by `self.db`. No need to pass `self.db` or any connection object.
+
 ## 🔄 Routing Convention
 
 The framework uses convention over configuration for the routing:

{aws_python_helper-0.30.1 → aws_python_helper-0.31.0}/README.md

@@ -40,6 +40,7 @@ All available classes and functions:
 | `FargateTask` | `aws_python_helper.fargate.task_base` | Base class for Fargate tasks |
 | `FargateExecutor` | `aws_python_helper.fargate.executor` | Launches Fargate tasks from Lambda |
 | `fargate_handler` | `aws_python_helper.fargate.handler` | Entry point handler for Fargate |
+| `Repository` | `aws_python_helper.repository.base` | Base class for MongoDB repositories |
 | `MongoJSONEncoder` | `aws_python_helper.utils.json_encoder` | JSON encoder for MongoDB types |
 | `mongo_json_dumps` | `aws_python_helper.utils.json_encoder` | Helper to serialize MongoDB types |
 | `serialize_mongo_types` | `aws_python_helper.utils.serializer` | Recursively serialize MongoDB types |
@@ -469,6 +470,143 @@ class AddressAPI(API):
 
 `self.external_db` is available in `API`, `SQSConsumer`, `Lambda`, and `FargateTask`.
 
+## 🗂️ Repository Pattern
+
+The framework provides a `Repository` base class that eliminates repetitive boilerplate in data access layers. Each repository only declares what collection it uses, whether it belongs to an external cluster, and what indexes to create. The base class handles the MongoDB connection and index creation automatically.
+
+### Properties to override
+
+| Property | Type | Default | Required |
+|----------|------|---------|----------|
+| `collection_name` | `str` | — | **Yes** |
+| `database_name` | `str` | `"core"` | No |
+| `is_external` | `bool` | `False` | No |
+| `cluster_name` | `str` | `None` | Only if `is_external=True` |
+| `indexes` | `list` | `[]` | No |
+
+### Index format
+
+```python
+@property
+def indexes(self):
+    return [
+        {"key": [("field", 1)]},                               # simple ASC
+        {"key": [("field", -1)]},                              # simple DESC
+        {"key": [("f1", 1), ("f2", -1)], "unique": True},     # compound + unique
+        {"key": [("expires_at", 1)], "expireAfterSeconds": 0}, # TTL index
+    ]
+```
+
+Indexes are created automatically in the background on first collection access — no need to call any initialization method.
+
+### Repository on the main cluster (`database_name` defaults to `"core"`)
+
+```python
+from aws_python_helper import Repository
+
+class TownsRepository(Repository):
+
+    @property
+    def collection_name(self):
+        return "towns"
+
+    @property
+    def indexes(self):
+        return [
+            {"key": [("name", 1)]},
+            {"key": [("platform", 1)]},
+        ]
+
+    async def get_available(self, platforms):
+        return await self.collection.find(
+            {"platform": {"$in": platforms}},
+            {"name": 1, "platform": 1}
+        ).to_list(length=None)
+
+    async def find_by_name(self, name):
+        return await self.collection.find_one({"name": name})
+```
+
+### Repository on a different database (not `"core"`)
+
+```python
+from aws_python_helper import Repository
+
+class LandRecordsRepository(Repository):
+
+    @property
+    def database_name(self):
+        return "land_data"
+
+    @property
+    def collection_name(self):
+        return "records"
+
+    @property
+    def indexes(self):
+        return [
+            {"key": [("unique_id", 1)]},
+            {"key": [("owner", 1), ("town", 1)]},
+        ]
+
+    async def bulk_upsert(self, records):
+        from pymongo import UpdateOne
+        operations = [
+            UpdateOne({"unique_id": r["unique_id"]}, {"$set": r}, upsert=True)
+            for r in records
+        ]
+        result = await self.collection.bulk_write(operations)
+        return {"upserted": result.upserted_count, "modified": result.modified_count}
+```
+
+### Repository on an external cluster
+
+```python
+from aws_python_helper import Repository
+
+class AddressRepository(Repository):
+
+    @property
+    def database_name(self):
+        return "smart_data"
+
+    @property
+    def collection_name(self):
+        return "address"
+
+    @property
+    def is_external(self):
+        return True
+
+    @property
+    def cluster_name(self):
+        return "ClusterDockets"  # Must match a name in EXTERNAL_MONGODB_CONNECTIONS
+
+    async def find_by_query(self, query, limit=None):
+        cursor = self.collection.find(query)
+        if limit:
+            cursor = cursor.limit(limit)
+        return await cursor.to_list(length=None)
+```
+
+### Instantiation — no `db` argument needed
+
+```python
+class MyAPI(API):
+
+    @property
+    def towns_repository(self):
+        if not self._towns_repository:
+            self._towns_repository = TownsRepository()  # no args!
+        return self._towns_repository
+
+    async def process(self):
+        towns = await self.towns_repository.get_available(["platform_a", "platform_b"])
+        self.set_body({"towns": towns})
+```
+
+The repository connects itself using the already-initialized `MongoManager` singleton — the same one used by `self.db`. No need to pass `self.db` or any connection object.
+
 ## 🔄 Routing Convention
 
 The framework uses convention over configuration for the routing:

{aws_python_helper-0.30.1 → aws_python_helper-0.31.0}/aws_python_helper/__init__.py

@@ -24,6 +24,9 @@ from .lambda_standalone.handler import lambda_handler
 from .utils.json_encoder import MongoJSONEncoder, mongo_json_dumps
 from .utils.serializer import serialize_mongo_types
 
+# Repository
+from .repository.base import Repository
+
 
 __all__ = [
     'API',
@@ -34,6 +37,7 @@ __all__ = [
     'FargateTask',
     'FargateExecutor',
     'Lambda',
+    'Repository',
     'fargate_handler',
     'api_handler',
     'sqs_handler',

aws_python_helper-0.31.0/aws_python_helper/repository/__init__.py

@@ -0,0 +1,3 @@
+from .base import Repository
+
+__all__ = ['Repository']

aws_python_helper-0.31.0/aws_python_helper/repository/base.py

@@ -0,0 +1,188 @@
+"""
+Repository Base - Base class for all MongoDB repository classes.
+
+Eliminates boilerplate by providing automatic connection management,
+collection access, and index creation without requiring the user to
+pass a database connection or call any initialization method.
+"""
+
+import asyncio
+import logging
+from abc import ABC, abstractmethod
+from typing import Any, Dict, List, Optional
+
+from ..database.mongo_manager import MongoManager
+from ..database.external_mongo_manager import ExternalMongoManager
+
+
+class Repository(ABC):
+    """
+    Base class for all MongoDB repositories.
+
+    Subclasses only need to declare which collection they use,
+    whether it is external, and what indexes to create.
+    The connection and index creation are handled automatically.
+
+    Required properties to override:
+        collection_name (str): Name of the MongoDB collection.
+
+    Optional properties to override:
+        database_name (str): Name of the database. Default: "core".
+        is_external (bool): Whether to use an external cluster. Default: False.
+        cluster_name (str): External cluster name. Required if is_external=True.
+        indexes (list): List of index definitions to create automatically.
+
+    Usage:
+        class TownsRepository(Repository):
+
+            @property
+            def collection_name(self):
+                return "towns"
+
+            @property
+            def indexes(self):
+                return [
+                    {"key": [("name", 1)]},
+                    {"key": [("platform", 1)]},
+                ]
+
+            async def get_all(self):
+                return await self.collection.find({}).to_list(length=None)
+
+        # Instantiate without passing any db connection
+        repo = TownsRepository()
+
+    External cluster usage:
+        class AddressRepository(Repository):
+
+            @property
+            def database_name(self):
+                return "smart_data"
+
+            @property
+            def collection_name(self):
+                return "address"
+
+            @property
+            def is_external(self):
+                return True
+
+            @property
+            def cluster_name(self):
+                return "ClusterDockets"
+    """
+
+    def __init__(self):
+        self.logger = logging.getLogger(self.__class__.__name__)
+        self._indexes_created = False
+        self._collection_ref = None
+
+    @property
+    @abstractmethod
+    def collection_name(self) -> str:
+        """Name of the MongoDB collection."""
+        ...
+
+    @property
+    def database_name(self) -> str:
+        """Name of the MongoDB database. Default: 'core'."""
+        return "core"
+
+    @property
+    def is_external(self) -> bool:
+        """Whether this repository uses an external MongoDB cluster. Default: False."""
+        return False
+
+    @property
+    def cluster_name(self) -> Optional[str]:
+        """
+        Name of the external cluster to use.
+        Required when is_external=True. Must match a name defined
+        in the EXTERNAL_MONGODB_CONNECTIONS environment variable.
+        """
+        return None
+
+    @property
+    def indexes(self) -> List[Dict[str, Any]]:
+        """
+        List of index definitions to create automatically on first collection access.
+
+        Each item is a dict with a required 'key' field and optional Motor kwargs.
+
+        Example:
+            return [
+                {"key": [("field", 1)]},                               # simple ASC
+                {"key": [("field", -1)]},                              # simple DESC
+                {"key": [("f1", 1), ("f2", -1)], "unique": True},     # compound + unique
+                {"key": [("expires_at", 1)], "expireAfterSeconds": 0}, # TTL index
+            ]
+
+        The 'key' value follows pymongo format: list of (field, direction) tuples.
+        Any additional keys are passed as kwargs to collection.create_index().
+        'background' defaults to True if not specified.
+        """
+        return []
+
+    @property
+    def collection(self):
+        """
+        Lazy-loaded reference to the Motor collection.
+
+        Resolves the collection from MongoManager (main cluster) or
+        ExternalMongoManager (external cluster) based on is_external.
+
+        On first access, schedules index creation as a background asyncio task
+        so indexes are created without blocking the caller.
+        """
+        if self._collection_ref is None:
+            if self.is_external:
+                if not self.cluster_name:
+                    raise ValueError(
+                        f"{self.__class__.__name__}: 'cluster_name' is required when is_external=True"
+                    )
+                db = ExternalMongoManager.get_database(self.cluster_name, self.database_name)
+            else:
+                db = MongoManager.get_database(self.database_name)
+
+            self._collection_ref = db[self.collection_name]
+
+            # Schedule index creation as a background task on the running event loop.
+            # This works because all framework handlers use loop.run_until_complete(),
+            # which keeps the loop running while user code executes.
+            # create_task() simply adds a coroutine to the existing loop queue
+            # without modifying or interrupting it.
+            if self.indexes and not self._indexes_created:
+                try:
+                    asyncio.get_running_loop().create_task(self.ensure_indexes())
+                except RuntimeError:
+                    pass  # No running event loop (e.g. synchronous test context)
+
+        return self._collection_ref
+
+    async def ensure_indexes(self):
+        """
+        Creates all indexes defined in the `indexes` property.
+
+        Called automatically in background on first collection access.
+        Can also be called explicitly at the start of a method when index
+        creation must be guaranteed to complete before proceeding.
+
+        Idempotent: safe to call multiple times, only runs once.
+        """
+        if self._indexes_created:
+            return
+
+        for index_def in self.indexes:
+            key = index_def.get("key")
+            if not key:
+                self.logger.warning(f"Index definition missing 'key': {index_def}")
+                continue
+            options = {k: v for k, v in index_def.items() if k != "key"}
+            options.setdefault("background", True)
+            try:
+                await self.collection.create_index(key, **options)
+                self.logger.debug(f"Index created: {key}")
+            except Exception as e:
+                self.logger.error(f"Error creating index {key}: {e}")
+
+        self._indexes_created = True

{aws_python_helper-0.30.1 → aws_python_helper-0.31.0}/aws_python_helper.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aws-python-helper
-Version: 0.30.1
+Version: 0.31.0
 Summary: AWS Python Helper Framework
 Author-email: Fabian Claros <neufabiae@gmail.com>
 License: MIT
@@ -60,6 +60,7 @@ All available classes and functions:
 | `FargateTask` | `aws_python_helper.fargate.task_base` | Base class for Fargate tasks |
 | `FargateExecutor` | `aws_python_helper.fargate.executor` | Launches Fargate tasks from Lambda |
 | `fargate_handler` | `aws_python_helper.fargate.handler` | Entry point handler for Fargate |
+| `Repository` | `aws_python_helper.repository.base` | Base class for MongoDB repositories |
 | `MongoJSONEncoder` | `aws_python_helper.utils.json_encoder` | JSON encoder for MongoDB types |
 | `mongo_json_dumps` | `aws_python_helper.utils.json_encoder` | Helper to serialize MongoDB types |
 | `serialize_mongo_types` | `aws_python_helper.utils.serializer` | Recursively serialize MongoDB types |
@@ -489,6 +490,143 @@ class AddressAPI(API):
 
 `self.external_db` is available in `API`, `SQSConsumer`, `Lambda`, and `FargateTask`.
 
+## 🗂️ Repository Pattern
+
+The framework provides a `Repository` base class that eliminates repetitive boilerplate in data access layers. Each repository only declares what collection it uses, whether it belongs to an external cluster, and what indexes to create. The base class handles the MongoDB connection and index creation automatically.
+
+### Properties to override
+
+| Property | Type | Default | Required |
+|----------|------|---------|----------|
+| `collection_name` | `str` | — | **Yes** |
+| `database_name` | `str` | `"core"` | No |
+| `is_external` | `bool` | `False` | No |
+| `cluster_name` | `str` | `None` | Only if `is_external=True` |
+| `indexes` | `list` | `[]` | No |
+
+### Index format
+
+```python
+@property
+def indexes(self):
+    return [
+        {"key": [("field", 1)]},                               # simple ASC
+        {"key": [("field", -1)]},                              # simple DESC
+        {"key": [("f1", 1), ("f2", -1)], "unique": True},     # compound + unique
+        {"key": [("expires_at", 1)], "expireAfterSeconds": 0}, # TTL index
+    ]
+```
+
+Indexes are created automatically in the background on first collection access — no need to call any initialization method.
+
+### Repository on the main cluster (`database_name` defaults to `"core"`)
+
+```python
+from aws_python_helper import Repository
+
+class TownsRepository(Repository):
+
+    @property
+    def collection_name(self):
+        return "towns"
+
+    @property
+    def indexes(self):
+        return [
+            {"key": [("name", 1)]},
+            {"key": [("platform", 1)]},
+        ]
+
+    async def get_available(self, platforms):
+        return await self.collection.find(
+            {"platform": {"$in": platforms}},
+            {"name": 1, "platform": 1}
+        ).to_list(length=None)
+
+    async def find_by_name(self, name):
+        return await self.collection.find_one({"name": name})
+```
+
+### Repository on a different database (not `"core"`)
+
+```python
+from aws_python_helper import Repository
+
+class LandRecordsRepository(Repository):
+
+    @property
+    def database_name(self):
+        return "land_data"
+
+    @property
+    def collection_name(self):
+        return "records"
+
+    @property
+    def indexes(self):
+        return [
+            {"key": [("unique_id", 1)]},
+            {"key": [("owner", 1), ("town", 1)]},
+        ]
+
+    async def bulk_upsert(self, records):
+        from pymongo import UpdateOne
+        operations = [
+            UpdateOne({"unique_id": r["unique_id"]}, {"$set": r}, upsert=True)
+            for r in records
+        ]
+        result = await self.collection.bulk_write(operations)
+        return {"upserted": result.upserted_count, "modified": result.modified_count}
+```
+
+### Repository on an external cluster
+
+```python
+from aws_python_helper import Repository
+
+class AddressRepository(Repository):
+
+    @property
+    def database_name(self):
+        return "smart_data"
+
+    @property
+    def collection_name(self):
+        return "address"
+
+    @property
+    def is_external(self):
+        return True
+
+    @property
+    def cluster_name(self):
+        return "ClusterDockets"  # Must match a name in EXTERNAL_MONGODB_CONNECTIONS
+
+    async def find_by_query(self, query, limit=None):
+        cursor = self.collection.find(query)
+        if limit:
+            cursor = cursor.limit(limit)
+        return await cursor.to_list(length=None)
+```
+
+### Instantiation — no `db` argument needed
+
+```python
+class MyAPI(API):
+
+    @property
+    def towns_repository(self):
+        if not self._towns_repository:
+            self._towns_repository = TownsRepository()  # no args!
+        return self._towns_repository
+
+    async def process(self):
+        towns = await self.towns_repository.get_available(["platform_a", "platform_b"])
+        self.set_body({"towns": towns})
+```
+
+The repository connects itself using the already-initialized `MongoManager` singleton — the same one used by `self.db`. No need to pass `self.db` or any connection object.
+
 ## 🔄 Routing Convention
 
 The framework uses convention over configuration for the routing:

{aws_python_helper-0.30.1 → aws_python_helper-0.31.0}/aws_python_helper.egg-info/SOURCES.txt

@@ -28,6 +28,8 @@ aws_python_helper/lambda_standalone/__init__.py
 aws_python_helper/lambda_standalone/base.py
 aws_python_helper/lambda_standalone/fetcher.py
 aws_python_helper/lambda_standalone/handler.py
+aws_python_helper/repository/__init__.py
+aws_python_helper/repository/base.py
 aws_python_helper/sns/__init__.py
 aws_python_helper/sns/publisher.py
 aws_python_helper/sqs/__init__.py

{aws_python_helper-0.30.1 → aws_python_helper-0.31.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "aws-python-helper"
-version = "0.30.1"
+version = "0.31.0"
 description = "AWS Python Helper Framework"
 readme = "README.md"
 requires-python = ">=3.9"