confarg 0.0.1.dev4__tar.gz → 0.0.1.dev6__tar.gz

{confarg-0.0.1.dev4 → confarg-0.0.1.dev6}/PKG-INFO

@@ -1,9 +1,10 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.4
 Name: confarg
-Version: 0.0.1.dev4
-Summary: A tool to manage complex, dynamic configurations.
+Version: 0.0.1.dev6
+Summary: Load and resolve complex configurations from files, environment variables and command line arguments. Keep your favorite CLI library.
 Author: confarg
 Author-email: confarg <280620574+confarg@users.noreply.github.com>
+License-Expression: MPL-2.0
 Requires-Dist: argcomplete>=3.0 ; extra == 'completion'
 Requires-Python: >=3.12
 Project-URL: Documentation, https://confarg.github.io/confarg
@@ -11,32 +12,69 @@ Project-URL: Repository, https://github.com/confarg/confarg
 Provides-Extra: completion
 Description-Content-Type: text/markdown
 
+<!-- pytest-markdown-console-file: notest -->
+<p align="center">
+  <img src="docs/assets/banner.svg" alt="confarg" />
+</p>
+
 # A tool to manage complex configurations
 
-> Load and resolve complex configurations from files, environment variables and command line arguments. Keep your favorite CLI library.
+> Load and resolve complex configurations from files, environment variables and command line arguments. Keep your data structures and favorite CLI library.
 
+`confarg` is a Python library that helps you load configurations in a modular fashion from multiple sources: files, environment variables, and command line arguments.
 
-`confarg` is a Python library that helps you load your app configuration in a modular fashion from multiple sources: configuration files, environment variables, and command line arguments.
+It can handle deeply nested configurations, type unions, derived classes, expressions and variable interpolation, configuration compositions and more, and can integrate with your favorite argument parser library such as `argparse`, `click` or `typer`.
 
-It can handle deeply nested configurations, type unions, derived classes, expressions and variable interpolation, configuration compositions, and can coexist with your favorite argument parser library such as `argparse`, `click`, `typer` or `cyclopts`.
+`confarg` is not a framework. No decorator, base class or special annotation type required: none are provided. It is just a tool for the deserialization and serialization of complex configurations. Its footprint in your code is typically a few lines of code.
 
-If none of this makes sense to you, read along.
+## Install
 
-## Keep your data structures and CLI
+```bash
+pip install confarg
+```
 
-`confarg` is deliberately not a framework, but just a tool.
+`confarg` comes with no dependency, but installing additional libraries such as `pyyaml` unlocks the support of extra configuration file formats.
 
-It does not offer custom data types or decorators, and does not own your CLI. Instead, it strives to play along with your own data structures and CLI framework, to make it easy to switch to it, or away from it.
+## TL;DR
 
-The scope of `confarg` is limited to the deserialization and serialization of complex configurations. By limiting itself to those transient moments in the lifetime of your application, the footprint of `confarg` in your app is limited to a few lines of code.
+This library lets you read configurations stored in classes like this
 
-## Install
+```python
+@dataclass
+class Config:
+  value: float
+  flag: bool
+  subconfig: SubConfig1 | SubConfig2
+```
+
+with this kind of code
+
+```python
+config = confarg.load(Config)
+```
+
+which lets you build a configuration object from files,
+
+```yaml
+value: 1.0
+flag: false
+subconfig:
+  foo: 42
+```
+
+but also and simultaneously from environment variables,
+
+```properties
+MYAPP_VALUE=0.0
+```
+
+and command line arguments,
 
 ```bash
-pip install confarg
+myapp --subconfig.foo=33
 ```
 
-Installing additional libraries such as `pyyaml` unlocks the support of extra configuration file formats.
+Still here? Read along, we are just getting started.
 
 ## Getting started
 
@@ -62,46 +100,46 @@ This allows you to construct a `DBConfig` object by collecting data from three p
 
 1. From a configuration file. By passing `--config <config_file>` to your app, `confarg` will load the content of the file and fill the `DBConfig` object. For example, a config file could look like so:
 
