define.param.param

InjectedParam

Bases: Param[T]

Injected Params are params whose values do not come from the command line, but from a dependancy injection. Used to get access to things like the arc Context and State

Source code in /home/runner/work/arc/arc/arc/define/param/param.py

class InjectedParam(Param[T]):
    """Injected Params are params whose values do
    not come from the command line, but from a dependancy injection.
    Used to get access to things like the arc Context and State
    """

    callback: at.ParamGetter  # type: ignore[assignment]

    def get_injected_value(self, ctx: t.Any) -> t.Any:
        value = api.dispatch_args(self.callback, ctx, self)
        return value

    @property
    def is_injected(self) -> bool:
        return True

Param

Bases: t.Generic[T]

Source code in /home/runner/work/arc/arc/arc/define/param/param.py

class Param(t.Generic[T]):
    argument_name: str
    """The cannonical name of the function's argument"""
    param_name: str
    """The names used on the command line / for parsing"""
    short_name: str | None
    """Optional single-character name alternabive for keyword params"""
    type: TypeInfo[T]
    """Information on the type of the argument"""
    default: T | Constant | None
    """Default value for this Param, will be used if no
    other source provides a value. A value `MISSING` indicates
    that the parameter is required. Otherwise, the parameter is optional"""
    description: str | None
    """Documentation for this parameter. If none is provided explicitly,
    it may also originate from the command's docstring"""
    envvar: str | None
    """Optional Enviroment variable to pull the value from
    if there is no value provided on the CLI"""
    prompt: str | None
    """Optional input prompt text to pull the value from
    stdin with when no valus is provided on the CLI"""
    action: Action | t.Type[argparse.Action]
    """argparse action associated with this param"""
    expose: bool
    """If a param is 'exposed' it will be passed to the command's callback.
    If it's not 'exposed' then it will not be passed to the command's callback.
    This is useful when the parameter's side effects are desired, but the value
    doesn't matter. This is used to implment the `--version` and `--help` flags"""
    comp_func: at.CompletionFunc | None
    """Function that can provide shell completions for the parameter"""
    getter_func: at.ParamGetter | None
    """Function that can retrieve a value not provided on the command line"""
    data: dict[str, t.Any]
    """Dictionary of any other key values passed to the constructors"""

    def __init__(
        self,
        argument_name: str,
        type: TypeInfo[T],
        default: T | None | Constant = MISSING,
        param_name: str | None = None,
        short_name: str | None = None,
        description: str | None = None,
        callback: at.ParamCallback | None = None,
        envvar: str | None = None,
        prompt: str | None = None,
        action: Action | t.Type[argparse.Action] | None = None,
        expose: bool = True,
        comp_func: at.CompletionFunc | None = None,
        getter_func: at.ParamGetter | None = None,
        data: dict[str, t.Any] = None,
    ):
        self.argument_name = argument_name
        self.param_name = param_name or argument_name
        self.type = type
        self.short_name = short_name
        self.default = default
        self.description = description
        self.callback = callback
        self.envvar = envvar
        self.prompt = prompt
        self.action = action or Action.STORE
        self.expose = expose
        self.comp_func = comp_func
        self.getter_func = getter_func
        self.data = data or {}

        if self.type.is_optional_type and self.default is MISSING:
            self.default = None

    __repr__ = api.display("argument_name", "type")

    def __completions__(
        self, info: CompletionInfo, *args: t.Any, **kwargs: t.Any
    ) -> at.CompletionReturn:
        if self.comp_func:
            return self.comp_func(info, self)

        if hasattr(self.type.resolved_type, "__completions__"):
            return get_completions(self.type.resolved_type, info, self)  # type: ignore

        return None

    @property
    def schema(self) -> dict[str, t.Any]:
        return {
            "argument_name": self.argument_name,
            "type": self.type,
            "param_name": self.param_name,
            "short_name": self.short_name,
            "default": self.default,
        }

    @property
    def is_argument(self) -> bool:
        return False

    @property
    def is_keyword(self) -> bool:
        return False

    @property
    def is_option(self) -> bool:
        return False

    @property
    def is_flag(self) -> bool:
        return False

    @property
    def is_injected(self) -> bool:
        return False

    @property
    def is_optional(self) -> bool:
        return self.type.is_optional_type or self.default is not MISSING

    @property
    def is_required(self) -> bool:
        return not self.is_optional

    @property
    def prompt_string(self) -> str:
        assert isinstance(self.prompt, str), "No prompt string provided"

        if self.default is not MISSING:
            return self.prompt + colorize(f" ({self.default}) ", fg.GREY)
        return self.prompt

    @property
    def cli_name(self) -> str:
        return self.param_name

    @property
    def parser_default(self) -> t.Any:
        return MISSING

    @cached_property
    def nargs(self) -> at.NArgs:
        if (
            safe.issubclass(self.type.origin, tuple)
            and self.type.sub_types
            and self.type.sub_types[-1].origin is not Ellipsis
        ):
            return len(self.type.sub_types)  # Consume a specific number
        elif self.type.is_collection_type:
            return "*"  # Consume one or more

        return "?"  # Optional

    def convert(self, value: t.Any) -> T:
        return convert_type(self.type.resolved_type, value, self.type)

    def run_middleware(self, value: t.Any, ctx: t.Any) -> t.Any:
        for middleware in self.type.middleware:
            value = api.dispatch_args(middleware, value, ctx, self)

        return value

    def get_param_names(self) -> list[str]:
        return []

action: Action | t.Type[argparse.Action] = action or Action.STORE instance-attribute

argparse action associated with this param

argument_name: str = argument_name instance-attribute

The cannonical name of the function's argument

comp_func: at.CompletionFunc | None = comp_func instance-attribute

Function that can provide shell completions for the parameter

data: dict[str, t.Any] = data or {} instance-attribute

Dictionary of any other key values passed to the constructors

default: T | Constant | None = default instance-attribute

Default value for this Param, will be used if no other source provides a value. A value MISSING indicates that the parameter is required. Otherwise, the parameter is optional

description: str | None = description instance-attribute

Documentation for this parameter. If none is provided explicitly, it may also originate from the command's docstring

envvar: str | None = envvar instance-attribute

Optional Enviroment variable to pull the value from if there is no value provided on the CLI

expose: bool = expose instance-attribute

If a param is 'exposed' it will be passed to the command's callback. If it's not 'exposed' then it will not be passed to the command's callback. This is useful when the parameter's side effects are desired, but the value doesn't matter. This is used to implment the --version and --help flags

getter_func: at.ParamGetter | None = getter_func instance-attribute

Function that can retrieve a value not provided on the command line

param_name: str = param_name or argument_name instance-attribute

The names used on the command line / for parsing

prompt: str | None = prompt instance-attribute

Optional input prompt text to pull the value from stdin with when no valus is provided on the CLI

short_name: str | None = short_name instance-attribute

Optional single-character name alternabive for keyword params

type: TypeInfo[T] = type instance-attribute

Information on the type of the argument