pluggable-namespace 2.0.0__py3-none-any.whl

_config/config.yaml

@@ -0,0 +1,41 @@
+
+cli_config:
+  pns:
+    config:
+      default: ~/.pns/config.yaml
+      os: PNS_CONFIG
+      help: The config file used for PNS
+      group: Config Options
+      options:
+      - -c
+      subcommands:
+      - __global__
+
+dyne:
+  config:
+    - plugin
+
+import:
+  - aiofiles
+  - aiofiles.os
+  - aiologger.handlers.files
+  - argparse
+  - asyncio
+  - ast
+  - collections
+  - pns.contract
+  - pns.data
+  - pns.exc
+  - pns.hub
+  - importlib
+  - importlib.resources
+  - logging
+  - msgpack
+  - os
+  - pathlib
+  - pickle
+  - signal
+  - sys
+  - traceback
+  - yaml
+  - typing

_config/plugin/choices.py

@@ -0,0 +1,37 @@
+async def parse_opt(hub, opts: dict[str, object]) -> dict[str, object]:
+    """
+    Handle choices that may come from a loaded mod.
+
+    You specify a sub on the hub for "choices" to dynamically use the loaded mods of that sub as the choices
+
+    I.e.
+
+    config:
+      my_app:
+        my_opt:
+          choices:
+            my_sub
+
+    Otherwise, you can specify a list of static choices that may be used
+
+    I.e.
+
+    config:
+      my_app:
+        my_opt:
+          choices:
+            - choice_1
+            - choice_2
+    """
+    choices = opts.pop("choices", ())
+    if isinstance(choices, str):
+        finder = hub
+        for part in choices.split("."):
+            try:
+                finder = getattr(finder, part)
+            except AttributeError:
+                return {}
+
+        opts["choices"] = sorted(finder)
+
+    return {}

_config/plugin/contract/init.py

@@ -0,0 +1 @@
+async def sig_parse_opt(hub, opts: dict[str, object]) -> dict[str, object]: ...

_config/plugin/default.py

@@ -0,0 +1,30 @@
+async def __init__(hub):
+    hub._.REF_PATTERN = hub.lib.re.compile(r"^hub\.(\w+(\.\w+)+)\(\)$")
+
+
+async def parse_opt(hub, opts: dict[str, object]) -> dict[str, object]:
+    """
+    Remove 'default' from the argument opts, it will be handled by the config prioritizer, not argparse.
+    If the "default" is a function that exists on the hub, then call it to get the default value.
+    This allows you to call a function on the hub to do more processing on the default.
+    This could be useful for using a different value for the default based on OS.
+
+    I.e.
+
+    config:
+      my_app:
+        my_opt:
+          default: hub.my_sub.mod.func()
+    """
+    default = opts.pop("default", None)
+
+    if default and isinstance(default, str):
+        match = hub._.REF_PATTERN.match(default)
+        if match:
+            ref = match.group(1)
+            func = hub.lib.pns.ref.find(hub, ref)
+            default = func()
+            if hub.lib.asyncio.iscoroutine(default):
+                default = await default
+
+    return {"default": default}

_config/plugin/display_priority.py

@@ -0,0 +1,34 @@
+async def parse_opt(hub, opts: dict[str, object]) -> dict[str, object]:
+    """
+    Handle the display priority of positional arguments.
+    This ensures that positional arguments appear in the defined order
+
+    I.e.
+
+        config:
+          my_app:
+            my_opt_1:
+              positional: True
+              display_priority: 1
+            my_opt_2:
+              positional: True
+              display_priority: 2
+    """
+    display_priority = opts.pop("display_priority", None)
+    return {"display_priority": display_priority}
+
+
+async def sort(hub, cli_args: list[dict[str, object]]) -> list[dict[str, object]]:
+    """
+    Sort the CLI arguments by display_priority.
+    The negative display_priorities were applied to args with no display priority,
+    They will come in the order they were defined
+    """
+    # Sort arguments by display_priority
+    return sorted(
+        cli_args,
+        key=lambda opt: (
+            opt["extra"]["display_priority"] is None,
+            opt["extra"]["display_priority"],
+        ),
+    )

_config/plugin/group.py