-   ```yaml
-   # config.yaml
-   host: example.com
-   port: 1234
-   name: mydb
-   ```
+    ```yaml
+    # config.yaml
+    host: example.com
+    port: 1234
+    name: mydb
+    ```
 
-   You would then call your application as
+    You would then call your application as
 
-   ```console notest
-   $ myapp.py --config config.yaml
-   DBConfig(host='example.com', port=1234, name='mydb')
-   ```
+    ```console
+    $ myapp.py --config config.yaml
+    DBConfig(host='example.com', port=1234, name='mydb')
+    ```
 
-   Configuration files in TOML and JSON formats are also supported.
+    Configuration files in TOML and JSON formats are also supported.
 
-   > You can change the default `config` flag to something else using the `config_flag` parameter.
+    > You can change the default `config` flag to something else using the `config_flag` parameter.
 
 2. From environment variables. You can declare
 
-   ```properties
-   MYAPP_HOST=example.com
-   MYAPP_PORT=1234
-   MYAPP_NAME=mydb
-   ```
+    ```properties
+    MYAPP_HOST=example.com
+    MYAPP_PORT=1234
+    MYAPP_NAME=mydb
+    ```
 
-   for the same effect.
+    for the same effect.
 
-   > Note that the environment variable prefix of your app should actually be passed to `confarg.load` like so:
-   >
-   > ```python
-   > db_config = confarg.load(DBConfig, env_prefix="MYAPP_")
-   > ```
+    > Note that the environment variable prefix of your app should actually be passed to `confarg.load` like so:
+    >
+    > ```python
+    > db_config = confarg.load(DBConfig, env_prefix="MYAPP_")
+    > ```
 
 3. From command line arguments.
 
-   ```console notest
-   $ my_app --host example.com --port 1234 --name mydb
-   DBConfig(host='example.com', port=1234, name='mydb')
-   ```
+    ```console
+    $ my_app --host example.com --port 1234 --name mydb
+    DBConfig(host='example.com', port=1234, name='mydb')
+    ```
 
 ### Progressive build-up
 
@@ -119,7 +157,7 @@ port: 1234
 
 and provide the schema name from the command line:
 
-```console notest
+```console
 $ myapp.py --config partial_config.yaml --name mydb
 DBConfig(host='example.com', port=1234, name='mydb')
 ```
@@ -134,7 +172,7 @@ Configuration data is read in the following order, later read overwriting existi
 
 This allows for surgical modifications of configuration files. For example, one could overwrite the schema configuration from our existing `full_config` from the command line like so:
 
-```console notest
+```console
 $ # Overwrite the schema name defined in the config file from the command line
 $ myapp.py --config config.yaml --name otherdb
 DBConfig(host='example.com', port=1234, name='otherdb')
@@ -164,7 +202,7 @@ type DBConfig = SQLiteConfig | DBServerConfig
 
 `confarg` can handle this new union type and figure out which configuration is desired based on the arguments it got:
 
-```console notest
+```console
 $ # Pass DBServerConfig parameters, and you get a DBServerConfig
 $ myapp.py --host example.com --port 1234 --name mydb
 DBServerConfig(host='example.com', port=1234, name='mydb')
@@ -183,7 +221,7 @@ Even when disambiguation is possible, it may not be obvious to the human eye whi
 
 Therefore, by necessity or for the sake of clarity, you can provide the class path of the required configuration by using the `class` tag, like so
 
-```console notest
+```console
 $ # Explicitly ask for a SQLiteConfig
 $ myapp.py --class myapp.SQLiteConfig --dbpath db.sqlite
 SQLiteConfig(dbpath='db.sqlite')
@@ -191,7 +229,7 @@ SQLiteConfig(dbpath='db.sqlite')
 
 One example where it is necessary to provide the `class` path is to overwrite the configuration with a new class. Without it, command line arguments are added to the configuration, resulting in an invalid input.
 
-```console notest
+```console
 $ # Config file contains a DBServerConfig
 $ myapp.py --config db_server.yaml
 DBServerConfig(host='example.com', port=1234, name='mydb')
@@ -227,7 +265,7 @@ This allows configurations to be easily extensible. Contrast with unions, where
 
 The downside is that the concrete class must be tagged, as `confarg` cannot discover classes derived from a given class.
 
-```console notest
+```console
 $ # Fails:  derived class not specified
 $ uv run myapp.py --dbpath db.sqlite
 ...
@@ -259,7 +297,7 @@ Our DB configuration, which used to be the root configuration, is now located un
 
 For command line arguments, we follow the common convention of using dot-separated paths to address nested fields. Previous command line arguments for `DBConfig` are now prefixed by `db.`, like so:
 
-```console notest
+```console
 $ myapp.py --db.class myapp.SQLiteConfig --db.dbpath db.sqlite
 Config(db=SQLiteConfig(dbpath='db.sqlite'), log_level='INFO')
 ```
