argmerge 0.0.0__py3-none-any.whl

argmerge/__init__.py

@@ -0,0 +1,6 @@
+from loguru import logger
+
+from .decorator import threshold
+
+__all__ = ["threshold"]
+logger.remove()

argmerge/base.py

@@ -0,0 +1,38 @@
+"""Module that holds the Abstract Base Class for all external parsers."""
+
+from abc import ABC, abstractmethod
+
+__all__ = ["SourceParser"]
+
+
+class SourceParser(ABC):
+    """The base parser from which all other parsers are built.
+
+    To build a new parser, you will need to subclass this one. Set 'rank' and 'label'
+    as class variables and overwrite `__call__` with your parser. You MUST include
+    three parameters: `threshold_kwargs`, `ledger`, and `debug`. This will allow you
+    to add your own with other keyword arguments. You can look at any of the existing
+    subclasses for how this works. After you build your subclass, you will instantiate
+    it, setting it equal to a variable, ideally beginning with `'parse_'`. This will
+    allow you to treat it like a function by invoking the `__call__` method, which calls
+    your parser.
+
+    Args:
+        rank (int): The priority of the parser. Generally, we aim between [0,100] for
+            human-readabilty.
+        label (str): The debugging label to indicate an argument was set at the
+            <source level>.
+    """
+
+    rank: int = -100
+    label: str = ""
+
+    def __init__(cls):
+        cls.label
+        cls.rank
+
+    @abstractmethod
+    def __call__(
+        cls, threshold_kwargs: dict, ledger: dict, debug: bool = False, **kwargs
+    ) -> tuple[dict, dict]:
+        """This is too abstract to be covered"""

argmerge/cli.py

@@ -0,0 +1,93 @@
+"""Module that provides a flexible CLI parser component in the decorator.
+
+
+```py
+CLI_PATTERN: re.Pattern = re.compile(r"--([A-Za-z_-]+)=([0-9A-Za-z_-\.]+)")
+```
+
+- matches `'--arg=value'`
+- does not match `'--arg value'`
+"""
+
+import re
+import sys
+from typing import Any
+
+from loguru import logger as LOGGER
+
+from argmerge.base import SourceParser
+
+__all__ = ["CLI_PATTERN", "parse_cli"]
+
+# matches '--arg=value'
+# does not match '--arg value'
+CLI_PATTERN: re.Pattern = re.compile(r"--([A-Za-z_-]+)=([0-9A-Za-z_-\.]+)")
+
+
+class CLIParser(SourceParser):
+    """The parser the extracts relevant CLI arguments.
+
+    params:
+        label (str): The debugging label to indicate an argument was set at the CLI.
+        rank (int): The priority of the parser. Generally, we aim between [0,100] for
+            human-readabilty.
+
+    """
+
+    label: str = "CLI"
+    rank: int = 40
+
+    def __call__(
+        cls,
+        threshold_kwargs: dict[str, Any],
+        change_ledger: dict[str, dict[str, str | int]],
+        cli_pattern: re.Pattern[str] = CLI_PATTERN,
+        debug: bool = False,
+        **kwargs,
+    ) -> tuple[dict, dict]:
+        """Parse the CLI commands using the cli_pattern regular expression.
+
+        Args:
+            threshold_kwargs (dict[str, Any]): kwargs passed around the
+                @threshold decorator.
+            change_ledger (dict[str, dict[str, str  |  int]]): Tracks when kwargs are
+                updated inside the @threshold decorator.
+            cli_pattern (re.Pattern[str], optional): The regular expression pattern
+                used to extract arguments from the CLI. Defaults to CLI_PATTERN.
+            debug (bool, optional): Flag to turn on more logging. Defaults to False.
+
+        Returns:
+            tuple[dict, dict]: an updated `threshold_kwargs` and `change_ledger`.
+        """
+        _cli_kwargs: dict
+        _cli_input: str
+
+        if debug:
+            LOGGER.remove()
+            LOGGER.add(sys.stderr, level="DEBUG")
+
+        if isinstance(cli_pattern, re.Pattern):
+            _cli_pattern = cli_pattern
+
+        else:
+            _cli_pattern = re.compile(rf"{cli_pattern}")
+
+        LOGGER.debug(f"{cli_pattern=}")
+        LOGGER.debug(f"{_cli_pattern=}")
+        LOGGER.debug(f"{sys.argv=}")
+        _cli_input = " ".join(sys.argv[1:])
+        LOGGER.debug(f"{_cli_input}")
+
+        _cli_kwargs = dict(_cli_pattern.findall(_cli_input))
+        LOGGER.debug(f"{_cli_kwargs=}")
+
+        threshold_kwargs.update(_cli_kwargs)
+        LOGGER.debug(f"Updated {threshold_kwargs=}")
+
+        for key in _cli_kwargs:
+            change_ledger[key] = {"label": cls.label, "rank": cls.rank}
+
+        return threshold_kwargs, change_ledger
+
+
+parse_cli = CLIParser()

