yapx.arg¶

Functions¶

arg ¶

arg(
    *flags: str,
    default: Optional[Any] = MISSING,
    env: Union[None, str, Sequence[str]] = None,
    pos: Optional[bool] = False,
    is_secret: Optional[bool] = False,
    stdin: Union[None, bool, str] = None,
    group: Optional[str] = None,
    exclusive: Optional[bool] = False,
    help: Optional[str] = None,
    metavar: Optional[str] = None,
    nargs: Optional[Union[int, str]] = None,
    choices: Optional[Sequence[Any]] = None,
    action: Union[None, str, type[Action]] = None,
    _type: Union[
        None, type[Any], Callable[[str], Any]
    ] = None,
    _const: Optional[Any] = None,
    _required: Optional[bool] = None
) -> Field

Provides an interface to modify argument options.

PARAMETER	DESCRIPTION
`*flags`	one or more flags to use for the argument. TYPE: `str` DEFAULT: `()`
`default`	default value for the argument. Argument is required if no default is given. TYPE: `Optional[Any]` DEFAULT: `MISSING`
`env`	list of environment variables that will provide the argument value. TYPE: `Union[None, str, Sequence[str]]` DEFAULT: `None`
`pos`	if True, argument is positional (no flags). TYPE: `Optional[bool]` DEFAULT: `False`
`stdin`	if True, argument can get its value from stdin. If a `str`, mock stdin with this value. TYPE: `Union[None, bool, str]` DEFAULT: `None`
`group`	group for the argument. TYPE: `Optional[str]` DEFAULT: `None`
`exclusive`	if True, this arg cannot be specified along with another exclusive arg in the same group. TYPE: `Optional[bool]` DEFAULT: `False`
`help`	help text / description TYPE: `Optional[str]` DEFAULT: `None`
`metavar`	variable name printed in help text. TYPE: `Optional[str]` DEFAULT: `None`
`nargs`	the number of values this argument accepts. TYPE: `Optional[Union[int, str]]` DEFAULT: `None`
`choices`	a sequence of acceptable values. TYPE: `Optional[Sequence[Any]]` DEFAULT: `None`
`action`	custom action for this argument. TYPE: `Union[None, str, type[Action]]` DEFAULT: `None`

RETURNS	DESCRIPTION
`Field`	...

Examples:

import yapx
from typing import Annotated


def say_hello(value=yapx.arg(default="World")):
    print(f"Hello {value}")


yapx.run(say_hello, args=[])
# Hello World

import yapx
from typing import Annotated


def say_hello(value: Annotated[str, yapx.arg(default="World")]):
    print(f"Hello {value}")


yapx.run(say_hello, args=[])
# Hello World

counting_arg ¶

counting_arg(*args, **kwargs) -> Field

Designates this argument as a counting argument.

yapx.counting_arg(...) is equal to yapx.arg(nargs=0, ...)

Must be used with a parameter annotated with type int.

PARAMETER	DESCRIPTION
`*args`	passed to arg(...) DEFAULT: `()`
`**kwargs`	passed to arg(...) DEFAULT: `{}`

RETURNS	DESCRIPTION
`Field`	...

Examples:

import yapx
from typing import Annotated


def say_hello(verbosity: Annotated[int, yapx.feature_arg("v")] = 0):
    return verbosity


result = yapx.run(say_hello, args=["-vvvvv"])
assert result == 5

feature_arg ¶

feature_arg(*args, **kwargs) -> Field

Designates this argument as a feature-flag argument.

yapx.feature_arg(...) is equal to yapx.arg(nargs=0, ...)

Must be used with a parameter annotated with type str.

PARAMETER	DESCRIPTION
`*args`	passed to arg(...) DEFAULT: `()`
`**kwargs`	passed to arg(...) DEFAULT: `{}`

RETURNS	DESCRIPTION
`Field`	...

Examples:

import yapx
from typing import Annotated


def say_hello(
    value: Annotated[str, yapx.feature_arg("dev", "test", "prod")],
):
    return value


result = yapx.run(say_hello, args=["--prod"])

assert result == "prod"

unbounded_arg ¶

unbounded_arg(*args, **kwargs) -> Field

Designates this argument as an unbounded, multi-value argument.

yapx.unbounded_arg(...) is equal to yapx.arg(nargs=-1, ...)

Must be used with a parameter annotated with a sequence type: Sequence[...], List[...], Set[...], Tuple[..., ...], or Dict[str, ...]

PARAMETER	DESCRIPTION
`*args`	passed to arg(...) DEFAULT: `()`
`**kwargs`	passed to arg(...) DEFAULT: `{}`

RETURNS	DESCRIPTION
`Field`	...

Examples:

import yapx
from typing import Annotated


def say_hello(values: Annotated[list[int], yapx.unbounded_arg()]):
    return values


result = yapx.run(say_hello, args=["--values", "1", "2", "3"])
assert result == [1, 2, 3]