@@ -277,7 +315,7 @@ db:
 
 and is used just like before:
 
-```console notest
+```console
 $ myapp.py --config config.yaml
 Config(db=DBServerConfig(host='example.com', port=1234, name='mydb'),
        log_level='DEBUG')
@@ -345,7 +383,7 @@ resources:
   max_heap_size_mb: ${int(resources.memory_gb * 1024 * 0.8)}
 ```
 
-```console notest
+```console
 $ myapp.py --config expression_config.yaml
 Config(db=SQLiteConfig(dbpath='db.sqlite'),
        resources=Resources(cpu_count=4, memory_gb=16, max_heap_size_mb=13107),
@@ -354,7 +392,7 @@ Config(db=SQLiteConfig(dbpath='db.sqlite'),
 
 Note that variable interpolation occurs after all configuration data is read. This means here that you can override `memory_gb` from the command line, and `max_heap_size_mb` will be adjusted accordingly, even though the expression is defined in the configuration file.
 
-```console notest
+```console
 $ # Max heap is recomputed according to the expression in the config file
 $ myapp.py --config expression_config.yaml --resources.memory_gb 8
 Config(db=SQLiteConfig(dbpath='db.sqlite'),
@@ -372,7 +410,7 @@ Some configuration components may even be generated automatically, in which case
 
 From the command line, the `--config` flag can be suffixed with a key path to load configurations there. For example,
 
-```console notest
+```console
 # Load a config file specific to the `db` key
 $ myapp.py --config.db db_config.yaml
 Config(db=DBServerConfig(host='example.com', port=1234, name='mydb'), log_level='INFO')
@@ -380,7 +418,7 @@ Config(db=DBServerConfig(host='example.com', port=1234, name='mydb'), log_level=
 
 A similar pattern applies to environment variables:
 
-```console notest
+```console
 $ MYAPP_CONFIG_DB=db_config.py myapp.py
 Config(db=DBServerConfig(host='example.com', port=1234, name='mydb'), log_level='INFO')
 ```

{confarg-0.0.1.dev4 → confarg-0.0.1.dev6}/README.md

@@ -1,29 +1,66 @@
+<!-- pytest-markdown-console-file: notest -->
+<p align="center">
+  <img src="docs/assets/banner.svg" alt="confarg" />
+</p>
+
 # A tool to manage complex configurations
 
-> Load and resolve complex configurations from files, environment variables and command line arguments. Keep your favorite CLI library.
+> Load and resolve complex configurations from files, environment variables and command line arguments. Keep your data structures and favorite CLI library.
 
+`confarg` is a Python library that helps you load configurations in a modular fashion from multiple sources: files, environment variables, and command line arguments.
 
-`confarg` is a Python library that helps you load your app configuration in a modular fashion from multiple sources: configuration files, environment variables, and command line arguments.
+It can handle deeply nested configurations, type unions, derived classes, expressions and variable interpolation, configuration compositions and more, and can integrate with your favorite argument parser library such as `argparse`, `click` or `typer`.
 