argmerge/decorator.py

@@ -0,0 +1,134 @@
+"""Module that contains the main decorator, `@threshold`.
+
+Usage:
+    ```py
+    # main.py
+    from argmerge import threshold
+
+    @threshold
+    def main(first: int, second: str, third: float = 3.0):
+        ...
+
+    if __name__ == '__main__':
+        main()
+    ```
+    Many more examples of how to use this can be found in [the Examples section](/examples/)
+"""
+
+import functools
+import re
+from pathlib import Path
+
+from argmerge.cli import CLI_PATTERN, parse_cli
+from argmerge.env import ENV_PREFIX, parse_env
+from argmerge.func import parse_func, parse_func_runtime
+from argmerge.json import parse_json
+from argmerge.trace import LOG_LEVELS, trace_arg_lineage
+from argmerge.yaml import parse_yaml
+
+
+def threshold(
+    *args,
+    fpath_json: str | Path = "",
+    fpath_yaml: str | Path = "",
+    env_prefix: str | re.Pattern[str] = ENV_PREFIX,  # 'THRESH', also set at PYTHRESH
+    cli_pattern: str | re.Pattern[str] = CLI_PATTERN,
+    trace_level: str = "",
+    debug: bool = False,
+    **kwargs,
+):
+    """Merge arguments from external environment sources into the program.
+
+    We allow syntax of both @threshold and @threshold(), depending whether you want to
+    allow for defaults or override them.
+
+    Args:
+        fpath_json (str | Path, optional): The path to find a JSON configuration file.
+            Defaults to "".
+        fpath_yaml (str | Path, optional): The path to find a YAML configuration file.
+            Defaults to "".
+        env_prefix (str | re.Pattern[str], optional): The string or Regex to match
+            environment variables against. Defaults to ENV_PREFIX, which is 'THRESH'.
+        cli_pattern (str | re.Pattern[str], optional): The string or Regex to match
+            CLI arguments against. Defaults to CLI_PATTERN.
+        trace_level (str, optional): Trace the source of each kwarg and display at the
+            specified trace log level. Defaults to "", which skips the trace entirely.
+        debug (bool, optional): Turns on debugging for all the parsers.
+            Defaults to False.
+
+    Raises:
+        ValueError: `level` must be in one of the default loguru logger levels:
+            `("critical", "warning", "success", "info", "debug")`
+
+    Returns:
+        callable: A wrapped, yet-to-be-called function with resolved arguments.
+    """
+    if len(args) == 1:
+        # allow syntax of @threshold and @threshold()
+        return threshold()(args[0])
+
+    else:
+
+        def wrapped(f):
+            @functools.wraps(f)
+            def wrapped_f(*_args, **_kwargs):
+                _threshold_kwargs, _change_ledger = dict(), dict()
+                _threshold_kwargs, _change_ledger = parse_func(
+                    _threshold_kwargs, _change_ledger, f, debug=debug
+                )
+
+                _threshold_kwargs, _change_ledger = parse_json(
+                    _threshold_kwargs,
+                    _change_ledger,
+                    fpath_json=fpath_json,
+                    debug=debug,
+                )
+
+                _threshold_kwargs, _change_ledger = parse_yaml(
+                    _threshold_kwargs,
+                    _change_ledger,
+                    fpath_yaml=fpath_yaml,
+                    debug=debug,
+                )
+
+                _threshold_kwargs, _change_ledger = parse_env(
+                    _threshold_kwargs,
+                    _change_ledger,
+                    env_prefix=env_prefix,
+                    debug=debug,
+                )
+
+                _threshold_kwargs, _change_ledger = parse_cli(
+                    _threshold_kwargs,
+                    _change_ledger,
+                    cli_pattern=cli_pattern,
+                    debug=debug,
+                )
+
+                _threshold_kwargs, _change_ledger = parse_func_runtime(
+                    _threshold_kwargs, _change_ledger, func_kwargs=_kwargs, debug=debug
+                )
+
+                if trace_level.lower() in LOG_LEVELS:
+                    trace_arg_lineage(
+                        f,
+                        _change_ledger,
+                        level=trace_level,
+                    )
+
+                elif trace_level == "":
+                    # default behavior
+                    pass
+
+                else:
+                    raise ValueError(
+                        f"'trace_level' has been set to '{trace_level}', which is not "
+                        "supported. Please set 'trace_level' to an empty string or one"
+                        f" of: {LOG_LEVELS}."
+                    )
+
+                return f(*_args, **_threshold_kwargs)
+
+            return wrapped_f
+
+        return wrapped