@@ -0,0 +1,31 @@
+async def parse_opt(hub, opts: dict[str, object]) -> dict[str, object]:
+    """
+    This config value groups arguments together in the --help text.
+
+    config:
+      my_app:
+        my_opt:
+          group: my_group
+        other_opt:
+          group: my_group
+    """
+    group = opts.pop("group", False)
+    return {"group": group}
+
+
+async def merge(hub, name: str, groups: dict[str, object], subcmd: str, subparser):
+    """
+    Merge the group into the subparser if a group name is provided.
+
+    Args:
+        name (str): The name of the group.
+        groups (dict): The existing groups dictionary.
+        subcmd (str): The subcommand name.
+        subparser (ArgumentParser): The subparser instance.
+
+    Returns:
+        ArgumentParser: The argument group added to the subparser.
+    """
+    if name:
+        return groups[subcmd].setdefault(name, subparser.add_argument_group(name))
+    return subparser

_config/plugin/init.py

@@ -0,0 +1,318 @@
+DEFAULT_GLOBAL_CLIS = ("pns", "log")
+
+
+async def load(
+    hub,
+    cli: str = None,
+    cli_config: dict[str, object] = None,
+    config: dict[str, object] = None,
+    subcommands: dict[str, object] = None,
+    global_clis: list[str] = None,
+    parser_args: tuple = None,
+    parser_init_kwargs: dict[str, object] = None,
+):
+    """
+    Use the pns-config system to load up a fresh configuration for this project
+    from the included conf.py file.
+
+    Args:
+        cli (str): The name of the authoritative CLI to parse.
+        cli_config (dict): The cli_config section of the plugin's config.yaml
+        config (dict): The config section of the plugin's config.yaml
+        subcommands (dict): The subcommands section of the plugin's config.yaml
+        global_clis (list): The namespaces that should be implicitly added to any cli parser or subparser
+        parser_args (tuple): Arguments for the parser.
+        parser_init_kwargs (dict): Keyword arguments for initializing the parser or subparsers.
+
+    Returns:
+        dict: The parsed CLI options.
+    """
+    if parser_init_kwargs is None:
+        parser_init_kwargs = {}
+    if cli_config is None:
+        cli_config = hub._dynamic.config.cli_config
+
+    # Get the plain config data that will tell us about OS vars and defaults
+    if config is None:
+        config = hub._dynamic.config.get("config") or {}
+
+    # Merge config and cli_config
+    full_config = hub.lib.pns.data.update(cli_config, config, merge_lists=True)
+
+    # These CLI namespaces will be added on top of any cli
+    if global_clis is None:
+        global_clis = DEFAULT_GLOBAL_CLIS
+
+    # Initialize the active cli, this is what will go into argparse
+    active_cli = {}
+
+    # Logging options and config file are part of the global namespace
+    for gn in global_clis:
+        active_cli.update(full_config.get(gn, {}).copy())
+
+    if subcommands is None:
+        subcommands = hub._dynamic.config.subcommands
+    else:
+        active_subcommands = subcommands
+    if cli:
+        active_subcommands = subcommands.get(cli, {})
+
+        # Grab the named cli last so that it can override globals
+        active_cli.update(full_config.get(cli, {}))
+        # Handle options that are sourced from other apps
+        await hub.config.source.resolve(cli, active_cli, full_config)
+
+        main_parser = await hub.config.init.parser(cli, **parser_init_kwargs)
+
+        # Process config/cli_config values
+        subparsers, arguments = await hub.config.init.parse_cli(
+            main_parser,
+            active_cli=active_cli,
+            subcommands=active_subcommands,
+        )
+
+        # Add all the cli options to argparse and call the parser
+        main_parser = await hub.config.subcommands.create_parsers(
+            main_parser, arguments, subparsers
+        )
+
+        cli_opts = await hub.config.init.parse(main_parser, parser_args)
+    else:
+        cli_opts = {}
+
+    # Load the config file parameter in the proper order
+    pns_config = full_config.get("pns", {}).get("config") or {}
+    config_file = (
+        cli_opts.get("config")
+        or hub.lib.os.environ.get("PNS_CONFIG", pns_config.get("os"))
+        or pns_config.get("default")
+    )
+
+    config_data = {}
+    if config_file:
+        config_file = hub.lib.pathlib.Path(config_file)
+        if config_file.exists():
+            with config_file.open("r") as fh:
+                config_data = hub.lib.yaml.safe_load(fh.read())
+
+    if not isinstance(config_data, dict):
+        if not config_data:  # The config is just empty, just let the user know
+            hub.lib.warnings.warn(
+                f"The configuration file {config_file} "
+                "retunred no data or failed to load, no configuration "
+                "file data will be used"
+            )
+        else:  # The config is invalid, warn the user
+            hub.lib.warnings.warn(
+                f"Configuration file must contain "
+                f"key/value pairs, not {type(config_data)}, the supplied "
+                f"configuration file {config_file} is not returning valid "
+                f"data. No configuration file data will be used"
+            )
+        config_data = {}
+
+    opt = await hub.config.init.prioritize(
+        cli=cli,
+        cli_opts=cli_opts,
+        config=full_config,
+        config_file_data=config_data,
+        global_clis=global_clis,
+    )
+
+    return hub.lib.pns.data.NamespaceDict(opt)
+
+
+async def parse(
+    hub,
+    main_parser: object,
+    parser_args: tuple[dict[str, object]],
+) -> dict[str, object]:
+    # Actually call the main parser
+    parsed_args = main_parser.parse_args(args=parser_args)
+    return hub.lib.pns.data.NamespaceDict(parsed_args.__dict__)
+
+
+async def parser(hub, cli: str, parser: object = None, **kwargs) -> object:
+    """
+    Create a new ArgumentParser or add a subparser to an existing parser.
+
+    Args:
+        cli (str): The name of the CLI being parsed.
+        parser (ArgumentParser, optional): An existing ArgumentParser instance.
+        **kwargs: Additional keyword arguments for ArgumentParser.
+
+    Returns:
+        ArgumentParser: The created or modified ArgumentParser instance.
+    """
+    if cli and "prog" not in kwargs:
+        kwargs["prog"] = cli.title()
+    if cli and "description" not in kwargs:
+        kwargs["description"] = f"{cli.title().replace('_', ' ')} CLI Parser"
+    if "conflict_handler" not in kwargs:
+        kwargs["conflict_handler"] = "resolve"
+    if parser is None:
+        return hub.lib.argparse.ArgumentParser(**kwargs)
+    else:
+        return parser.add_parser(cli, **kwargs)
+
+
+async def parse_opt(hub, opts: dict[str, object]) -> dict[str, object]:
+    """
+    Parse and process CLI options, handling custom config values.
+
+    Args:
+        opts (dict): The options to be parsed.
+
+    Returns:
+        dict: The processed options.
+    """
+    extra = {}
+    for parser_mod in sorted(hub.config):
+        if parser_mod == "init":
+            continue
+
+        if "parse_opt" not in hub.config[parser_mod]:
+            continue
+
+        new_extras = await hub.config[parser_mod].parse_opt(opts)
+        extra.update(new_extras)
+    return hub.lib.pns.data.NamespaceDict(extra)
+
+
+async def parse_cli(
+    hub,
+    main_parser,
+    active_cli: dict[str, object],
+    subcommands: dict[str, object] = None,
+) -> dict[str, object]:
+    """
+    Create a parser and parse all the CLI options.
+
+    Args:
+        main_parser (ArgumentParser): The main parser instance.
+        active_cli (dict): The active CLI configuration.
+        subcommands (dict): The subcommands configuration.
+
+    Returns:
+        tuple: A tuple containing the subparsers dictionary and the list of arguments.
+    """
+    if subcommands is None:
+        subcommands = {}
+    # Create the main parser for the CLI
+    if subcommands:
+        sparser = main_parser.add_subparsers(dest="SUBPARSER")
+    subparsers = {}
+
+    for subcommand, opts in subcommands.items():
+        subparsers[subcommand] = await hub.config.init.parser(
+            subcommand, sparser, **opts
+        )
+
+    # Collect all arguments and their metadata
+    arguments = []
+
+    for name, namespace_opts in active_cli.items():
+        opts = namespace_opts.copy()
+        opts["__name__"] = name
+        # Separate/process our custom config values from those consumed by argparse
+        extra = await hub.config.init.parse_opt(opts)
+        options = extra.options
+        group_name = extra.group
+        cli_name = opts.pop("__name__")
+
+        argument_meta = {
+            "cli_name": cli_name,
+            "options": options,
+            "opts": opts,
+            "group_name": group_name,
+            "extra": extra,
+        }
+
+        arguments.append(argument_meta)
+
+    return subparsers, arguments
+
+
+PLACEHOLDER = object()
+
+
+async def prioritize(
+    hub,
+    cli: str,
+    cli_opts: dict[str, any],
+    config: dict[str, any],
+    config_file_data: dict[str, any],
+    global_clis: list[str],
+    *,
+    document_parameters: bool = False,
+):
+    """
+    Prioritize configuration data from various sources.
+
+    The order of priority is:
+    1. CLI options (highest priority)
+    2. Configuration file data
+    3. OS environment variables
+    4. Default values (lowest priority)
+    5. Rewrite the root_dir option so running apps automatically changes dirs to user preferences
+
+    Args:
+        cli (str): The name of the CLI being prioritized.
+        cli_opts (dict): The parsed CLI options.
+        config (dict): The configuration dictionary.
+        config_file_data (dict): The data from the configuration file.
+        Document_parameters: If True, hub.OPT will contain docstrings for leaf nodes
+
+    Returns:
+       pns.data.NamespaceDict: The prioritized configuration options.
+    """
+    opt = hub.lib.collections.defaultdict(dict)
+    for namespace, args in config.items():
+        # Boolean to determine if the given option is part of the active cli
+        is_active_namespace = namespace == cli or namespace in global_clis
+        for arg, data in args.items():
+            is_active_cli = is_active_namespace
+            # This option belongs to a different part of the namespace
+            if data.get("source"):
+                # If the source is not the current namespace, skip it
+                if data["source"] != namespace:
+                    continue
+                is_active_cli = True
+            # Initialize value to None
+            value = None
+
+            # 1. Check CLI options first
+            if is_active_cli and arg in cli_opts:
+                value = cli_opts.get(arg)
+
+            # 2. Check config file data if CLI option is not set
+            if value is None:
+                value = config_file_data.get(namespace, {}).get(arg, PLACEHOLDER)
+
+            # Skip malformed config
+            if not isinstance(data, dict):
+                msg = f"Invalid data from config.yaml: {data}"
+                raise TypeError(msg)
+
+            # 3. Check OS environment variables if config file data is not set
+            if value is PLACEHOLDER and "os" in data:
+                value = hub.lib.os.environ.get(data["os"], PLACEHOLDER)
+
+            # 4. Use default value if none of the above are set
+            if value is PLACEHOLDER:
+                if "default" not in data:
+                    msg = f"Option '{namespace}.{arg}' has no value from config, os, or defaults"
+                    if is_active_cli:
+                        raise ValueError(msg)
+                value = data.get("default")
+            if document_parameters:
+                # Wrap the value in a class that gives it a docstring
+                value = hub.lib.pns.data.wrap_value(arg, value, data.get("help", ""))
+
+            # Set the value in the OPT dictionary
+            opt[namespace][arg] = value
+
+    opt["pns"]["subparser"] = cli_opts.get("SUBPARSER", "")
+    opt["pns"]["global_clis"] = global_clis
+
+    return opt