-It can handle deeply nested configurations, type unions, derived classes, expressions and variable interpolation, configuration compositions, and can coexist with your favorite argument parser library such as `argparse`, `click`, `typer` or `cyclopts`.
+`confarg` is not a framework. No decorator, base class or special annotation type required: none are provided. It is just a tool for the deserialization and serialization of complex configurations. Its footprint in your code is typically a few lines of code.
 
-If none of this makes sense to you, read along.
+## Install
 
-## Keep your data structures and CLI
+```bash
+pip install confarg
+```
 
-`confarg` is deliberately not a framework, but just a tool.
+`confarg` comes with no dependency, but installing additional libraries such as `pyyaml` unlocks the support of extra configuration file formats.
 
-It does not offer custom data types or decorators, and does not own your CLI. Instead, it strives to play along with your own data structures and CLI framework, to make it easy to switch to it, or away from it.
+## TL;DR
 
-The scope of `confarg` is limited to the deserialization and serialization of complex configurations. By limiting itself to those transient moments in the lifetime of your application, the footprint of `confarg` in your app is limited to a few lines of code.
+This library lets you read configurations stored in classes like this
 
-## Install
+```python
+@dataclass
+class Config:
+  value: float
+  flag: bool
+  subconfig: SubConfig1 | SubConfig2
+```
+
+with this kind of code
+
+```python
+config = confarg.load(Config)
+```
+
+which lets you build a configuration object from files,
+
+```yaml
+value: 1.0
+flag: false
+subconfig:
+  foo: 42
+```
+
+but also and simultaneously from environment variables,
+
+```properties
+MYAPP_VALUE=0.0
+```
+
+and command line arguments,
 
 ```bash
-pip install confarg
+myapp --subconfig.foo=33
 ```
 
-Installing additional libraries such as `pyyaml` unlocks the support of extra configuration file formats.
+Still here? Read along, we are just getting started.
 
 ## Getting started
 
@@ -49,46 +86,46 @@ This allows you to construct a `DBConfig` object by collecting data from three p
 
 1. From a configuration file. By passing `--config <config_file>` to your app, `confarg` will load the content of the file and fill the `DBConfig` object. For example, a config file could look like so:
 
-   ```yaml
-   # config.yaml
-   host: example.com
-   port: 1234
-   name: mydb
-   ```
+    ```yaml
+    # config.yaml
+    host: example.com
+    port: 1234
+    name: mydb
+    ```
 
-   You would then call your application as
+    You would then call your application as
 
-   ```console notest
-   $ myapp.py --config config.yaml
-   DBConfig(host='example.com', port=1234, name='mydb')
-   ```
+    ```console
+    $ myapp.py --config config.yaml
+    DBConfig(host='example.com', port=1234, name='mydb')
+    ```
 
-   Configuration files in TOML and JSON formats are also supported.
+    Configuration files in TOML and JSON formats are also supported.
 
-   > You can change the default `config` flag to something else using the `config_flag` parameter.
+    > You can change the default `config` flag to something else using the `config_flag` parameter.
 
 2. From environment variables. You can declare
 
-   ```properties
-   MYAPP_HOST=example.com
-   MYAPP_PORT=1234
-   MYAPP_NAME=mydb
-   ```
+    ```properties
+    MYAPP_HOST=example.com
+    MYAPP_PORT=1234
+    MYAPP_NAME=mydb
+    ```
 
-   for the same effect.
+    for the same effect.
 
-   > Note that the environment variable prefix of your app should actually be passed to `confarg.load` like so:
-   >
-   > ```python
-   > db_config = confarg.load(DBConfig, env_prefix="MYAPP_")
-   > ```
+    > Note that the environment variable prefix of your app should actually be passed to `confarg.load` like so:
+    >
+    > ```python
+    > db_config = confarg.load(DBConfig, env_prefix="MYAPP_")
+    > ```
 
 3. From command line arguments.
 
-   ```console notest
-   $ my_app --host example.com --port 1234 --name mydb
-   DBConfig(host='example.com', port=1234, name='mydb')
-   ```
+    ```console
+    $ my_app --host example.com --port 1234 --name mydb
+    DBConfig(host='example.com', port=1234, name='mydb')
+    ```
 
 ### Progressive build-up
 