argmerge/env.py

@@ -0,0 +1,103 @@
+# cython: linetrace=True
+# distutils: define_macros=CYTHON_TRACE=1
+import os
+import re
+import sys
+from typing import Any
+
+from loguru import logger as LOGGER
+
+from argmerge.base import SourceParser
+from argmerge.utils import extract_literals
+
+__all__ = ["ENV_PREFIX", "parse_env"]
+
+ENV_PREFIX = os.environ.get("PYTHRESH", "THRESH")
+
+
+class EnvParser(SourceParser):
+    """The parser the extracts relevant environment variables.
+
+    Args:
+        label (str): The debugging label to indicate an argument was set by environment
+            variables.
+        rank (int): The priority of the parser. Generally, we aim between [0,100] for
+            human-readabilty.
+    """
+
+    rank: int = 30
+    label: str = "Environment Variable"
+
+    def __call__(
+        cls,
+        threshold_kwargs: dict[str, Any],
+        change_ledger: dict[str, dict[str, str | int]],
+        env_prefix: str | re.Pattern[str] = ENV_PREFIX,
+        debug=False,
+        **kwargs,
+    ):
+        """Parse the environment variables using the `env_prefix` and update inputs.
+
+        Args:
+            threshold_kwargs (dict[str, Any]): kwargs passed around the
+                @threshold decorator.
+            change_ledger (dict[str, dict[str, str  |  int]]): Tracks when kwargs are
+                updated inside the @threshold decorator.
+            env_prefix (str | re.Pattern[str], optional): The prefix used to search for
+                set environment variables. Defaults to ENV_PREFIX, which is 'THRESH_'.
+            debug (bool, optional): Flag to turn on more logging. Defaults to False.
+
+        Raises:
+            ValueError: `env_prefix` must either be a string or Regex string pattern.
+
+        Returns:
+            tuple[dict, dict]: an updated `threshold_kwargs` and `change_ledger`.
+        """
+        if debug:
+            LOGGER.remove()
+            LOGGER.add(sys.stderr, level="DEBUG")
+
+        if isinstance(env_prefix, re.Pattern):
+            pattern = env_prefix
+
+        elif isinstance(env_prefix, str):
+            pattern = re.compile(rf"(?:{env_prefix.upper()}.)([A-Za-z0\-\_]+)")
+
+        else:
+            raise ValueError(
+                f"'env_prefix' must be either a string or Regex string pattern. Received: {env_prefix} ({type(env_prefix)})."
+            )
+
+        LOGGER.debug(f"{env_prefix=}")
+        LOGGER.debug(f"{pattern=}")
+
+        _env_kwargs = {}
+
+        for k, v in os.environ.items():
+            _search = pattern.search(k)
+
+            if _search is not None:
+                try:
+                    key = _search.group(1).lower()
+                    LOGGER.debug(f"{key=} {v=}")
+                    _env_kwargs[key] = extract_literals(v)
+
+                except IndexError:
+                    LOGGER.debug(f"Regex search failed on environment variable {k}.")
+
+            else:
+                LOGGER.debug(f"Miss: {k=}")
+
+        LOGGER.debug(f"{_env_kwargs=}")
+        threshold_kwargs.update(_env_kwargs)
+
+        LOGGER.debug(f"Updated {threshold_kwargs=}")
+
+        for key in _env_kwargs:
+            change_ledger[key] = {"label": cls.label, "rank": cls.rank}
+
+        return threshold_kwargs, change_ledger
+
+
+# Make EnvParser appear as a function when it uses __call__.
+parse_env = EnvParser()

argmerge/func.py