_config/plugin/options.py

@@ -0,0 +1,14 @@
+async def parse_opt(hub, opts: dict[str, object]) -> dict[str, object]:
+    """
+    Alternate flags that can be used for this config option
+
+    config:
+      my_app:
+        my_opt:
+          options:
+          - -o
+          - --opt
+          - --opt1
+    """
+    options = opts.pop("options", ())
+    return {"options": options}

_config/plugin/os.py

@@ -0,0 +1,10 @@
+async def parse_opt(hub, opts: dict[str, object]) -> dict[str, object]:
+    """
+    Remove 'os' from the argument kwargs, it will be handled by the config prioritizer
+
+    config:
+      my_app:
+        my_opt:
+          os: MY_ENV_VAR
+    """
+    return {"os": opts.pop("os", False)}

_config/plugin/positional.py

@@ -0,0 +1,21 @@
+async def parse_opt(hub, opts: dict[str, object]) -> dict[str, object]:
+    """
+    Mark an argument as a positional
+
+    I.e.
+
+    config:
+      my_app:
+        my_opt_1:
+          positional: True
+    """
+    positional = opts.pop("positional", False)
+
+    if positional:
+        # A positional argument cannot have flag options
+        opts.pop("options", None)
+    else:
+        # For non-positional args, create an inituitive cli name
+        opts["__name__"] = f"--{opts['__name__'].lower().replace('_', '-')}"
+
+    return {}

