feat: add array mapping

Author: guillaume-chervet

README.md

@@ -35,6 +35,8 @@ settings = (
 - `.env` file support
 - Typed validation with Pydantic v2
 - Compatible with `dict[str, SubModel]`, lists, booleans, integers, etc.
+- Direct path access with `config["section:key"]`
+- Typed subsections with `.get_section("...").get(MyModel)`
 
 ## Installation
 
@@ -60,6 +62,16 @@ from pydantic import Field
 from axa_fr_app_settings import SettingsModel
 
 
+class EndpointSettings(SettingsModel):
+    name: str
+    url: str
+
+
+class RegionSettings(SettingsModel):
+    name: str
+    endpoints: list[EndpointSettings] = Field(default_factory=list)
+
+
 class OIDCSettings(SettingsModel):
     endpoint_url: str
     issuer: str
@@ -91,6 +103,8 @@ class AppSettings(SettingsModel):
     http_timeout: int = 45
     http_verify: bool = False
     cache: CacheSettings = Field(default_factory=CacheSettings)
+    allowed_hosts: list[str] = Field(default_factory=list)
+    regions: list[RegionSettings] = Field(default_factory=list)
 ```
 
 ### 2. Build the configuration
@@ -121,18 +135,43 @@ export DEBUG=true
 export HTTP_TIMEOUT=30
 export CACHE__REDIS__EXPIRY_TIME=120
 export DATABASE__main__ENDPOINT_URL="postgresql://localhost:5432/app"
+export ALLOWED_HOSTS__0="api.local"
+export ALLOWED_HOSTS__1="admin.local"
+export REGIONS__0__NAME="eu-west"
+export REGIONS__0__ENDPOINTS__0__NAME="catalog"
+export REGIONS__0__ENDPOINTS__0__URL="https://eu-west/catalog"
+export REGIONS__0__ENDPOINTS__1__NAME="orders"
+export REGIONS__0__ENDPOINTS__1__URL="https://eu-west/orders"
+export REGIONS__1__NAME="us-east"
+export REGIONS__1__ENDPOINTS__0__NAME="catalog"
+export REGIONS__1__ENDPOINTS__0__URL="https://us-east/catalog"
 ```
 
 ### 4. YAML example
 
 ```yaml
 debug: false
 http_timeout: 45
+allowed_hosts:
+  - api.local
+  - admin.local
 
 database:
   main:
     endpoint_url: "postgresql://localhost:5432/app"
 
+regions:
+  - name: eu-west
+    endpoints:
+      - name: catalog
+        url: "https://eu-west/catalog"
+      - name: orders
+        url: "https://eu-west/orders"
+  - name: us-east
+    endpoints:
+      - name: catalog
+        url: "https://us-east/catalog"
+
 cache:
   type: redis
   redis:
@@ -147,11 +186,36 @@ cache:
 {
   "debug": false,
   "http_timeout": 45,
+  "allowed_hosts": ["api.local", "admin.local"],
   "database": {
     "main": {
       "endpoint_url": "postgresql://localhost:5432/app"
     }
   },
+  "regions": [
+    {
+      "name": "eu-west",
+      "endpoints": [
+        {
+          "name": "catalog",
+          "url": "https://eu-west/catalog"
+        },
+        {
+          "name": "orders",
+          "url": "https://eu-west/orders"
+        }
+      ]
+    },
+    {
+      "name": "us-east",
+      "endpoints": [
+        {
+          "name": "catalog",
+          "url": "https://us-east/catalog"
+        }
+      ]
+    }
+  ],
   "cache": {
     "type": "redis",
     "redis": {
@@ -165,6 +229,48 @@ cache:
 
 YAML and JSON sources can be mixed freely. The last source added always wins.
 
+## Arrays and nested arrays
+
+Arrays are supported in file sources (`yaml`, `json`) and also in flat sources
+like environment variables and `.env` files.
+
+### Simple array
+
+```yaml
+allowed_hosts:
+  - api.local
+  - admin.local
+```
+
+### Nested array with `regions`
+
+```yaml
+regions:
+  - name: eu-west
+    endpoints:
+      - name: catalog
+        url: https://eu-west/catalog
+      - name: orders
+        url: https://eu-west/orders
+  - name: us-east
+    endpoints:
+      - name: catalog
+        url: https://us-east/catalog
+```
+
+Equivalent environment variables:
+
+```bash
+export REGIONS__0__NAME="eu-west"
+export REGIONS__0__ENDPOINTS__0__NAME="catalog"
+export REGIONS__0__ENDPOINTS__0__URL="https://eu-west/catalog"
+export REGIONS__0__ENDPOINTS__1__NAME="orders"
+export REGIONS__0__ENDPOINTS__1__URL="https://eu-west/orders"
+export REGIONS__1__NAME="us-east"
+export REGIONS__1__ENDPOINTS__0__NAME="catalog"
+export REGIONS__1__ENDPOINTS__0__URL="https://us-east/catalog"
+```
+
 ## Priority order
 
 As in .NET, **the last source added wins**.
@@ -198,6 +304,7 @@ Here:
 | `add_source(source)` | Add a custom source (any object with a `load()` method) |
 | `build()` | Build and return the validated settings model |
 | `build_data()` | Build and return the raw merged dict |
+| `build_configuration()` | Build and return a navigable configuration root |
 | `build_watched(*, debounce_seconds=0.3, polling_interval_seconds=None)` | Build and return a `SettingsWatcher` with auto-reload |
 
 **Key parameters:**
@@ -353,9 +460,83 @@ The Key Vault source (or any custom source) follows the same priority rule: **th
 
 A complete example is available in [`examples/custom_keyvault_source.py`](examples/custom_keyvault_source.py).
 
+## Direct key access and typed sections
+
+Like in .NET, you can also work with the raw merged configuration tree.
+This is useful when you want direct path access or when you only want to bind
+one subsection.
+
+```python
+from pydantic import Field
+
+from axa_fr_app_settings import ConfigurationBuilder, SettingsModel
+
+
+class EndpointSettings(SettingsModel):
+    name: str
+    url: str
+
+
+class RegionSettings(SettingsModel):
+    name: str
+    endpoints: list[EndpointSettings] = Field(default_factory=list)
+
+
+class AppSettings(SettingsModel):
+    application_name: str
+    max_users: int
+    feature_toggle: bool = False
+    allowed_hosts: list[str] = Field(default_factory=list)
+    regions: list[RegionSettings] = Field(default_factory=list)
+
+
+class RootSettings(SettingsModel):
+    appsettings: AppSettings
+
+
+config = (
+    ConfigurationBuilder(RootSettings)
+    .add_json_file("appsettings.json")
+    .build_configuration()
+)
+
+app_name = config["appsettings:application_name"]
+max_users = config["appsettings:max_users"]
+first_region = config["appsettings:regions:0:name"]
+first_endpoint_url = config["appsettings:regions:0:endpoints:0:url"]
+
+app_settings = config.get_section("appsettings").get(AppSettings)
+print(f"FeatureToggle: {app_settings.feature_toggle}")
+print(f"Application Name: {app_settings.application_name}")
+print(f"Max Users: {app_settings.max_users}")
+print(f"First Region: {first_region}")
+print(f"First Endpoint URL: {first_endpoint_url}")
+```
+
+You can also bind the full root model directly:
+
+```python
+root_settings = config.bind()
+```
+
+For environment variables or `.env` files, use numeric indexes with `__`:
+
+```bash
+export APPSETTINGS__ALLOWED_HOSTS__0=api.local
+export APPSETTINGS__ALLOWED_HOSTS__1=admin.local
+export APPSETTINGS__REGIONS__0__NAME="eu-west"
+export APPSETTINGS__REGIONS__0__ENDPOINTS__0__NAME="catalog"
+export APPSETTINGS__REGIONS__0__ENDPOINTS__0__URL="https://eu/catalog"
+```
+
+A complete runnable example is available in [`examples/configuration_sections.py`](examples/configuration_sections.py).
+
 ## Full example
 
-A complete example is provided in [`examples/api_settings.py`](examples/api_settings.py).
+Complete examples are provided in:
+
+- [`examples/api_settings.py`](examples/api_settings.py)
+- [`examples/configuration_sections.py`](examples/configuration_sections.py)
 
 ## Publishing to PyPI with GitHub Actions
 

examples/configuration_sections.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+from pydantic import Field
+
+from axa_fr_app_settings import ConfigurationBuilder, SettingsModel
+
+
+class EndpointSettings(SettingsModel):
+    name: str
+    url: str
+
+
+class RegionSettings(SettingsModel):
+    name: str
+    endpoints: list[EndpointSettings] = Field(default_factory=list)
+
+
+class AppSettings(SettingsModel):
+    application_name: str
+    max_users: int
+    feature_toggle: bool = False
+    allowed_hosts: list[str] = Field(default_factory=list)
+    regions: list[RegionSettings] = Field(default_factory=list)
+
+
+class RootSettings(SettingsModel):
+    appsettings: AppSettings
+
+
+config = (
+    ConfigurationBuilder(RootSettings)
+    .add_in_memory_collection(
+        {
+            "appsettings": {
+                "application_name": "AXA Portal",
+                "max_users": 150,
+                "feature_toggle": True,
+                "allowed_hosts": ["api.local", "admin.local"],
+                "regions": [
+                    {
+                        "name": "eu-west",
+                        "endpoints": [
+                            {"name": "catalog", "url": "https://eu/catalog"},
+                            {"name": "orders", "url": "https://eu/orders"},
+                        ],
+                    },
+                    {
+                        "name": "us-east",
+                        "endpoints": [
+                            {"name": "catalog", "url": "https://us/catalog"},
+                        ],
+                    },
+                ],
+            }
+        }
+    )
+    .build_configuration()
+)
+
+app_name = config["appsettings:application_name"]
+max_users = config["appsettings:max_users"]
+first_region_name = config["appsettings:regions:0:name"]
+first_endpoint_url = config["appsettings:regions:0:endpoints:0:url"]
+
+app_settings = config.get_section("appsettings").get(AppSettings)
+root_settings = config.bind()
+
+print(f"Application Name: {app_name}")
+print(f"Max Users: {max_users}")
+print(f"First Region: {first_region_name}")
+print(f"First Endpoint URL: {first_endpoint_url}")
+print(f"Allowed Hosts: {app_settings.allowed_hosts}")
+print(f"Region count: {len(app_settings.regions)}")
+print(f"Root bound application name: {root_settings.appsettings.application_name}")

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "axa-fr-app-settings"
-version = "0.2.0"
+version = "0.3.0"
 description = "Typed application settings with a .NET-like configuration builder for Python."
 readme = "README.md"
 license = { file = "LICENSE" }

src/axa_fr_app_settings/__init__.py

@@ -2,6 +2,7 @@
 
 from .base import SettingsModel
 from .builder import ConfigurationBuilder, SettingsBuilder
+from .configuration import ConfigurationRoot, ConfigurationSection
 from .sources import (
     CallableSource,
     DictSource,
@@ -18,6 +19,8 @@
 __all__ = [
     "CallableSource",
     "ConfigurationBuilder",
+    "ConfigurationRoot",
+    "ConfigurationSection",
     "DictSource",
     "DotEnvFileSource",
     "EnvironmentVariablesSource",

src/axa_fr_app_settings/builder.py

@@ -6,6 +6,7 @@
 
 from pydantic import BaseModel
 
+from .configuration import ConfigurationRoot
 from .merge import deep_merge
 from .sources import (
     CallableSource,
@@ -139,6 +140,9 @@ def build(self) -> TSettings:
         data = self.build_data()
         return self._settings_type.model_validate(data)
 
+    def build_configuration(self) -> ConfigurationRoot[TSettings]:
+        return ConfigurationRoot(self.build_data(), self._settings_type)
+
     def build_watched(
         self,
         *,