@@ -0,0 +1,126 @@
+"""Module to work with retrieving arguments functions"""
+
+import sys
+from inspect import Parameter, signature
+from typing import Any, Callable
+
+from loguru import logger as LOGGER
+
+from argmerge.base import SourceParser
+
+__all__ = ["parse_func", "parse_func_runtime"]
+
+
+class FuncDefaultParser(SourceParser):
+    """Builds the parser to extract default arguments from a function signature
+
+    This is the lowest-ranked parser.
+
+    params:
+        label (str): The debugging label to indicate an argument was set at the CLI.
+        rank (int): The priority of the parser. Generally, we aim between [0,100] for
+            human-readabilty.
+
+    """
+
+    label: str = "Python Function Default"
+    rank: int = 0
+
+    def __call__(
+        cls,
+        threshold_kwargs: dict,
+        change_ledger: dict,
+        f: Callable,
+        debug: bool = False,
+    ) -> tuple[dict, dict]:
+        """Lowest level parser - retrieve function defaults as fallback arguments.
+
+        Args:
+            threshold_kwargs (dict[str, Any]): kwargs passed around the
+                @threshold decorator.
+            change_ledger (dict[str, dict[str, str  |  int]]): Tracks when kwargs are
+                updated inside the @threshold decorator.
+            f (Callable): The function we wrap.
+            debug (bool, optional): Flag to turn on more logging. Defaults to False.
+
+
+        Returns:
+            tuple[dict, dict]: an updated `threshold_kwargs` and `change_ledger`.
+        """
+
+        if debug:
+            LOGGER.remove()
+            LOGGER.add(sys.stderr, level="DEBUG")
+
+        _sig = signature(f)
+        LOGGER.debug(f"Function {signature=}")
+        _default: dict = {}
+
+        for k, v in _sig.parameters.items():
+            if v.default is not Parameter.empty:
+                _default[k] = v.default
+
+        LOGGER.debug(f"{_default=}")
+        for k in _default:
+            change_ledger[k] = {"label": cls.label, "rank": cls.rank}
+
+        threshold_kwargs.update(**_default)
+
+        return threshold_kwargs, change_ledger
+
+
+parse_func = FuncDefaultParser()
+
+
+class FuncUpdater(SourceParser):
+    """Builds the parser to extract default arguments from a function signature
+
+    This is the highest-ranked parser.
+
+    params:
+        label (str): The debugging label to indicate an argument was set at Runtime by
+            the developer.
+        rank (int): The priority of the parser. Generally, we aim between [0,100] for
+            human-readabilty.
+    """
+
+    label: str = "Developer-provided"
+    rank: int = 100
+
+    def __call__(
+        cls,
+        threshold_kwargs: dict[str, Any],
+        change_ledger: dict[str, dict[str, str | int]],
+        func_kwargs: dict[str, Any],
+        debug: bool = False,
+    ) -> tuple[dict, dict]:
+        """Update the external values with the function's runtime arguments.
+
+        Args:
+            threshold_kwargs (dict[str, Any]): kwargs passed around the
+                @threshold decorator.
+            change_ledger (dict[str, dict[str, str  |  int]]): Tracks when kwargs are
+                updated inside the @threshold decorator.
+            func_kwargs (dict[str, Any]): The Runtime kwargs of the function.
+            debug (bool, optional): Flag to turn on more logging. Defaults to False.
+
+        Returns:
+            Returns:
+            tuple[dict, dict]: an updated `threshold_kwargs` and `change_ledger`.
+        """
+        if debug:
+            LOGGER.remove()
+            LOGGER.add(sys.stderr, level="DEBUG")
+
+        LOGGER.debug(f"{threshold_kwargs=}")
+        LOGGER.debug(f"{func_kwargs=}")
+
+        threshold_kwargs.update(**func_kwargs)
+
+        for key in func_kwargs:
+            change_ledger[key] = {"label": cls.label, "rank": cls.rank}
+
+        return threshold_kwargs, change_ledger
+
+
+parse_func_runtime = FuncUpdater()

argmerge/json.py

