confargs 0.2.0__py3-none-any.whl

confargs/__init__.py

@@ -0,0 +1,44 @@
+"""confargs: declarative CLI parsing that merges CLI, env vars and TOML config.
+
+Declare options as methods on an :class:`ArgConfig` subclass, decorate them with
+:func:`option`, then resolve everything with ``ConfigurationProcessor``.
+"""
+
+from __future__ import annotations
+
+from confargs.argfile import read_argument_file, split_argument_file
+from confargs.base import ArgConfig
+from confargs.exceptions import (
+    MISSING,
+    ArgConfigError,
+    CliUsageError,
+    ConfigDiscoveryError,
+    Exit,
+    OptionDefinitionError,
+    OptionValueError,
+)
+from confargs.namespace import Namespace
+from confargs.options import Option, collect_options, option, resolve_names
+from confargs.processor import ConfigurationProcessor
+
+__version__ = "0.2.0"  # x-release-please-version
+
+__all__ = [
+    "MISSING",
+    "ArgConfig",
+    "ArgConfigError",
+    "CliUsageError",
+    "ConfigDiscoveryError",
+    "ConfigurationProcessor",
+    "Exit",
+    "Namespace",
+    "Option",
+    "OptionDefinitionError",
+    "OptionValueError",
+    "__version__",
+    "collect_options",
+    "option",
+    "read_argument_file",
+    "resolve_names",
+    "split_argument_file",
+]

confargs/argfile.py

@@ -0,0 +1,77 @@
+"""Helpers for reading *argument files* — text files that contain more options.
+
+This mirrors the well-known Robot Framework ``--argumentfile`` format so that an
+eager option (see :func:`confargs.option`) can expand a file into extra CLI
+tokens:
+
+* each line is stripped of surrounding whitespace,
+* blank lines and ``#`` comment lines are ignored,
+* a line starting with ``-`` is an option; it is split into a name and value on
+  the first space or ``=`` (whichever comes first), and
+* any other non-empty line is passed through as a positional token.
+
+Only the parsing is provided here; the decision to inject the resulting tokens
+is made by the eager option's method, which returns them to the processor.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+def _option_separator(line: str) -> str | None:
+    """Return the separator (space or ``=``) between an option and its value."""
+    if " " not in line and "=" not in line:
+        return None
+    if "=" not in line:
+        return " "
+    if " " not in line:
+        return "="
+    return " " if line.index(" ") < line.index("=") else "="
+
+
+def _split_option(line: str) -> list[str]:
+    separator = _option_separator(line)
+    if separator is None:
+        return [line]
+    name, value = line.split(separator, 1)
+    if separator == " ":
+        value = value.strip()
+    return [name, value]
+
+
+def split_argument_file(text: str) -> list[str]:
+    """Tokenize the *contents* of an argument file into a list of argv tokens.
+
+    Args:
+        text: The full text of an argument file.
+
+    Returns:
+        The tokens to splice into ``argv``.
+    """
+    tokens: list[str] = []
+    for raw_line in text.splitlines():
+        line = raw_line.strip()
+        if line.startswith("-"):
+            tokens.extend(_split_option(line))
+        elif line and not line.startswith("#"):
+            tokens.append(line)
+    return tokens
+
+
+def read_argument_file(path: str | Path, *, encoding: str = "utf-8") -> list[str]:
+    """Read an argument file from disk and tokenize it.
+
+    Args:
+        path: Path to the argument file.
+        encoding: Text encoding used to read the file.
+
+    Returns:
+        The tokens to splice into ``argv``.
+    """
+    from pathlib import Path as _Path
+
+    return split_argument_file(_Path(path).read_text(encoding=encoding))

confargs/base.py

@@ -0,0 +1,72 @@
+"""The :class:`ArgConfig` base class that tool authors subclass."""
+
+from __future__ import annotations
+
+from confargs.exceptions import Exit
+from confargs.options import option
+
+
+class ArgConfig:
+    """Base class for a tool's configuration.
+
+    Subclass this and declare options as methods decorated with
+    :func:`confargs.option`. Class attributes configure discovery and naming:
+
+    Attributes:
+        name: The tool name. Used for the default TOML section
+            (``[tool.<name>]``) and, when ``auto_env_vars`` is enabled, for the
+            environment variable prefix.
+        config_names: File names to look for when discovering TOML config,
+            in priority order.
+        default_config_section: Dotted path of the TOML table to read
+            (e.g. ``"tool.mytool"``). When unset, ``tool.<name>`` is used.
+        auto_env_vars: When true, every option (that is not ``cli_only``) gets
+            an implicit environment variable named ``<NAME>_<OPTION>``.
+        strict_config: When true (the default), unknown keys or ``cli_only``
+            options found in a TOML config section raise an error instead of
+            being ignored.
+    """
+
+    name: str | None = None
+    config_names: list[str] = ["pyproject.toml"]  # noqa: RUF012 - documented, per-subclass override
+    default_config_section: str | None = None
+    auto_env_vars: bool = False
+    strict_config: bool = True
+
+    @option(names="--help/-h", cli_only=True)
+    def help(self, value: bool = False) -> bool:
+        """Show this help message and exit."""
+        if value:
+            from confargs.help import format_help
+
+            print(format_help(self))
+            raise Exit(0)
+        return value
+
+    @option(names="--config", cli_only=True)
+    def config(self, value: str | None = None) -> str | None:
+        """Read configuration from this file only, skipping discovery."""
+        return value
+
+    @option(names="--no-config", cli_only=True)
+    def no_config(self, value: bool = False) -> bool:
+        """Do not read any configuration file."""
+        return value
+
+    @option(names="--ignore-git", cli_only=True)
+    def ignore_git(self, value: bool = False) -> bool:
+        """Keep searching for config files above the project's .git directory."""
+        return value
+
+    @property
+    def config_section(self) -> tuple[str, ...]:
+        """The TOML table path to read configuration from."""
+        if self.default_config_section:
+            return tuple(self.default_config_section.split("."))
+        base = self.name or type(self).__name__.lower()
+        return ("tool", base)
+
+    @property
+    def tool_name(self) -> str:
+        """A non-optional tool name, falling back to the class name."""
+        return self.name or type(self).__name__.lower()