@@ -106,7 +143,7 @@ port: 1234
 
 and provide the schema name from the command line:
 
-```console notest
+```console
 $ myapp.py --config partial_config.yaml --name mydb
 DBConfig(host='example.com', port=1234, name='mydb')
 ```
@@ -121,7 +158,7 @@ Configuration data is read in the following order, later read overwriting existi
 
 This allows for surgical modifications of configuration files. For example, one could overwrite the schema configuration from our existing `full_config` from the command line like so:
 
-```console notest
+```console
 $ # Overwrite the schema name defined in the config file from the command line
 $ myapp.py --config config.yaml --name otherdb
 DBConfig(host='example.com', port=1234, name='otherdb')
@@ -151,7 +188,7 @@ type DBConfig = SQLiteConfig | DBServerConfig
 
 `confarg` can handle this new union type and figure out which configuration is desired based on the arguments it got:
 
-```console notest
+```console
 $ # Pass DBServerConfig parameters, and you get a DBServerConfig
 $ myapp.py --host example.com --port 1234 --name mydb
 DBServerConfig(host='example.com', port=1234, name='mydb')
@@ -170,7 +207,7 @@ Even when disambiguation is possible, it may not be obvious to the human eye whi
 
 Therefore, by necessity or for the sake of clarity, you can provide the class path of the required configuration by using the `class` tag, like so
 
-```console notest
+```console
 $ # Explicitly ask for a SQLiteConfig
 $ myapp.py --class myapp.SQLiteConfig --dbpath db.sqlite
 SQLiteConfig(dbpath='db.sqlite')
@@ -178,7 +215,7 @@ SQLiteConfig(dbpath='db.sqlite')
 
 One example where it is necessary to provide the `class` path is to overwrite the configuration with a new class. Without it, command line arguments are added to the configuration, resulting in an invalid input.
 
-```console notest
+```console
 $ # Config file contains a DBServerConfig
 $ myapp.py --config db_server.yaml
 DBServerConfig(host='example.com', port=1234, name='mydb')
@@ -214,7 +251,7 @@ This allows configurations to be easily extensible. Contrast with unions, where
 
 The downside is that the concrete class must be tagged, as `confarg` cannot discover classes derived from a given class.
 
-```console notest
+```console
 $ # Fails:  derived class not specified
 $ uv run myapp.py --dbpath db.sqlite
 ...
@@ -246,7 +283,7 @@ Our DB configuration, which used to be the root configuration, is now located un
 
 For command line arguments, we follow the common convention of using dot-separated paths to address nested fields. Previous command line arguments for `DBConfig` are now prefixed by `db.`, like so:
 
-```console notest
+```console
 $ myapp.py --db.class myapp.SQLiteConfig --db.dbpath db.sqlite
 Config(db=SQLiteConfig(dbpath='db.sqlite'), log_level='INFO')
 ```
@@ -264,7 +301,7 @@ db:
 
 and is used just like before:
 
-```console notest
+```console
 $ myapp.py --config config.yaml
 Config(db=DBServerConfig(host='example.com', port=1234, name='mydb'),
        log_level='DEBUG')