@@ -0,0 +1,85 @@
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+from loguru import logger as LOGGER
+
+from argmerge.base import SourceParser
+
+__all__ = ["parse_json"]
+
+
+class JSONParser(SourceParser):
+    """The parser the extracts relevant arguments from a JSON file.
+
+    params:
+        label (str): The debugging label to indicate an argument was set in a JSON
+            config file.
+        rank (int): The priority of the parser. Generally, we aim between [0,100] for
+            human-readabilty.
+
+    """
+
+    label: str = "JSON"
+    rank: int = 10
+
+    def __call__(
+        cls,
+        threshold_kwargs: dict[str, Any],
+        change_ledger: dict[str, dict[str, str | int]],
+        fpath_json: str | Path,
+        debug: bool = False,
+    ) -> tuple[dict, dict]:
+        """Parse a JSON configuration file for arguments
+
+         Args:
+            threshold_kwargs (dict[str, Any]): kwargs passed around the
+                @threshold decorator.
+            change_ledger (dict[str, dict[str, str  |  int]]): Tracks when kwargs are
+                updated inside the @threshold decorator.
+            fpath_json (str | Path): The filepath to the JSON configuration file.
+            debug (bool, optional): Flag to turn on more logging. Defaults to False.
+
+        Raises:
+            ValueError: If filepath extension is not `json`.
+
+        Returns:
+            tuple[dict, dict]: an updated `threshold_kwargs` and `change_ledger`.
+        """
+        _json_kwargs: dict
+
+        if debug:
+            LOGGER.remove()
+            LOGGER.add(sys.stderr, level="DEBUG")
+
+        LOGGER.debug(f"{threshold_kwargs=}")
+        LOGGER.debug(f"{fpath_json=}")
+
+        _fpath_json = Path(fpath_json)
+        if _fpath_json == Path(""):
+            LOGGER.debug("fpath_json not provided, skipping.")
+
+        else:
+            if _fpath_json.suffix != ".json":
+                raise ValueError(
+                    f"The JSON suffix of '{_fpath_json.as_posix()}' is not correct."
+                    " Please use '.json'."
+                )
+
+            cls.label = f"JSON ({_fpath_json})"
+
+            with open(fpath_json, "rb") as fy:
+                _json_kwargs = json.load(fy)
+
+            LOGGER.debug(f"{_json_kwargs=}")
+            threshold_kwargs.update(_json_kwargs)
+            LOGGER.debug(f"Updated {threshold_kwargs=}")
+
+            for key in _json_kwargs:
+                change_ledger[key] = {"label": cls.label, "rank": cls.rank}
+
+        return threshold_kwargs, change_ledger
+
+
+parse_json = JSONParser()

argmerge/trace.py

