confarg 0.0.1.dev3__tar.gz → 0.0.1.dev4__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: confarg
-Version: 0.0.1.dev3
+Version: 0.0.1.dev4
 Summary: A tool to manage complex, dynamic configurations.
 Author: confarg
 Author-email: confarg <280620574+confarg@users.noreply.github.com>
@@ -11,27 +11,22 @@ 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 favorite CLI library.
 
-## What is `confarg`?
 
-`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 strives to have minimal footprint on your data and app, to make it easy to switch to it, or switch from it.
+`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 can coexist with your favorite argument parser library such as `argparse`, `click`, `typer` or `cyclopts`.
 
 If none of this makes sense to you, read along.
 
-
-## What is not `confarg`?
+## Keep your data structures and CLI
 
 `confarg` is deliberately not a framework, but just a tool.
 
-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.
-
-It doesn't require you to use custom data classes, or to use custom annotations.
+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.
 
 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.
 
@@ -41,7 +36,7 @@ The scope of `confarg` is limited to the deserialization and serialization of co
 pip install confarg
 ```
 
-`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.
+Installing additional libraries such as `pyyaml` unlocks the support of extra configuration file formats.
 
 ## Getting started
 
@@ -411,46 +406,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.dev4}/README.md

@@ -1,24 +1,19 @@
-# 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 favorite CLI library.
 
-## What is `confarg`?
 
-`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 strives to have minimal footprint on your data and app, to make it easy to switch to it, or switch from it.
+`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 can coexist with your favorite argument parser library such as `argparse`, `click`, `typer` or `cyclopts`.
 
 If none of this makes sense to you, read along.
 
-
-## What is not `confarg`?
+## Keep your data structures and CLI
 
 `confarg` is deliberately not a framework, but just a tool.
 
-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.
-
-It doesn't require you to use custom data classes, or to use custom annotations.
+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.
 
 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.
 
@@ -28,7 +23,7 @@ The scope of `confarg` is limited to the deserialization and serialization of co
 pip install confarg
 ```
 
-`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.
+Installing additional libraries such as `pyyaml` unlocks the support of extra configuration file formats.
 
 ## Getting started
 
@@ -398,46 +393,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.dev4}/pyproject.toml

@@ -7,7 +7,7 @@ description = "A tool to manage complex, dynamic configurations."
 name = "confarg"
 readme = "README.md"
 requires-python = ">=3.12"
-version = "0.0.1.dev3"
+version = "0.0.1.dev4"
 
 [project.urls]
 Documentation = "https://confarg.github.io/confarg"

{confarg-0.0.1.dev3 → confarg-0.0.1.dev4}/src/confarg/__init__.py

@@ -15,8 +15,6 @@ if TYPE_CHECKING:
     from collections.abc import Mapping, Sequence
 
 from confarg import _defaults
-from confarg._argparse import FieldMeta, from_namespace, populate_parser
-from confarg._completion import setup_completion
 from confarg._errors import (
     AmbiguousUnionError,
     CircularReferenceError,
@@ -437,11 +435,6 @@ __all__ = [
     "dump_file",
     # Types
     "TagPolicy",
-    # argparse helpers
-    "populate_parser",
-    "from_namespace",
-    "FieldMeta",
-    "setup_completion",
     # Errors / warnings
     "ConfargError",
     "ConfargWarning",

{confarg-0.0.1.dev3 → confarg-0.0.1.dev4}/src/confarg/_merge.py

@@ -301,6 +301,22 @@ def _set_nested(d: dict[str, Any], path: list[str], value: Any) -> None:
         value: The value to set at the target path.
     """
     for part in path[:-1]:
+        # Negative index into an active append-spec: navigate directly into the
+        # appended item so multiple --field+ / --field.-1.sub sequences each
+        # patch their own newly-added item rather than colliding on the "-N" key.
+        if isinstance(d, dict) and LIST_APPEND_KEY in d:
+            try:
+                idx = int(part)
+            except ValueError:
+                pass
+            else:
+                if idx < 0:
+                    items = d[LIST_APPEND_KEY]
+                    if isinstance(items, list):
+                        resolved = idx + len(items)
+                        if 0 <= resolved < len(items) and isinstance(items[resolved], dict):
+                            d = items[resolved]
+                            continue
         if part not in d:
             d[part] = {}
         elif isinstance(d[part], list):

{confarg-0.0.1.dev3 → confarg-0.0.1.dev4}/src/confarg/_types.py

@@ -398,6 +398,45 @@ def _literal_values(tp: Any) -> tuple[Any, ...]:
     return get_args(_resolve_type(tp))
 
 
+def _is_singleton_literal(tp: Any) -> bool:
+    """Check whether a type is a Literal with exactly one allowed value.
+
+    Args:
+        tp: The type to check.
+
+    Returns:
+        True if tp is Literal[X] for a single value X.
+    """
+    return _is_literal(tp) and len(_literal_values(tp)) == 1
+
+
+def _is_final(tp: Any) -> bool:
+    """Check whether a type is a Final annotation.
+
+    Args:
+        tp: The type to check.
+
+    Returns:
+        True if tp is Final[X] for some X.
+    """
+    from typing import Final
+
+    return get_origin(tp) is Final
+
+
+def _final_inner(tp: Any) -> Any:
+    """Return the inner type of a Final annotation.
+
+    Args:
+        tp: A Final[X] type.
+
+    Returns:
+        X, or Any if Final has no argument.
+    """
+    args = get_args(tp)
+    return args[0] if args else Any
+
+
 def _is_enum(tp: Any) -> bool:
     """Check whether a type is an Enum subclass.
 

confarg-0.0.1.dev4/src/confarg/cli/__init__.py

@@ -0,0 +1,15 @@
+# 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/.
+
+"""Framework-agnostic CLI building blocks for confarg."""
+
+from confarg.cli.argparse._build import build_dynamic_flags, build_static_flags
+from confarg.cli.argparse._spec import FieldMeta, FlagSpec
+
+__all__ = [
+    "FieldMeta",
+    "FlagSpec",
+    "build_dynamic_flags",
+    "build_static_flags",
+]

confarg-0.0.1.dev4/src/confarg/cli/argparse/__init__.py

@@ -0,0 +1,34 @@
+# 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/.
+
+"""Argparse integration for confarg.
+
+Public API
+----------
+- :class:`FlagSpec` — framework-agnostic description of one CLI flag
+- :class:`FieldMeta` — per-field metadata (help text, metavar)
+- :func:`build_static_flags` — collect flag specs from a dataclass type
+- :func:`build_dynamic_flags` — collect flag specs discoverable from partial argv
+- :func:`load_flags_into_parser` — load specs into an :class:`argparse.ArgumentParser`
+- :func:`populate_parser` — one-shot: build + load (+ optional dynamic extension)
+- :func:`from_namespace` — construct a dataclass from a parsed :class:`argparse.Namespace`
+- :func:`setup_completion` — enable tab-completion (requires ``argcomplete``)
+"""
+
+from confarg.cli.argparse._build import build_dynamic_flags, build_static_flags
+from confarg.cli.argparse._completion import setup_completion
+from confarg.cli.argparse._namespace import from_namespace
+from confarg.cli.argparse._register import load_flags_into_parser, populate_parser
+from confarg.cli.argparse._spec import FieldMeta, FlagSpec
+
+__all__ = [
+    "FieldMeta",
+    "FlagSpec",
+    "build_dynamic_flags",
+    "build_static_flags",
+    "from_namespace",
+    "load_flags_into_parser",
+    "populate_parser",
+    "setup_completion",
+]