snakeboot 0.1.2__tar.gz → 0.3.0__tar.gz

{snakeboot-0.1.2 → snakeboot-0.3.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: snakeboot
-Version: 0.1.2
-Summary: Spring Boot ergonomics for hexagonal Python: @transactional, application events, a component scan and singleton REST controllers on Django Ninja, wired by wireup.
+Version: 0.3.0
+Summary: Spring Boot ergonomics for hexagonal Python: @transactional, application events, a component scan, typed configuration with profiles and singleton REST controllers on Django Ninja, wired by wireup.
 Keywords: spring-boot,hexagonal-architecture,ddd,django,django-ninja,wireup,dependency-injection,transactional
 Author: Wouter Deketelaere
 Author-email: Wouter Deketelaere <wouter.deketelaere@kdg.be>
@@ -19,6 +19,7 @@ Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
 Classifier: Typing :: Typed
 Requires-Dist: wireup>=2.12.0
+Requires-Dist: pydantic-settings>=2.16.0,<3 ; extra == 'configuration'
 Requires-Dist: django>=6.1.1 ; extra == 'django'
 Requires-Dist: django>=6.1.1 ; extra == 'ninja'
 Requires-Dist: django-ninja>=1.7.1 ; extra == 'ninja'
@@ -27,6 +28,7 @@ Project-URL: Homepage, https://github.com/KdG-OCDI/snakeboot
 Project-URL: Repository, https://github.com/KdG-OCDI/snakeboot
 Project-URL: Issues, https://github.com/KdG-OCDI/snakeboot/issues
 Project-URL: Changelog, https://github.com/KdG-OCDI/snakeboot/blob/main/CHANGELOG.md
+Provides-Extra: configuration
 Provides-Extra: django
 Provides-Extra: ninja
 Description-Content-Type: text/markdown
@@ -46,6 +48,8 @@ classes you can read in an afternoon, and none of them knows anything about your
 | `ApplicationEventPublisher`, `@event_listener`, `@transactional_event_listener` | the same names | wireup |
 | `@rest_controller`, `@route.get`, `@rest_controller_advice`, `@exception_handler` | `@RestController`, `@GetMapping`, `@RestControllerAdvice`, `@ExceptionHandler` | `snakeboot[ninja]` |
 | `DjangoAtomicTransactionManager` | `PlatformTransactionManager` for JDBC | `snakeboot[django]` |
+| `@configuration_properties`, `Section`, `load_configuration`, `application-<profile>.toml` | `@ConfigurationProperties`, `@EnableConfigurationProperties`, profiles | `snakeboot[configuration]` |
+| `DjangoProperties`, `DatabaseProperties`, `CacheProperties` | `server.*`, `spring.datasource.*`, `spring.data.redis.*` | `snakeboot[configuration]` |
 | `RecordingTransactionManager`, `declared_classes` | spring-test | nothing |
 
 The transaction, component scan and testing packages import nothing but the standard library,
@@ -54,7 +58,7 @@ so the application layer of a hexagonal application can use `@transactional` wit
 ## Install
 
 ```bash
-uv add "snakeboot[django,ninja]"
+uv add "snakeboot[configuration,django,ninja]"
 ```
 
 ## A tour
@@ -73,6 +77,39 @@ class MyApplication: ...
 WIREUP = WireupSettings(injectables=[*ComponentScan.of(MyApplication).module_names()], auto_inject_views=False)
 ```
 
+**Typed configuration.** A `Section` (a frozen Pydantic model that refuses unknown keys) is bound to one
+table of `application.toml`, like `@ConfigurationProperties`. Settings lists the sections once, like
+`@EnableConfigurationProperties`; every section then reaches wireup by its type. The sections Django itself
+needs come with snakeboot: `DjangoProperties` (`[django]`), `DatabaseProperties` (`[database]`, PostgreSQL) and
+`CacheProperties` (`[cache]`, Redis).
+
+```python
+@configuration_properties("chatbot")
+class ChatbotProperties(Section):
+    model: str  # no default: the value is in application.toml
+    llm: LanguageModelProperties  # a nested Section is the table [chatbot.llm]
+
+
+# settings.py
+CONFIGURATION = load_configuration(DjangoProperties, DatabaseProperties, ChatbotProperties, package="myapp")
+SECRET_KEY = CONFIGURATION.get(DjangoProperties).secret_key.get_secret_value()
+DATABASES = {"default": CONFIGURATION.get(DatabaseProperties).as_django_database()}
+WIREUP = WireupSettings(injectables=[*ComponentScan.of(MyApplication).module_names(), *CONFIGURATION.injectables()])
+```
+
+The values come from three places, a later one overriding an earlier one key by key:
+
+| Source | Holds | Spring Boot |
+|---|---|---|
+| `application.toml` in the package | every value the application runs with in production | `application.yml` |
+| `application-<profile>.toml`, when `SNAKEBOOT_PROFILE` names one | what differs on a developer machine, say | `application-local.yml`, `SPRING_PROFILES_ACTIVE` |
+| environment variables `SECTION__KEY__SUBKEY` | secrets and addresses of one deployment | relaxed binding |
+
+Nothing else is read: no `.env` file, no default in code, no command line. The start stops when a model has
+a default, ignores unknown keys or is mutable; when a file or a value is missing; when a key or a table is
+unknown (a typo in `application.toml` or in `CHATBOT__LLM__MODLE`). Tables are merged, not replaced, so put the
+variant without keys of its own in `application.toml` when a profile or the environment may choose another.
+
 **Transactions.** A use case declares its boundary; composition chooses the technology.
 
 ```python
@@ -129,8 +166,8 @@ mounted = RestControllerMounter().mount(api, scan=settings.WIREUP.injectables or
 
 ## Design rules
 
-* Imitate the basics, not all of Spring: no AOP, no profiles, no scheduling, no message brokers.
-* Fail at start-up, not at the first request: a broken controller, listener or root stops the application.
+* Imitate the basics, not all of Spring: no AOP, no scheduling, no message brokers.
+* Fail at start-up, not at the first request: a broken controller, listener, root or configuration stops the application.
 * Each package knows as little as possible; `uv run lint-imports` enforces it.
 
 ## Develop

{snakeboot-0.1.2 → snakeboot-0.3.0}/README.md

@@ -13,6 +13,8 @@ classes you can read in an afternoon, and none of them knows anything about your
 | `ApplicationEventPublisher`, `@event_listener`, `@transactional_event_listener` | the same names | wireup |
 | `@rest_controller`, `@route.get`, `@rest_controller_advice`, `@exception_handler` | `@RestController`, `@GetMapping`, `@RestControllerAdvice`, `@ExceptionHandler` | `snakeboot[ninja]` |
 | `DjangoAtomicTransactionManager` | `PlatformTransactionManager` for JDBC | `snakeboot[django]` |
+| `@configuration_properties`, `Section`, `load_configuration`, `application-<profile>.toml` | `@ConfigurationProperties`, `@EnableConfigurationProperties`, profiles | `snakeboot[configuration]` |
+| `DjangoProperties`, `DatabaseProperties`, `CacheProperties` | `server.*`, `spring.datasource.*`, `spring.data.redis.*` | `snakeboot[configuration]` |
 | `RecordingTransactionManager`, `declared_classes` | spring-test | nothing |
 
 The transaction, component scan and testing packages import nothing but the standard library,
@@ -21,7 +23,7 @@ so the application layer of a hexagonal application can use `@transactional` wit
 ## Install
 
 ```bash
-uv add "snakeboot[django,ninja]"
+uv add "snakeboot[configuration,django,ninja]"
 ```
 
 ## A tour
@@ -40,6 +42,39 @@ class MyApplication: ...
 WIREUP = WireupSettings(injectables=[*ComponentScan.of(MyApplication).module_names()], auto_inject_views=False)
 ```
 
+**Typed configuration.** A `Section` (a frozen Pydantic model that refuses unknown keys) is bound to one
+table of `application.toml`, like `@ConfigurationProperties`. Settings lists the sections once, like
+`@EnableConfigurationProperties`; every section then reaches wireup by its type. The sections Django itself
+needs come with snakeboot: `DjangoProperties` (`[django]`), `DatabaseProperties` (`[database]`, PostgreSQL) and
+`CacheProperties` (`[cache]`, Redis).
+
+```python
+@configuration_properties("chatbot")
+class ChatbotProperties(Section):
+    model: str  # no default: the value is in application.toml
+    llm: LanguageModelProperties  # a nested Section is the table [chatbot.llm]
+
+
+# settings.py
+CONFIGURATION = load_configuration(DjangoProperties, DatabaseProperties, ChatbotProperties, package="myapp")
+SECRET_KEY = CONFIGURATION.get(DjangoProperties).secret_key.get_secret_value()
+DATABASES = {"default": CONFIGURATION.get(DatabaseProperties).as_django_database()}
+WIREUP = WireupSettings(injectables=[*ComponentScan.of(MyApplication).module_names(), *CONFIGURATION.injectables()])
+```
+
+The values come from three places, a later one overriding an earlier one key by key:
+
+| Source | Holds | Spring Boot |
+|---|---|---|
+| `application.toml` in the package | every value the application runs with in production | `application.yml` |
+| `application-<profile>.toml`, when `SNAKEBOOT_PROFILE` names one | what differs on a developer machine, say | `application-local.yml`, `SPRING_PROFILES_ACTIVE` |
+| environment variables `SECTION__KEY__SUBKEY` | secrets and addresses of one deployment | relaxed binding |
+
+Nothing else is read: no `.env` file, no default in code, no command line. The start stops when a model has
+a default, ignores unknown keys or is mutable; when a file or a value is missing; when a key or a table is
+unknown (a typo in `application.toml` or in `CHATBOT__LLM__MODLE`). Tables are merged, not replaced, so put the
+variant without keys of its own in `application.toml` when a profile or the environment may choose another.
+
 **Transactions.** A use case declares its boundary; composition chooses the technology.
 
 ```python
@@ -96,8 +131,8 @@ mounted = RestControllerMounter().mount(api, scan=settings.WIREUP.injectables or
 
 ## Design rules
 
-* Imitate the basics, not all of Spring: no AOP, no profiles, no scheduling, no message brokers.
-* Fail at start-up, not at the first request: a broken controller, listener or root stops the application.
+* Imitate the basics, not all of Spring: no AOP, no scheduling, no message brokers.
+* Fail at start-up, not at the first request: a broken controller, listener, root or configuration stops the application.
 * Each package knows as little as possible; `uv run lint-imports` enforces it.
 
 ## Develop

{snakeboot-0.1.2 → snakeboot-0.3.0}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "snakeboot"
-version = "0.1.2"
-description = "Spring Boot ergonomics for hexagonal Python: @transactional, application events, a component scan and singleton REST controllers on Django Ninja, wired by wireup."
+version = "0.3.0"
+description = "Spring Boot ergonomics for hexagonal Python: @transactional, application events, a component scan, typed configuration with profiles and singleton REST controllers on Django Ninja, wired by wireup."
 readme = "README.md"
 license = "MIT"
 license-files = ["LICENSE"]
@@ -47,6 +47,7 @@ ninja = [
     "django>=6.1.1",
     "django-ninja>=1.7.1",
 ]
+configuration = ["pydantic-settings>=2.16.0,<3"]
 
 [build-system]
 requires = ["uv_build>=0.12.19,<0.13.0"]
@@ -60,6 +61,7 @@ dev = [
     "import-linter>=2.15",
     "mypy>=2.4.0",
     "pre-commit>=4.7.0",
+    "pydantic-settings>=2.16.0,<3",
     "pytest>=9.1.1",
     "pytest-django>=4.14.0",
     "ruff>=0.17.1",
@@ -84,6 +86,9 @@ forbidden_modules = [
     "django",
     "ninja",
     "wireup",
+    "pydantic",
+    "pydantic_settings",
+    "snakeboot.configuration",
     "snakeboot.component_scan",
     "snakeboot.events",
     "snakeboot.rest",
@@ -99,6 +104,9 @@ forbidden_modules = [
     "django",
     "ninja",
     "wireup",
+    "pydantic",
+    "pydantic_settings",
+    "snakeboot.configuration",
     "snakeboot.transaction",
     "snakeboot.events",
     "snakeboot.rest",
@@ -114,6 +122,7 @@ forbidden_modules = [
     "django",
     "ninja",
     "pydantic",
+    "snakeboot.configuration",
     "snakeboot.component_scan",
     "snakeboot.rest",
     "snakeboot.django",
@@ -125,6 +134,7 @@ name = "rest knows Ninja and wireup, but not the transaction and event libraries
 type = "forbidden"
 source_modules = ["snakeboot.rest"]
 forbidden_modules = [
+    "snakeboot.configuration",
     "snakeboot.transaction",
     "snakeboot.events",
     "snakeboot.component_scan",
@@ -139,6 +149,7 @@ source_modules = ["snakeboot.django"]
 forbidden_modules = [
     "ninja",
     "wireup",
+    "snakeboot.configuration",
     "snakeboot.component_scan",
     "snakeboot.events",
     "snakeboot.rest",
@@ -153,11 +164,29 @@ forbidden_modules = [
     "django",
     "ninja",
     "wireup",
+    "pydantic",
+    "pydantic_settings",
+    "snakeboot.configuration",
     "snakeboot.rest",
     "snakeboot.events",
     "snakeboot.django",
 ]
 
+[[tool.importlinter.contracts]]
+name = "configuration knows Pydantic Settings and wireup, but no web or ORM framework and no other part of snakeboot"
+type = "forbidden"
+source_modules = ["snakeboot.configuration"]
+forbidden_modules = [
+    "django",
+    "ninja",
+    "snakeboot.transaction",
+    "snakeboot.component_scan",
+    "snakeboot.events",
+    "snakeboot.rest",
+    "snakeboot.django",
+    "snakeboot.testing",
+]
+
 [tool.ruff]
 line-length = 120
 target-version = "py313"

{snakeboot-0.1.2 → snakeboot-0.3.0}/pyproject.toml.orig

@@ -1,7 +1,7 @@
 [project]
 name = "snakeboot"
-version = "0.1.2"
-description = "Spring Boot ergonomics for hexagonal Python: @transactional, application events, a component scan and singleton REST controllers on Django Ninja, wired by wireup."
+version = "0.3.0"
+description = "Spring Boot ergonomics for hexagonal Python: @transactional, application events, a component scan, typed configuration with profiles and singleton REST controllers on Django Ninja, wired by wireup."
 readme = "README.md"
 license = "MIT"
 license-files = ["LICENSE"]
@@ -38,6 +38,8 @@ Changelog = "https://github.com/KdG-OCDI/snakeboot/blob/main/CHANGELOG.md"
 django = ["django>=6.1.1"]
 # Singleton REST controllers and advices on Django Ninja (snakeboot.rest).
 ninja = ["django>=6.1.1", "django-ninja>=1.7.1"]
+# Typed configuration from application.toml, one profile and the environment (snakeboot.configuration).
+configuration = ["pydantic-settings>=2.16.0,<3"]
 
 [build-system]
 requires = ["uv_build>=0.12.19,<0.13.0"]
@@ -51,6 +53,7 @@ dev = [
     "import-linter>=2.15",
     "mypy>=2.4.0",
     "pre-commit>=4.7.0",
+    "pydantic-settings>=2.16.0,<3",
     "pytest>=9.1.1",
     "pytest-django>=4.14.0",
     "ruff>=0.17.1",
@@ -80,6 +83,9 @@ forbidden_modules = [
     "django",
     "ninja",
     "wireup",
+    "pydantic",
+    "pydantic_settings",
+    "snakeboot.configuration",
     "snakeboot.component_scan",
     "snakeboot.events",
     "snakeboot.rest",
@@ -95,6 +101,9 @@ forbidden_modules = [
     "django",
     "ninja",
     "wireup",
+    "pydantic",
+    "pydantic_settings",
+    "snakeboot.configuration",
     "snakeboot.transaction",
     "snakeboot.events",
     "snakeboot.rest",
@@ -110,6 +119,7 @@ forbidden_modules = [
     "django",
     "ninja",
     "pydantic",
+    "snakeboot.configuration",
     "snakeboot.component_scan",
     "snakeboot.rest",
     "snakeboot.django",
@@ -121,6 +131,7 @@ name = "rest knows Ninja and wireup, but not the transaction and event libraries
 type = "forbidden"
 source_modules = ["snakeboot.rest"]
 forbidden_modules = [
+    "snakeboot.configuration",
     "snakeboot.transaction",
     "snakeboot.events",
     "snakeboot.component_scan",
@@ -135,6 +146,7 @@ source_modules = ["snakeboot.django"]
 forbidden_modules = [
     "ninja",
     "wireup",
+    "snakeboot.configuration",
     "snakeboot.component_scan",
     "snakeboot.events",
     "snakeboot.rest",
@@ -145,7 +157,32 @@ forbidden_modules = [
 name = "testing helpers run without a framework"
 type = "forbidden"
 source_modules = ["snakeboot.testing"]
-forbidden_modules = ["django", "ninja", "wireup", "snakeboot.rest", "snakeboot.events", "snakeboot.django"]
+forbidden_modules = [
+    "django",
+    "ninja",
+    "wireup",
+    "pydantic",
+    "pydantic_settings",
+    "snakeboot.configuration",
+    "snakeboot.rest",
+    "snakeboot.events",
+    "snakeboot.django",
+]
+
+[[tool.importlinter.contracts]]
+name = "configuration knows Pydantic Settings and wireup, but no web or ORM framework and no other part of snakeboot"
+type = "forbidden"
+source_modules = ["snakeboot.configuration"]
+forbidden_modules = [
+    "django",
+    "ninja",
+    "snakeboot.transaction",
+    "snakeboot.component_scan",
+    "snakeboot.events",
+    "snakeboot.rest",
+    "snakeboot.django",
+    "snakeboot.testing",
+]
 
 # ---------------------------------------------------------------------------
 # Code contracts: the Clean Code rules in AGENTS.md, enforced by Ruff and mypy.

{snakeboot-0.1.2 → snakeboot-0.3.0}/src/snakeboot/__init__.py

@@ -3,6 +3,7 @@
     snakeboot.transaction     @transactional, after_commit, TransactionManager    (no dependencies)
     snakeboot.component_scan  @application_root, ComponentScan                    (no dependencies)
     snakeboot.events          ApplicationEventPublisher, @transactional_event_listener   (wireup)
+    snakeboot.configuration   @configuration_properties, load_configuration       (extra: configuration)
     snakeboot.rest            @rest_controller, @route, @rest_controller_advice   (extra: ninja)
     snakeboot.django          DjangoAtomicTransactionManager                      (extra: django)
     snakeboot.testing         RecordingTransactionManager, declared_classes       (no dependencies)

snakeboot-0.3.0/src/snakeboot/configuration/__init__.py

@@ -0,0 +1,41 @@
+"""Technical library: typed configuration from application.toml, one profile and the environment.
+
+    @configuration_properties("chatbot")         # @ConfigurationProperties(prefix = "chatbot")
+    class ChatbotProperties(Section):
+        model: str                               # no default: the value is in application.toml
+
+    # in settings.py, like @EnableConfigurationProperties({DjangoProperties.class, ChatbotProperties.class}):
+    CONFIGURATION = load_configuration(DjangoProperties, ChatbotProperties, package="myservice")
+    SECRET_KEY = CONFIGURATION.get(DjangoProperties).secret_key.get_secret_value()
+    WIREUP = WireupSettings(injectables=[*scan.module_names(), *CONFIGURATION.injectables()])
+
+The values come from `application.toml` in the package, then `application-<profile>.toml` when
+SNAKEBOOT_PROFILE is set, then environment variables such as CHATBOT__MODEL; nothing else.
+`DjangoProperties`, `DatabaseProperties` and `CacheProperties` are the sections Django itself needs.
+"""
+
+from snakeboot.configuration.cache_properties import CacheProperties
+from snakeboot.configuration.configuration import Configuration
+from snakeboot.configuration.configuration_errors import (
+    ConfigurationFileNotFoundError,
+    InvalidConfigurationPropertiesError,
+)
+from snakeboot.configuration.configuration_properties import configuration_properties
+from snakeboot.configuration.database_properties import DatabaseProperties
+from snakeboot.configuration.django_properties import DjangoProperties
+from snakeboot.configuration.load_configuration import BASE_FILE, PROFILE_VARIABLE, load_configuration
+from snakeboot.configuration.section import Section
+
+__all__ = [
+    "BASE_FILE",
+    "PROFILE_VARIABLE",
+    "CacheProperties",
+    "Configuration",
+    "ConfigurationFileNotFoundError",
+    "DatabaseProperties",
+    "DjangoProperties",
+    "InvalidConfigurationPropertiesError",
+    "Section",
+    "configuration_properties",
+    "load_configuration",
+]

snakeboot-0.3.0/src/snakeboot/configuration/cache_properties.py

@@ -0,0 +1,16 @@
+from snakeboot.configuration.configuration_properties import configuration_properties
+from snakeboot.configuration.section import Section
+
+
+@configuration_properties("cache")
+class CacheProperties(Section):
+    """The section `[cache]`: the Redis that backs Django's cache, like Spring Boot's `spring.data.redis.*`.
+
+    CACHES = {"default": CONFIGURATION.get(CacheProperties).as_django_cache()}
+    """
+
+    redis_url: str
+
+    def as_django_cache(self) -> dict[str, str]:
+        """The entry of Django's `CACHES` setting."""
+        return {"BACKEND": "django.core.cache.backends.redis.RedisCache", "LOCATION": self.redis_url}

snakeboot-0.3.0/src/snakeboot/configuration/configuration.py

@@ -0,0 +1,55 @@
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from types import ModuleType
+from typing import Final
+
+from pydantic import BaseModel
+from wireup import injectable
+
+from snakeboot.configuration.configuration_properties import prefix_of
+
+INJECTABLES_MODULE: Final = "snakeboot.configuration.loaded_sections"
+
+
+@dataclass(frozen=True, slots=True)
+class Configuration:
+    """What `load_configuration` read: the active profile and one validated, immutable object per section.
+
+    Composition reads the sections Django itself needs with `get`, and hands every section to wireup with
+    `injectables`: an adapter then asks for its section by type, like a `@ConfigurationProperties` bean.
+    """
+
+    profile: str | None
+    sections: Mapping[type[BaseModel], BaseModel]
+
+    def get[S: BaseModel](self, section: type[S]) -> S:
+        """Returns the loaded object of `section`."""
+        loaded = self.sections.get(section)
+        if not isinstance(loaded, section):
+            raise LookupError(
+                f"{section.__name__} is not a section of this configuration: pass it to load_configuration."
+            )
+        return loaded
+
+    def injectables(self) -> list[ModuleType]:
+        """Returns a module with one wireup provider per section, for `WireupSettings(injectables=[...])`.
+
+        The list is empty when there are no sections.
+        """
+        if not self.sections:
+            return []
+        module = ModuleType(INJECTABLES_MODULE, "The sections of the configuration, provided by type.")
+        module.__file__ = f"<{INJECTABLES_MODULE}>"  # wireup only reads the members of a module with a file
+        for section, loaded in self.sections.items():
+            provider = _provider_of(section, loaded)
+            setattr(module, provider.__name__, provider)
+        return [module]
+
+
+def _provider_of(section: type[BaseModel], loaded: BaseModel) -> Callable[[], BaseModel]:
+    def provide() -> BaseModel:
+        return loaded
+
+    provide.__name__ = provide.__qualname__ = f"provide_{prefix_of(section)}_properties"
+    provide.__annotations__ = {"return": section}
+    return injectable(provide)

snakeboot-0.3.0/src/snakeboot/configuration/configuration_errors.py

@@ -0,0 +1,12 @@
+class InvalidConfigurationPropertiesError(TypeError):
+    """Raised at start-up when a class cannot be bound to a section of the configuration.
+
+    A default in code, a model that ignores unknown keys, an unmarked section or two models claiming
+    the same section: each would let a value come from somewhere else than application.toml, the active
+    profile or the environment. Like an invalid `@ConfigurationProperties` class in Spring, it stops the
+    application from starting.
+    """
+
+
+class ConfigurationFileNotFoundError(FileNotFoundError):
+    """Raised at start-up when `application.toml`, or the file of the active profile, is not in the package."""

snakeboot-0.3.0/src/snakeboot/configuration/configuration_properties.py

@@ -0,0 +1,48 @@
+import re
+from collections.abc import Callable
+from typing import Final
+
+from pydantic import BaseModel
+
+from snakeboot.configuration.configuration_errors import InvalidConfigurationPropertiesError
+
+PREFIX_ATTRIBUTE: Final = "__configuration_properties_prefix__"
+_PREFIX: Final = re.compile(r"[a-z][a-z0-9]*(?:_[a-z0-9]+)*")
+
+
+def configuration_properties[M: type[BaseModel]](prefix: str) -> Callable[[M], M]:
+    """Binds a Pydantic model to the table `[prefix]`, like Spring's `@ConfigurationProperties(prefix = ...)`.
+
+    The model receives the table `[prefix]` of `application.toml`, merged with the active profile and the
+    environment variables `PREFIX__FIELD__SUBFIELD` (`CHATBOT__LLM__MODEL` sets `chatbot.llm.model`). The
+    prefix is one lowercase name with single underscores: a double underscore separates the levels of an
+    environment variable.
+    """
+    if not _PREFIX.fullmatch(prefix):
+        raise InvalidConfigurationPropertiesError(
+            f"A configuration prefix is one lowercase name with single underscores, got {prefix!r}."
+        )
+
+    def declare(model: M) -> M:
+        if not _is_pydantic_model(model):
+            raise InvalidConfigurationPropertiesError(
+                f"@configuration_properties marks a Pydantic model, not {model!r}."
+            )
+        setattr(model, PREFIX_ATTRIBUTE, prefix)
+        return model
+
+    return declare
+
+
+def prefix_of(model: type[BaseModel]) -> str:
+    """Returns the prefix `model` was declared with. A subclass does not inherit it: it is another section."""
+    prefix = vars(model).get(PREFIX_ATTRIBUTE)
+    if not isinstance(prefix, str):
+        raise InvalidConfigurationPropertiesError(
+            f"{model.__name__} is not marked with @configuration_properties, so it is not a section."
+        )
+    return prefix
+
+
+def _is_pydantic_model(candidate: object) -> bool:
+    return isinstance(candidate, type) and issubclass(candidate, BaseModel)

snakeboot-0.3.0/src/snakeboot/configuration/database_properties.py

@@ -0,0 +1,29 @@
+from pydantic import SecretStr
+
+from snakeboot.configuration.configuration_properties import configuration_properties
+from snakeboot.configuration.section import Section
+
+
+@configuration_properties("database")
+class DatabaseProperties(Section):
+    """The section `[database]`: the PostgreSQL database of the service, like Spring Boot's `spring.datasource.*`.
+
+    DATABASES = {"default": CONFIGURATION.get(DatabaseProperties).as_django_database()}
+    """
+
+    host: str
+    port: int
+    name: str
+    user: str
+    password: SecretStr
+
+    def as_django_database(self) -> dict[str, str]:
+        """The entry of Django's `DATABASES` setting."""
+        return {
+            "ENGINE": "django.db.backends.postgresql",
+            "HOST": self.host,
+            "PORT": str(self.port),
+            "NAME": self.name,
+            "USER": self.user,
+            "PASSWORD": self.password.get_secret_value(),
+        }

snakeboot-0.3.0/src/snakeboot/configuration/django_properties.py

@@ -0,0 +1,19 @@
+from typing import Literal
+
+from pydantic import SecretStr
+
+from snakeboot.configuration.configuration_properties import configuration_properties
+from snakeboot.configuration.section import Section
+
+
+@configuration_properties("django")
+class DjangoProperties(Section):
+    """The section `[django]`: what settings.py hands to Django itself, like Spring Boot's `server.*` properties.
+
+    `secret_key` is a SecretStr, so it never shows in a log or a traceback; settings.py unwraps it once.
+    """
+
+    secret_key: SecretStr
+    debug: bool
+    allowed_hosts: tuple[str, ...]
+    log_level: Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]

snakeboot-0.3.0/src/snakeboot/configuration/load_configuration.py

@@ -0,0 +1,107 @@
+import os
+import re
+from collections.abc import Sequence
+from importlib.resources import files
+from importlib.resources.abc import Traversable
+from types import MappingProxyType
+from typing import Any, Final, override
+
+from pydantic import BaseModel, create_model
+from pydantic_settings import BaseSettings, PydanticBaseSettingsSource, SettingsConfigDict, TomlConfigSettingsSource
+
+from snakeboot.configuration.configuration import Configuration
+from snakeboot.configuration.configuration_errors import (
+    ConfigurationFileNotFoundError,
+    InvalidConfigurationPropertiesError,
+)
+from snakeboot.configuration.configuration_properties import prefix_of
+from snakeboot.configuration.properties_rules import refuse_loose_models
+
+PROFILE_VARIABLE: Final = "SNAKEBOOT_PROFILE"
+"""The environment variable that activates a profile, like `SPRING_PROFILES_ACTIVE` (one profile at most)."""
+
+BASE_FILE: Final = "application.toml"
+_PROFILE_NAME: Final = re.compile(r"[a-z][a-z0-9-]*")
+
+
+def load_configuration(*sections: type[BaseModel], package: str) -> Configuration:
+    """Loads `sections` from the files in `package` and the environment, like Spring Boot's `application.yml`.
+
+    Three sources; a later one overrides an earlier one key by key, so nested tables are merged:
+
+        application.toml              every value the application runs with
+        application-<profile>.toml    only when SNAKEBOOT_PROFILE names a profile
+        environment variables         SECTION__KEY__SUBKEY, for example CHATBOT__LLM__MODEL
+
+    Nothing else is read: no `.env` file, no default in code, no command line. The files are package
+    data, so a source checkout and an installed wheel find them alike. Everything fails here, at
+    start-up: InvalidConfigurationPropertiesError for a broken model, ConfigurationFileNotFoundError
+    for a missing file, pydantic's ValidationError for a missing, unknown or invalid value.
+    """
+    sections_by_prefix = _sections_by_prefix(sections)
+    profile = _active_profile()
+    root_model = _root_model(sections_by_prefix, _configuration_files(package, profile))
+    loaded = root_model()
+    return Configuration(
+        profile=profile,
+        sections=MappingProxyType({section: getattr(loaded, prefix) for prefix, section in sections_by_prefix.items()}),
+    )
+
+
+def _sections_by_prefix(sections: Sequence[type[BaseModel]]) -> dict[str, type[BaseModel]]:
+    by_prefix: dict[str, type[BaseModel]] = {}
+    for section in sections:
+        prefix = prefix_of(section)
+        if (earlier := by_prefix.get(prefix)) is not None:
+            raise InvalidConfigurationPropertiesError(
+                f"{earlier.__name__} and {section.__name__} both claim the section [{prefix}]."
+            )
+        refuse_loose_models(section)
+        by_prefix[prefix] = section
+    return by_prefix
+
+
+def _active_profile() -> str | None:
+    profile = os.environ.get(PROFILE_VARIABLE, "")
+    if profile and not _PROFILE_NAME.fullmatch(profile):
+        raise ConfigurationFileNotFoundError(
+            f"{PROFILE_VARIABLE}={profile!r} cannot name a profile file: a profile is one lowercase name."
+        )
+    return profile or None
+
+
+def _configuration_files(package: str, profile: str | None) -> list[Traversable]:
+    directory = files(package)
+    base = directory.joinpath(BASE_FILE)
+    if not base.is_file():
+        raise ConfigurationFileNotFoundError(f"{package} has no {BASE_FILE}: it holds every value of the application.")
+    if profile is None:
+        return [base]
+    profile_file = directory.joinpath(f"application-{profile}.toml")
+    if not profile_file.is_file():
+        raise ConfigurationFileNotFoundError(
+            f"{PROFILE_VARIABLE}={profile}, but {package} has no application-{profile}.toml."
+        )
+    return [base, profile_file]
+
+
+def _root_model(sections_by_prefix: dict[str, type[BaseModel]], toml_files: list[Traversable]) -> type[BaseSettings]:
+    class ConfigurationSources(BaseSettings):
+        model_config = SettingsConfigDict(env_prefix="", env_nested_delimiter="__", extra="forbid", frozen=True)
+
+        @classmethod
+        @override
+        def settings_customise_sources(  # reason: the signature is pydantic-settings' hook
+            cls,
+            settings_cls: type[BaseSettings],
+            init_settings: PydanticBaseSettingsSource,
+            env_settings: PydanticBaseSettingsSource,
+            dotenv_settings: PydanticBaseSettingsSource,
+            file_secret_settings: PydanticBaseSettingsSource,
+        ) -> tuple[PydanticBaseSettingsSource, ...]:
+            # Only the environment and the files: no initial values, no .env file, no secrets directory.
+            return env_settings, TomlConfigSettingsSource(settings_cls, toml_file=toml_files, deep_merge=True)
+
+    fields: dict[str, Any] = {prefix: (section, ...) for prefix, section in sections_by_prefix.items()}
+    root: type[BaseSettings] = create_model("Configuration", __base__=ConfigurationSources, **fields)
+    return root

snakeboot-0.3.0/src/snakeboot/configuration/properties_rules.py

@@ -0,0 +1,56 @@
+from collections.abc import Iterator
+from typing import get_args, get_origin
+
+from pydantic import BaseModel
+
+from snakeboot.configuration.configuration_errors import InvalidConfigurationPropertiesError
+
+
+def refuse_loose_models(section: type[BaseModel]) -> None:
+    """Refuses a section whose model, or a model nested in it, could get a value from somewhere else.
+
+    A default in code is a second place for a value next to application.toml. A model that ignores
+    unknown keys turns a typo into a setting that silently does nothing. A mutable model lets a value
+    change after start-up.
+    """
+    for model in _models_in(section):
+        _refuse_open_model(model)
+        _refuse_defaults(model)
+
+
+def _models_in(section: type[BaseModel]) -> list[type[BaseModel]]:
+    found: dict[type[BaseModel], None] = {}
+    waiting = [section]
+    while waiting:
+        model = waiting.pop()
+        if model not in found:
+            found[model] = None
+            for field in model.model_fields.values():
+                waiting.extend(_models_named_by(field.annotation))
+    return list(found)
+
+
+def _models_named_by(annotation: object) -> Iterator[type[BaseModel]]:
+    # `tuple[Llm, ...]`, `Llm | None` and `Annotated[Llm | Extractive, ...]` all name models in their arguments.
+    if get_origin(annotation) is None and isinstance(annotation, type) and issubclass(annotation, BaseModel):
+        yield annotation
+        return
+    for argument in get_args(annotation):
+        yield from _models_named_by(argument)
+
+
+def _refuse_open_model(model: type[BaseModel]) -> None:
+    if model.model_config.get("extra") != "forbid" or model.model_config.get("frozen") is not True:
+        raise InvalidConfigurationPropertiesError(
+            f"{model.__name__} must extend Section (extra='forbid', frozen=True): an unknown key is a typo that "
+            "must stop the start, and the configuration does not change while running."
+        )
+
+
+def _refuse_defaults(model: type[BaseModel]) -> None:
+    for name, field in model.model_fields.items():
+        if not field.is_required():
+            raise InvalidConfigurationPropertiesError(
+                f"{model.__name__}.{name} has a default in code. Give it its value in application.toml or a "
+                "profile: every configuration value is written in one place."
+            )

snakeboot-0.3.0/src/snakeboot/configuration/section.py

@@ -0,0 +1,12 @@
+from pydantic import BaseModel, ConfigDict
+
+
+class Section(BaseModel):
+    """A table of application.toml as a class: a frozen Pydantic model that refuses unknown keys.
+
+    Every section and every table nested in it extends `Section`, so a typo in a key stops the start and a value
+    cannot change while the application runs. Give no field a default: every value is written in application.toml
+    or in a profile, where everyone can read it.
+    """
+
+    model_config = ConfigDict(extra="forbid", frozen=True)