aws-python-helper 1.0.0__tar.gz → 1.0.2__tar.gz

{aws_python_helper-1.0.0 → aws_python_helper-1.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aws-python-helper
-Version: 1.0.0
+Version: 1.0.2
 Summary: AWS Python Helper Framework
 Author-email: Fabian Claros <neufabiae@gmail.com>
 License-Expression: MIT
@@ -39,6 +39,7 @@ Mini-framework to create REST APIs, SQS Consumers, SNS Publishers, Fargate Tasks
 - **LambdaInvoker**: Invoke other Lambda functions (sync or async) with built-in error handling
 - **ApiClient**: HTTP client for inter-service communication — resolves service URLs and auth token from environment variables automatically
 - **ModelQueryLambda**: Base class for MongoDB query-proxy Lambdas — declare an `allowed_collections` whitelist and the framework handles `find` and `aggregate` operations generically
+- **ModelIndexSyncLambda**: Base class for index-synchronization Lambdas — declare your `repositories` and the framework creates every declared index across the `core` database and all active state databases, idempotently, in a single run (run once per deploy)
 - **JSON utilities**: Automatic serialization of MongoDB types
 - **Type hints**: Modern Python with type annotations
 - **Async/await**: Full support for asynchronous operations
@@ -67,6 +68,7 @@ All available classes and functions:
 | `fargate_handler` | `aws_python_helper.fargate.handler` | Entry point handler for Fargate |
 | `Repository` | `aws_python_helper.repository.base` | Base class for MongoDB repositories |
 | `ModelQueryLambda` | `aws_python_helper` | Generic MongoDB query-proxy Lambda base class |
+| `ModelIndexSyncLambda` | `aws_python_helper` | Index-sync Lambda base class (creates indexes across `core` + all state DBs) |
 | `LambdaInvoker` | `aws_python_helper` | Invoke Lambda functions (sync/async) with error handling |
 | `ApiClient` | `aws_python_helper` | HTTP client for inter-service communication |
 | `LambdaInvocationError` | `aws_python_helper` | Raised when boto3 fails to invoke a Lambda |
@@ -77,6 +79,8 @@ All available classes and functions:
 | `Session` | `aws_python_helper` | Request-scoped session object (state + user) |
 | `get_session` | `aws_python_helper` | Read the current Session from async context |
 | `set_session` | `aws_python_helper` | Set the current Session in async context |
+| `StateValidator` | `aws_python_helper` | Validates a state against `core.states` (cached, active states only) |
+| `InvalidStateError` | `aws_python_helper` | Raised when a state is not found or not active |
 | `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 |
@@ -250,6 +254,15 @@ class GenerateRouteLambda(Lambda):
         }
 ```
 
+> **`requires_state` (session requirement)** — By default (`requires_state = True`) the framework requires the event to carry a `session` with a valid `state` and validates it against `core.states` before running. Override `requires_state` to return `False` for Lambdas that operate across **all** states and must not be tied to a single one (e.g. index synchronization) — the `session`/`state` then becomes optional. See [ModelIndexSyncLambda](#-modelindexsynclambda).
+>
+> ```python
+> class SyncAllStatesLambda(Lambda):
+>     @property
+>     def requires_state(self) -> bool:
+>         return False  # no session.state required; runs across every state
+> ```
+
 **2. Configure the handler** in `src/handlers/lambda_handler.py`:
 
 ```python
@@ -511,7 +524,9 @@ class AddressAPI(API):
 
 ## 🗂️ 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.
+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 it needs. The base class handles the MongoDB connection automatically.
+
+> **Index creation is not triggered at request time.** Declaring `indexes` only *describes* the indexes; it does not create them on collection access (this avoids per-request overhead and half-finished index builds in short-lived Lambda/API runtimes). Indexes are created by the [`ModelIndexSyncLambda`](#-modelindexsynclambda) — run once per deploy — or by calling `await repo.ensure_indexes()` explicitly.
 
 ### Properties to override
 
@@ -542,7 +557,15 @@ def indexes(self):
     ]
 ```
 
-Indexes are created automatically in the background on first collection access — no need to call any initialization method.
+These definitions are consumed by `ensure_indexes()`, which the [`ModelIndexSyncLambda`](#-modelindexsynclambda) runs across the relevant databases at deploy time. `ensure_indexes()` is idempotent (safe to re-run) and accepts an explicit `database_name` so the same state-scoped repository can be materialized in every state database:
+
+```python
+# Create this repository's indexes in a specific database (what the index-sync Lambda does):
+await repo.ensure_indexes(database_name="connecticut")
+
+# Or, with no argument, in the repository's resolved database (database_key or session.state):
+await repo.ensure_indexes()
+```
 
 ### Repository with a fixed database
 
@@ -669,7 +692,7 @@ The framework propagates a `Session` object automatically across the entire asyn
 | Entry point | How the session is read |
 |-------------|-------------------------|
 | **API Gateway** | `constitution-state` header → `session.state` (when `AUTHORIZATION` includes `state`); auth middleware → `session.user` (when includes `user`). Returns `400` if required header is missing |
-| **Standalone Lambda** | `session` dict in the event payload — **required** (must include `state`), raises `ValueError` if missing |
+| **Standalone Lambda** | `session` dict in the event payload — **required by default** (must include `state`), raises `ValueError` if missing. A Lambda can opt out via `requires_state = False` (e.g. `ModelIndexSyncLambda`), making the session optional |
 | **SQS Consumer (single mode)** | Per-record: reads `session` from SNS `MessageAttributes` (Base64-encoded JSON) |
 | **SQS Consumer (batch mode)** | Groups records by `session.state`; calls `process_batch()` once per group with the correct session in context |
 | **Fargate Task** | `SESSION` env var (JSON) — auto-injected by `FargateExecutor` |
@@ -1179,13 +1202,15 @@ Create `src/lambda/model-query/main.py` in the microservice that owns the data:
 ```python
 from aws_python_helper import ModelQueryLambda
 
-class ModelQueryLambda(ModelQueryLambda):
+class OrdersModelQueryLambda(ModelQueryLambda):
 
     @property
     def allowed_collections(self) -> list:
         return ["orders", "customers"]  # whitelist — unlisted collections are rejected
 ```
 
+> **Class discovery:** name your subclass distinctly from the imported base (e.g. `OrdersModelQueryLambda`, not `ModelQueryLambda`). The framework loads the class **defined in the file** — not the imported base — so subclassing an imported concrete base (`ModelQueryLambda`, `ModelIndexSyncLambda`) works without name collisions.
+
 Register the handler in `src/handlers/lambda_handler.py`:
 
 ```python
@@ -1333,6 +1358,114 @@ Always pass `self.session.to_dict()` when calling from an API or Lambda to ensur
 
 ---
 
+## 🧱 ModelIndexSyncLambda
+
+`ModelIndexSyncLambda` is a ready-to-use base class for **creating all of a service's MongoDB indexes deterministically**, in one run. Because index creation is no longer triggered at request time (see the [Repository Pattern](#️-repository-pattern) note), this Lambda is the single source of truth for materializing indexes — typically invoked **once per deploy**.
+
+**Why:** in short-lived Lambda/API runtimes, creating indexes lazily on first access often never finishes (the function responds and freezes). This Lambda creates every declared index up front, `await`-ing each one, idempotently — and across **every** active state database, not just the one of the current request.
+
+### Creating an index-sync Lambda
+
+Create `src/lambda/model-index-sync/main.py` and declare which repositories to sync:
+
+```python
+import aws_python_helper
+
+from repositories.parcels import ParcelsRepository   # state-scoped (database_key = None)
+from repositories.users import UsersRepository       # core (database_key = "core")
+from repositories.tokens import TokensRepository     # core
+
+class OrdersModelIndexSyncLambda(aws_python_helper.ModelIndexSyncLambda):
+
+    @property
+    def repositories(self) -> list:
+        return [ParcelsRepository, UsersRepository, TokensRepository]
+```
+
+Register the handler in `src/handlers/lambda_handler.py`:
+
+```python
+from aws_python_helper.lambda_standalone.handler import lambda_handler
+
+index_sync_handler = lambda_handler('model-index-sync')
+
+__all__ = ["index_sync_handler"]
+```
+
+> Declare repositories **explicitly** (don't auto-discover) so the synced set is intentional. List your own collections; **external** repositories (`is_external = True`) belong to another cluster/service and are typically excluded.
+
+### How it routes each repository
+
+For every repository in the list, the Lambda decides where to create its indexes:
+
+| Repository kind | `database_key` | Target databases |
+|-----------------|----------------|------------------|
+| **Core / fixed** | `"core"` (or any string) | that single database |
+| **State-scoped** | `None` | **every active state**, read from `core.states` where `is_active = true` (e.g. `connecticut`, `new_jersey`, …) |
+
+A state-scoped collection such as `parcels` therefore gets its indexes created in `connecticut`, `new_jersey`, and any other active state — automatically. Creation is idempotent, so re-running it is safe.
+
+This Lambda sets `requires_state = False`: it is not tied to a single state and does not require a `session` in the event.
+
+### Response format
+
+```json
+{
+  "success": true,
+  "data": [
+    {"repository": "ParcelsRepository", "database": "connecticut", "collection": "parcels", "indexes": ["parcel_id_1", "..."]},
+    {"repository": "ParcelsRepository", "database": "new_jersey",  "collection": "parcels", "indexes": ["parcel_id_1", "..."]},
+    {"repository": "UsersRepository",   "database": "core",        "collection": "users",   "indexes": ["email_1"]}
+  ]
+}
+```
+
+### Properties to override / configure
+
+| Property | Default | Purpose |
+|----------|---------|---------|
+| `repositories` | `[]` | **Required.** List of `Repository` subclasses (the classes, not instances) to sync. Empty raises a validation error |
+| `states_database` | `"core"` | Database holding the states collection |
+| `states_collection` | `"states"` | Collection listing the states (filtered by `is_active = true`, field `name`) |
+| `requires_state` | `False` | Inherited override — the Lambda runs across all states, no session required |
+
+### Running it once per deploy (Terraform)
+
+Since deploys are applied manually with Terraform, attach an `aws_lambda_invocation` that runs **on every `apply`**, right after the function code is updated. `timestamp()` changes on every plan, so it always re-runs (creation is idempotent and also picks up any newly-activated state). The `postcondition` fails the `apply` if the sync reports `success = false` (the framework handler returns HTTP 200 with `success = false` on internal errors, so this check is required to surface failures):
+
+```hcl
+module "lambda" {
+  source         = "../../../../../modules/lambda"
+  function_name  = "${...service_name}${var.lambda_name}-${...env}"
+  source_handler = "handlers.lambda_handler.index_sync_handler"
+  timeout        = 300
+  memory_size    = 512
+  # ... mongo + vpc config (same as any other Lambda)
+}
+
+resource "aws_lambda_invocation" "sync_on_deploy" {
+  function_name = module.lambda.lambda_function_name
+  input         = jsonencode({ _invoked_at = timestamp() })  # always changes → always re-runs
+
+  depends_on = [module.lambda]                                # run after the code is updated
+
+  lifecycle {
+    postcondition {
+      condition     = try(jsondecode(self.result).success, false) == true
+      error_message = "Index sync failed during apply: ${self.result}"
+    }
+  }
+}
+```
+
+You can also invoke it manually at any time (e.g. after activating a new state without a code deploy):
+
+```bash
+aws lambda invoke --function-name MyServiceModelIndexSync-dev out.json
+```
+
+---
+
 ## 🏗️ Architecture Overview
 
 Typical flow for event-driven architectures using this framework:

{aws_python_helper-1.0.0 → aws_python_helper-1.0.2}/README.md

@@ -19,6 +19,7 @@ Mini-framework to create REST APIs, SQS Consumers, SNS Publishers, Fargate Tasks
 - **LambdaInvoker**: Invoke other Lambda functions (sync or async) with built-in error handling
 - **ApiClient**: HTTP client for inter-service communication — resolves service URLs and auth token from environment variables automatically
 - **ModelQueryLambda**: Base class for MongoDB query-proxy Lambdas — declare an `allowed_collections` whitelist and the framework handles `find` and `aggregate` operations generically
+- **ModelIndexSyncLambda**: Base class for index-synchronization Lambdas — declare your `repositories` and the framework creates every declared index across the `core` database and all active state databases, idempotently, in a single run (run once per deploy)
 - **JSON utilities**: Automatic serialization of MongoDB types
 - **Type hints**: Modern Python with type annotations
 - **Async/await**: Full support for asynchronous operations
@@ -47,6 +48,7 @@ All available classes and functions:
 | `fargate_handler` | `aws_python_helper.fargate.handler` | Entry point handler for Fargate |
 | `Repository` | `aws_python_helper.repository.base` | Base class for MongoDB repositories |
 | `ModelQueryLambda` | `aws_python_helper` | Generic MongoDB query-proxy Lambda base class |
+| `ModelIndexSyncLambda` | `aws_python_helper` | Index-sync Lambda base class (creates indexes across `core` + all state DBs) |
 | `LambdaInvoker` | `aws_python_helper` | Invoke Lambda functions (sync/async) with error handling |
 | `ApiClient` | `aws_python_helper` | HTTP client for inter-service communication |
 | `LambdaInvocationError` | `aws_python_helper` | Raised when boto3 fails to invoke a Lambda |
@@ -57,6 +59,8 @@ All available classes and functions:
 | `Session` | `aws_python_helper` | Request-scoped session object (state + user) |
 | `get_session` | `aws_python_helper` | Read the current Session from async context |
 | `set_session` | `aws_python_helper` | Set the current Session in async context |
+| `StateValidator` | `aws_python_helper` | Validates a state against `core.states` (cached, active states only) |
+| `InvalidStateError` | `aws_python_helper` | Raised when a state is not found or not active |
 | `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 |
@@ -230,6 +234,15 @@ class GenerateRouteLambda(Lambda):
         }
 ```
 
+> **`requires_state` (session requirement)** — By default (`requires_state = True`) the framework requires the event to carry a `session` with a valid `state` and validates it against `core.states` before running. Override `requires_state` to return `False` for Lambdas that operate across **all** states and must not be tied to a single one (e.g. index synchronization) — the `session`/`state` then becomes optional. See [ModelIndexSyncLambda](#-modelindexsynclambda).
+>
+> ```python
+> class SyncAllStatesLambda(Lambda):
+>     @property
+>     def requires_state(self) -> bool:
+>         return False  # no session.state required; runs across every state
+> ```
+
 **2. Configure the handler** in `src/handlers/lambda_handler.py`:
 
 ```python
@@ -491,7 +504,9 @@ class AddressAPI(API):
 
 ## 🗂️ 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.
+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 it needs. The base class handles the MongoDB connection automatically.
+
+> **Index creation is not triggered at request time.** Declaring `indexes` only *describes* the indexes; it does not create them on collection access (this avoids per-request overhead and half-finished index builds in short-lived Lambda/API runtimes). Indexes are created by the [`ModelIndexSyncLambda`](#-modelindexsynclambda) — run once per deploy — or by calling `await repo.ensure_indexes()` explicitly.
 
 ### Properties to override
 
@@ -522,7 +537,15 @@ def indexes(self):
     ]
 ```
 
-Indexes are created automatically in the background on first collection access — no need to call any initialization method.
+These definitions are consumed by `ensure_indexes()`, which the [`ModelIndexSyncLambda`](#-modelindexsynclambda) runs across the relevant databases at deploy time. `ensure_indexes()` is idempotent (safe to re-run) and accepts an explicit `database_name` so the same state-scoped repository can be materialized in every state database:
+
+```python
+# Create this repository's indexes in a specific database (what the index-sync Lambda does):
+await repo.ensure_indexes(database_name="connecticut")
+
+# Or, with no argument, in the repository's resolved database (database_key or session.state):
+await repo.ensure_indexes()
+```
 
 ### Repository with a fixed database
 
@@ -649,7 +672,7 @@ The framework propagates a `Session` object automatically across the entire asyn
 | Entry point | How the session is read |
 |-------------|-------------------------|
 | **API Gateway** | `constitution-state` header → `session.state` (when `AUTHORIZATION` includes `state`); auth middleware → `session.user` (when includes `user`). Returns `400` if required header is missing |
-| **Standalone Lambda** | `session` dict in the event payload — **required** (must include `state`), raises `ValueError` if missing |
+| **Standalone Lambda** | `session` dict in the event payload — **required by default** (must include `state`), raises `ValueError` if missing. A Lambda can opt out via `requires_state = False` (e.g. `ModelIndexSyncLambda`), making the session optional |
 | **SQS Consumer (single mode)** | Per-record: reads `session` from SNS `MessageAttributes` (Base64-encoded JSON) |
 | **SQS Consumer (batch mode)** | Groups records by `session.state`; calls `process_batch()` once per group with the correct session in context |
 | **Fargate Task** | `SESSION` env var (JSON) — auto-injected by `FargateExecutor` |
@@ -1159,13 +1182,15 @@ Create `src/lambda/model-query/main.py` in the microservice that owns the data:
 ```python
 from aws_python_helper import ModelQueryLambda
 
-class ModelQueryLambda(ModelQueryLambda):
+class OrdersModelQueryLambda(ModelQueryLambda):
 
     @property
     def allowed_collections(self) -> list:
         return ["orders", "customers"]  # whitelist — unlisted collections are rejected
 ```
 
+> **Class discovery:** name your subclass distinctly from the imported base (e.g. `OrdersModelQueryLambda`, not `ModelQueryLambda`). The framework loads the class **defined in the file** — not the imported base — so subclassing an imported concrete base (`ModelQueryLambda`, `ModelIndexSyncLambda`) works without name collisions.
+
 Register the handler in `src/handlers/lambda_handler.py`:
 
 ```python
@@ -1313,6 +1338,114 @@ Always pass `self.session.to_dict()` when calling from an API or Lambda to ensur
 
 ---
 
+## 🧱 ModelIndexSyncLambda
+
+`ModelIndexSyncLambda` is a ready-to-use base class for **creating all of a service's MongoDB indexes deterministically**, in one run. Because index creation is no longer triggered at request time (see the [Repository Pattern](#️-repository-pattern) note), this Lambda is the single source of truth for materializing indexes — typically invoked **once per deploy**.
+
+**Why:** in short-lived Lambda/API runtimes, creating indexes lazily on first access often never finishes (the function responds and freezes). This Lambda creates every declared index up front, `await`-ing each one, idempotently — and across **every** active state database, not just the one of the current request.
+
+### Creating an index-sync Lambda
+
+Create `src/lambda/model-index-sync/main.py` and declare which repositories to sync:
+
+```python
+import aws_python_helper
+
+from repositories.parcels import ParcelsRepository   # state-scoped (database_key = None)
+from repositories.users import UsersRepository       # core (database_key = "core")
+from repositories.tokens import TokensRepository     # core
+
+class OrdersModelIndexSyncLambda(aws_python_helper.ModelIndexSyncLambda):
+
+    @property
+    def repositories(self) -> list:
+        return [ParcelsRepository, UsersRepository, TokensRepository]
+```
+
+Register the handler in `src/handlers/lambda_handler.py`:
+
+```python
+from aws_python_helper.lambda_standalone.handler import lambda_handler
+
+index_sync_handler = lambda_handler('model-index-sync')
+
+__all__ = ["index_sync_handler"]
+```
+
+> Declare repositories **explicitly** (don't auto-discover) so the synced set is intentional. List your own collections; **external** repositories (`is_external = True`) belong to another cluster/service and are typically excluded.
+
+### How it routes each repository
+
+For every repository in the list, the Lambda decides where to create its indexes:
+
+| Repository kind | `database_key` | Target databases |
+|-----------------|----------------|------------------|
+| **Core / fixed** | `"core"` (or any string) | that single database |
+| **State-scoped** | `None` | **every active state**, read from `core.states` where `is_active = true` (e.g. `connecticut`, `new_jersey`, …) |
+
+A state-scoped collection such as `parcels` therefore gets its indexes created in `connecticut`, `new_jersey`, and any other active state — automatically. Creation is idempotent, so re-running it is safe.
+
+This Lambda sets `requires_state = False`: it is not tied to a single state and does not require a `session` in the event.
+
+### Response format
+
+```json
+{
+  "success": true,
+  "data": [
+    {"repository": "ParcelsRepository", "database": "connecticut", "collection": "parcels", "indexes": ["parcel_id_1", "..."]},
+    {"repository": "ParcelsRepository", "database": "new_jersey",  "collection": "parcels", "indexes": ["parcel_id_1", "..."]},
+    {"repository": "UsersRepository",   "database": "core",        "collection": "users",   "indexes": ["email_1"]}
+  ]
+}
+```
+
+### Properties to override / configure
+
+| Property | Default | Purpose |
+|----------|---------|---------|
+| `repositories` | `[]` | **Required.** List of `Repository` subclasses (the classes, not instances) to sync. Empty raises a validation error |
+| `states_database` | `"core"` | Database holding the states collection |
+| `states_collection` | `"states"` | Collection listing the states (filtered by `is_active = true`, field `name`) |
+| `requires_state` | `False` | Inherited override — the Lambda runs across all states, no session required |
+
+### Running it once per deploy (Terraform)
+
+Since deploys are applied manually with Terraform, attach an `aws_lambda_invocation` that runs **on every `apply`**, right after the function code is updated. `timestamp()` changes on every plan, so it always re-runs (creation is idempotent and also picks up any newly-activated state). The `postcondition` fails the `apply` if the sync reports `success = false` (the framework handler returns HTTP 200 with `success = false` on internal errors, so this check is required to surface failures):
+
+```hcl
+module "lambda" {
+  source         = "../../../../../modules/lambda"
+  function_name  = "${...service_name}${var.lambda_name}-${...env}"
+  source_handler = "handlers.lambda_handler.index_sync_handler"
+  timeout        = 300
+  memory_size    = 512
+  # ... mongo + vpc config (same as any other Lambda)
+}
+
+resource "aws_lambda_invocation" "sync_on_deploy" {
+  function_name = module.lambda.lambda_function_name
+  input         = jsonencode({ _invoked_at = timestamp() })  # always changes → always re-runs
+
+  depends_on = [module.lambda]                                # run after the code is updated
+
+  lifecycle {
+    postcondition {
+      condition     = try(jsondecode(self.result).success, false) == true
+      error_message = "Index sync failed during apply: ${self.result}"
+    }
+  }
+}
+```
+
+You can also invoke it manually at any time (e.g. after activating a new state without a code deploy):
+
+```bash
+aws lambda invoke --function-name MyServiceModelIndexSync-dev out.json
+```
+
+---
+
 ## 🏗️ Architecture Overview
 
 Typical flow for event-driven architectures using this framework:

{aws_python_helper-1.0.0 → aws_python_helper-1.0.2}/aws_python_helper/__init__.py

@@ -2,7 +2,7 @@
 AWS Python Framework
 """
 
-__version__ = "0.1.0"
+__version__ = "1.0.2"
 
 # All classes
 from .api.base import API
@@ -34,6 +34,9 @@ from .context.state_validator import StateValidator, InvalidStateError
 # Model Query
 from .model_query import ModelQueryLambda
 
+# Model Index Sync
+from .model_index_sync import ModelIndexSyncLambda
+
 # Invoker
 from .invoker import (
     LambdaInvoker,
@@ -69,6 +72,7 @@ __all__ = [
     'StateValidator',
     'InvalidStateError',
     'ModelQueryLambda',
+    'ModelIndexSyncLambda',
     'LambdaInvoker',
     'ApiClient',
     'LambdaInvocationError',

{aws_python_helper-1.0.0 → aws_python_helper-1.0.2}/aws_python_helper/api/fetcher.py

@@ -190,9 +190,10 @@ class Fetcher:
         controller_class = None
         for item_name in dir(module):
             item = getattr(module, item_name)
-            if (isinstance(item, type) and 
-                hasattr(item, 'process') and 
-                item.__name__ not in ['API', 'ABC']):
+            if (isinstance(item, type) and
+                hasattr(item, 'process') and
+                item.__name__ not in ['API', 'ABC'] and
+                item.__module__ == module.__name__):
                 controller_class = item
                 break
         

{aws_python_helper-1.0.0 → aws_python_helper-1.0.2}/aws_python_helper/fargate/fetcher.py

@@ -98,9 +98,10 @@ class FargateTaskFetcher:
         task_class = None
         for item_name in dir(module):
             item = getattr(module, item_name)
-            if (isinstance(item, type) and 
-                hasattr(item, 'execute') and 
-                item.__name__ not in ['FargateTask', 'ABC']):
+            if (isinstance(item, type) and
+                hasattr(item, 'execute') and
+                item.__name__ not in ['FargateTask', 'ABC'] and
+                item.__module__ == module.__name__):
                 task_class = item
                 break
         

{aws_python_helper-1.0.0 → aws_python_helper-1.0.2}/aws_python_helper/lambda_standalone/base.py

@@ -47,6 +47,21 @@ class Lambda(ABC):
         """
         return get_session()
 
+    @property
+    def requires_state(self) -> bool:
+        """
+        Whether this Lambda requires a valid 'state' in the session.
+
+        Default True: run() enforces that the event carries session.state and
+        validates it against core.states before processing.
+
+        Override to return False for Lambdas that operate across all states and
+        must not be tied to a single one (e.g. index synchronization). When
+        False, a session is still set if provided, but state is not required
+        nor validated.
+        """
+        return True
+
     @property
     def schema(self):
         """
@@ -188,11 +203,15 @@ class Lambda(ABC):
         try:
             # Step 0: Setup session context
             session_data = self.event.get('session')
-            if not session_data or not session_data.get('state'):
-                raise ValueError("'session' with 'state' is required in the event")
-            session = Session.from_dict(session_data)
-            await StateValidator.validate(session.state)
-            set_session(session)
+            if self.requires_state:
+                if not session_data or not session_data.get('state'):
+                    raise ValueError("'session' with 'state' is required in the event")
+                session = Session.from_dict(session_data)
+                await StateValidator.validate(session.state)
+                set_session(session)
+            elif session_data:
+                # state not required, but honor a session if one was provided
+                set_session(Session.from_dict(session_data))
 
             # Step 1: Schema validation (automatic, if schema property is defined)
             if self.schema is not None:

{aws_python_helper-1.0.0 → aws_python_helper-1.0.2}/aws_python_helper/lambda_standalone/fetcher.py

@@ -100,9 +100,10 @@ class LambdaFetcher:
         lambda_class = None
         for item_name in dir(module):
             item = getattr(module, item_name)
-            if (isinstance(item, type) and 
-                issubclass(item, Lambda) and 
-                item.__name__ not in ['Lambda', 'ABC']):
+            if (isinstance(item, type) and
+                issubclass(item, Lambda) and
+                item.__name__ not in ['Lambda', 'ABC'] and
+                item.__module__ == module.__name__):
                 lambda_class = item
                 break
         

aws_python_helper-1.0.2/aws_python_helper/model_index_sync/__init__.py

@@ -0,0 +1,3 @@
+from .base import ModelIndexSyncLambda
+
+__all__ = ["ModelIndexSyncLambda"]

aws_python_helper-1.0.2/aws_python_helper/model_index_sync/base.py

@@ -0,0 +1,114 @@
+"""
+ModelIndexSyncLambda - Synchronizes MongoDB indexes for a service's repositories.
+
+Creates (idempotently) every index declared in the service's repositories, in
+the correct databases:
+  - Repositories with a fixed database_key (e.g. 'core') → that database.
+  - State-scoped repositories (database_key is None) → every active state
+    database, read from core.states (is_active=True). A state-scoped collection
+    (e.g. 'parcels') therefore gets its indexes created in 'connecticut',
+    'new_jersey', etc.
+
+Designed to run once per deploy (and on demand), guaranteeing index creation
+without the per-request overhead of creating indexes at runtime.
+
+Usage — subclass and declare the repositories to sync:
+
+    import aws_python_helper
+    from repositories.parcels import ParcelsRepository
+    from repositories.users import UsersRepository
+
+    class PropertiesModelIndexSyncLambda(aws_python_helper.ModelIndexSyncLambda):
+        @property
+        def repositories(self) -> list:
+            return [ParcelsRepository, UsersRepository]
+
+This Lambda does not require a session state (requires_state = False); it
+operates across all active states.
+
+Response (via Lambda base run()):
+    {"success": True, "data": [
+        {"repository": "ParcelsRepository", "database": "connecticut",
+         "collection": "parcels", "indexes": ["parcel_id_1", ...]},
+        {"repository": "UsersRepository", "database": "core",
+         "collection": "users", "indexes": ["email_1"]},
+        ...
+    ]}
+"""
+
+from typing import Any, List, Type
+
+from ..lambda_standalone.base import Lambda
+from ..repository.base import Repository
+from ..database.mongo_manager import MongoManager
+
+
+class ModelIndexSyncLambda(Lambda):
+    """
+    Base class for index-synchronization Lambdas.
+
+    Subclass and override `repositories` to declare which repositories to sync.
+    Everything else (resolving core vs state-scoped, reading active states and
+    creating the indexes) is handled automatically.
+    """
+
+    @property
+    def requires_state(self) -> bool:
+        # Operates across all states; not tied to a single one.
+        return False
+
+    @property
+    def repositories(self) -> List[Type[Repository]]:
+        """
+        Repositories whose indexes should be synchronized.
+
+        Override returning a list of Repository subclasses (the classes, not
+        instances). Declare them explicitly rather than auto-discovering, so the
+        synced set is intentional and nothing is silently missed or added.
+        """
+        return []
+
+    @property
+    def states_database(self) -> str:
+        """Database holding the states collection. Default: 'core'."""
+        return "core"
+
+    @property
+    def states_collection(self) -> str:
+        """Collection listing the states. Default: 'states'."""
+        return "states"
+
+    async def validate(self):
+        if not self.repositories:
+            raise ValueError(
+                "repositories is not configured on this ModelIndexSyncLambda"
+            )
+
+    async def _active_states(self) -> List[str]:
+        """Names of active states — i.e. the state-scoped database names."""
+        db = MongoManager.get_database(self.states_database)
+        cursor = db[self.states_collection].find(
+            {"is_active": True}, {"name": 1, "_id": 0}
+        )
+        return [doc["name"] async for doc in cursor if doc.get("name")]
+
+    async def process(self) -> Any:
+        active_states = await self._active_states()
+        report: List[dict] = []
+
+        for repo_cls in self.repositories:
+            repo = repo_cls()
+            # database_key is None -> state-scoped (collection repeats per state db).
+            is_state_scoped = repo.database_key is None and not repo.is_external
+            target_databases = active_states if is_state_scoped else [repo.database_name]
+
+            for db_name in target_databases:
+                created = await repo.ensure_indexes(database_name=db_name)
+                report.append({
+                    "repository": repo_cls.__name__,
+                    "database": db_name,
+                    "collection": repo.collection_name,
+                    "indexes": created,
+                })
+
+        return report

{aws_python_helper-1.0.0 → aws_python_helper-1.0.2}/aws_python_helper/repository/base.py

@@ -6,7 +6,6 @@ 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, Tuple
@@ -183,8 +182,9 @@ class Repository(ABC):
         so state-scoped repositories resolve the correct collection for each
         request state without cross-contamination between requests.
 
-        On first access for a given key, schedules index creation as a
-        background asyncio task so indexes are created without blocking the caller.
+        Index creation is NOT triggered here: indexes are created exclusively
+        by the index-sync Lambda (see ensure_indexes), so request-time access
+        carries no index-creation overhead.
         """
         key = (self.database_name, self.collection_name)
 
@@ -200,29 +200,45 @@ class Repository(ABC):
 
             self._collection_cache[key] = db[self.collection_name]
 
-            # Schedule index creation as a background task on the running event loop.
-            if self.indexes and not self._indexes_created.get(key):
-                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_cache[key]
 
-    async def ensure_indexes(self):
+    async def ensure_indexes(self, database_name: Optional[str] = None):
         """
-        Creates all indexes defined in the `indexes` property.
+        Creates all indexes defined in the `indexes` property, blocking until done.
+
+        Args:
+            database_name: Target database to create the indexes in.
+                - If None (default): uses the resolved database_name
+                  (database_key or the current session state).
+                - If set: creates the indexes in that specific database. This is
+                  used by the index-sync Lambda to create the indexes of a
+                  state-scoped repository across every active state database
+                  (e.g. 'connecticut', 'new_jersey', ...).
+
+        Index creation is no longer triggered automatically at request time;
+        call this explicitly (the index-sync Lambda does) to guarantee creation.
 
-        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 per (database, collection): safe to call multiple times.
 
-        Idempotent: safe to call multiple times, only runs once per (database, collection).
+        Returns:
+            List of created index names (as returned by create_index).
         """
-        key = (self.database_name, self.collection_name)
+        db_name = database_name or self.database_name
+        key = (db_name, self.collection_name)
         if self._indexes_created.get(key):
-            return
-
+            return []
+
+        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, db_name)
+        else:
+            db = MongoManager.get_database(db_name)
+        collection = db[self.collection_name]
+
+        created: List[str] = []
         for index_def in self.indexes:
             index_key = index_def.get("key")
             if not index_key:
@@ -231,9 +247,11 @@ class Repository(ABC):
             options = {k: v for k, v in index_def.items() if k != "key"}
             options.setdefault("background", True)
             try:
-                await self.collection.create_index(index_key, **options)
-                self.logger.debug(f"Index created: {index_key}")
+                name = await collection.create_index(index_key, **options)
+                created.append(name)
+                self.logger.debug(f"Index created on '{db_name}.{self.collection_name}': {index_key}")
             except Exception as e:
-                self.logger.error(f"Error creating index {index_key}: {e}")
+                self.logger.error(f"Error creating index {index_key} on '{db_name}': {e}")
 
         self._indexes_created[key] = True
+        return created

{aws_python_helper-1.0.0 → aws_python_helper-1.0.2}/aws_python_helper/sqs/fetcher.py

@@ -91,9 +91,10 @@ class SQSFetcher:
         consumer_class = None
         for item_name in dir(module):
             item = getattr(module, item_name)
-            if (isinstance(item, type) and 
-                hasattr(item, 'process_record') and 
-                item.__name__ not in ['SQSConsumer', 'ABC']):
+            if (isinstance(item, type) and
+                hasattr(item, 'process_record') and
+                item.__name__ not in ['SQSConsumer', 'ABC'] and
+                item.__module__ == module.__name__):
                 consumer_class = item
                 break
         

{aws_python_helper-1.0.0 → aws_python_helper-1.0.2}/aws_python_helper.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aws-python-helper
-Version: 1.0.0
+Version: 1.0.2
 Summary: AWS Python Helper Framework
 Author-email: Fabian Claros <neufabiae@gmail.com>
 License-Expression: MIT
@@ -39,6 +39,7 @@ Mini-framework to create REST APIs, SQS Consumers, SNS Publishers, Fargate Tasks
 - **LambdaInvoker**: Invoke other Lambda functions (sync or async) with built-in error handling
 - **ApiClient**: HTTP client for inter-service communication — resolves service URLs and auth token from environment variables automatically
 - **ModelQueryLambda**: Base class for MongoDB query-proxy Lambdas — declare an `allowed_collections` whitelist and the framework handles `find` and `aggregate` operations generically
+- **ModelIndexSyncLambda**: Base class for index-synchronization Lambdas — declare your `repositories` and the framework creates every declared index across the `core` database and all active state databases, idempotently, in a single run (run once per deploy)
 - **JSON utilities**: Automatic serialization of MongoDB types
 - **Type hints**: Modern Python with type annotations
 - **Async/await**: Full support for asynchronous operations
@@ -67,6 +68,7 @@ All available classes and functions:
 | `fargate_handler` | `aws_python_helper.fargate.handler` | Entry point handler for Fargate |
 | `Repository` | `aws_python_helper.repository.base` | Base class for MongoDB repositories |
 | `ModelQueryLambda` | `aws_python_helper` | Generic MongoDB query-proxy Lambda base class |
+| `ModelIndexSyncLambda` | `aws_python_helper` | Index-sync Lambda base class (creates indexes across `core` + all state DBs) |
 | `LambdaInvoker` | `aws_python_helper` | Invoke Lambda functions (sync/async) with error handling |
 | `ApiClient` | `aws_python_helper` | HTTP client for inter-service communication |
 | `LambdaInvocationError` | `aws_python_helper` | Raised when boto3 fails to invoke a Lambda |
@@ -77,6 +79,8 @@ All available classes and functions:
 | `Session` | `aws_python_helper` | Request-scoped session object (state + user) |
 | `get_session` | `aws_python_helper` | Read the current Session from async context |
 | `set_session` | `aws_python_helper` | Set the current Session in async context |
+| `StateValidator` | `aws_python_helper` | Validates a state against `core.states` (cached, active states only) |
+| `InvalidStateError` | `aws_python_helper` | Raised when a state is not found or not active |
 | `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 |
@@ -250,6 +254,15 @@ class GenerateRouteLambda(Lambda):
         }
 ```
 
+> **`requires_state` (session requirement)** — By default (`requires_state = True`) the framework requires the event to carry a `session` with a valid `state` and validates it against `core.states` before running. Override `requires_state` to return `False` for Lambdas that operate across **all** states and must not be tied to a single one (e.g. index synchronization) — the `session`/`state` then becomes optional. See [ModelIndexSyncLambda](#-modelindexsynclambda).
+>
+> ```python
+> class SyncAllStatesLambda(Lambda):
+>     @property
+>     def requires_state(self) -> bool:
+>         return False  # no session.state required; runs across every state
+> ```
+
 **2. Configure the handler** in `src/handlers/lambda_handler.py`:
 
 ```python
@@ -511,7 +524,9 @@ class AddressAPI(API):
 
 ## 🗂️ 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.
+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 it needs. The base class handles the MongoDB connection automatically.
+
+> **Index creation is not triggered at request time.** Declaring `indexes` only *describes* the indexes; it does not create them on collection access (this avoids per-request overhead and half-finished index builds in short-lived Lambda/API runtimes). Indexes are created by the [`ModelIndexSyncLambda`](#-modelindexsynclambda) — run once per deploy — or by calling `await repo.ensure_indexes()` explicitly.
 
 ### Properties to override
 
@@ -542,7 +557,15 @@ def indexes(self):
     ]
 ```
 
-Indexes are created automatically in the background on first collection access — no need to call any initialization method.
+These definitions are consumed by `ensure_indexes()`, which the [`ModelIndexSyncLambda`](#-modelindexsynclambda) runs across the relevant databases at deploy time. `ensure_indexes()` is idempotent (safe to re-run) and accepts an explicit `database_name` so the same state-scoped repository can be materialized in every state database:
+
+```python
+# Create this repository's indexes in a specific database (what the index-sync Lambda does):
+await repo.ensure_indexes(database_name="connecticut")
+
+# Or, with no argument, in the repository's resolved database (database_key or session.state):
+await repo.ensure_indexes()
+```
 
 ### Repository with a fixed database
 
@@ -669,7 +692,7 @@ The framework propagates a `Session` object automatically across the entire asyn
 | Entry point | How the session is read |
 |-------------|-------------------------|
 | **API Gateway** | `constitution-state` header → `session.state` (when `AUTHORIZATION` includes `state`); auth middleware → `session.user` (when includes `user`). Returns `400` if required header is missing |
-| **Standalone Lambda** | `session` dict in the event payload — **required** (must include `state`), raises `ValueError` if missing |
+| **Standalone Lambda** | `session` dict in the event payload — **required by default** (must include `state`), raises `ValueError` if missing. A Lambda can opt out via `requires_state = False` (e.g. `ModelIndexSyncLambda`), making the session optional |
 | **SQS Consumer (single mode)** | Per-record: reads `session` from SNS `MessageAttributes` (Base64-encoded JSON) |
 | **SQS Consumer (batch mode)** | Groups records by `session.state`; calls `process_batch()` once per group with the correct session in context |
 | **Fargate Task** | `SESSION` env var (JSON) — auto-injected by `FargateExecutor` |
@@ -1179,13 +1202,15 @@ Create `src/lambda/model-query/main.py` in the microservice that owns the data:
 ```python
 from aws_python_helper import ModelQueryLambda
 
-class ModelQueryLambda(ModelQueryLambda):
+class OrdersModelQueryLambda(ModelQueryLambda):
 
     @property
     def allowed_collections(self) -> list:
         return ["orders", "customers"]  # whitelist — unlisted collections are rejected
 ```
 
+> **Class discovery:** name your subclass distinctly from the imported base (e.g. `OrdersModelQueryLambda`, not `ModelQueryLambda`). The framework loads the class **defined in the file** — not the imported base — so subclassing an imported concrete base (`ModelQueryLambda`, `ModelIndexSyncLambda`) works without name collisions.
+
 Register the handler in `src/handlers/lambda_handler.py`:
 
 ```python
@@ -1333,6 +1358,114 @@ Always pass `self.session.to_dict()` when calling from an API or Lambda to ensur
 
 ---
 
+## 🧱 ModelIndexSyncLambda
+
+`ModelIndexSyncLambda` is a ready-to-use base class for **creating all of a service's MongoDB indexes deterministically**, in one run. Because index creation is no longer triggered at request time (see the [Repository Pattern](#️-repository-pattern) note), this Lambda is the single source of truth for materializing indexes — typically invoked **once per deploy**.
+
+**Why:** in short-lived Lambda/API runtimes, creating indexes lazily on first access often never finishes (the function responds and freezes). This Lambda creates every declared index up front, `await`-ing each one, idempotently — and across **every** active state database, not just the one of the current request.
+
+### Creating an index-sync Lambda
+
+Create `src/lambda/model-index-sync/main.py` and declare which repositories to sync:
+
+```python
+import aws_python_helper
+
+from repositories.parcels import ParcelsRepository   # state-scoped (database_key = None)
+from repositories.users import UsersRepository       # core (database_key = "core")
+from repositories.tokens import TokensRepository     # core
+
+class OrdersModelIndexSyncLambda(aws_python_helper.ModelIndexSyncLambda):
+
+    @property
+    def repositories(self) -> list:
+        return [ParcelsRepository, UsersRepository, TokensRepository]
+```
+
+Register the handler in `src/handlers/lambda_handler.py`:
+
+```python
+from aws_python_helper.lambda_standalone.handler import lambda_handler
+
+index_sync_handler = lambda_handler('model-index-sync')
+
+__all__ = ["index_sync_handler"]
+```
+
+> Declare repositories **explicitly** (don't auto-discover) so the synced set is intentional. List your own collections; **external** repositories (`is_external = True`) belong to another cluster/service and are typically excluded.
+
+### How it routes each repository
+
+For every repository in the list, the Lambda decides where to create its indexes:
+
+| Repository kind | `database_key` | Target databases |
+|-----------------|----------------|------------------|
+| **Core / fixed** | `"core"` (or any string) | that single database |
+| **State-scoped** | `None` | **every active state**, read from `core.states` where `is_active = true` (e.g. `connecticut`, `new_jersey`, …) |
+
+A state-scoped collection such as `parcels` therefore gets its indexes created in `connecticut`, `new_jersey`, and any other active state — automatically. Creation is idempotent, so re-running it is safe.
+
+This Lambda sets `requires_state = False`: it is not tied to a single state and does not require a `session` in the event.
+
+### Response format
+
+```json
+{
+  "success": true,
+  "data": [
+    {"repository": "ParcelsRepository", "database": "connecticut", "collection": "parcels", "indexes": ["parcel_id_1", "..."]},
+    {"repository": "ParcelsRepository", "database": "new_jersey",  "collection": "parcels", "indexes": ["parcel_id_1", "..."]},
+    {"repository": "UsersRepository",   "database": "core",        "collection": "users",   "indexes": ["email_1"]}
+  ]
+}
+```
+
+### Properties to override / configure
+
+| Property | Default | Purpose |
+|----------|---------|---------|
+| `repositories` | `[]` | **Required.** List of `Repository` subclasses (the classes, not instances) to sync. Empty raises a validation error |
+| `states_database` | `"core"` | Database holding the states collection |
+| `states_collection` | `"states"` | Collection listing the states (filtered by `is_active = true`, field `name`) |
+| `requires_state` | `False` | Inherited override — the Lambda runs across all states, no session required |
+
+### Running it once per deploy (Terraform)
+
+Since deploys are applied manually with Terraform, attach an `aws_lambda_invocation` that runs **on every `apply`**, right after the function code is updated. `timestamp()` changes on every plan, so it always re-runs (creation is idempotent and also picks up any newly-activated state). The `postcondition` fails the `apply` if the sync reports `success = false` (the framework handler returns HTTP 200 with `success = false` on internal errors, so this check is required to surface failures):
+
+```hcl
+module "lambda" {
+  source         = "../../../../../modules/lambda"
+  function_name  = "${...service_name}${var.lambda_name}-${...env}"
+  source_handler = "handlers.lambda_handler.index_sync_handler"
+  timeout        = 300
+  memory_size    = 512
+  # ... mongo + vpc config (same as any other Lambda)
+}
+
+resource "aws_lambda_invocation" "sync_on_deploy" {
+  function_name = module.lambda.lambda_function_name
+  input         = jsonencode({ _invoked_at = timestamp() })  # always changes → always re-runs
+
+  depends_on = [module.lambda]                                # run after the code is updated
+
+  lifecycle {
+    postcondition {
+      condition     = try(jsondecode(self.result).success, false) == true
+      error_message = "Index sync failed during apply: ${self.result}"
+    }
+  }
+}
+```
+
+You can also invoke it manually at any time (e.g. after activating a new state without a code deploy):
+
+```bash
+aws lambda invoke --function-name MyServiceModelIndexSync-dev out.json
+```
+
+---
+
 ## 🏗️ Architecture Overview
 
 Typical flow for event-driven architectures using this framework:

{aws_python_helper-1.0.0 → aws_python_helper-1.0.2}/aws_python_helper.egg-info/SOURCES.txt

@@ -35,6 +35,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/model_index_sync/__init__.py
+aws_python_helper/model_index_sync/base.py
 aws_python_helper/model_query/__init__.py
 aws_python_helper/model_query/base.py
 aws_python_helper/repository/__init__.py

{aws_python_helper-1.0.0 → aws_python_helper-1.0.2}/pyproject.toml

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