@@ -332,7 +369,7 @@ resources:
   max_heap_size_mb: ${int(resources.memory_gb * 1024 * 0.8)}
 ```
 
-```console notest
+```console
 $ myapp.py --config expression_config.yaml
 Config(db=SQLiteConfig(dbpath='db.sqlite'),
        resources=Resources(cpu_count=4, memory_gb=16, max_heap_size_mb=13107),
@@ -341,7 +378,7 @@ Config(db=SQLiteConfig(dbpath='db.sqlite'),
 
 Note that variable interpolation occurs after all configuration data is read. This means here that you can override `memory_gb` from the command line, and `max_heap_size_mb` will be adjusted accordingly, even though the expression is defined in the configuration file.
 
-```console notest
+```console
 $ # Max heap is recomputed according to the expression in the config file
 $ myapp.py --config expression_config.yaml --resources.memory_gb 8
 Config(db=SQLiteConfig(dbpath='db.sqlite'),
@@ -359,7 +396,7 @@ Some configuration components may even be generated automatically, in which case
 
 From the command line, the `--config` flag can be suffixed with a key path to load configurations there. For example,
 
-```console notest
+```console
 # Load a config file specific to the `db` key
 $ myapp.py --config.db db_config.yaml
 Config(db=DBServerConfig(host='example.com', port=1234, name='mydb'), log_level='INFO')
@@ -367,7 +404,7 @@ Config(db=DBServerConfig(host='example.com', port=1234, name='mydb'), log_level=
 
 A similar pattern applies to environment variables:
 
-```console notest
+```console
 $ MYAPP_CONFIG_DB=db_config.py myapp.py
 Config(db=DBServerConfig(host='example.com', port=1234, name='mydb'), log_level='INFO')
 ```

{confarg-0.0.1.dev4 → confarg-0.0.1.dev6}/pyproject.toml

@@ -2,12 +2,12 @@
 authors = [
     { name = "confarg", email = "280620574+confarg@users.noreply.github.com" },
 ]
-dependencies = []
-description = "A tool to manage complex, dynamic configurations."
+description = "Load and resolve complex configurations from files, environment variables and command line arguments. Keep your favorite CLI library."
+license = "MPL-2.0"
 name = "confarg"
 readme = "README.md"
 requires-python = ">=3.12"
-version = "0.0.1.dev4"
+version = "0.0.1.dev6"
 
 [project.urls]
 Documentation = "https://confarg.github.io/confarg"
@@ -23,14 +23,16 @@ dev = [
     "hypothesis>=6.100",
     "ipython>=9.12.0",
     "jsonargparse>=4.48.0",
+    "just>=0.8.165",
     "mkdocstrings-python>=2.0.3",
     "mkdocstrings>=1.0.4",
     "pre-commit>=4.5.1",
     "pytest-cov>=7.0.0",
-    "pytest-markdown-docs>=0.9.2",
+    "pytest-markdown-console>=0.0.1.dev2",
     "pytest>=8.0",
     "pyyaml>=6.0",
     "tomli-w>=1.0",
+    "ty>=0.0.39",
     "typer>=0.25.1",
     "zensical>=0.0.41",
 ]

confarg-0.0.1.dev6/src/confarg/__init__.py

@@ -0,0 +1,60 @@
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+"""A tool to manage complex configurations.
+
+> Load and resolve complex configurations from files, environment variables and command line arguments. Keep your data
+> structures and favorite CLI library.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+from confarg import exceptions
+from confarg._api import build, dump, dump_file, from_dict, load, merge, resolve
+from confarg._types import TagPolicy
+from confarg.typedload._coerce import _LEAF_COERCIONS
+
+
+def register_leaf_type(tp: type, coerce: Callable[[Any], Any]) -> None:
+    """Register a custom leaf type.
+
+    After registration, ``tp`` is treated as a leaf: values of that type can
+    appear as scalars in config files, env vars, and CLI args.  ``coerce`` is
+    called with the raw input value — either a ``_StrToken`` (a ``str``
+    subclass) from CLI/env sources, or the natively-parsed Python object from
+    config files — and must return an instance of ``tp``, raising
+    ``ValueError`` or ``TypeError`` on failure.
+
+    Example::
+
+        from uuid import UUID
+        confarg.register_leaf_type(UUID, UUID)
+    """
+    _LEAF_COERCIONS[tp] = coerce
+
+
+__all__ = [  # noqa: RUF022
+    # Two-step API
+    "merge",
+    "build",
+    # Three-step API (dict-centric)
+    "resolve",
+    "from_dict",
+    # One-step convenience
+    "load",
+    # Dump
+    "dump",
+    "dump_file",
+    # Types
+    "TagPolicy",
+    # Leaf-type extension
+    "register_leaf_type",
+    # Exceptions / warnings
+    "exceptions",
+]