confargs/cli.py

@@ -0,0 +1,167 @@
+"""A minimal command-line tokenizer.
+
+This is deliberately tiny: it only splits ``argv`` into raw per-option values.
+It does **no** type conversion, defaulting or validation — those happen later so
+that the same coercion/validation path is shared by every source (CLI, env,
+TOML). Supported forms:
+
+* ``--long value`` and ``--long=value``
+* ``-s value``, ``-svalue`` (attached) and combined flags ``-abc``
+* boolean flags: ``--flag`` / ``-f`` (and ``--flag=false``)
+* boolean negation: ``--no-flag`` sets a boolean option to ``False``
+* ``--`` terminates option parsing; the rest are positionals
+* a lone ``-`` is treated as a positional (stdin convention)
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+
+from confargs.exceptions import CliUsageError
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from confargs.options import NameTable
+
+
+@dataclass
+class CliResult:
+    """The outcome of tokenizing ``argv``."""
+
+    values: dict[str, Any] = field(default_factory=dict)
+    positionals: list[str] = field(default_factory=list)
+
+
+def _store(result: CliResult, attr: str, value: Any, list_opts: set[str]) -> None:
+    if attr in list_opts:
+        result.values.setdefault(attr, []).append(value)
+    else:
+        result.values[attr] = value
+
+
+def negation_name(long_name: str) -> str:
+    """Return the ``--no-`` negation form of a long option name."""
+    return f"--no-{long_name[2:]}"
+
+
+def _negated_flag_attr(name: str, table: NameTable, flags: set[str]) -> str | None:
+    """If ``name`` is a ``--no-<flag>`` negation of a known flag, return its attr."""
+    if not name.startswith("--no-"):
+        return None
+    base = f"--{name[len('--no-') :]}"
+    attr = table.long_to_attr.get(base)
+    if attr is not None and attr in flags:
+        return attr
+    return None
+
+
+def parse_cli(
+    argv: Sequence[str],
+    table: NameTable,
+    flags: set[str],
+    list_opts: set[str],
+) -> CliResult:
+    """Tokenize ``argv`` into raw per-option values.
+
+    Args:
+        argv: Arguments to parse (without the program name).
+        table: Resolved name-to-attribute mapping.
+        flags: Attribute names of boolean flag options.
+        list_opts: Attribute names of repeatable (list) options.
+    """
+    result = CliResult()
+    args = list(argv)
+    index = 0
+    positional_only = False
+
+    while index < len(args):
+        token = args[index]
+        index += 1
+
+        if positional_only:
+            result.positionals.append(token)
+            continue
+        if token == "--":
+            positional_only = True
+            continue
+        if token == "-" or not token.startswith("-"):
+            result.positionals.append(token)
+            continue
+
+        if token.startswith("--"):
+            index = _handle_long(token, args, index, result, table, flags, list_opts)
+        else:
+            index = _handle_short(token, args, index, result, table, flags, list_opts)
+
+    return result
+
+
+def _consume_value(name: str, args: list[str], index: int, table: NameTable) -> tuple[str, int]:
+    if index >= len(args) or table.attr_for(args[index]) is not None or args[index] == "--":
+        raise CliUsageError(f"option {name!r} expects a value")
+    return args[index], index + 1
+
+
+def _handle_long(
+    token: str,
+    args: list[str],
+    index: int,
+    result: CliResult,
+    table: NameTable,
+    flags: set[str],
+    list_opts: set[str],
+) -> int:
+    name, sep, inline = token.partition("=")
+    attr = table.long_to_attr.get(name)
+    if attr is None:
+        negated = _negated_flag_attr(name, table, flags)
+        if negated is not None:
+            if sep:
+                raise CliUsageError(f"option {name!r} does not take a value")
+            _store(result, negated, False, list_opts)
+            return index
+        raise CliUsageError(f"unknown option {name!r}")
+
+    if attr in flags:
+        _store(result, attr, inline if sep else True, list_opts)
+        return index
+
+    if sep:
+        _store(result, attr, inline, list_opts)
+        return index
+    value, index = _consume_value(name, args, index, table)
+    _store(result, attr, value, list_opts)
+    return index
+
+
+def _handle_short(
+    token: str,
+    args: list[str],
+    index: int,
+    result: CliResult,
+    table: NameTable,
+    flags: set[str],
+    list_opts: set[str],
+) -> int:
+    body = token[1:]
+    position = 0
+    while position < len(body):
+        name = f"-{body[position]}"
+        attr = table.short_to_attr.get(name)
+        if attr is None:
+            raise CliUsageError(f"unknown option {name!r}")
+        if attr in flags:
+            _store(result, attr, True, list_opts)
+            position += 1
+            continue
+        # Value option: the remainder of the cluster is the value, else the next token.
+        attached = body[position + 1 :]
+        if attached:
+            _store(result, attr, attached, list_opts)
+        else:
+            value, index = _consume_value(name, args, index, table)
+            _store(result, attr, value, list_opts)
+        return index
+    return index

confargs/coercion.py

@@ -0,0 +1,129 @@
+"""Type resolution and coercion of raw source values.
+
+confargs only performs *basic* coercion so that the value handed to a user's
+option method matches the type they annotated. All domain validation and
+parsing is left to the method itself.
+
+Values arrive in two shapes:
+
+* **strings** from the command line and environment variables, and
+* **already-typed** values from TOML (``int``, ``float``, ``bool``, ``str``,
+  ``list``).
+
+:func:`coerce_value` normalises both into the option's declared type.
+"""
+
+from __future__ import annotations
+
+import types
+import typing
+from dataclasses import dataclass
+from typing import Any, Union, get_args, get_origin
+
+from confargs.exceptions import MISSING, OptionValueError
+
+if typing.TYPE_CHECKING:
+    from confargs.options import Option
+
+_TRUE = {"1", "true", "yes", "on", "y", "t"}
+_FALSE = {"0", "false", "no", "off", "n", "f"}
+
+_UNION_ORIGINS = {Union, types.UnionType}
+
+
+@dataclass(frozen=True)
+class ValueType:
+    """A simplified description of an option's declared value type."""
+
+    base: type
+    is_list: bool = False
+    allows_none: bool = False
+
+    @property
+    def is_flag(self) -> bool:
+        """A boolean, non-list option — a command line flag."""
+        return self.base is bool and not self.is_list
+
+
+def resolve_value_type(option: Option) -> ValueType:
+    """Inspect an option method and describe the type its value expects."""
+    annotation = option.raw_annotation
+    if annotation is MISSING:
+        return ValueType(base=str)
+
+    hints = typing.get_type_hints(option.func)
+    hint = hints.get(option.value_parameter.name, str)
+    return _analyse(hint)
+
+
+def _analyse(hint: Any) -> ValueType:
+    allows_none = False
+    origin = get_origin(hint)
+
+    if origin in _UNION_ORIGINS:
+        args = [arg for arg in get_args(hint) if arg is not type(None)]
+        allows_none = len(args) != len(get_args(hint))
+        # Take the first concrete member as the representative type.
+        hint = args[0] if args else str
+        origin = get_origin(hint)
+
+    if origin in (list, set, tuple):
+        elem_args = get_args(hint)
+        element = elem_args[0] if elem_args else str
+        base = element if isinstance(element, type) else str
+        return ValueType(base=base, is_list=True, allows_none=allows_none)
+
+    base = hint if isinstance(hint, type) else str
+    return ValueType(base=base, is_list=False, allows_none=allows_none)
+
+
+def parse_bool(raw: str) -> bool:
+    """Parse a boolean from a string, accepting common spellings."""
+    lowered = raw.strip().lower()
+    if lowered in _TRUE:
+        return True
+    if lowered in _FALSE:
+        return False
+    raise OptionValueError(f"cannot interpret {raw!r} as a boolean")
+
+
+def _coerce_scalar(raw: Any, base: type) -> Any:
+    if base is bool:
+        if isinstance(raw, bool):
+            return raw
+        return parse_bool(str(raw))
+    if base is str:
+        return raw if isinstance(raw, str) else str(raw)
+    if base in (int, float):
+        try:
+            return base(raw)
+        except (TypeError, ValueError) as exc:
+            raise OptionValueError(f"cannot interpret {raw!r} as {base.__name__}") from exc
+    # Unknown/custom base type: pass the raw value through untouched.
+    return raw
+
+
+def _as_list(raw: Any) -> list[Any]:
+    if isinstance(raw, (list, tuple, set)):
+        return list(raw)
+    if isinstance(raw, str):
+        return [item.strip() for item in raw.split(",") if item.strip()]
+    return [raw]
+
+
+def coerce_value(raw: Any, value_type: ValueType) -> Any:
+    """Coerce a raw source value into the option's declared type.
+
+    ``None`` is passed through when the option allows it. List options accept
+    native sequences (TOML arrays, repeated CLI flags) or comma-separated
+    strings (environment variables).
+    """
+    if raw is None:
+        if value_type.allows_none:
+            return None
+        raise OptionValueError("value may not be null")
+
+    if value_type.is_list:
+        return [_coerce_scalar(item, value_type.base) for item in _as_list(raw)]
+
+    return _coerce_scalar(raw, value_type.base)