@@ -0,0 +1,138 @@
+"""Module to write the source of each function keyword argument for the developer
+
+Example:
+
+    $ uv run main.py  # trace_level=DEBUG set in the program
+    2025-10-14 16:15:33.466 | DEBUG    | argmerge.trace:_write_trace:50 -
+    Parameter Name  | Source
+    =======================================
+    third   | Python Function default
+    fourth  | Python Function default
+    fifth   | Python Function default
+    first   | developer-provided
+    second  | developer-provided
+    =======================================
+"""
+
+import sys
+from inspect import signature
+from typing import Callable
+
+from loguru import logger as LOGGER
+
+LOG_LEVELS = ("critical", "warning", "success", "info", "debug")
+
+
+def _write_trace(message: str, level: str):
+    """Write the trace message out to the specified log level.
+
+    args:
+        message (str): The debugging message for the developer.
+        level (str): The `loguru` log level to set.
+
+    raises:
+        TypeError: `level` must be a string.
+        ValueError: `level` must be in one of the default loguru logger levels:
+            `("critical", "warning", "success", "info", "debug")`
+    """
+    if isinstance(level, str):
+        _level = level.lower()
+
+    else:
+        raise TypeError(f"Log level '{level}' ({type(level)}) is not a string.")
+
+    if _level not in LOG_LEVELS:
+        raise ValueError(
+            f"Log level '{_level}' not in basic loguru log levels: '{LOG_LEVELS}''."
+        )
+
+    _trace_logger: int = LOGGER.add(sys.stderr, level=level.upper())
+
+    getattr(LOGGER, _level.lower())(message)
+
+    LOGGER.remove(_trace_logger)
+
+
+def _log_trace(ledger: dict[str, dict[str, str | int]], level: str = ""):
+    """Compose a developer-friendly report of each kwarg's source form the ledger.
+
+    First, sort the keys by their ranks. Ranks are sorted in ascending order such that
+    the highest ranked sources (Developer-Provided, etc) will be seen first. Then sort
+    the labels by that same order. Next, we will dynamically produce the report. We
+    will find the kwarg and source each with the longest length. Then, left-justify
+    (ljust) each kwarg and source to fill the space. Repeat for each kwarg-source pair.
+    We then set the heading such that the '=' characters "hang" over the report,
+    visually grouping them.
+
+    Args:
+        ledger (dict[str, dict[str, str  |  int]]): The change ledger that describes
+            each kwarg's highest-ranked source.
+        level (str, optional): A `loguru` logging level. Defaults to "", which means
+            'DEBUG' will be set.
+    """
+
+    if len(ledger) == 0:
+        LOGGER.warning("Change ledger is empty, will not write out!")
+
+    else:
+        # split the ranks from the labels
+        ranks: dict[str, int] = {k: int(v["rank"]) for k, v in ledger.items()}
+        labels: dict[str, str] = {k: str(v["label"]) for k, v in ledger.items()}
+
+        # First, sort the keys by their ranks.
+        sorted_keys = [x for x, _ in sorted(ranks.items(), key=lambda x: x[1])]
+        sorted_labels = {k: labels[k] for k in sorted_keys}
+
+        # calculate the longest kwarg name and source name
+        _key_spacing: int = max(list(map(len, sorted_labels.keys())))
+        _value_spacing: int = max(list(map(len, sorted_labels.values())))
+
+        # left-justify
+        _pre_join_spacing = {
+            k.ljust(_key_spacing, " "): v.ljust(_value_spacing, " ")
+            for k, v in sorted_labels.items()
+        }
+
+        # stringified, left-justified kwargs and sources
+        _params = [f"{k}\t| {v}" for k, v in _pre_join_spacing.items()]
+
+        # set up the heading
+        # heading will extend over the params
+        _heading_spacing: int = max(map(len, _params)) + 7
+
+        _heading_param = "Parameter Name".ljust(_key_spacing)
+        _heading_loc = "Source".ljust(_value_spacing)
+
+        # construct the full heading
+        _heading = f"{_heading_param}\t| {_heading_loc}"
+
+        _body = "\n".join(_params)
+
+        # combine the heading with the body
+        msg = (
+            f"\n{_heading}\n{'=' * _heading_spacing}\n{_body}\n{'=' * _heading_spacing}"
+        )
+
+        # log it to the appropriate level
+        _write_trace(message=msg, level=level)
+
+
+def trace_arg_lineage(
+    f: Callable,
+    change_ledger: dict[str, dict[str, str | int]],
+    level: str = "",
+):
+    """Determine where each argument in the function came from.
+
+    Only include arguments that exist in the function header. If a function accepts
+    **kwargs and an irrelevant keyword is provided - discard it.
+
+    args:
+        f (callable):
+        change_ledger (dict): The final dictionary detailing where every argument
+            is set - defaults, files, environment variables, CLI arguments, etc.
+    """
+    sig = signature(f)
+    _changed = {k: v for k, v in change_ledger.items() if k in sig.parameters}
+
+    _log_trace(ledger=_changed, level=level)

argmerge/utils.py

@@ -0,0 +1,13 @@
+"""Module for utility functions."""
+
+import ast
+
+from loguru import logger as LOGGER
+
+
+def extract_literals(s: str):
+    try:
+        return ast.literal_eval(s)
+    except Exception as e:
+        LOGGER.debug(e)
+        return s

argmerge/yaml.py

