argbind-dbraun 0.5.2__py3-none-any.whl

argbind/__init__.py

@@ -0,0 +1,21 @@
+from .argbind import (
+    bind,
+    bind_module,
+    build_parser,
+    dump_args,
+    get_used_args,
+    load_args,
+    parse_args,
+    scope,
+)
+
+__all__ = [
+    "bind",
+    "bind_module",
+    "build_parser",
+    "parse_args",
+    "dump_args",
+    "load_args",
+    "get_used_args",
+    "scope",
+]

argbind/argbind.py

@@ -0,0 +1,798 @@
+import argparse
+import ast
+import dataclasses
+import inspect
+import os
+import sys
+import textwrap
+import types
+import warnings
+from contextlib import contextmanager
+from functools import wraps
+from pathlib import Path
+from typing import Literal, Union, get_args, get_origin
+
+import docstring_parser
+import yaml
+
+PARSE_FUNCS = {}
+ARGS = {}
+USED_ARGS = {}
+PATTERN = None
+DEBUG = False
+HELP_WIDTH = 60
+
+
+# A dataclass field with a default_factory shows this singleton as its __init__
+# default; capture it via public API (rather than importing a private name) so it
+# can be filtered out before serialization. See dump_args.
+@dataclasses.dataclass
+class _FactoryProbe:
+    x: list = dataclasses.field(default_factory=list)
+
+
+_DEFAULT_FACTORY_SENTINEL = (
+    inspect.signature(_FactoryProbe.__init__).parameters["x"].default
+)
+
+
+@contextmanager
+def scope(parsed_args, pattern=""):
+    """
+    Context manager to put parsed arguments into
+    a state.
+    """
+    parsed_args = parsed_args.copy()
+    remove_keys = []
+    matched = {}
+
+    global ARGS
+    global PATTERN
+
+    old_args = ARGS
+    old_pattern = PATTERN
+
+    for key in parsed_args:
+        if "/" in key:
+            if key.split("/")[0] == pattern:
+                matched[key.split("/")[-1]] = parsed_args[key]
+            remove_keys.append(key)
+
+    parsed_args.update(matched)
+    for key in remove_keys:
+        parsed_args.pop(key)
+    ARGS = parsed_args
+    PATTERN = pattern
+    yield
+
+    ARGS = old_args
+    PATTERN = old_pattern
+
+
+def _format_func_debug(func_name, func_kwargs, scope=None):
+    formatted = [f"{func_name}("]
+    if scope is not None:
+        formatted.append(f"  # scope = {scope}")
+    for key, val in func_kwargs.items():
+        formatted.append(f"  {key} : {type(val).__name__} = {val}")
+    formatted.append(")")
+    return "\n".join(formatted)
+
+
+def bind(
+    *args, without_prefix=False, positional=False, group: Union[list, str] = "default"
+):
+    """Binds a functions arguments so that it looks up argument
+    values in a dictionary scoped by ArgBind.
+
+    Parameters
+    ----------
+    args : List[str] or [fn or Object] + List[str], optional
+        List of patterns to bind the function under. If the first item
+        in the list is a function or Object, then the function is bound
+        here (e.g. decorate is called on the first argument). Otherwise,
+        it is treated is a decorator.
+    without_prefix : bool, optional
+        Whether or not to bind without the function name as the prefix.
+        If True, the functions arguments will be available at "arg_name"
+        rather than "func_name.arg_name", by default False
+    positional : bool, optional
+        Arguments that are not keyword arguments are not bound by default. If
+        this is True, then the arguments will be bound as positional arguments
+        in some order, by default False
+    group : list or str, optional
+        Group or list of groups to assign this function to. ``build_parser``
+        and ``parse_args`` can then build a parser for only a subset of bound
+        functions by group, by default "default".
+    """
+
+    if args and not isinstance(args[0], str):
+        bound_fn_or_cls = args[0]
+        patterns = args[1:] if len(args) > 1 else []
+    else:
+        bound_fn_or_cls = None
+        patterns = args
+
+    if positional and patterns:
+        warnings.warn(
+            f"Combining positional arguments with scoping patterns is not allowed. Removing scoping patterns {patterns}. \n"
+            "See https://github.com/pseeth/argbind/tree/main/examples/hello_world#argbind-with-positional-arguments"
+        )
+        patterns = []
+
+    if isinstance(group, str):
+        group = [group]
+
+    def decorator(object_or_func):
+        func = object_or_func
+        prefix = func.__qualname__  # get prefix before a potential monkey patch below changes it to a superclass's prefix
+        is_class = inspect.isclass(func)
+        if is_class:
+            # If the class has no __init__ method, find the __init__ method from the closest superclass
+            # that defines one. Then monkey patch that __init__ onto the class.
+            if "__init__" not in func.__dict__:
+                for base in func.__mro__[1:]:
+                    if "__init__" in base.__dict__:
+                        func.__init__ = base.__init__  # monkey patch
+                        break
+            func = getattr(func, "__init__")
+
+        if "__init__" in prefix:
+            prefix = prefix.split(".")[0]
+
+        # Check if function is bound already. If it is, just re-wrap it,
+        # instead of wrapping the function twice.
+        if prefix in PARSE_FUNCS:
+            func = PARSE_FUNCS[prefix][0]
+        else:
+            PARSE_FUNCS[prefix] = (func, patterns, without_prefix, positional, group)
+
+        @wraps(func)
+        def cmd_func(*args, **kwargs):
+            parameters = list(inspect.signature(func).parameters.items())
+
+            cmd_kwargs = {}
+            pos_kwargs = {parameters[i][0]: arg for i, arg in enumerate(args)}
+
+            for key, param in parameters:
+                arg_val = param.default
+                if arg_val is not inspect.Parameter.empty or positional:
+                    arg_name = f"{prefix}.{key}" if not without_prefix else f"{key}"
+                    if arg_name in ARGS and key not in kwargs:
+                        val = ARGS[arg_name]
+                        if key in pos_kwargs:
+                            val = pos_kwargs[key]
+                        # Cast value to the expected type (important for YAML-loaded values)
+                        val = _cast_value(val, param.annotation)
+                        cmd_kwargs[key] = val
+                        use_key = arg_name
+                        if PATTERN:
+                            use_key = f"{PATTERN}/{use_key}"
+                        USED_ARGS[use_key] = val
+
+            kwargs.update(cmd_kwargs)
+            cmd_args = []
+            for i, arg in enumerate(args):
+                key = parameters[i][0]
+                if key not in kwargs:
+                    cmd_args.append(arg)
+
+            # Ensure dictionary order is in parameter order
+            kwargs = {k: kwargs[k] for k, _ in parameters if k in kwargs}
+
+            if "args.debug" not in ARGS:
+                ARGS["args.debug"] = False
+            if ARGS["args.debug"] or DEBUG:
+                if PATTERN:
+                    scope = PATTERN
+                else:
+                    scope = None
+                print(_format_func_debug(prefix, kwargs, scope))
+            return func(*cmd_args, **kwargs)
+
+        if is_class:
+            setattr(object_or_func, "__init__", cmd_func)
+            cmd_func = object_or_func
+
+        return cmd_func
+
+    if bound_fn_or_cls is None:
+        return decorator
+    else:
+        return decorator(bound_fn_or_cls)
+
+
+class bind_module:
+    def __init__(self, module, *scopes, filter_fn=lambda fn: True, **kwargs):
+        """Binds every function/class in a specified module. The output
+        class is a bound version of the original module, with the
+        attributes in the same place.
+
+        Parameters
+        ----------
+        module : ModuleType
+            Module or object whose attributes to bind.
+        scopes : List[str] or [fn or Object] + List[str], optional
+            List of patterns to bind the function under.
+        filter_fn : Callable, optional
+            A function that takes in the function that is to be bound, and
+            returns a boolean whether it should be bound.
+            Defaults to always True, no matter what the function is.
+        kwargs : keyword arguments, optional
+            Keyword arguments to the bind function.
+
+        """
+        for fn_name in dir(module):
+            fn = getattr(module, fn_name)
+            if not isinstance(fn, type(sys)) and hasattr(fn, "__qualname__"):
+                if filter_fn(fn):
+                    bound_fn = bind(fn, *scopes, **kwargs)
+                    setattr(self, fn_name, bound_fn)
+
+
+def get_used_args():
+    """
+    Gets the args that have been used so far
+    by the script (e.g. their function they target
+    was actually called).
+    """
+    return USED_ARGS
+
+
+def dump_args(args, output_path):
+    """
+    Dumps the provided arguments to a
+    file.
+    """
+    path = Path(output_path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    # Drop the dataclasses default_factory sentinel; it is not serializable.
+    filtered_args = {}
+    for key, value in args.items():
+        if value is not _DEFAULT_FACTORY_SENTINEL:
+            filtered_args[key] = value
+
+    with open(path, "w") as f:
+        yaml.Dumper.ignore_aliases = lambda *args: True
+        x = yaml.dump(filtered_args, Dumper=yaml.Dumper)
+        prev_line = None
+        output = []
+        for line in x.split("\n"):
+            cur_line = line.split(".")[0].strip()
+            if not cur_line.startswith("-"):
+                if cur_line != prev_line and prev_line:
+                    line = f"\n{line}"
+                prev_line = line.split(".")[0].strip()
+            output.append(line)
+        f.write("\n".join(output))
+
+
+def load_args(input_path_or_stream):
+    """
+    Loads arguments from a given input path or file stream, if
+    the file is already open.
+    """
+    if isinstance(input_path_or_stream, (str, Path)):
+        path = Path(input_path_or_stream)
+        # Resolve $include relative to THIS file's directory (not the process CWD), so a
+        # config and its include tree load identically regardless of where it's invoked
+        # from — including when installed read-only in site-packages.
+        base_dir = path.resolve().parent
+        with path.open("r") as f:
+            data = yaml.load(f, Loader=yaml.Loader)
+    else:
+        base_dir = None
+        data = yaml.load(input_path_or_stream, Loader=yaml.Loader)
+
+    if "$include" in data:
+        include_files = data.pop("$include")
+        include_args = {}
+        for include_file in include_files:
+            # Prefer file-relative resolution (CWD-independent). Fall back to the legacy
+            # CWD-relative path if the file-relative one doesn't exist, so configs that
+            # still write includes relative to the run directory keep working.
+            if base_dir is not None and not Path(include_file).is_absolute():
+                file_relative = base_dir / include_file
+                if file_relative.exists():
+                    include_file = file_relative
+            include_args.update(load_args(include_file))
+        include_args.update(data)
+        data = include_args
+
+    _vars = os.environ.copy()
+    if "$vars" in data:
+        _vars.update(data.pop("$vars"))
+
+    for key, val in data.items():
+        # Check if string starts with $.
+        if isinstance(val, str):
+            if val.startswith("$"):
+                lookup = val[1:]
+                if lookup in _vars:
+                    data[key] = _vars[lookup]
+
+        elif isinstance(val, list):
+            new_list = []
+            for subval in val:
+                if isinstance(subval, str) and subval.startswith("$"):
+                    lookup = subval[1:]
+                    if lookup in _vars:
+                        new_list.append(_vars[lookup])
+                    else:
+                        new_list.append(subval)
+                else:
+                    new_list.append(subval)
+            data[key] = new_list
+
+    if "args.debug" not in data:
+        data["args.debug"] = DEBUG
+    return data
+
+
+class str_to_list:
+    def __init__(self, _type):
+        self._type = _type
+
+    def __call__(self, values):
+        _values = values.split(" ")
+        _values = [self._type(v) for v in _values]
+        return _values
+
+
+class str_to_tuple:
+    def __init__(self, _type_list):
+        self._type_list = _type_list
+
+    def __call__(self, values):
+        _values = values.split(" ")
+        if len(self._type_list) == 2 and self._type_list[1] is Ellipsis:
+            # Variable-length tuple[X, ...]: every element has the same type
+            return tuple(self._type_list[0](v) for v in _values)
+        _values = [self._type_list[i](v) for i, v in enumerate(_values)]
+        return tuple(_values)
+
+
+class str_to_dict:
+    def __init__(self):
+        pass
+
+    def _guess_type(self, s):
+        try:
+            value = ast.literal_eval(s)
+        except ValueError:
+            return s
+        else:
+            return value
+
+    def __call__(self, values):
+        values = values.split(" ")
+        _values = {}
+
+        for elem in values:
+            key, val = elem.split("=", 1)
+            key = self._guess_type(key)
+            val = self._guess_type(val)
+            _values[key] = val
+
+        return _values
+
+
+class str_to_bool:
+    def __init__(self):
+        pass
+
+    def __call__(self, value):
+        """Convert string or int to bool.
+
+        Accepts: 0, 1, 'true', 'false', 'True', 'False'
+        """
+        if isinstance(value, bool):
+            return value
+        if isinstance(value, int):
+            return bool(value)
+        if value.lower() in ("true", "1"):
+            return True
+        if value.lower() in ("false", "0"):
+            return False
+        raise ValueError(f"Cannot convert {value} to bool")
+
+
+# PEP 604 unions (X | None) have origin types.UnionType rather than
+# typing.Union on Python 3.11-3.13 (the two are unified in 3.14).
+_UNION_ORIGINS = tuple({Union, types.UnionType})
+
+
+def _unwrap_optional(arg_type):
+    """Unwrap Optional[X] or X | None to X, return None if not Optional.
+
+    Args:
+        arg_type: Type annotation to check
+
+    Returns:
+        The inner type if arg_type is Optional[X] / X | None, otherwise None
+    """
+    origin = get_origin(arg_type)
+    if origin in _UNION_ORIGINS:
+        args = get_args(arg_type)
+        # Check if this is Optional[X] (i.e., Union[X, None])
+        if len(args) == 2 and type(None) in args:
+            # Return the non-None type
+            return args[0] if args[1] is type(None) else args[1]
+    return None
+
+
+def _unwrap_literal(arg_type):
+    """Unwrap Literal[v1, v2, ...] to its allowed values, return None if not Literal.
+
+    Args:
+        arg_type: Type annotation to check
+
+    Returns:
+        Tuple of allowed values if arg_type is Literal[...], otherwise None
+    """
+    if get_origin(arg_type) is Literal:
+        return get_args(arg_type)
+    return None
+
+
+def _cast_value(value, target_type):
+    """Cast a value to the target type if needed.
+
+    This is used when loading values from YAML files to ensure they match
+    the expected type from function signatures.
+
+    Args:
+        value: The value to cast
+        target_type: The target type annotation
+
+    Returns:
+        The value cast to the target type, or the original value if already correct type
+    """
+    # If target_type is not specified, return as-is
+    if target_type is inspect.Parameter.empty:
+        return value
+
+    # Unwrap Optional[X] to X if needed
+    unwrapped = _unwrap_optional(target_type)
+    if unwrapped is not None:
+        target_type = unwrapped
+
+    # Handle None values
+    if value is None:
+        return value
+
+    # Handle Literal[v1, v2, ...] — cast to the type of the first allowed value
+    literal_values = _unwrap_literal(target_type)
+    if literal_values is not None:
+        val_type = type(literal_values[0])
+        try:
+            value = val_type(value)
+        except (ValueError, TypeError):
+            pass
+        if value not in literal_values:
+            raise ValueError(
+                f"invalid value {value!r} - must be one of {list(literal_values)}"
+            )
+        return value
+
+    # Fast path: if the value is already the right type, return it. Parameterized
+    # generics like list[int] are not valid second arguments to isinstance(), but
+    # isinstance(generic, type) is False for them on Python 3.11+, so the guard
+    # skips them safely.
+    if isinstance(target_type, type) and isinstance(value, target_type):
+        return value
+
+    # Try to cast to the target type
+    try:
+        # For bool, use str_to_bool converter to handle string inputs correctly
+        if target_type is bool:
+            converter = str_to_bool()
+            return converter(value)
+        # For other basic types (int, float, str), use the type directly
+        elif target_type in (int, float, str):
+            return target_type(value)
+        # For other types (including generics), return as-is and let Python handle it
+        return value
+    except (ValueError, TypeError):
+        # If casting fails, return the original value
+        return value
+
+
+def build_parser(group: Union[list, str] = "default"):
+    """Builds the argument parser from all the bound functions.
+
+    Returns
+    -------
+    ArgumentParser
+        Argument parser built by ArgBind.
+    """
+    p = argparse.ArgumentParser(formatter_class=argparse.RawTextHelpFormatter)
+
+    p.add_argument(
+        "--args.save",
+        type=str,
+        required=False,
+        help="Path to save all arguments used to run script to.",
+    )
+    p.add_argument(
+        "--args.load",
+        type=str,
+        required=False,
+        help="Path to load arguments from, stored as a .yml file.",
+    )
+    p.add_argument(
+        "--args.debug",
+        type=int,
+        required=False,
+        default=0,
+        help="Print arguments as they are passed to each function.",
+    )
+
+    if isinstance(group, str):
+        group = [group]
+    if "default" not in group:
+        group.append("default")
+    # Add kwargs from function to parser
+    for prefix in PARSE_FUNCS:
+        func, patterns, without_prefix, positional, fn_group = PARSE_FUNCS[prefix]
+        if not set(fn_group) & set(group):
+            continue
+
+        # Resolve string annotations produced by ``from __future__ import
+        # annotations`` (PEP 563). ``eval_str=True`` evaluates them in the
+        # function's own namespace; if a name can't be resolved at runtime (e.g. a
+        # ``TYPE_CHECKING``-only import), fall back to the raw, possibly stringized
+        # annotations and handle the leftover strings per-parameter below.
+        try:
+            sig = inspect.signature(func, eval_str=True)
+        except Exception:
+            sig = inspect.signature(func)
+
+        docstring = docstring_parser.parse(func.__doc__)
+        parameter_help = docstring.params
+        parameter_help = {x.arg_name: x.description for x in parameter_help}
+
+        f = p.add_argument_group(
+            title=f"Generated arguments for function {prefix}",
+        )
+
+        def _get_arg_names(key, is_kwarg):
+            arg_names = []
+
+            prepend = "--" if is_kwarg else ""
+            if without_prefix:
+                arg_name = prepend + f"PATTERN/{key}"
+            else:
+                arg_name = prepend + f"PATTERN/{prefix}.{key}"
+
+            arg_names.append(arg_name.replace("PATTERN/", ""))
+
+            if patterns is not None:
+                for p in patterns:
+                    arg_names.append(arg_name.replace("PATTERN", p))
+            return arg_names
+
+        for key, val in sig.parameters.items():
+            arg_val = val.default
+            arg_type = val.annotation
+            is_kwarg = arg_val is not inspect.Parameter.empty
+
+            if arg_type is inspect.Parameter.empty and is_kwarg:
+                arg_type = type(arg_val)
+            elif isinstance(arg_type, str) and is_kwarg and arg_val is not None:
+                # An unresolved PEP 563 annotation (the eval_str fallback above
+                # kept it as a string): infer the type from the default value.
+                arg_type = type(arg_val)
+
+            if is_kwarg or positional:
+                arg_names = _get_arg_names(key, is_kwarg)
+                arg_help = {}
+                help_text = ""
+                if key in parameter_help:
+                    # A documented parameter may have no description text (None).
+                    help_text = textwrap.fill(
+                        parameter_help[key] or "", width=HELP_WIDTH
+                    )
+                arg_help[arg_names[0]] = help_text
+                if len(arg_names) > 1:
+                    for pattern_arg_name in arg_names[1:]:
+                        arg_help[pattern_arg_name] = argparse.SUPPRESS
+
+                for arg_name in arg_names:
+                    inner_types = [str, int, float, bool]
+
+                    # Unwrap Optional[X] / X | None to X
+                    unwrapped_type = _unwrap_optional(arg_type)
+                    is_optional = unwrapped_type is not None
+                    effective_type = unwrapped_type if is_optional else arg_type
+                    # Origin of generic aliases: list for list[X]/List[X],
+                    # dict for dict[K, V]/Dict[K, V], etc. None for plain types.
+                    origin = get_origin(effective_type)
+
+                    if isinstance(effective_type, str):
+                        # An unresolved PEP 563 annotation with no informative
+                        # default to infer from: no CLI converter can be built, so
+                        # leave it YAML-configurable only rather than crashing
+                        # build_parser (matches the unsupported-union behavior).
+                        continue
+
+                    if effective_type is bool:
+                        # For bool with a default, support both flag and value syntax:
+                        # --Example.on      -> True (uses const)
+                        # --Example.on=1    -> True (uses type converter)
+                        # --Example.on=0    -> False (uses type converter)
+                        # (nothing)         -> default value
+                        if is_optional or arg_val is not inspect.Parameter.empty:
+                            f.add_argument(
+                                arg_name,
+                                type=str_to_bool(),
+                                nargs="?",
+                                const=True,
+                                default=arg_val,
+                                help=arg_help[arg_name],
+                            )
+                        else:
+                            # For bool without a default, use store_true action
+                            f.add_argument(
+                                arg_name, action="store_true", help=arg_help[arg_name]
+                            )
+                    elif effective_type is list or origin is list:
+                        # Covers list, List, list[X], and List[X]. Bare
+                        # list defaults to str elements.
+                        type_args = get_args(effective_type)
+                        _type = type_args[0] if type_args else str
+                        if _type in inner_types:
+                            f.add_argument(
+                                arg_name,
+                                type=str_to_list(_type),
+                                default=arg_val,
+                                help=arg_help[arg_name],
+                            )
+                        # Lists of other element types cannot be parsed from
+                        # the command line; they stay configurable via YAML.
+                    elif effective_type is dict or origin is dict:
+                        # Covers dict, Dict, dict[K, V], and Dict[K, V].
+                        # Value types are guessed with ast.literal_eval.
+                        f.add_argument(
+                            arg_name,
+                            type=str_to_dict(),
+                            default=arg_val,
+                            help=arg_help[arg_name],
+                        )
+                    elif _unwrap_literal(effective_type) is not None:
+                        literal_values = _unwrap_literal(effective_type)
+                        val_type = type(literal_values[0])
+                        f.add_argument(
+                            arg_name,
+                            type=val_type,
+                            choices=literal_values,
+                            default=arg_val,
+                            help=arg_help[arg_name],
+                        )
+                    elif origin is tuple:
+                        _type_list = get_args(effective_type)
+                        f.add_argument(
+                            arg_name,
+                            type=str_to_tuple(_type_list),
+                            default=arg_val,
+                            help=arg_help[arg_name],
+                        )
+                    elif origin in _UNION_ORIGINS:
+                        # Union of several real types, e.g.
+                        # str | os.PathLike | None. A command-line value is
+                        # already a str, so if str is a member, pass it
+                        # through unchanged. Unions without str cannot be
+                        # parsed from the command line and stay configurable
+                        # via YAML.
+                        if str in get_args(effective_type):
+                            f.add_argument(
+                                arg_name,
+                                type=str,
+                                default=arg_val,
+                                help=arg_help[arg_name],
+                            )
+                    elif origin is not None:
+                        # Other generics (Mapping[K, V], custom generics,
+                        # ...) cannot be parsed from the command line; they
+                        # stay configurable via YAML.
+                        pass
+                    elif callable(effective_type):
+                        # A plain, callable type (int, float, str, or a custom
+                        # converter): argparse calls it on the raw string value.
+                        f.add_argument(
+                            arg_name,
+                            type=effective_type,
+                            default=arg_val,
+                            help=arg_help[arg_name],
+                        )
+                    else:
+                        # Not a recognized generic and not callable: the
+                        # annotation is not a usable type (e.g. `x: None` or a
+                        # non-type value), so no argument can be built for it.
+                        raise RuntimeError(
+                            f"argbind cannot bind {prefix}.{key}: its annotation "
+                            f"{effective_type!r} is not a callable type or a "
+                            f"supported generic."
+                        )
+
+        desc = docstring.short_description
+        if desc is None:
+            desc = ""
+
+        if patterns:
+            # Use the last parameter as the example; fall back to a placeholder
+            # for a parameter-less function (sig.parameters is empty).
+            param_keys = list(sig.parameters)
+            example_key = param_keys[-1] if param_keys else "arg"
+            if not without_prefix:
+                scope_pattern = f"--{patterns[0]}/{prefix}.{example_key}"
+            else:
+                scope_pattern = f"--{patterns[0]}/{example_key}"
+
+            desc += (
+                f" Additional scope patterns: {', '.join(list(patterns))}. "
+                "Use these by prefacing any of the args below with one "
+                "of these patterns. For example: "
+                f"{scope_pattern} VALUE."
+            )
+
+        desc = textwrap.fill(desc, width=HELP_WIDTH)
+        f.description = desc
+
+    return p
+
+
+def parse_args(p=None, group: Union[list, str] = "default"):
+    """
+    Parses the command line and returns a dictionary.
+    Builds the argument parser if p is None.
+    """
+    p = build_parser(group=group) if p is None else p
+    used_args = [
+        x.replace("--", "").split("=")[0] for x in sys.argv if x.startswith("--")
+    ]
+    used_args.extend(["args.save", "args.load"])
+
+    known, unknown = p.parse_known_args()
+    args = vars(known)
+    args["args.unknown"] = unknown
+    load_args_path = args.pop("args.load")
+    save_args_path = args.pop("args.save")
+    debug_args = args.pop("args.debug")
+
+    pattern_keys = [key for key in args if "/" in key]
+    top_level_args = [key for key in args if "/" not in key]
+
+    # If the top-level arguments were altered but the scoped ones were not,
+    # change the scoped ones to match the top-level (inherit from top-level).
+    args |= {
+        key: args[key.split("/")[1]] for key in pattern_keys if key not in used_args
+    }
+
+    if load_args_path:
+        loaded_args = load_args(load_args_path)
+        # Overwrite defaults with loaded arguments, except those from the command line.
+        args |= {k: v for k, v in loaded_args.items() if k not in used_args}
+        for key in pattern_keys:
+            pattern, arg_name = key.split("/")
+            if key not in loaded_args and key not in used_args:
+                if arg_name in loaded_args:
+                    args[key] = args[arg_name]
+
+    for key in top_level_args:
+        if key in used_args:
+            for pattern_key in pattern_keys:
+                pattern, arg_name = pattern_key.split("/")
+                if key == arg_name and pattern_key not in used_args:
+                    args[pattern_key] = args[key]
+
+    if save_args_path:
+        dump_args(args, save_args_path)
+
+    # Put them back in case the script wants to use them
+    args["args.load"] = load_args_path
+    args["args.save"] = save_args_path
+    args["args.debug"] = debug_args
+
+    return args

argbind_dbraun-0.5.2.dist-info/METADATA

@@ -0,0 +1,341 @@
+Metadata-Version: 2.4
+Name: argbind-dbraun
+Version: 0.5.2
+Summary: Simple way to bind function arguments to the command line. An extended fork of pseeth/argbind with new features (imported as `argbind`).
+Author-email: Prem Seetharaman <prem@descript.com>
+Maintainer-email: David Braun <braun@ccrma.stanford.edu>
+License: MIT
+Project-URL: Homepage, https://github.com/DBraun/argbind/
+Project-URL: Repository, https://github.com/DBraun/argbind/
+Project-URL: Original project, https://github.com/pseeth/argbind/
+Keywords: command-line,configuration,yaml,argument,parsing
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Requires-Dist: pyyaml
+Requires-Dist: docstring-parser
+Provides-Extra: tests
+Requires-Dist: pytest; extra == "tests"
+Requires-Dist: pytest-cov; extra == "tests"
+Provides-Extra: lint
+Requires-Dist: ruff; extra == "lint"
+Dynamic: license-file
+
+# ArgBind
+
+**Build CLIs via docstrings and type annotations, with YAML support.**
+
+[![Tests](https://github.com/DBraun/argbind/actions/workflows/tests.yml/badge.svg)](https://github.com/DBraun/argbind/actions/workflows/tests.yml)
+[![PyPI version](https://badge.fury.io/py/argbind-dbraun.svg)](https://pypi.org/project/argbind-dbraun/)
+[![Python versions](https://img.shields.io/pypi/pyversions/argbind-dbraun)](https://pypi.org/project/argbind-dbraun/)
+[![Downloads](https://static.pepy.tech/badge/argbind-dbraun)](https://pepy.tech/project/argbind-dbraun)
+
+> **Note:** This is an extended fork of [pseeth/argbind](https://github.com/pseeth/argbind) that
+> adds new features — modern type annotations (PEP 585/604), `Literal` and flexible boolean
+> handling, dataclass `default_factory`, and YAML `$include` — published on PyPI as
+> [`argbind-dbraun`](https://pypi.org/project/argbind-dbraun/). The import name is unchanged
+> (`import argbind`), so it remains a drop-in replacement.
+
+*ArgBind is a simple way to bind function or class arguments to the command line or to .yml files!*
+It supports scoping of arguments, similar to other frameworks like
+[Hydra](https://github.com/facebookresearch/hydra) and
+[gin-config](https://github.com/google/gin-config).
+ArgBind is *very* small (only ~800 lines of code, in one file), can be used to make complex and well-documented command line programs, and allows
+you to configure program execution from .yml files.
+
+If you're migrating from an ArgParse script to an ArgBind script, check out the
+[migration guide](./examples/migration). Scroll down to see some [examples](#examples). Please also look at the
+current known [limitations](#limitations-and-known-issues) of ArgBind.
+
+## Why ArgBind?
+
+ArgBind was written by [Prem Seetharaman](https://github.com/pseeth) to help configure machine
+learning experiments. ML experiment configuration is often highly nested, and can get out of hand
+quickly. Rather than switching workflows around too much to accommodate a new framework, the goal
+was to make already-written scripts easily adaptable, to achieve a few things:
+
+1. Configure scripts using `.yml` files. Be able to save `.yml` files that can be used to rerun scripts the exact same way twice.
+2. Spend time writing actual functions needed to run experiments, not argument parsers.
+3. Be able to run experiment code from other Python scripts, notebooks, or the command line.
+4. Be able to specify arguments from the command line directly to various functions.
+5. Be able to use scoping patterns, so a function can run inside a `train` scope and `test` scope, with different results (e.g., for getting a train dataset and a test dataset).
+
+Nothing out there really fit the bill, so Prem wrote ArgBind. If you have
+an `argparse` based script, converting it to ArgBind should be very quick! ArgBind is simple,
+small, and easy to use. To get a feel for how it works, check out [usage](#usage), [design](#design), and [examples](#examples)!
+
+## Installation
+
+Install via `pip`:
+
+```
+python -m pip install argbind-dbraun
+```
+
+Or from source:
+
+```
+git clone https://github.com/DBraun/argbind.git
+cd argbind
+python -m pip install -e .
+```
+
+This project uses [uv](https://docs.astral.sh/uv/). To create a dev environment with the
+test dependencies and run the suite:
+
+```
+uv sync --extra tests
+uv run pytest
+```
+
+Install the [pre-commit](https://pre-commit.com/) hooks (ruff format + lint) so they run
+on every commit:
+
+```
+uvx pre-commit install
+```
+
+## Examples
+
+- [Example 1: Hello World](./examples/hello_world/)
+- [Example 2: Scope patterns](./examples/scoping/)
+- [Example 3: Typing](./examples/typing/)
+- [Example 4: Modern type annotations (PEP 585/604)](./examples/modern_typing)
+- [Example 5: Literal arguments](./examples/literal)
+- [Example 6: Flexible boolean syntax](./examples/booleans)
+- [Example 7: Using default_factory with dataclasses](./examples/default_factory)
+- [Example 8: Loading, saving, and using .yml files](./examples/yaml)
+- [Example 9: Nested .yml files with `$include`](./examples/nested_yaml)
+- [Example 10: Multi-stage programs](./examples/multistage)
+- [Example 11: Mimic more traditional CLI, without `func.arg` notation](./examples/without_prefix)
+- [Example 12: Debug mode](./examples/debug)
+- [Example 13: Migrating from ArgParse](./examples/migration)
+- [Example 14: Binding existing functions and classes](./examples/bind_existing)
+- [Example 15: Binding functions to specific groups](./examples/groups)
+
+## Usage
+
+There are six main functions.
+
+- `bind`: Binds keyword arguments (and positional arguments if `positional=True`) of a function or class to ArgBind.
+- `parse_args`: Actually parses command line arguments into a dictionary.
+- `scope`: Context manager that scopes a dictionary containing function arguments to be used by the functions.
+- `dump_args`: Dumps the args dictionary to a `.yml` file. Used internally when program is called with `--args.save path/to/save.yml`.
+- `load_args`: Loads args from a `.yml` file. Used internally when program is called with `--args.load path/to/load.yml`.
+- `get_used_args`: Gets arguments that have actually been used by call functions up to this point.
+
+Your code with ArgBind generally follows this pattern:
+
+1. Write a function with a good docstring, and typed arguments. If arguments are not typed, their type will be inferred from the type of the default.
+2. Bind it via `bind`.
+3. When program is called, parse the arguments via `parse_args`.
+4. Scope the arguments, and call the bound function within the context block.
+5. Optionally call program with `--args.save` to save the current execution configuration to a `.yml` file or `--args.load` to load arguments from a prior saved execution configuration to run it the same way twice.
+6. Optionally, run your script with `--args.debug=1` to see exactly how every bound function is called.
+
+In your program, you can call `get_used_args` to see which arguments were actually used. Here's a minimal example:
+
+```python
+import argbind
+
+@argbind.bind()
+def hello(
+    name : str = 'world'
+):
+    """Say hello to someone.
+
+    Parameters
+    ----------
+    name : str, optional
+        Who you're saying hello to, by default 'world'
+    """
+    print("Hello " + name)
+
+if __name__ == "__main__":
+    # Arguments for CLI automatically generated from bound functions under the pattern
+    # function_name.function_arg.
+    args = argbind.parse_args()
+    # When called within a scope, the keyword arguments map to those from CLI or
+    # from defaults.
+    with argbind.scope(args):
+        hello()
+    # get_used_args() returns the arguments that were actually used by the bound
+    # functions that ran -- here, {'hello.name': 'world'}.
+    print(argbind.get_used_args())
+```
+
+Help text is automatically generated from the docstring:
+
+```
+❯ python examples/hello_world/with_argbind.py -h
+usage: with_argbind.py [-h] [--args.save ARGS.SAVE] [--args.load ARGS.LOAD] [--args.debug ARGS.DEBUG] [--hello.name HELLO.NAME]
+
+optional arguments:
+  -h, --help            show this help message and exit
+  --args.save ARGS.SAVE
+                        Path to save all arguments used to run script to.
+  --args.load ARGS.LOAD
+                        Path to load arguments from, stored as a .yml file.
+  --args.debug ARGS.DEBUG
+                        Print arguments as they are passed to each function.
+
+Generated arguments for function hello:
+  Say hello to someone.
+
+  --hello.name HELLO.NAME
+                        Who you're saying hello to, by default 'world'
+```
+
+Execution of this could look like:
+
+```
+# Default arguments
+❯ python examples/hello_world/with_argbind.py
+Hello world
+# Binding name from the command line and saving the args.
+❯ python examples/hello_world/with_argbind.py --hello.name=you --args.save=/tmp/args.yml
+Hello you
+# Loading saved arguments.
+❯ python examples/hello_world/with_argbind.py --args.load=/tmp/args.yml
+Hello you
+# Loading saved arguments, and overriding via command line.
+❯ python examples/hello_world/with_argbind.py --args.load=/tmp/args.yml --hello.name=me
+Hello me
+# See how each function is called with args.debug=1.
+❯ python examples/hello_world/with_argbind.py --args.load=/tmp/args.yml --args.debug=1
+hello(
+  name : str = you
+)
+Hello you
+```
+
+You can also run the `hello` function from another Python script or a Jupyter notebook:
+
+```python
+import argbind
+# Import the bound function
+from .hello_world import hello
+# Load the args
+args = argbind.load_args('/tmp/args.yml')
+# Scope the args
+with argbind.scope(args):
+    # Run the bound function
+    hello() # Prints 'Hello you'.
+hello() # Prints 'Hello world', as it's outside scope.
+# Can edit the args before scoping again.
+args['hello.name'] = 'me'
+with argbind.scope(args):
+    hello() # Prints 'Hello me'.
+```
+
+You'll notice that ArgBind forces you to document and type your
+function arguments, which is always a good idea!
+Please check out the [examples](#examples) for more details!
+
+
+## Design
+
+ArgBind is designed around a decorator that can be used on
+functions the user wants to expose to command line or to a .yml file.
+The arguments to that function are
+then bound to a dictionary. When the function is called,
+each argument is looked up in the dictionary and its
+value is replaced with the corresponding value in the dictionary. The
+dictionary that the function looks for values in is controlled by
+`scope`:
+
+```python
+import argbind
+
+@argbind.bind()
+def func(arg : str = 'default'):
+    print(arg)
+
+dict1 = {
+    'func.arg': 1,
+}
+dict2 = {
+    'func.arg': 2
+}
+
+with argbind.scope(dict1):
+    func() # prints 1
+with argbind.scope(dict2):
+    func() # prints 2
+func(arg=3) # prints 3.
+```
+
+The function arguments are bound to the command line. Continuing the
+simple program from above:
+
+```python
+if __name__ == "__main__":
+    args = argbind.parse_args()
+    with argbind.scope(args):
+        func()
+    with argbind.scope(args):
+        func(arg=3)
+```
+
+You can call this function like so:
+
+```bash
+❯ python examples/readme_example.py --func.arg 5
+1 # Looks up `arg` in dict1
+2 # Looks up `arg` in dict2
+3 # arg is passed in on python call `func(arg=3)`
+5 # Looks up `arg` from command line call `--func.arg 5`
+3 # arg is passed in from two places: `func(arg=3)` and `--func.arg 5`. Former overrides the latter.
+```
+
+The logic here is that arguments that are bound that are closer to the actual function call get priority. From highest priority, to lowest, it goes:
+
+1. Bound explicitly in Python code
+2. Bound via command line
+3. Bound via .yml file
+4. Bound via default for kwarg
+
+You can also use `bind` directly on classes - see [here](./examples/bind_existing).
+
+# Limitations and known issues
+
+There are some limitations to ArgBind, some due to how Python function decorators work,
+and others out of a desire to keep ArgBind's code simple and straightforward.
+
+## Bound function names should be unique
+
+Functions that are bound must be unique, even if they are in different files. The
+function name is resolved in the argument parser only using the immediate name, not
+a path to the function etc.
+
+## Supported docstring formats
+
+ArgBind uses [docstring-parser](https://github.com/rr-/docstring_parser), and so
+the only supported styles are: ReST, Google, and Numpydoc-style docstrings.
+
+## Not all types are supported
+
+ArgBind supports most types that might pop up in your script, but not all. The
+supported types can be seen in the [typing](./examples/typing/) and
+[modern annotations](./examples/modern_typing/) examples.
+
+## Positional arguments should not be saved into .yml files
+
+If a positional argument is saved into a .yml file and loaded via `--args.load`,
+then any positional argument passed in the command line will be overridden. Take
+care not to pass positional arguments via `.yml` files.
+
+# Issues? Questions?
+
+If you've run into some issues with ArgBind, or have some questions, please ask
+via GitHub Issues. Projects like ArgBind are pretty tricky to get right, so there
+may be some edge cases that have been missed.

argbind_dbraun-0.5.2.dist-info/RECORD

@@ -0,0 +1,8 @@
+argbind/__init__.py,sha256=sBNHxroc2miAKC_di7g3C3wfHnmNRVwMIb_ozxI0WLo,298
+argbind/argbind.py,sha256=n5pqzuj-ruB3jP72sOxcVlUjE7WLv3Z1HhyWly9EFvE,29570
+argbind/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+argbind_dbraun-0.5.2.dist-info/licenses/LICENSE.md,sha256=hbhfuwy5BW5kON9X_wC23iw1qZxT96p2XKwtdh_LWz4,1129
+argbind_dbraun-0.5.2.dist-info/METADATA,sha256=FzDoei0r2qHEzR_rFnJbE0-XpPnQIhocCJ1TbMIIwqo,13383
+argbind_dbraun-0.5.2.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+argbind_dbraun-0.5.2.dist-info/top_level.txt,sha256=4I81NScLijEMVYA3LWvX4q2kAh618wG84JBLJLXYQwc,8
+argbind_dbraun-0.5.2.dist-info/RECORD,,

argbind_dbraun-0.5.2.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

argbind_dbraun-0.5.2.dist-info/licenses/LICENSE.md

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2020, Prem Seetharaman
+Copyright (c) 2024-2026, David Braun (fork maintainer)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

argbind_dbraun-0.5.2.dist-info/top_level.txt

@@ -0,0 +1 @@
+argbind