confargs/demo.py

@@ -0,0 +1,77 @@
+"""A small, runnable example tool built with confargs.
+
+This module doubles as the ``confargs-demo`` console script (see
+``[project.scripts]`` in ``pyproject.toml``). Try it once installed::
+
+    confargs-demo --console quiet --retries 5
+    confargs-demo --log NONE
+    MYTOOL_CONSOLE=dotted confargs-demo
+    confargs-demo --help
+
+Or without installing::
+
+    uv run confargs-demo --console quiet
+
+Configuration is also read from ``[tool.mytool]`` in a discovered
+``pyproject.toml`` and from ``MYTOOL_*`` environment variables.
+"""
+
+from __future__ import annotations
+
+import confargs
+from confargs import ArgConfig
+
+__all__ = ["MyArgs", "main"]
+
+
+class MyArgs(ArgConfig):
+    """mytool - a tiny demo CLI built with confargs.
+
+    Shows how command line arguments, environment variables and TOML config are
+    merged into one configuration object.
+    """
+
+    name = "mytool"
+    auto_env_vars = True
+
+    @confargs.option
+    def log(self, value: str | None = "log.html") -> str | None:
+        """HTML log file. Disable with the special value 'NONE'."""
+        if value == "NONE":
+            return None
+        return value
+
+    @confargs.option(names="--console/-c")
+    def console(self, value: str = "verbose") -> str:
+        """Console output mode: verbose, dotted, quiet or none."""
+        choices = ["verbose", "dotted", "quiet", "none"]
+        if value not in choices:
+            raise confargs.OptionValueError(f"console must be one of {choices}, got {value!r}")
+        return value
+
+    @confargs.option
+    def retries(self, value: int = 3) -> int:
+        """Number of retries on failure."""
+        if value < 0:
+            raise confargs.OptionValueError("retries must be >= 0")
+        return value
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Entry point for the ``confargs-demo`` console script."""
+    try:
+        config = confargs.ConfigurationProcessor(MyArgs, argv=argv).process()
+    except confargs.Exit as exit_signal:
+        return exit_signal.code
+    except confargs.ArgConfigError as error:
+        print(f"error: {error}")
+        return 2
+
+    print("log     =", config.log)
+    print("console =", config.console)
+    print("retries =", config.retries)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

confargs/env_source.py

@@ -0,0 +1,50 @@
+"""Environment-variable configuration source.
+
+Each option can read from an environment variable in one of two ways:
+
+* explicitly, via ``@option(envvar="MY_TOOL_LOG")``, or
+* implicitly, when the config class sets ``auto_env_vars = True``, in which case
+  every non-``cli_only`` option gets an implicit variable named
+  ``<TOOL_NAME>_<OPTION>`` (upper-cased).
+
+An explicit ``envvar`` always wins over the auto-generated name.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+    from confargs.options import Option
+
+
+def env_var_name(
+    option: Option,
+    tool_name: str,
+    *,
+    auto_env_vars: bool,
+) -> str | None:
+    """Return the environment variable name for ``option``, or ``None``."""
+    if option.envvar:
+        return option.envvar
+    if auto_env_vars and not option.cli_only:
+        return f"{tool_name.upper()}_{option.attr_name.upper()}"
+    return None
+
+
+def collect_env_values(
+    options: Mapping[str, Option],
+    tool_name: str,
+    *,
+    auto_env_vars: bool,
+    environ: Mapping[str, str],
+) -> dict[str, str]:
+    """Collect raw option values present in ``environ``."""
+    values: dict[str, str] = {}
+    for attr, option in options.items():
+        name = env_var_name(option, tool_name, auto_env_vars=auto_env_vars)
+        if name is not None and name in environ:
+            values[attr] = environ[name]
+    return values

