python-ppa 0.1.9__tar.gz → 0.1.10__tar.gz

{python_ppa-0.1.9 → python_ppa-0.1.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-ppa
-Version: 0.1.9
+Version: 0.1.10
 Summary: JPA-like ORM for Python
 Author: Pratyush Kumar
 License-Expression: MIT
@@ -14,7 +14,7 @@ Requires-Dist: idna==3.18
 Requires-Dist: pydantic==2.13.4
 Requires-Dist: pydantic_core==2.46.4
 Requires-Dist: psycopg[binary]>=3.2.0
-Requires-Dist: pymongo==4.18.1
+Requires-Dist: pymongo==4.18.2
 Requires-Dist: python-dotenv==1.2.2
 Requires-Dist: PyYAML==6.0.3
 Requires-Dist: typing-inspection==0.4.2
@@ -83,6 +83,20 @@ pip install -r requirements.txt
 
 ## ⚙️ Configuration Management
 
+Start with the root `settings.yaml` and copy `.env.example` to `.env`. Set
+`mongoURI` (or `MONGO_URI`) and `MONGO_DB_NAME`. Secrets stay outside YAML.
+The loader accepts a single `settings.yaml`, with optional recursively merged
+`settings-<profile>.yaml` overrides. Existing `.yml` files under `resources/`
+remain supported. Use `PROJECT_ROOT` to select an application's configuration
+when several applications share a checkout.
+
+MongoDB pool sizes, timeouts and driver retries are configured in
+`mongodb.options` using PyMongo option names. Call `ping_mongo()` from
+`ppa.config` to verify readiness and call `close_db_connection()` at shutdown
+after requests finish. PyMongo handles transient disconnects; requests during
+an outage can still fail. See [the configuration and lifecycle design](DESIGN.md)
+for API integration, error handling and shutdown behavior.
+
 The framework supports multi-profile YAML configurations with real-time environment substitution syntax (e.g., ${ENV_VAR:default_value}).
 Create a `resources/` directory at the root of your execution workspace and include your application sheets.
 

{python_ppa-0.1.9 → python_ppa-0.1.10}/README.md

@@ -60,6 +60,20 @@ pip install -r requirements.txt
 
 ## ⚙️ Configuration Management
 
+Start with the root `settings.yaml` and copy `.env.example` to `.env`. Set
+`mongoURI` (or `MONGO_URI`) and `MONGO_DB_NAME`. Secrets stay outside YAML.
+The loader accepts a single `settings.yaml`, with optional recursively merged
+`settings-<profile>.yaml` overrides. Existing `.yml` files under `resources/`
+remain supported. Use `PROJECT_ROOT` to select an application's configuration
+when several applications share a checkout.
+
+MongoDB pool sizes, timeouts and driver retries are configured in
+`mongodb.options` using PyMongo option names. Call `ping_mongo()` from
+`ppa.config` to verify readiness and call `close_db_connection()` at shutdown
+after requests finish. PyMongo handles transient disconnects; requests during
+an outage can still fail. See [the configuration and lifecycle design](DESIGN.md)
+for API integration, error handling and shutdown behavior.
+
 The framework supports multi-profile YAML configurations with real-time environment substitution syntax (e.g., ${ENV_VAR:default_value}).
 Create a `resources/` directory at the root of your execution workspace and include your application sheets.
 

{python_ppa-0.1.9 → python_ppa-0.1.10}/ppa/config.py

@@ -2,6 +2,7 @@ import logging
 import os
 import re
 from pathlib import Path
+from threading import Lock
 from typing import Any
 
 import yaml
@@ -19,23 +20,32 @@ def _detect_resources_dir() -> Path:
     """
     # 1. Honor explicit override if provided
     if env_root := os.getenv("PROJECT_ROOT"):
-        return Path(env_root) / "resources"
+        root = Path(env_root)
+        return root if _settings_file(root).exists() else root / "resources"
 
     # 2. Implicit Discovery: Look at where the application is being executed from
     cwd = Path.cwd()
     for parent in [cwd, *cwd.parents]:
-        candidate_dir = parent / "resources"
-        # Verify this directory exists and contains your master settings file
-        if candidate_dir.is_dir() and (candidate_dir / "settings.yml").exists():
-            return candidate_dir
+        for candidate_dir in (parent, parent / "resources"):
+            if _settings_file(candidate_dir).exists():
+                return candidate_dir
 
     # 3. Fallback to package-relative directory if all else fails
     return Path(__file__).resolve().parent / "resources"
 
 
+def _settings_file(directory: Path, stem: str = "settings") -> Path:
+    """Prefer .yaml while retaining support for existing .yml applications."""
+    yaml_path = directory / f"{stem}.yaml"
+    return yaml_path if yaml_path.exists() else directory / f"{stem}.yml"
+
+
 # Establish dynamic path routing based on runtime context
 RESOURCES_DIR = _detect_resources_dir()
 BASE_DIR = RESOURCES_DIR.parent
+# Also load .env beside the discovered application settings, without overriding exports.
+load_dotenv(RESOURCES_DIR / ".env")
+load_dotenv(BASE_DIR / ".env")
 FRAMEWORK_LOGGER_NAME = "framework"
 DEFAULT_FRAMEWORK_LOG_FORMAT = "%(asctime)s | %(levelname)s | %(name)s | %(message)s"
 DEFAULT_FRAMEWORK_LOG_DATE_FORMAT = "%Y-%m-%d %H:%M:%S"
@@ -61,7 +71,7 @@ def _as_dict(value: Any, *, context: str) -> dict[str, Any]:
 
 
 def _load_and_interpolate_yaml(file_path: Path) -> dict[str, Any]:
-    """Reads a configuration file as raw text, swaps environment placeholders, and parses YAML."""
+    """Parse YAML before substitution so environment values cannot change its structure."""
     if not file_path.exists():
         raise FileNotFoundError(f"Configuration file missing at: {file_path}")
 
@@ -74,16 +84,38 @@ def _load_and_interpolate_yaml(file_path: Path) -> dict[str, Any]:
         # Pull from live environment parameters; defer to fallback if empty
         return os.getenv(env_var_name, fallback_value)
 
-    # Perform a global substitution across the text body
-    interpolated_content = ENV_VAR_PATTERN.sub(match_replacer, raw_content)
-    loaded = yaml.safe_load(interpolated_content)
-    return _as_dict(loaded, context=str(file_path))
+    def interpolate(node: Any) -> Any:
+        if isinstance(node, dict):
+            return {key: interpolate(value) for key, value in node.items()}
+        if isinstance(node, list):
+            return [interpolate(value) for value in node]
+        if isinstance(node, str):
+            result = ENV_VAR_PATTERN.sub(match_replacer, node)
+            if ENV_VAR_PATTERN.fullmatch(node):
+                if result.lower() in ("true", "false"):
+                    return result.lower() == "true"
+                if re.fullmatch(r"-?\d+", result):
+                    return int(result)
+            return result
+        return node
+
+    return _as_dict(interpolate(yaml.safe_load(raw_content)), context=str(file_path))
+
+
+def _merge_config(base: dict, override: dict) -> dict:
+    merged = dict(base)
+    for key, value in override.items():
+        if isinstance(value, dict) and isinstance(merged.get(key), dict):
+            merged[key] = _merge_config(merged[key], value)
+        else:
+            merged[key] = value
+    return merged
 
 
 class ConfigSettings:
     def __init__(self):
         # 1. Bootstrap: Read the master settings.yml to find the active profile
-        master_config_path = RESOURCES_DIR / "settings.yml"
+        master_config_path = _settings_file(RESOURCES_DIR)
         master_data = _load_and_interpolate_yaml(master_config_path)
         app_config = _as_dict(master_data.get("app"), context="settings.app")
 
@@ -91,10 +123,13 @@ class ConfigSettings:
         self.profile = str(app_config.get("profile", "dev"))
 
         # 2. Profile Loading: Read the target profile file (e.g., settings-dev.yml)
-        profile_filename = f"settings-{self.profile}.yml" if self.profile != "prod" else "settings-prod.yml"
-        profile_config_path = RESOURCES_DIR / profile_filename
-
-        self._config_data = _load_and_interpolate_yaml(profile_config_path)
+        if not re.fullmatch(r"[\w-]+", self.profile):
+            raise ValueError("app.profile must contain only letters, numbers, underscores or hyphens")
+        profile_config_path = _settings_file(RESOURCES_DIR, f"settings-{self.profile}")
+        profile_filename = profile_config_path.name
+        self._config_data = master_data
+        if profile_config_path.exists():
+            self._config_data = _merge_config(master_data, _load_and_interpolate_yaml(profile_config_path))
         mongodb_config = _as_dict(self._config_data.get("mongodb"), context=f"{profile_filename}.mongodb")
         postgres_config = _as_dict(
             self._config_data.get("postgresql", self._config_data.get("postgres")),
@@ -102,8 +137,9 @@ class ConfigSettings:
         )
 
         # 3. Expose parameters to the framework
-        self.mongo_uri = mongodb_config.get("uri")
+        self.mongo_uri = mongodb_config.get("uri") or os.getenv("mongoURI") or os.getenv("MONGO_URI")
         self.database_name = mongodb_config.get("database")
+        self.mongo_options = _as_dict(mongodb_config.get("options"), context="mongodb.options")
         self.postgres_dsn = self._resolve_postgres_dsn(postgres_config)
         self.postgres_database_name = postgres_config.get("database") or postgres_config.get("dbname")
 
@@ -188,6 +224,7 @@ settings = ConfigSettings()
 framework_logger = _configure_framework_logger()
 framework_logger.info("Bootstrapping framework with active profile [%s]", settings.profile)
 _mongo_client: MongoClient | None = None
+_mongo_lock = Lock()
 db = None
 
 
@@ -198,12 +235,12 @@ def _get_mongo_client() -> MongoClient:
     if not isinstance(settings.database_name, str) or not settings.database_name:
         raise ValueError("MongoDB database name must be provided before using Mongo repositories")
 
-    if _mongo_client is None:
-        _mongo_client = MongoClient(settings.mongo_uri)
-        db = _mongo_client[settings.database_name]
-        framework_logger.debug("Mongo client initialized for database [%s]", settings.database_name)
-
-    return _mongo_client
+    with _mongo_lock:
+        if _mongo_client is None:
+            _mongo_client = MongoClient(settings.mongo_uri, **settings.mongo_options)
+            db = _mongo_client[settings.database_name]
+            framework_logger.debug("Mongo client initialized for database [%s]", settings.database_name)
+        return _mongo_client
 
 
 def value(place_holder: str) -> Any:
@@ -251,8 +288,12 @@ def value(place_holder: str) -> Any:
 
 def get_collection(collection_name: str):
     """Provides repositories access to the shared single client pool."""
-    _get_mongo_client()
-    return db[collection_name]
+    return _get_mongo_client()[settings.database_name][collection_name]
+
+
+def ping_mongo() -> None:
+    """Check readiness; propagate PyMongo errors for the application to handle."""
+    _get_mongo_client().admin.command("ping")
 
 
 def get_postgres_connection():
@@ -270,7 +311,11 @@ def get_postgres_connection():
 
 
 def close_db_connection():
-    """Gracefully terminates open framework connection pools."""
-    if _mongo_client is not None:
-        framework_logger.debug("Closing MongoDB client connection pool")
-        _mongo_client.close()
+    """Close at application shutdown, after in-flight requests have completed."""
+    global _mongo_client, db
+    with _mongo_lock:
+        if _mongo_client is not None:
+            framework_logger.debug("Closing MongoDB client connection pool")
+            _mongo_client.close()
+            _mongo_client = None
+            db = None

{python_ppa-0.1.9 → python_ppa-0.1.10}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-ppa"
-version = "0.1.9"
+version = "0.1.10"
 description = "JPA-like ORM for Python"
 readme = "README.md"
 requires-python = ">=3.13"
@@ -21,7 +21,7 @@ dependencies = [
     "pydantic==2.13.4",
     "pydantic_core==2.46.4",
     "psycopg[binary]>=3.2.0",
-    "pymongo==4.18.1",
+    "pymongo==4.18.2",
     "python-dotenv==1.2.2",
     "PyYAML==6.0.3",
     "typing-inspection==0.4.2",

{python_ppa-0.1.9 → python_ppa-0.1.10}/python_ppa.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-ppa
-Version: 0.1.9
+Version: 0.1.10
 Summary: JPA-like ORM for Python
 Author: Pratyush Kumar
 License-Expression: MIT
@@ -14,7 +14,7 @@ Requires-Dist: idna==3.18
 Requires-Dist: pydantic==2.13.4
 Requires-Dist: pydantic_core==2.46.4
 Requires-Dist: psycopg[binary]>=3.2.0
-Requires-Dist: pymongo==4.18.1
+Requires-Dist: pymongo==4.18.2
 Requires-Dist: python-dotenv==1.2.2
 Requires-Dist: PyYAML==6.0.3
 Requires-Dist: typing-inspection==0.4.2
@@ -83,6 +83,20 @@ pip install -r requirements.txt
 
 ## ⚙️ Configuration Management
 
+Start with the root `settings.yaml` and copy `.env.example` to `.env`. Set
+`mongoURI` (or `MONGO_URI`) and `MONGO_DB_NAME`. Secrets stay outside YAML.
+The loader accepts a single `settings.yaml`, with optional recursively merged
+`settings-<profile>.yaml` overrides. Existing `.yml` files under `resources/`
+remain supported. Use `PROJECT_ROOT` to select an application's configuration
+when several applications share a checkout.
+
+MongoDB pool sizes, timeouts and driver retries are configured in
+`mongodb.options` using PyMongo option names. Call `ping_mongo()` from
+`ppa.config` to verify readiness and call `close_db_connection()` at shutdown
+after requests finish. PyMongo handles transient disconnects; requests during
+an outage can still fail. See [the configuration and lifecycle design](DESIGN.md)
+for API integration, error handling and shutdown behavior.
+
 The framework supports multi-profile YAML configurations with real-time environment substitution syntax (e.g., ${ENV_VAR:default_value}).
 Create a `resources/` directory at the root of your execution workspace and include your application sheets.
 

{python_ppa-0.1.9 → python_ppa-0.1.10}/python_ppa.egg-info/SOURCES.txt

@@ -11,4 +11,5 @@ python_ppa.egg-info/PKG-INFO
 python_ppa.egg-info/SOURCES.txt
 python_ppa.egg-info/dependency_links.txt
 python_ppa.egg-info/requires.txt
-python_ppa.egg-info/top_level.txt
+python_ppa.egg-info/top_level.txt
+tests/test_config.py

{python_ppa-0.1.9 → python_ppa-0.1.10}/python_ppa.egg-info/requires.txt

@@ -5,7 +5,7 @@ idna==3.18
 pydantic==2.13.4
 pydantic_core==2.46.4
 psycopg[binary]>=3.2.0
-pymongo==4.18.1
+pymongo==4.18.2
 python-dotenv==1.2.2
 PyYAML==6.0.3
 typing-inspection==0.4.2

python_ppa-0.1.10/tests/test_config.py

@@ -0,0 +1,109 @@
+import os
+from concurrent.futures import ThreadPoolExecutor
+from pathlib import Path
+from tempfile import TemporaryDirectory
+import unittest
+from unittest.mock import MagicMock, patch
+
+# Bootstrapping configuration never needs a live database.
+with patch.dict(os.environ, {"mongoURI": "mongodb://localhost:27017"}):
+    from ppa import config
+
+
+class ConfigTests(unittest.TestCase):
+    def setUp(self):
+        self.temp = TemporaryDirectory()
+        self.addCleanup(self.temp.cleanup)
+        self.root = Path(self.temp.name)
+        self.resources = patch.object(config, "RESOURCES_DIR", self.root)
+        self.resources.start()
+        self.addCleanup(self.resources.stop)
+
+    def write(self, filename, content):
+        (self.root / filename).write_text(content)
+
+    def test_single_yaml_and_mongo_uri_alias(self):
+        self.write("settings.yaml", "mongodb:\n  database: test\n")
+        with patch.dict(os.environ, {"mongoURI": "mongodb://localhost:27017"}):
+            settings = config.ConfigSettings()
+        self.assertEqual(settings.database_name, "test")
+        self.assertEqual(settings.mongo_uri, "mongodb://localhost:27017")
+
+    def test_legacy_postgres_profile(self):
+        self.write("settings.yml", "app:\n  profile: dev\n")
+        self.write("settings-dev.yml", "postgresql:\n  dsn: postgresql://localhost/test\n")
+        settings = config.ConfigSettings()
+        self.assertEqual(settings.postgres_dsn, "postgresql://localhost/test")
+
+    def test_recursive_profile_override_and_yaml_precedence(self):
+        self.write("settings.yaml", "mongodb:\n  uri: mongodb://localhost\n  database: test\n  options:\n    maxPoolSize: 10\n    retryReads: true\n")
+        self.write("settings.yml", "invalid: legacy file should not be selected\n")
+        self.write("settings-dev.yaml", "mongodb:\n  options:\n    maxPoolSize: 20\n")
+        settings = config.ConfigSettings()
+        self.assertEqual(settings.database_name, "test")
+        self.assertEqual(settings.mongo_options, {"maxPoolSize": 20, "retryReads": True})
+
+    def test_environment_cannot_inject_yaml_keys(self):
+        self.write("settings.yaml", "secret: ${TEST_SECRET}\noptions:\n  enabled: ${TEST_ENABLED:false}\n  size: ${TEST_SIZE:10}\n")
+        secret = 'quotes: "\nadmin: true # preserved as data'
+        with patch.dict(os.environ, {"TEST_SECRET": secret, "TEST_ENABLED": "false"}):
+            result = config._load_and_interpolate_yaml(self.root / "settings.yaml")
+        self.assertEqual(result, {"secret": secret, "options": {"enabled": False, "size": 10}})
+
+    def test_incomplete_mongo_config_fails(self):
+        self.write("settings.yaml", "mongodb:\n  uri: mongodb://localhost\n")
+        with self.assertRaises(KeyError):
+            config.ConfigSettings()
+
+    def test_explicit_root_supports_both_layouts(self):
+        with patch.dict(os.environ, {"PROJECT_ROOT": str(self.root)}):
+            self.assertEqual(config._detect_resources_dir(), self.root / "resources")
+            self.write("settings.yaml", "app: {}\n")
+            self.assertEqual(config._detect_resources_dir(), self.root)
+
+
+class MongoLifecycleTests(unittest.TestCase):
+    def setUp(self):
+        for name, value in (("_mongo_client", None), ("db", None)):
+            patcher = patch.object(config, name, value)
+            patcher.start()
+            self.addCleanup(patcher.stop)
+        self.factory = patch.object(config, "MongoClient")
+        self.client_factory = self.factory.start()
+        self.addCleanup(self.factory.stop)
+        self.options = patch.object(config.settings, "mongo_options", {"serverSelectionTimeoutMS": 123})
+        self.options.start()
+        self.addCleanup(self.options.stop)
+
+    def test_concurrent_initialization_uses_one_pool_and_options(self):
+        with ThreadPoolExecutor(max_workers=8) as workers:
+            clients = list(workers.map(lambda _: config._get_mongo_client(), range(32)))
+        self.client_factory.assert_called_once_with(config.settings.mongo_uri, serverSelectionTimeoutMS=123)
+        self.assertTrue(all(client is clients[0] for client in clients))
+
+    def test_close_is_idempotent_and_new_collection_uses_fresh_client(self):
+        first, second = MagicMock(), MagicMock()
+        self.client_factory.side_effect = [first, second]
+        config.get_collection("users")
+        config.close_db_connection()
+        config.close_db_connection()
+        first.close.assert_called_once()
+        self.assertIsNone(config.db)
+        config.get_collection("users")
+        self.assertIs(config._mongo_client, second)
+        self.assertEqual(self.client_factory.call_count, 2)
+
+    def test_ping_propagates_outage_and_reuses_client_after_recovery(self):
+        from pymongo.errors import AutoReconnect
+
+        client = self.client_factory.return_value
+        client.admin.command.side_effect = [AutoReconnect("offline"), {"ok": 1}]
+        with self.assertRaises(AutoReconnect):
+            config.ping_mongo()
+        config.ping_mongo()
+        self.client_factory.assert_called_once()
+        self.assertEqual(client.admin.command.call_count, 2)
+
+
+if __name__ == "__main__":
+    unittest.main()