confarg 0.0.1.dev5__tar.gz → 0.0.1.dev6__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: confarg
-Version: 0.0.1.dev5
+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>
@@ -12,6 +12,11 @@ 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 data structures and favorite CLI library.
@@ -20,7 +25,7 @@ Description-Content-Type: text/markdown
 
 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`.
 
-`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, making it easy to switch to it, or away from it.
+`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.
 
 ## Install
 
@@ -95,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
 
@@ -152,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')
 ```
@@ -167,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')
@@ -197,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')
@@ -216,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')
@@ -224,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')
@@ -260,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
 ...
@@ -292,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')
 ```
@@ -310,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')
@@ -378,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),
@@ -387,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'),
@@ -405,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')
@@ -413,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.dev5 → confarg-0.0.1.dev6}/README.md

@@ -1,3 +1,8 @@
+<!-- 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 data structures and favorite CLI library.
@@ -6,7 +11,7 @@
 
 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`.
 
-`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, making it easy to switch to it, or away from it.
+`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.
 
 ## Install
 
@@ -81,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
 
@@ -138,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')
 ```
@@ -153,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')
@@ -183,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')
@@ -202,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')
@@ -210,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')
@@ -246,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
 ...
@@ -278,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')
 ```
@@ -296,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')
@@ -364,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),
@@ -373,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'),
@@ -391,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')
@@ -399,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.dev5 → confarg-0.0.1.dev6}/pyproject.toml

@@ -7,7 +7,7 @@ license = "MPL-2.0"
 name = "confarg"
 readme = "README.md"
 requires-python = ">=3.12"
-version = "0.0.1.dev5"
+version = "0.0.1.dev6"
 
 [project.urls]
 Documentation = "https://confarg.github.io/confarg"
@@ -23,11 +23,12 @@ 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",

{confarg-0.0.1.dev5 → confarg-0.0.1.dev6}/src/confarg/__init__.py

@@ -10,9 +10,34 @@
 
 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
@@ -28,6 +53,8 @@ __all__ = [  # noqa: RUF022
     "dump_file",
     # Types
     "TagPolicy",
+    # Leaf-type extension
+    "register_leaf_type",
     # Exceptions / warnings
     "exceptions",
 ]

{confarg-0.0.1.dev5 → confarg-0.0.1.dev6}/src/confarg/_api.py

@@ -60,7 +60,7 @@ def _load_cli_config(fpath: Path, subpath: str, config_flag: str) -> dict[str, A
 def merge(  # noqa: PLR0913
     target: type | TypeAliasType | UnionType,
     *,
-    args: Sequence[str] | None = None,
+    argv: Sequence[str] | None = None,
     env: Mapping[str, str] | None = None,
     env_prefix: str | None = _defaults.ENV_PREFIX,
     env_separator: str = "__",
@@ -80,7 +80,7 @@ def merge(  # noqa: PLR0913
 
     Args:
         target: The dataclass type (or scalar type) used to guide CLI parsing.
-        args: CLI arguments to parse. Defaults to sys.argv[1:].
+        argv: CLI arguments to parse. Defaults to sys.argv[1:].
         env: Environment variable mapping to scan. Defaults to os.environ.
         env_prefix: Prefix that env vars must start with. Defaults to ``None``,
             which disables environment variable parsing entirely. Set to ``""``
@@ -120,13 +120,13 @@ def merge(  # noqa: PLR0913
         InvalidConfigFileError: If a config file cannot be loaded.
         UnknownArgumentError: If an unrecognized CLI argument is encountered.
     """
-    if args is None:
-        args = sys.argv[1:]
+    if argv is None:
+        argv = sys.argv[1:]
     if env is None:
         env = os.environ
 
     # 1. Parse CLI
-    cli_data, cli_configs = _parse_cli(args, target, cli_prefix, config_flag, union_tag)
+    cli_data, cli_configs = _parse_cli(argv, target, cli_prefix, config_flag, union_tag)
 
     # 2. Parse env vars (done here so env-specified config files are loaded in order)
     if env_prefix is None:
@@ -263,7 +263,7 @@ def from_dict[T](
 def load[T](
     target: type[T],
     *,
-    args: Sequence[str] | None = ...,
+    argv: Sequence[str] | None = ...,
     env: Mapping[str, str] | None = ...,
     env_prefix: str | None = ...,
     env_separator: str = ...,
@@ -277,7 +277,7 @@ def load[T](
 def load(
     target: object,
     *,
-    args: Sequence[str] | None = ...,
+    argv: Sequence[str] | None = ...,
     env: Mapping[str, str] | None = ...,
     env_prefix: str | None = ...,
     env_separator: str = ...,
@@ -290,7 +290,7 @@ def load(
 def load[T](  # noqa: PLR0913
     target: type[T] | TypeAliasType | UnionType,
     *,
-    args: Sequence[str] | None = None,
+    argv: Sequence[str] | None = None,
     env: Mapping[str, str] | None = None,
     env_prefix: str | None = _defaults.ENV_PREFIX,
     env_separator: str = "__",
@@ -308,7 +308,7 @@ def load[T](  # noqa: PLR0913
 
     Args:
         target: The dataclass type (or scalar type) to load configuration into.
-        args: CLI arguments to parse. Defaults to sys.argv[1:].
+        argv: CLI arguments to parse. Defaults to sys.argv[1:].
         env: Environment variable mapping to scan. Defaults to os.environ.
         env_prefix: Prefix that env vars must start with. Defaults to ``None``,
             which disables environment variable parsing entirely. Set to ``""``
@@ -344,7 +344,7 @@ def load[T](  # noqa: PLR0913
     """
     data = merge(
         target,
-        args=args,
+        argv=argv,
         env=env,
         env_prefix=env_prefix,
         env_separator=env_separator,