confarg 0.0.1.dev3__tar.gz → 0.0.1.dev5__tar.gz

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

@@ -1,9 +1,10 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.4
 Name: confarg
-Version: 0.0.1.dev3
-Summary: A tool to manage complex, dynamic configurations.
+Version: 0.0.1.dev5
+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,37 +12,64 @@ Project-URL: Repository, https://github.com/confarg/confarg
 Provides-Extra: completion
 Description-Content-Type: text/markdown
 
-# A tool to manage complex, dynamic configurations
+# 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.
 
-## What is `confarg`?
+`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: one or more 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 strives to have minimal footprint on your data and app, to make it easy to switch to it, or switch 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, making it easy to switch to it, or away from it.
 
-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`.
+## Install
 
-If none of this makes sense to you, read along.
+```bash
+pip install confarg
+```
 
+`confarg` comes with no dependency, but installing additional libraries such as `pyyaml` unlocks the support of extra configuration file formats.
 
-## What is not `confarg`?
+## TL;DR
 
-`confarg` is deliberately not a framework, but just a tool.
+This library lets you read configurations stored in classes like this
 
-It does not own the interface with the command line, and it won't help you build a beautiful CLI. However, it can coexist with the one you might be already using.
+```python
+@dataclass
+class Config:
+  value: float
+  flag: bool
+  subconfig: SubConfig1 | SubConfig2
+```
 
-It doesn't require you to use custom data classes, or to use custom annotations.
+with this kind of code
 
-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.
+```python
+config = confarg.load(Config)
+```
 
-## Install
+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
 ```
 
-`confarg` is a stand-alone library that comes with no required dependencies. Installing libraries such as `pyyaml` unlocks the support of additioanl configuration file formats.
+Still here? Read along, we are just getting started.
 
 ## Getting started
 
@@ -411,46 +439,6 @@ db:
   __include__: ./db_config.yaml
 ```
 
-## `confarg` and command-line interfaces
-
-Command line arguments are an essential part of `confarg`. We have seen how they are parsed and consumed implicitly by `confarg.load`.
-
-Although it is not needed for `confarg` to work, application generally provide a command line interface to offer some help and parse parameters.
-
-### What to expect from a CLI regarding complex configurations
-
-We are used to the great user experience provided by CLI libraries such as `click`, `typer` or `cyclopts`. However, porting this great UX to complex configurations is no small feat because of their size and dynamic nature. Inline help is bound to be both very long, reflecting the configuration's complexity, and incomplete, as options coming from derived classes are not available. This could be frustrating.
-
-At the same time, the command line is not the main configuration interface: configuration files are. Building a great CLI UX for complex configuration has a somewhat poor benefit/effort ratio.
-
-### Using a CLI library
-
-The python ecosystem offers many libraries to build powerful and beautiful CLI apps, such as `click`, `typer` or `cyclopts`. Those libraries parse and consume command line arguments, but they also offer a rich user experience by providing help on available commands, sometimes even auto-completion. Some like `cyclopts` also parse concrete nested dataclasses using the dot-separated field command line argument convention used by `confarg` and similar libraries.
-
-Should you use such a library, `confarg` can coexist with them by parsing unused arguments. Currently however, `confarg` will essentially work in "suppress" (`argparse` terminology) or "hidden" (`click` terminology) mode: the arguments won't show in the help generated by those libraries.
-
-### Building your interface with `argparse`
-
-If you manage your interface yourself with `argparse`, `confarg` can step in and provide (limited) help for command line arguments. This is currently an experimental feature.
-
-Not registering `confarg` with your `ArgumentParser` and running in hidden mode is of course an option.
-
-### Optional command line argument prefix
-
-When mixing `confarg` arguments with other application arguments, you may worry about name conflicts, or you may want to clearly identify which arguments belong to the configuration handled by `confarg`, especially if `confarg` is running in hidden arguments mode.
-
-For this purpose, you can specify a prefix for `confarg` command line arguments, using the `cli_prefix` parameter:
-
-```python
-config = confarg.load(Config, args=rgs, cli_prefix="settings")
-```
-
-The command line now cleanly conveys which arguments are routed to the configuration.
-
-```python
-myapp.py --app_arg=hello --settings.config=config.yaml --settings.resources.cpu_count=2
-```
-
 ## Next steps
 
 We have more than scratched the surface, and you should have enough knowledge to cover most of your needs.

{confarg-0.0.1.dev3 → confarg-0.0.1.dev5}/README.md