@@ -0,0 +1,87 @@
+# cython: linetrace=True
+# distutils: define_macros=CYTHON_TRACE=1
+
+import sys
+from pathlib import Path
+
+import yaml
+from loguru import logger as LOGGER
+
+from argmerge.base import SourceParser
+
+__all__ = ["parse_yaml"]
+
+
+class YAMLParser(SourceParser):
+    """The parser the extracts relevant arguments from a YAML file.
+
+    params:
+        label (str): The debugging label to indicate an argument was set in a YAML
+            config file.
+        rank (int): The priority of the parser. Generally, we aim between [0,100] for
+            human-readabilty.
+
+    """
+
+    label: str = "YAML"
+    rank: int = 20
+
+    def __call__(
+        cls,
+        threshold_kwargs: dict[str, str],
+        change_ledger: dict[str, dict[str, str | int]],
+        fpath_yaml: str | Path,
+        debug: bool = False,
+    ) -> tuple[dict, dict]:
+        """Parse a YAML configuration file for arguments
+
+         Args:
+            threshold_kwargs (dict[str, Any]): kwargs passed around the
+                @threshold decorator.
+            change_ledger (dict[str, dict[str, str  |  int]]): Tracks when kwargs are
+                updated inside the @threshold decorator.
+            fpath_yaml (str | Path): The filepath to the YAML configuration file.
+            debug (bool, optional): Flag to turn on more logging. Defaults to False.
+
+        Raises:
+            ValueError: If filepath extension is not `yml` or `yaml`.
+
+        Returns:
+            tuple[dict, dict]: an updated `threshold_kwargs` and `change_ledger`.
+        """
+        _yaml_kwargs: dict
+
+        if debug:
+            LOGGER.remove()
+            LOGGER.add(sys.stderr, level="DEBUG")
+
+        LOGGER.debug(f"{threshold_kwargs=}")
+        LOGGER.debug(f"{fpath_yaml=}")
+
+        _fpath_yaml = Path(fpath_yaml)
+        if _fpath_yaml == Path(""):
+            LOGGER.debug("fpath_yaml not provided, skipping.")
+
+        else:
+            if _fpath_yaml.suffix not in (".yml", ".yaml"):
+                raise ValueError(
+                    f"The YAML suffix of '{_fpath_yaml.suffix}' is not correct."
+                    " Please use '.yml' or '.yaml'."
+                )
+
+            cls.label = f"YAML ({_fpath_yaml})"
+
+            with open(fpath_yaml, "rb") as fy:
+                _yaml_kwargs = yaml.safe_load(fy)
+
+            LOGGER.debug(f"{_yaml_kwargs=}")
+            threshold_kwargs.update(_yaml_kwargs)
+            LOGGER.debug(f"Updated {threshold_kwargs=}")
+
+            for key in _yaml_kwargs:
+                change_ledger[key] = {"label": cls.label, "rank": cls.rank}
+
+        return threshold_kwargs, change_ledger
+
+
+parse_yaml = YAMLParser()

argmerge-0.0.0.dist-info/METADATA