_config/plugin/source.py

@@ -0,0 +1,53 @@
+async def parse_opt(hub, opts: dict[str, object]) -> dict[str, object]:
+    """
+    Include an option defined in another app's config in this app's CLI
+    Merge over the source app's config for the option.
+
+    It will still show up under the namespace of the other app.
+
+    I.e.
+
+    config:
+      my_app:
+        my_opt:
+          source: other_app
+          default: override
+
+      other_app:
+        my_opt:
+          default: value
+    """
+    opts.pop("source", None)
+
+    # This is already handled in hub.config.init.load since it needs to happen before everything else.
+
+    return {}
+
+
+async def resolve(
+    hub, cli: str, active_cli: dict[str, object], full_config: dict[str, object]
+):
+    """
+    Add an option from another app's cli_config to the active cli
+    """
+    new_stuff = {}
+    for name, opt in active_cli.items():
+        source = opt.pop("source", None)
+        if not source:
+            continue
+        # Get the config for the opt from the source
+        if not full_config.get(source):
+            full_config[source] = {}
+        if not full_config[source].get(name):
+            full_config[source][name] = {}
+
+        # Override the sourced option config with the values from the active cli
+        full_config[source][name].update(opt)
+        new_stuff[name] = full_config[source][name]
+        new_stuff[name]["source"] = source
+
+    for key in new_stuff:
+        # Ensure that the key only shows up under the source's namespace
+        full_config[cli].pop(key, None)
+
+    active_cli.update(new_stuff)