@@ -1,34 +1,61 @@
-# A tool to manage complex, dynamic configurations
+# 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.
 
-## What is `confarg`?
+`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: one or more 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 strives to have minimal footprint on your data and app, to make it easy to switch to it, or switch 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, making it easy to switch to it, or away from it.
 
-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`.
+## Install
 
-If none of this makes sense to you, read along.
+```bash
+pip install confarg
+```
 
+`confarg` comes with no dependency, but installing additional libraries such as `pyyaml` unlocks the support of extra configuration file formats.
 
-## What is not `confarg`?
+## TL;DR
 
-`confarg` is deliberately not a framework, but just a tool.
+This library lets you read configurations stored in classes like this
 
-It does not own the interface with the command line, and it won't help you build a beautiful CLI. However, it can coexist with the one you might be already using.
+```python
+@dataclass
+class Config:
+  value: float
+  flag: bool
+  subconfig: SubConfig1 | SubConfig2
+```
 
-It doesn't require you to use custom data classes, or to use custom annotations.
+with this kind of code
 
-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.
+```python
+config = confarg.load(Config)
+```
 
-## Install
+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
 ```
 
-`confarg` is a stand-alone library that comes with no required dependencies. Installing libraries such as `pyyaml` unlocks the support of additioanl configuration file formats.
+Still here? Read along, we are just getting started.
 
 ## Getting started
 
@@ -398,46 +425,6 @@ db:
   __include__: ./db_config.yaml
 ```
 
-## `confarg` and command-line interfaces
-
-Command line arguments are an essential part of `confarg`. We have seen how they are parsed and consumed implicitly by `confarg.load`.
-
-Although it is not needed for `confarg` to work, application generally provide a command line interface to offer some help and parse parameters.
-
-### What to expect from a CLI regarding complex configurations
-
-We are used to the great user experience provided by CLI libraries such as `click`, `typer` or `cyclopts`. However, porting this great UX to complex configurations is no small feat because of their size and dynamic nature. Inline help is bound to be both very long, reflecting the configuration's complexity, and incomplete, as options coming from derived classes are not available. This could be frustrating.
-
-At the same time, the command line is not the main configuration interface: configuration files are. Building a great CLI UX for complex configuration has a somewhat poor benefit/effort ratio.
-
-### Using a CLI library
-
-The python ecosystem offers many libraries to build powerful and beautiful CLI apps, such as `click`, `typer` or `cyclopts`. Those libraries parse and consume command line arguments, but they also offer a rich user experience by providing help on available commands, sometimes even auto-completion. Some like `cyclopts` also parse concrete nested dataclasses using the dot-separated field command line argument convention used by `confarg` and similar libraries.
-
-Should you use such a library, `confarg` can coexist with them by parsing unused arguments. Currently however, `confarg` will essentially work in "suppress" (`argparse` terminology) or "hidden" (`click` terminology) mode: the arguments won't show in the help generated by those libraries.
-
-### Building your interface with `argparse`
-
-If you manage your interface yourself with `argparse`, `confarg` can step in and provide (limited) help for command line arguments. This is currently an experimental feature.
-
-Not registering `confarg` with your `ArgumentParser` and running in hidden mode is of course an option.
-
-### Optional command line argument prefix
-
-When mixing `confarg` arguments with other application arguments, you may worry about name conflicts, or you may want to clearly identify which arguments belong to the configuration handled by `confarg`, especially if `confarg` is running in hidden arguments mode.
-
-For this purpose, you can specify a prefix for `confarg` command line arguments, using the `cli_prefix` parameter:
-
-```python
-config = confarg.load(Config, args=rgs, cli_prefix="settings")
-```
-
-The command line now cleanly conveys which arguments are routed to the configuration.
-
-```python
-myapp.py --app_arg=hello --settings.config=config.yaml --settings.resources.cpu_count=2
-```
-
 ## Next steps
 
 We have more than scratched the surface, and you should have enough knowledge to cover most of your needs.

{confarg-0.0.1.dev3 → confarg-0.0.1.dev5}/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.dev3"
+version = "0.0.1.dev5"
 
 [project.urls]
 Documentation = "https://confarg.github.io/confarg"
@@ -31,6 +31,7 @@ dev = [
     "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.dev5/src/confarg/__init__.py

@@ -0,0 +1,33 @@
+# 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 confarg import exceptions
+from confarg._api import build, dump, dump_file, from_dict, load, merge, resolve
+from confarg._types import TagPolicy
+
+__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",
+    # Exceptions / warnings
+    "exceptions",
+]