@@ -0,0 +1,101 @@
+Metadata-Version: 2.4
+Name: argmerge
+Version: 0.0.0
+Summary: Add your description here
+Author-email: duck-bongos <billmannd@gmail.com>
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: loguru>=0.7.3
+Requires-Dist: mkdocs-material>=9.6.21
+Requires-Dist: pydantic>=2.12.2
+Requires-Dist: pyyaml>=6.0.3
+Provides-Extra: documentation
+Requires-Dist: mkdocs-autoapi>=0.4.1; extra == 'documentation'
+Requires-Dist: mkdocs-landing>=0.0.8; extra == 'documentation'
+Requires-Dist: mkdocs-terminal>=4.7.0; extra == 'documentation'
+Requires-Dist: mkdocs>=1.6.1; extra == 'documentation'
+Requires-Dist: mkdocstrings[python]>=0.30.1; extra == 'documentation'
+Description-Content-Type: text/markdown
+
+# `argmerge`
+## Description
+_Customize how program defaults and overrides from config files, environment variables, and CLI arguments "cross the threshold" into your program._
+
+| | |
+|---|---|
+CI/CD |
+Package | [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/argmerge.svg?logo=python&label=Python&logoColor=gold)](https://pypi.org/project/hatch-vcs/) |
+Meta|[![types - Mypy](https://img.shields.io/badge/types-Mypy-blue.svg)]
+
+
+![](https://raw.githubusercontent.com/duck-bongos/py-argmerge/ee26d70afb01489a43741ff9f88347b3ada3c25a/docs/img/argmerge.svg)
+![](/img/argmerge.svg)
+
+We retrieve each possible source of program arguments as Python dictionaries and then perform dictionary updates between each source before passing the final dictionary to the wrapped function. Effectively:
+```py
+source_1: dict
+source_2: dict
+
+source_1.update(source_2)
+
+function(**source_1)
+```
+
+## Installation
+We recommend using [`uv` for package management](http://docs.astral.sh/uv/).
+```sh
+uv add argmerge
+```
+
+If you're using pip you can run
+```sh
+pip install argmerge
+```
+
+## Usage
+### Code Example
+While designed for `main` functions, you can ddd the `@threshold` decorator to any program that interfaces with external variables or files.
+```py
+from argmerge import threshold
+
+
+@threshold
+def main(first: int, second: str, third: float = 0.0):
+    ...
+```
+
+## Hierarchy
+We determined the hierarchy based on (our perception of) developer experience. The intent is for higher priority sources to correspond to the quickest sources to change. For example, we perceive changing a CLI argument quicker than changing an environment variable - etc. 
+
+
+| Level | Rank |
+| --- | --- |
+| Developer-provided | 100 |
+| CLI | 40 |
+| Environment Variable | 30 |
+| YAML File | 20 |
+| JSON File | 10 |
+| Python Function Default | 0 |
+
+## FAQ
+#### Why YAML over JSON?
+We prioritized YAML above JSON is because we find it significantly easier to read because it has less "line noise". JSON contains copious amounts of brackets (`{`,`}`) and commas. These are the only two sources that can pass dictionaries in by default. Of course, passing in different Regular expressions for environment variables and CLI arguments could also capture dictionaries, if you want to figure that out.
+
+## Planned Future Work
+For specific bite-sized work, you can take a look at [our project's GitHub issues](https://github.com/duck-bongos/py-argmerge/issues). ⚠️ Caution - this project is new and issues may be under-specified ⚠️
+
+#### Validation
+We want users to be able to validate the input arguments to their program using a `PyDantic BaseModel`. This would slot in after we collect the arguments from all the different sources.
+
+### Customizing `@threshold`
+We provide ways to customize reading environment variables and CLI arguments with the `env_prefix` and `cli_pattern` parameters. If developers want to go a step further and pull values from external sources we haven't considered (like `.cfg` files), we would like to allow them to do so.
+
+#### Databricks
+Databricks offers a way to collect 'widgets' or 'secrets' in their notebooks at runtime and pass them into your program. [This is cool](https://docs.databricks.com/aws/en/notebooks/widgets). It also is higher-risk for not being able to exactly reproduce your workloads. This makes `@threshold` a very good candidate to merge arguments between the Databricks platform and other external sources. For example, though not recommended, it's possible to create widgets in a notebook that gets run in an asset bundle. Asset bundles can be run like CLI applications, which means you can pass arguments in from the CLI or the widgets.
+
+#### Authentication
+This is a tricky one, and we may not do it. Since we truly want to provide _everything_ a program needs to run, this would include any authentication keys - think Database access keys or application API keys. The way we'd retrieve keys varies between cloud platforms, as well as non-cloud platforms. What may make the most sense is for us to build some sort of plugin system that allows users to bring their own authentication 
+
+
+
+

argmerge-0.0.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+argmerge/__init__.py,sha256=Qwzs4V0UrF0t5xKzlkyETZ-2wFK5q4NRd9QzCzseDa4,101
+argmerge/base.py,sha256=sH40cnHH1hL2A3hTkT8KclQe5UsqNSEkXwR4ZF3avXo,1389
+argmerge/cli.py,sha256=L75YUHjQjYgRjGH9Px3T4L_d2prUemfWWZjAAk7kVfw,2725
+argmerge/decorator.py,sha256=ygETPoncQ8To-9-KJSl-T6thczRLBnrJ8k8ANnjhLA4,4606
+argmerge/env.py,sha256=4pujGpQQpaeXKFoEAs0gAYsp7xt0Dzwafxn16-ZJBVc,3244
+argmerge/func.py,sha256=wEdtnGy032qD8Bs5mPcB2JHp9icqgTFNYkJ0YZF6L44,3830
+argmerge/json.py,sha256=-MQHFvMqou1gTk3IQzjXEhzMbDeM1dV00Xixn3qdlyA,2542
+argmerge/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+argmerge/trace.py,sha256=TEL15zq4kB167g5_kol8gn_bcbu_g6Xfoi56F_QZcAY,4905
+argmerge/utils.py,sha256=vm831wU84oLYMECd9fNNgAoG_h4NRc4V09xLCuCSOt4,229
+argmerge/yaml.py,sha256=F67BBo3qdF8i_KSAbhHWu1-rAinvqE4OM4rHsVt5bvw,2621
+argmerge-0.0.0.dist-info/METADATA,sha256=3bhWAgxnw-9n3dKVl_BzoC6E0BnDarIlaZOqaym2LcY,4820
+argmerge-0.0.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+argmerge-0.0.0.dist-info/licenses/LICENSE,sha256=VCHxOgrvZCaQVMK2Si3ZzeN_EqtZGohk7zFmT6MSNeg,1069
+argmerge-0.0.0.dist-info/RECORD,,

argmerge-0.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

argmerge-0.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Dan Billmann
+
+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.