_config/plugin/subcommands.py

@@ -0,0 +1,82 @@
+async def parse_opt(hub, opts: dict[str, object]) -> dict[str, object]:
+    """
+    Specify that a given option belongs to a certain subcommand
+
+    I.e.
+
+        config:
+          my_app:
+            my_opt:
+              subcommands:
+              - my_subcommand
+            my_global_opt:
+              subcommands:
+              - __global__
+
+        subcommands:
+          my_app:
+            my_subcommand: {}
+    """
+    subcommands = opts.pop("subcommands", ())
+    return {"subcommands": subcommands}
+
+
+GLOBAL = "__global__"
+
+
+async def create_parsers(
+    hub,
+    main_parser,
+    cli_args: list[object],
+    subparsers: dict[str, object],
+):
+    """
+    Create and add CLI parsers and arguments.
+
+    Args:
+        hub: The PNS hub instance.
+        main_parser (ArgumentParser): The main parser instance.
+        parser_args (tuple): Arguments for the parser.
+        cli_args (list): List of CLI arguments.
+        subparsers (dict): Dictionary of subparsers.
+
+    Returns:
+        dict: The parsed CLI options.
+    """
+
+    # Add CLI options to the parser
+    groups = {}
+    subparser_groups = {subcommand: {} for subcommand in subparsers}
+    sorted_arguments = await hub.config.display_priority.sort(cli_args)
+
+    for arg_meta in sorted_arguments:
+        cli_name = arg_meta["cli_name"]
+        options = arg_meta["options"]
+        opts = arg_meta["opts"]
+        group_name = arg_meta["group_name"]
+        extra_subcommands = arg_meta["extra"].subcommands
+
+        # Handle argument groups for top-level parser
+        target_group = await hub.config.group.merge(
+            group_name, {None: groups}, None, main_parser
+        )
+        if GLOBAL in extra_subcommands or not extra_subcommands:
+            target_group.add_argument(cli_name, *options, **opts)
+
+        # Handle argument groups for subparsers
+        for subcommand in extra_subcommands:
+            if subcommand == GLOBAL:
+                for subcmd, sparser in subparsers.items():
+                    subparser_group = await hub.config.group.merge(
+                        group_name, subparser_groups, subcmd, sparser
+                    )
+                    subparser_group.add_argument(cli_name, *options, **opts)
+            elif subcommand in subparsers:
+                subcmd = subcommand
+                sparser = subparsers[subcommand]
+                subparser_group = await hub.config.group.merge(
+                    group_name, subparser_groups, subcmd, sparser
+                )
+                subparser_group.add_argument(cli_name, *options, **opts)
+
+    return main_parser

_config/plugin/type.py

@@ -0,0 +1,15 @@
+async def parse_opt(hub, opts: dict[str, object]) -> dict[str, object]:
+    """
+    Evaluate the "type" string to be a constructor for the actual type
+    I.e.
+
+        config:
+          my_app:
+            my_opt:
+              type: str
+    """
+    type_ = opts.pop("type", None)
+    if type_:
+        opts["type"] = eval(type_)
+
+    return {}