confargs/exceptions.py

@@ -0,0 +1,62 @@
+"""Exceptions and sentinels used across confargs."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class _Missing:
+    """Sentinel for "no value supplied" (distinct from ``None``)."""
+
+    _instance: _Missing | None = None
+
+    def __new__(cls) -> _Missing:
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+
+    def __repr__(self) -> str:
+        return "MISSING"
+
+    def __bool__(self) -> bool:
+        return False
+
+
+MISSING: Any = _Missing()
+"""Singleton sentinel meaning "this source did not provide a value"."""
+
+
+class ArgConfigError(Exception):
+    """Base class for every error raised by confargs."""
+
+
+class OptionDefinitionError(ArgConfigError):
+    """Raised when an option/config class is defined incorrectly.
+
+    This signals a *programming* error in the tool that uses confargs (for
+    example, two options claiming the same name), not bad user input.
+    """
+
+
+class OptionValueError(ArgConfigError):
+    """Raised when a supplied option value is invalid.
+
+    Tool authors raise this from their option methods to reject a value; the
+    processor turns it into a friendly command-line error.
+    """
+
+
+class ConfigDiscoveryError(ArgConfigError):
+    """Raised when configuration files cannot be read or parsed."""
+
+
+class CliUsageError(ArgConfigError):
+    """Raised for malformed command-line input (unknown or incomplete options)."""
+
+
+class Exit(ArgConfigError):
+    """Raised to stop processing and exit (e.g. after printing ``--help``)."""
+
+    def __init__(self, code: int = 0) -> None:
+        super().__init__(f"exit with code {code}")
+        self.code = code