ArgUtils

Module: terminaltexteffects.utils.argutils

Command line argument validators and METAVARs for consistent type parsing and help output.

This module includes a custom formatter for argparse, which combines the features of argparse.ArgumentDefaultsHelpFormatter and argparse.RawDescriptionHelpFormatter.

Classes:

Name	Description
CustomFormatter	A custom formatter for argparse that combines the features of argparse.ArgumentDefaultsHelpFormatter and argparse.RawDescriptionHelpFormatter.
CharacterGroup	An enum specifying character groupings.
CharacterGroupArg	Argument type for character groupings.
CharacterSort	An enum specifying character sorts.
CharacterSortArg	Argument type for character sorts.
ColorSort	An enum specifying color sorts.
ColorSortArg	Argument type for color sorts.
TupleAction	Custom argparse action to convert a list of values into a tuple.
ParserSpec	Specification for a parser in the argument parser.
ArgSpec	Specification for a command-line argument and default value.
GradientDirection	Argument type for gradient directions.
ColorArg	Argument type for color values.
Symbol	Argument type for single ASCII/UTF-8 characters.
Ease	Argument type for easing functions.
PositiveInt	Argument type for positive integers.
NonNegativeInt	Argument type for nonnegative integers.
PositiveIntRange	Argument type for integer ranges.
PositiveFloat	Argument type for positive floats.
NonNegativeFloat	Argument type for nonnegative floats.
PositiveFloatRange	Argument type for float ranges.
TerminalDimension	Argument type for terminal dimensions.
CanvasDimension	Argument type for canvas dimensions.
NonNegativeRatio	Argument type for float values between zero and one.
PositiveRatio	Argument type for positive float values greater than zero and less than or equal to one.
EasingStep	Argument type for easing step size values.

Functions:

Name	Description
is_ascii_or_utf8	Tests if the given string is either ASCII or UTF-8.

Constants

EASING_EPILOG (str): A detailed description of the easing functions supported.

ArgSpec dataclass

Specification for a command-line argument and default value.

The default value is used for both the argparse argument and to support direct instantiation of a config.

Source code in terminaltexteffects/utils/argutils.py

@dataclass(frozen=True)
class ArgSpec:
    """Specification for a command-line argument and default value.

    The default value is used for both the argparse argument and to support direct
    instantiation of a config.
    """

    name: str
    default: typing.Any
    metavar: str = _MISSING  # type: ignore[arg-type]
    type: typing.Any = _MISSING  # type: ignore[arg-type]
    required: bool = _MISSING  # type: ignore[arg-type]
    help: str = _MISSING  # type: ignore[arg-type]
    action: str | type[argparse.Action] = _MISSING  # type: ignore[arg-type]
    choices: list[typing.Any] = _MISSING  # type: ignore[arg-type]
    nargs: str | int = _MISSING  # type: ignore[arg-type]

CanvasDimension

Validate argument is a valid canvas dimension.

Raises:

Type	Description
ArgumentTypeError	Value is not a valid canvas dimension.

Source code in terminaltexteffects/utils/argutils.py

class CanvasDimension:
    """Validate argument is a valid canvas dimension.

    Raises:
        argparse.ArgumentTypeError: Value is not a valid canvas dimension.

    """

    METAVAR = "int >= -1"

    @staticmethod
    def type_parser(arg: str) -> int:
        """Validate argument is a valid canvas dimension.

        Args:
            arg (str): argument to validate

        Raises:
            argparse.ArgumentTypeError: Value is not a valid canvas dimension.

        Returns:
            int: validated canvas dimension

        """
        if arg.isdigit() or arg == "-1":
            return int(arg)
        msg = f"invalid value '{arg}' is not a valid integer. Must be >= -1."
        raise argparse.ArgumentTypeError(msg)

type_parser(arg) staticmethod

Validate argument is a valid canvas dimension.

Parameters:

Name	Type	Description	Default
arg	str	argument to validate	required

Raises:

Type	Description
ArgumentTypeError	Value is not a valid canvas dimension.

Returns:

Name	Type	Description
int	int	validated canvas dimension

Source code in terminaltexteffects/utils/argutils.py

@staticmethod
def type_parser(arg: str) -> int:
    """Validate argument is a valid canvas dimension.

    Args:
        arg (str): argument to validate

    Raises:
        argparse.ArgumentTypeError: Value is not a valid canvas dimension.

    Returns:
        int: validated canvas dimension

    """
    if arg.isdigit() or arg == "-1":
        return int(arg)
    msg = f"invalid value '{arg}' is not a valid integer. Must be >= -1."
    raise argparse.ArgumentTypeError(msg)

CharacterGroup

Bases: Enum

An enum specifying character groupings.

Source code in terminaltexteffects/utils/argutils.py

class CharacterGroup(Enum):
    """An enum specifying character groupings."""

    COLUMN_LEFT_TO_RIGHT = auto()
    COLUMN_RIGHT_TO_LEFT = auto()
    ROW_TOP_TO_BOTTOM = auto()
    ROW_BOTTOM_TO_TOP = auto()
    DIAGONAL_TOP_LEFT_TO_BOTTOM_RIGHT = auto()
    DIAGONAL_BOTTOM_LEFT_TO_TOP_RIGHT = auto()
    DIAGONAL_TOP_RIGHT_TO_BOTTOM_LEFT = auto()
    DIAGONAL_BOTTOM_RIGHT_TO_TOP_LEFT = auto()
    CENTER_TO_OUTSIDE = auto()
    OUTSIDE_TO_CENTER = auto()

CharacterGroupArg

Validate argument is a valid CharacterGroup.

Raises:

Type	Description
ArgumentTypeError	Value is not a valid CharacterGroup.

Source code in terminaltexteffects/utils/argutils.py

class CharacterGroupArg:
    """Validate argument is a valid CharacterGroup.

    Raises:
        argparse.ArgumentTypeError: Value is not a valid CharacterGroup.

    """

    METAVAR = tuple(n.lower() for n in CharacterGroup._member_names_)

    @staticmethod
    def type_parser(arg: str) -> CharacterGroup:
        """Validate argument is a valid CharacterGroup.

        Args:
            arg (str): argument to validate

        Raises:
            argparse.ArgumentTypeError: Value is not a valid CharacterGroup.

        Returns:
            CharacterGroup: validated CharacterGroup

        """
        try:
            return CharacterGroup[arg.upper()]
        except KeyError:
            msg = f"invalid CharacterGroup: '{arg}' is not a valid CharacterGroup."
            raise argparse.ArgumentTypeError(msg) from None

type_parser(arg) staticmethod

Validate argument is a valid CharacterGroup.

Parameters:

Name	Type	Description	Default
arg	str	argument to validate	required

Raises:

Type	Description
ArgumentTypeError	Value is not a valid CharacterGroup.

Returns:

Name	Type	Description
CharacterGroup	CharacterGroup	validated CharacterGroup

Source code in terminaltexteffects/utils/argutils.py

@staticmethod
def type_parser(arg: str) -> CharacterGroup:
    """Validate argument is a valid CharacterGroup.

    Args:
        arg (str): argument to validate

    Raises:
        argparse.ArgumentTypeError: Value is not a valid CharacterGroup.

    Returns:
        CharacterGroup: validated CharacterGroup

    """
    try:
        return CharacterGroup[arg.upper()]
    except KeyError:
        msg = f"invalid CharacterGroup: '{arg}' is not a valid CharacterGroup."
        raise argparse.ArgumentTypeError(msg) from None

CharacterSort

Bases: Enum

An enum for specifying character sorts.

Source code in terminaltexteffects/utils/argutils.py

class CharacterSort(Enum):
    """An enum for specifying character sorts."""

    RANDOM = auto()
    TOP_TO_BOTTOM_LEFT_TO_RIGHT = auto()
    TOP_TO_BOTTOM_RIGHT_TO_LEFT = auto()
    BOTTOM_TO_TOP_LEFT_TO_RIGHT = auto()
    BOTTOM_TO_TOP_RIGHT_TO_LEFT = auto()
    OUTSIDE_ROW_TO_MIDDLE = auto()
    MIDDLE_ROW_TO_OUTSIDE = auto()

CharacterSortArg

Validate argument is a valid CharacterSort.

Raises:

Type	Description
ArgumentTypeError	Value is not a valid CharacterSort.

Source code in terminaltexteffects/utils/argutils.py

class CharacterSortArg:
    """Validate argument is a valid CharacterSort.

    Raises:
        argparse.ArgumentTypeError: Value is not a valid CharacterSort.

    """

    METAVAR = tuple(n.lower() for n in CharacterSort._member_names_)

    @staticmethod
    def type_parser(arg: str) -> CharacterSort:
        """Validate argument is a valid CharacterSort.

        Args:
            arg (str): argument to validate

        Raises:
            argparse.ArgumentTypeError: Value is not a valid CharacterSort.

        Returns:
            CharacterSort: validated CharacterSort

        """
        try:
            return CharacterSort[arg.upper()]
        except KeyError:
            msg = f"invalid CharacterSort: '{arg}' is not a valid CharacterSort."
            raise argparse.ArgumentTypeError(msg) from None

type_parser(arg) staticmethod

Validate argument is a valid CharacterSort.

Parameters:

Name	Type	Description	Default
arg	str	argument to validate	required

Raises:

Type	Description
ArgumentTypeError	Value is not a valid CharacterSort.

Returns:

Name	Type	Description
CharacterSort	CharacterSort	validated CharacterSort

Source code in terminaltexteffects/utils/argutils.py

@staticmethod
def type_parser(arg: str) -> CharacterSort:
    """Validate argument is a valid CharacterSort.

    Args:
        arg (str): argument to validate

    Raises:
        argparse.ArgumentTypeError: Value is not a valid CharacterSort.

    Returns:
        CharacterSort: validated CharacterSort

    """
    try:
        return CharacterSort[arg.upper()]
    except KeyError:
        msg = f"invalid CharacterSort: '{arg}' is not a valid CharacterSort."
        raise argparse.ArgumentTypeError(msg) from None

ColorArg

Validate argument is a valid color value.

Color values can be either an XTerm color value (0-255) or an RGB hex value (000000-ffffff).

Raises:

Type	Description
ArgumentTypeError	Value is not in range of valid XTerm colors or RGB hex colors.

Source code in terminaltexteffects/utils/argutils.py

class ColorArg:
    """Validate argument is a valid color value.

    Color values can be either an XTerm color value (0-255) or an RGB hex value (000000-ffffff).

    Raises:
        argparse.ArgumentTypeError: Value is not in range of valid XTerm colors or RGB hex colors.

    """

    METAVAR = "(XTerm [0-255] OR RGB Hex [000000-ffffff])"

    @staticmethod
    def type_parser(arg: str) -> Color:
        """Validate argument is a valid color value.

        Args:
            arg (str): argument to validate

        Raises:
            argparse.ArgumentTypeError: Color value is not in range.

        Returns:
            Color : validated color value

        """
        xterm_min = 0
        xterm_max = 255
        if len(arg) <= 3:
            try:
                return Color(int(arg))
            except ValueError:
                msg = (
                    f"invalid color value: '{arg}' is not a valid XTerm or RGB color."
                    f" Must be in range {xterm_min}-{xterm_max} or 000000-FFFFFF."
                )
                raise argparse.ArgumentTypeError(msg) from None
        else:
            try:
                return Color(arg)
            except ValueError:
                msg = (
                    f"invalid color value: '{arg}' is not a valid XTerm or RGB color."
                    f" Must be in range {xterm_min}-{xterm_max} or 000000-FFFFFF."
                )
                raise argparse.ArgumentTypeError(msg) from None

type_parser(arg) staticmethod

Validate argument is a valid color value.

Parameters:

Name	Type	Description	Default
arg	str	argument to validate	required

Raises:

Type	Description
ArgumentTypeError	Color value is not in range.

Returns:

Name	Type	Description
Color	Color	validated color value

Source code in terminaltexteffects/utils/argutils.py

@staticmethod
def type_parser(arg: str) -> Color:
    """Validate argument is a valid color value.

    Args:
        arg (str): argument to validate

    Raises:
        argparse.ArgumentTypeError: Color value is not in range.

    Returns:
        Color : validated color value

    """
    xterm_min = 0
    xterm_max = 255
    if len(arg) <= 3:
        try:
            return Color(int(arg))
        except ValueError:
            msg = (
                f"invalid color value: '{arg}' is not a valid XTerm or RGB color."
                f" Must be in range {xterm_min}-{xterm_max} or 000000-FFFFFF."
            )
            raise argparse.ArgumentTypeError(msg) from None
    else:
        try:
            return Color(arg)
        except ValueError:
            msg = (
                f"invalid color value: '{arg}' is not a valid XTerm or RGB color."
                f" Must be in range {xterm_min}-{xterm_max} or 000000-FFFFFF."
            )
            raise argparse.ArgumentTypeError(msg) from None

ColorSort

Bases: Enum

An enum for specifying color sorts for the colors derived from the input text ansi sequences.

Source code in terminaltexteffects/utils/argutils.py

class ColorSort(Enum):
    """An enum for specifying color sorts for the colors derived from the input text ansi sequences."""

    LEAST_TO_MOST = auto()
    MOST_TO_LEAST = auto()
    RANDOM = auto()

ColorSortArg

Validate argument is a valid ColorSort.

Raises:

Type	Description
ArgumentTypeError	Value is not a valid ColorSort.

Source code in terminaltexteffects/utils/argutils.py

class ColorSortArg:
    """Validate argument is a valid ColorSort.

    Raises:
        argparse.ArgumentTypeError: Value is not a valid ColorSort.

    """

    METAVAR = tuple(n.lower() for n in ColorSort._member_names_)

    @staticmethod
    def type_parser(arg: str) -> ColorSort:
        """Validate argument is a valid ColorSort.

        Args:
            arg (str): argument to validate

        Raises:
            argparse.ArgumentTypeError: Value is not a valid ColorSort.

        Returns:
            ColorSort: validated ColorSort

        """
        try:
            return ColorSort[arg.upper()]
        except KeyError:
            msg = f"invalid ColorSort: '{arg}' is not a valid ColorSort."
            raise argparse.ArgumentTypeError(msg) from None

type_parser(arg) staticmethod

Validate argument is a valid ColorSort.

Parameters:

Name	Type	Description	Default
arg	str	argument to validate	required

Raises:

Type	Description
ArgumentTypeError	Value is not a valid ColorSort.

Returns:

Name	Type	Description
ColorSort	ColorSort	validated ColorSort

Source code in terminaltexteffects/utils/argutils.py

@staticmethod
def type_parser(arg: str) -> ColorSort:
    """Validate argument is a valid ColorSort.

    Args:
        arg (str): argument to validate

    Raises:
        argparse.ArgumentTypeError: Value is not a valid ColorSort.

    Returns:
        ColorSort: validated ColorSort

    """
    try:
        return ColorSort[arg.upper()]
    except KeyError:
        msg = f"invalid ColorSort: '{arg}' is not a valid ColorSort."
        raise argparse.ArgumentTypeError(msg) from None

CustomFormatter

Bases: ArgumentDefaultsHelpFormatter, RawDescriptionHelpFormatter

Combine ArgumentDefaultsHelpFormatter and RawDescriptionHelpFormatter for argparse.

Source code in terminaltexteffects/utils/argutils.py

class CustomFormatter(argparse.ArgumentDefaultsHelpFormatter, argparse.RawDescriptionHelpFormatter):
    """Combine ArgumentDefaultsHelpFormatter and RawDescriptionHelpFormatter for argparse."""

Ease

Validate argument is a valid easing function.

Easing functions are prefixed by "in", "out", or "in_out" and suffixed by a valid easing function.

Raises:

Type	Description
ArgumentTypeError	Value is not a valid easing function.

Source code in terminaltexteffects/utils/argutils.py

class Ease:
    """Validate argument is a valid easing function.

    Easing functions are prefixed by "in", "out", or "in_out" and suffixed by a valid easing function.

    Raises:
        argparse.ArgumentTypeError: Value is not a valid easing function.

    """

    METAVAR = "(Easing Function)"

    @staticmethod
    def type_parser(arg: str) -> typing.Callable:
        """Validate argument is a valid easing function.

        Args:
            arg (str): argument to validate

        Raises:
            argparse.ArgumentTypeError: Ease value is not a valid easing function.

        Returns:
            Ease: validated ease value

        """
        easing_func_map = {
            "linear": easing.linear,
            "in_sine": easing.in_sine,
            "out_sine": easing.out_sine,
            "in_out_sine": easing.in_out_sine,
            "in_quad": easing.in_quad,
            "out_quad": easing.out_quad,
            "in_out_quad": easing.in_out_quad,
            "in_cubic": easing.in_cubic,
            "out_cubic": easing.out_cubic,
            "in_out_cubic": easing.in_out_cubic,
            "in_quart": easing.in_quart,
            "out_quart": easing.out_quart,
            "in_out_quart": easing.in_out_quart,
            "in_quint": easing.in_quint,
            "out_quint": easing.out_quint,
            "in_out_quint": easing.in_out_quint,
            "in_expo": easing.in_expo,
            "out_expo": easing.out_expo,
            "in_out_expo": easing.in_out_expo,
            "in_circ": easing.in_circ,
            "out_circ": easing.out_circ,
            "in_out_circ": easing.in_out_circ,
            "in_back": easing.in_back,
            "out_back": easing.out_back,
            "in_out_back": easing.in_out_back,
            "in_elastic": easing.in_elastic,
            "out_elastic": easing.out_elastic,
            "in_out_elastic": easing.in_out_elastic,
            "in_bounce": easing.in_bounce,
            "out_bounce": easing.out_bounce,
            "in_out_bounce": easing.in_out_bounce,
        }

        try:
            return easing_func_map[arg.lower()]
        except KeyError:
            msg = f"invalid ease value: '{arg}' is not a valid ease."
            raise argparse.ArgumentTypeError(msg) from None

type_parser(arg) staticmethod

Validate argument is a valid easing function.

Parameters:

Name	Type	Description	Default
arg	str	argument to validate	required

Raises:

Type	Description
ArgumentTypeError	Ease value is not a valid easing function.

Returns:

Name	Type	Description
Ease	Callable	validated ease value

Source code in terminaltexteffects/utils/argutils.py

@staticmethod
def type_parser(arg: str) -> typing.Callable:
    """Validate argument is a valid easing function.

    Args:
        arg (str): argument to validate

    Raises:
        argparse.ArgumentTypeError: Ease value is not a valid easing function.

    Returns:
        Ease: validated ease value

    """
    easing_func_map = {
        "linear": easing.linear,
        "in_sine": easing.in_sine,
        "out_sine": easing.out_sine,
        "in_out_sine": easing.in_out_sine,
        "in_quad": easing.in_quad,
        "out_quad": easing.out_quad,
        "in_out_quad": easing.in_out_quad,
        "in_cubic": easing.in_cubic,
        "out_cubic": easing.out_cubic,
        "in_out_cubic": easing.in_out_cubic,
        "in_quart": easing.in_quart,
        "out_quart": easing.out_quart,
        "in_out_quart": easing.in_out_quart,
        "in_quint": easing.in_quint,
        "out_quint": easing.out_quint,
        "in_out_quint": easing.in_out_quint,
        "in_expo": easing.in_expo,
        "out_expo": easing.out_expo,
        "in_out_expo": easing.in_out_expo,
        "in_circ": easing.in_circ,
        "out_circ": easing.out_circ,
        "in_out_circ": easing.in_out_circ,
        "in_back": easing.in_back,
        "out_back": easing.out_back,
        "in_out_back": easing.in_out_back,
        "in_elastic": easing.in_elastic,
        "out_elastic": easing.out_elastic,
        "in_out_elastic": easing.in_out_elastic,
        "in_bounce": easing.in_bounce,
        "out_bounce": easing.out_bounce,
        "in_out_bounce": easing.in_out_bounce,
    }

    try:
        return easing_func_map[arg.lower()]
    except KeyError:
        msg = f"invalid ease value: '{arg}' is not a valid ease."
        raise argparse.ArgumentTypeError(msg) from None

EasingStep

Validate argument is a valid easing step size value.

Raises:

Type	Description
ArgumentTypeError	Value is not a valid easing step size.

Source code in terminaltexteffects/utils/argutils.py

class EasingStep:
    """Validate argument is a valid easing step size value.

    Raises:
        argparse.ArgumentTypeError: Value is not a valid easing step size.

    """

    METAVAR = "0 < float(n) <= 1"

    @staticmethod
    def type_parser(arg: str) -> float:
        """Validate argument is a valid easing step size value.

        Args:
            arg (str): argument to validate

        Raises:
            argparse.ArgumentTypeError: Value is not a valid easing step size.

        Returns:
            float: validated easing step size value

        """
        try:
            f = float(arg)
        except ValueError:
            msg = f"invalid value: '{arg}' is not a valid float."
            raise argparse.ArgumentTypeError(msg) from None

        if 0 < f <= 1:
            return f
        msg = f"invalid value: '{arg}' is not a float > 0 and <= 1. Example: 0.5"
        raise argparse.ArgumentTypeError(msg)

type_parser(arg) staticmethod

Validate argument is a valid easing step size value.

Parameters:

Name	Type	Description	Default
arg	str	argument to validate	required

Raises:

Type	Description
ArgumentTypeError	Value is not a valid easing step size.

Returns:

Name	Type	Description
float	float	validated easing step size value

Source code in terminaltexteffects/utils/argutils.py

@staticmethod
def type_parser(arg: str) -> float:
    """Validate argument is a valid easing step size value.

    Args:
        arg (str): argument to validate

    Raises:
        argparse.ArgumentTypeError: Value is not a valid easing step size.

    Returns:
        float: validated easing step size value

    """
    try:
        f = float(arg)
    except ValueError:
        msg = f"invalid value: '{arg}' is not a valid float."
        raise argparse.ArgumentTypeError(msg) from None

    if 0 < f <= 1:
        return f
    msg = f"invalid value: '{arg}' is not a float > 0 and <= 1. Example: 0.5"
    raise argparse.ArgumentTypeError(msg)

GradientDirection

Validate argument is a valid gradient direction.

Raises:

Type	Description
ArgumentTypeError	Argument value is not a valid gradient direction.

Source code in terminaltexteffects/utils/argutils.py

class GradientDirection:
    """Validate argument is a valid gradient direction.

    Raises:
        argparse.ArgumentTypeError: Argument value is not a valid gradient direction.

    """

    METAVAR = "(diagonal, horizontal, vertical, radial)"

    @staticmethod
    def type_parser(arg: str) -> Gradient.Direction:
        """Validate argument is a valid gradient direction.

        Args:
            arg (str): argument to validate

        Returns:
            Gradient.Direction: validated gradient direction

        Raises:
            argparse.ArgumentTypeError: Argument value is not a valid gradient direction.

        """
        direction_map = {
            "horizontal": Gradient.Direction.HORIZONTAL,
            "vertical": Gradient.Direction.VERTICAL,
            "diagonal": Gradient.Direction.DIAGONAL,
            "radial": Gradient.Direction.RADIAL,
        }
        if arg.lower() in direction_map:
            return direction_map[arg.lower()]
        msg = (
            f"invalid gradient direction: '{arg}' is not a valid gradient direction. Choices are diagonal,"
            " horizontal, vertical, or radial."
        )
        raise argparse.ArgumentTypeError(msg)

type_parser(arg) staticmethod

Validate argument is a valid gradient direction.

Parameters:

Name	Type	Description	Default
arg	str	argument to validate	required

Returns:

Type	Description
Direction	Gradient.Direction: validated gradient direction

Raises:

Type	Description
ArgumentTypeError	Argument value is not a valid gradient direction.

Source code in terminaltexteffects/utils/argutils.py

@staticmethod
def type_parser(arg: str) -> Gradient.Direction:
    """Validate argument is a valid gradient direction.

    Args:
        arg (str): argument to validate

    Returns:
        Gradient.Direction: validated gradient direction

    Raises:
        argparse.ArgumentTypeError: Argument value is not a valid gradient direction.

    """
    direction_map = {
        "horizontal": Gradient.Direction.HORIZONTAL,
        "vertical": Gradient.Direction.VERTICAL,
        "diagonal": Gradient.Direction.DIAGONAL,
        "radial": Gradient.Direction.RADIAL,
    }
    if arg.lower() in direction_map:
        return direction_map[arg.lower()]
    msg = (
        f"invalid gradient direction: '{arg}' is not a valid gradient direction. Choices are diagonal,"
        " horizontal, vertical, or radial."
    )
    raise argparse.ArgumentTypeError(msg)

NonNegativeFloat

Validate argument is a nonnegative float. n >= 0.

Raises:

Type	Description
ArgumentTypeError	Argument value is not in range.

Source code in terminaltexteffects/utils/argutils.py

class NonNegativeFloat:
    """Validate argument is a nonnegative float. n >= 0.

    Raises:
        argparse.ArgumentTypeError: Argument value is not in range.

    """

    METAVAR = "(float >= 0)"

    @staticmethod
    def type_parser(arg: str) -> float:
        """Validate argument is a nonnegative float. n >= 0.

        Args:
            arg (str): argument to validate

        Raises:
            argparse.ArgumentTypeError: Argument value is not in range.

        Returns:
            float: validated value

        """
        try:
            float(arg)
        except ValueError:
            msg = f"invalid argument value: '{arg}' is not a valid float."
            raise argparse.ArgumentTypeError(msg) from None

        if float(arg) < 0:
            msg = f"invalid argument value: '{arg}' is out of range. Must be float >= 0."
            raise argparse.ArgumentTypeError(msg)
        return float(arg)

type_parser(arg) staticmethod

Validate argument is a nonnegative float. n >= 0.

Parameters:

Name	Type	Description	Default
arg	str	argument to validate	required

Raises:

Type	Description
ArgumentTypeError	Argument value is not in range.

Returns:

Name	Type	Description
float	float	validated value

Source code in terminaltexteffects/utils/argutils.py

@staticmethod
def type_parser(arg: str) -> float:
    """Validate argument is a nonnegative float. n >= 0.

    Args:
        arg (str): argument to validate

    Raises:
        argparse.ArgumentTypeError: Argument value is not in range.

    Returns:
        float: validated value

    """
    try:
        float(arg)
    except ValueError:
        msg = f"invalid argument value: '{arg}' is not a valid float."
        raise argparse.ArgumentTypeError(msg) from None

    if float(arg) < 0:
        msg = f"invalid argument value: '{arg}' is out of range. Must be float >= 0."
        raise argparse.ArgumentTypeError(msg)
    return float(arg)

NonNegativeInt

Validate argument is a nonnegative integer. n >= 0.

Raises:

Type	Description
ArgumentTypeError	Value is not in range.

Source code in terminaltexteffects/utils/argutils.py

class NonNegativeInt:
    """Validate argument is a nonnegative integer. n >= 0.

    Raises:
        argparse.ArgumentTypeError: Value is not in range.

    """

    METAVAR = "(int >= 0)"

    @staticmethod
    def type_parser(arg: str) -> int:
        """Validate argument is a nonnegative integer. n >= 0.

        Args:
            arg (str): argument to validate

        Raises:
            argparse.ArgumentTypeError: Value is not in range.

        Returns:
            int: validated gap value

        """
        try:
            arg_int = int(arg)

        except ValueError:
            msg = f"invalid value: '{arg}' is not a valid integer."
            raise argparse.ArgumentTypeError(msg) from None

        if arg_int < 0:
            msg = f"invalid value: '{arg}' Argument must be int >= 0."
            raise argparse.ArgumentTypeError(msg) from None
        return arg_int

type_parser(arg) staticmethod

Validate argument is a nonnegative integer. n >= 0.

Parameters:

Name	Type	Description	Default
arg	str	argument to validate	required

Raises:

Type	Description
ArgumentTypeError	Value is not in range.

Returns:

Name	Type	Description
int	int	validated gap value

Source code in terminaltexteffects/utils/argutils.py

@staticmethod
def type_parser(arg: str) -> int:
    """Validate argument is a nonnegative integer. n >= 0.

    Args:
        arg (str): argument to validate

    Raises:
        argparse.ArgumentTypeError: Value is not in range.

    Returns:
        int: validated gap value

    """
    try:
        arg_int = int(arg)

    except ValueError:
        msg = f"invalid value: '{arg}' is not a valid integer."
        raise argparse.ArgumentTypeError(msg) from None

    if arg_int < 0:
        msg = f"invalid value: '{arg}' Argument must be int >= 0."
        raise argparse.ArgumentTypeError(msg) from None
    return arg_int

NonNegativeRatio

Validate argument is a float value between zero and one.

0 <= float(n) <= 1

Raises:

Type	Description
ArgumentTypeError	Value is not in range.

Source code in terminaltexteffects/utils/argutils.py

class NonNegativeRatio:
    """Validate argument is a float value between zero and one.

    0 <= float(n) <= 1

    Raises:
        argparse.ArgumentTypeError: Value is not in range.

    """

    METAVAR = "(0 <= float(n) <= 1)"

    @staticmethod
    def type_parser(arg: str) -> float:
        """Validate argument is a float value between zero and one.

        Args:
            arg (str): argument to validate

        Raises:
            argparse.ArgumentTypeError: Value is not in range.

        Returns:
            float: validated float value

        """
        try:
            float(arg)
        except ValueError:
            msg = f"invalid value: '{arg}' is not a float or int."
            raise argparse.ArgumentTypeError(msg) from None

        if 0 <= float(arg) <= 1:
            return float(arg)
        msg = f"invalid value: '{arg}' is not a float >= 0 and <= 1. Example: 0.5"
        raise argparse.ArgumentTypeError(msg)

type_parser(arg) staticmethod

Validate argument is a float value between zero and one.

Parameters:

Name	Type	Description	Default
arg	str	argument to validate	required

Raises:

Type	Description
ArgumentTypeError	Value is not in range.

Returns:

Name	Type	Description
float	float	validated float value

Source code in terminaltexteffects/utils/argutils.py

@staticmethod
def type_parser(arg: str) -> float:
    """Validate argument is a float value between zero and one.

    Args:
        arg (str): argument to validate

    Raises:
        argparse.ArgumentTypeError: Value is not in range.

    Returns:
        float: validated float value

    """
    try:
        float(arg)
    except ValueError:
        msg = f"invalid value: '{arg}' is not a float or int."
        raise argparse.ArgumentTypeError(msg) from None

    if 0 <= float(arg) <= 1:
        return float(arg)
    msg = f"invalid value: '{arg}' is not a float >= 0 and <= 1. Example: 0.5"
    raise argparse.ArgumentTypeError(msg)

ParserSpec dataclass

Specification for a parser in the argument parser.

Source code in terminaltexteffects/utils/argutils.py

@dataclass(frozen=True)
class ParserSpec:
    """Specification for a parser in the argument parser."""

    name: str
    help: str
    description: str
    epilog: str

PositiveFloat

Validate argument is a positive float. n > 0.

Raises:

Type	Description
ArgumentTypeError	Value is not in range.

Source code in terminaltexteffects/utils/argutils.py

class PositiveFloat:
    """Validate argument is a positive float. n > 0.

    Raises:
        argparse.ArgumentTypeError: Value is not in range.

    """

    METAVAR = "(float > 0)"

    @staticmethod
    def type_parser(arg: str) -> float:
        """Validate argument is a positive float. n > 0.

        Args:
            arg (str): argument to validate

        Raises:
            argparse.ArgumentTypeError: value is not in range.

        Returns:
            float: validated positive float

        """
        try:
            float(arg)
        except ValueError:
            msg = f"invalid value: '{arg}' is not a valid float."
            raise argparse.ArgumentTypeError(msg) from None

        if float(arg) > 0:
            return float(arg)
        msg = f"invalid value: '{arg}' is not a valid value. Argument must be a float > 0."
        raise argparse.ArgumentTypeError(msg)

type_parser(arg) staticmethod

Validate argument is a positive float. n > 0.

Parameters:

Name	Type	Description	Default
arg	str	argument to validate	required

Raises:

Type	Description
ArgumentTypeError	value is not in range.

Returns:

Name	Type	Description
float	float	validated positive float

Source code in terminaltexteffects/utils/argutils.py

@staticmethod
def type_parser(arg: str) -> float:
    """Validate argument is a positive float. n > 0.

    Args:
        arg (str): argument to validate

    Raises:
        argparse.ArgumentTypeError: value is not in range.

    Returns:
        float: validated positive float

    """
    try:
        float(arg)
    except ValueError:
        msg = f"invalid value: '{arg}' is not a valid float."
        raise argparse.ArgumentTypeError(msg) from None

    if float(arg) > 0:
        return float(arg)
    msg = f"invalid value: '{arg}' is not a valid value. Argument must be a float > 0."
    raise argparse.ArgumentTypeError(msg)

PositiveFloatRange

Validate argument is a valid range of positive floats.

Float ranges are a pair of positive floats separated by a hyphen. Ex: 0.1-1.0

Raises:

Type	Description
ArgumentTypeError	Value is not a valid range of floats.

Source code in terminaltexteffects/utils/argutils.py

class PositiveFloatRange:
    """Validate argument is a valid range of positive floats.

    Float ranges are a pair of positive floats separated by a hyphen. Ex: 0.1-1.0

    Raises:
        argparse.ArgumentTypeError: Value is not a valid range of floats.

    """

    METAVAR = "(hyphen separated float range e.g. '0.25-0.5')"

    @staticmethod
    def type_parser(arg: str) -> tuple[float, float]:
        """Validate argument is a valid range of positive floats.

        Args:
            arg (str): argument to validate

        Returns:
            tuple[float,float]: validated range

        """
        try:
            start, end = map(float, arg.split("-"))
            if start > end:
                msg = f"invalid range: '{arg}' is not a valid range of floats. Must be start <= end. Ex: 0.1-1.0"
                raise argparse.ArgumentTypeError(
                    msg,
                )
            if start == 0 or end == 0:
                msg = f"invalid range: '{arg}' is not a valid range of floats. Must be start > 0. Ex: 0.1-1.0"
                raise argparse.ArgumentTypeError(
                    msg,
                )

        except ValueError:
            msg = f"invalid range: '{arg}' is not a valid range. Must be start-end. Ex: 0.1-1.0"
            raise argparse.ArgumentTypeError(msg) from None

        else:
            return start, end

type_parser(arg) staticmethod

Validate argument is a valid range of positive floats.

Parameters:

Name	Type	Description	Default
arg	str	argument to validate	required

Returns:

Type	Description
tuple[float, float]	tuple[float,float]: validated range

Source code in terminaltexteffects/utils/argutils.py

@staticmethod
def type_parser(arg: str) -> tuple[float, float]:
    """Validate argument is a valid range of positive floats.

    Args:
        arg (str): argument to validate

    Returns:
        tuple[float,float]: validated range

    """
    try:
        start, end = map(float, arg.split("-"))
        if start > end:
            msg = f"invalid range: '{arg}' is not a valid range of floats. Must be start <= end. Ex: 0.1-1.0"
            raise argparse.ArgumentTypeError(
                msg,
            )
        if start == 0 or end == 0:
            msg = f"invalid range: '{arg}' is not a valid range of floats. Must be start > 0. Ex: 0.1-1.0"
            raise argparse.ArgumentTypeError(
                msg,
            )

    except ValueError:
        msg = f"invalid range: '{arg}' is not a valid range. Must be start-end. Ex: 0.1-1.0"
        raise argparse.ArgumentTypeError(msg) from None

    else:
        return start, end

PositiveInt

Validate argument is a positive integer. n > 0.

int(n) > 0

Raises:

Type	Description
ArgumentTypeError	Value is not a positive integer.

Source code in terminaltexteffects/utils/argutils.py

class PositiveInt:
    """Validate argument is a positive integer. n > 0.

    int(n) > 0

    Raises:
        argparse.ArgumentTypeError: Value is not a positive integer.

    """

    METAVAR = "(int > 0)"

    @staticmethod
    def type_parser(arg: str) -> int:
        """Validate argument is a positive integer. n > 0.

        Args:
            arg (str): argument to validate

        Returns:
            int: validated positive integer

        """
        try:
            arg_int = int(arg)

        except ValueError:
            msg = f"invalid value: '{arg}' is not a valid integer."
            raise argparse.ArgumentTypeError(msg) from None

        if arg_int > 0:
            return arg_int
        msg = f"invalid value: '{arg}' is not a valid value. Argument must be an integer > 0."
        raise argparse.ArgumentTypeError(msg)

type_parser(arg) staticmethod

Validate argument is a positive integer. n > 0.

Parameters:

Name	Type	Description	Default
arg	str	argument to validate	required

Returns:

Name	Type	Description
int	int	validated positive integer

Source code in terminaltexteffects/utils/argutils.py

@staticmethod
def type_parser(arg: str) -> int:
    """Validate argument is a positive integer. n > 0.

    Args:
        arg (str): argument to validate

    Returns:
        int: validated positive integer

    """
    try:
        arg_int = int(arg)

    except ValueError:
        msg = f"invalid value: '{arg}' is not a valid integer."
        raise argparse.ArgumentTypeError(msg) from None

    if arg_int > 0:
        return arg_int
    msg = f"invalid value: '{arg}' is not a valid value. Argument must be an integer > 0."
    raise argparse.ArgumentTypeError(msg)

PositiveIntRange

Validate argument is a valid range of integers n > 0.

Positive integer ranges are a pair of integers separated by a hyphen. Ex: 1-10

Example

'1-10' is a valid input.

Raises:

Type	Description
ArgumentTypeError	Value is not a valid range of positive integers.

Source code in terminaltexteffects/utils/argutils.py

class PositiveIntRange:
    """Validate argument is a valid range of integers n > 0.

    Positive integer ranges are a pair of integers separated by a hyphen. Ex: 1-10

    Example:
        '1-10' is a valid input.

    Raises:
        argparse.ArgumentTypeError: Value is not a valid range of positive integers.

    """

    METAVAR = "(hyphen separated positive int range e.g. '1-10')"

    @staticmethod
    def type_parser(arg: str) -> tuple[int, int]:
        """Validate argument is a valid range of integers n > 0.

        Args:
            arg (str): argument to validate

        Returns:
            tuple[int,int]: validated range

        """
        try:
            start, end = map(int, arg.split("-"))
            if start <= 0:
                msg = f"invalid range: '{arg}' is not a valid range of positive ints. Must be start > 0. Ex: 1-10"
                raise argparse.ArgumentTypeError(
                    msg,
                )
            if start > end:
                msg = f"invalid range: '{arg}' is not a valid range of positive ints. Must be start <= end. Ex: 1-10"
                raise argparse.ArgumentTypeError(
                    msg,
                )

        except ValueError:
            msg = f"invalid range: '{arg}' is not a valid range of positive ints. Must be start-end. Ex: 1-10"
            raise argparse.ArgumentTypeError(
                msg,
            ) from None
        else:
            return start, end

type_parser(arg) staticmethod

Validate argument is a valid range of integers n > 0.

Parameters:

Name	Type	Description	Default
arg	str	argument to validate	required

Returns:

Type	Description
tuple[int, int]	tuple[int,int]: validated range

Source code in terminaltexteffects/utils/argutils.py

@staticmethod
def type_parser(arg: str) -> tuple[int, int]:
    """Validate argument is a valid range of integers n > 0.

    Args:
        arg (str): argument to validate

    Returns:
        tuple[int,int]: validated range

    """
    try:
        start, end = map(int, arg.split("-"))
        if start <= 0:
            msg = f"invalid range: '{arg}' is not a valid range of positive ints. Must be start > 0. Ex: 1-10"
            raise argparse.ArgumentTypeError(
                msg,
            )
        if start > end:
            msg = f"invalid range: '{arg}' is not a valid range of positive ints. Must be start <= end. Ex: 1-10"
            raise argparse.ArgumentTypeError(
                msg,
            )

    except ValueError:
        msg = f"invalid range: '{arg}' is not a valid range of positive ints. Must be start-end. Ex: 1-10"
        raise argparse.ArgumentTypeError(
            msg,
        ) from None
    else:
        return start, end

PositiveRatio

Validate argument is a positive float.

0 < float(n) <= 1

Raises:

Type	Description
ArgumentTypeError	Value is not in range.

Source code in terminaltexteffects/utils/argutils.py

class PositiveRatio:
    """Validate argument is a positive float.

    0 < float(n) <= 1

    Raises:
        argparse.ArgumentTypeError: Value is not in range.

    """

    METAVAR = "(0 < float(n) <= 1)"

    @staticmethod
    def type_parser(arg: str) -> float:
        """Validate argument is a positive float.

        Args:
            arg (str): argument to validate

        Raises:
            argparse.ArgumentTypeError: Value is not in range.

        Returns:
            float: validated float value

        """
        try:
            float(arg)
        except ValueError:
            msg = f"invalid value: '{arg}' is not a float or int."
            raise argparse.ArgumentTypeError(msg) from None

        if 0 < float(arg) <= 1:
            return float(arg)
        msg = f"invalid value: '{arg}' must be 0 < n <=1. Example: 0.5"
        raise argparse.ArgumentTypeError(msg)

type_parser(arg) staticmethod

Validate argument is a positive float.

Parameters:

Name	Type	Description	Default
arg	str	argument to validate	required

Raises:

Type	Description
ArgumentTypeError	Value is not in range.

Returns:

Name	Type	Description
float	float	validated float value

Source code in terminaltexteffects/utils/argutils.py

@staticmethod
def type_parser(arg: str) -> float:
    """Validate argument is a positive float.

    Args:
        arg (str): argument to validate

    Raises:
        argparse.ArgumentTypeError: Value is not in range.

    Returns:
        float: validated float value

    """
    try:
        float(arg)
    except ValueError:
        msg = f"invalid value: '{arg}' is not a float or int."
        raise argparse.ArgumentTypeError(msg) from None

    if 0 < float(arg) <= 1:
        return float(arg)
    msg = f"invalid value: '{arg}' must be 0 < n <=1. Example: 0.5"
    raise argparse.ArgumentTypeError(msg)

Symbol

Validate argument is a single ASCII/UTF-8 character.

Raises:

Type	Description
ArgumentTypeError	Value is not a valid symbol.

Source code in terminaltexteffects/utils/argutils.py

class Symbol:
    """Validate argument is a single ASCII/UTF-8 character.

    Raises:
        argparse.ArgumentTypeError: Value is not a valid symbol.

    """

    METAVAR = "(ASCII/UTF-8 character)"

    @staticmethod
    def type_parser(arg: str) -> str:
        """Validate argument is a valid symbol.

        Args:
            arg (str): argument to validate

        Returns:
            str: validated symbol

        """
        if len(arg) == 1 and arg.isprintable():
            return arg
        msg = f"invalid symbol: '{arg}' is not a valid symbol. Must be a single ASCII/UTF-8 character."
        raise argparse.ArgumentTypeError(msg)

type_parser(arg) staticmethod

Validate argument is a valid symbol.

Parameters:

Name	Type	Description	Default
arg	str	argument to validate	required

Returns:

Name	Type	Description
str	str	validated symbol

Source code in terminaltexteffects/utils/argutils.py

@staticmethod
def type_parser(arg: str) -> str:
    """Validate argument is a valid symbol.

    Args:
        arg (str): argument to validate

    Returns:
        str: validated symbol

    """
    if len(arg) == 1 and arg.isprintable():
        return arg
    msg = f"invalid symbol: '{arg}' is not a valid symbol. Must be a single ASCII/UTF-8 character."
    raise argparse.ArgumentTypeError(msg)

TerminalDimension

Validate argument is a valid terminal dimension.

A Terminal Dimension is an integer >= 0.

Raises:

Type	Description
ArgumentTypeError	Value is not a valid terminal dimension.

Source code in terminaltexteffects/utils/argutils.py

class TerminalDimension:
    """Validate argument is a valid terminal dimension.

    A Terminal Dimension is an integer >= 0.

    Raises:
        argparse.ArgumentTypeError: Value is not a valid terminal dimension.

    """

    METAVAR = "int >= 0"

    @staticmethod
    def type_parser(arg: str) -> int:
        """Validate argument is a valid terminal dimension.

        Args:
            arg (str): argument to validate

        Returns:
            int: validated terminal dimension

        """
        try:
            dimension = int(arg)
            if dimension < 0:
                msg = f"invalid terminal dimensions: '{arg}' is not a valid terminal dimension. Must be >= 0."
                raise argparse.ArgumentTypeError(msg)

        except ValueError:
            msg = f"invalid terminal dimensions: '{arg}' is not a valid terminal dimension. Must be >= 0."
            raise argparse.ArgumentTypeError(msg) from None

        else:
            return dimension

type_parser(arg) staticmethod

Validate argument is a valid terminal dimension.

Parameters:

Name	Type	Description	Default
arg	str	argument to validate	required

Returns:

Name	Type	Description
int	int	validated terminal dimension

Source code in terminaltexteffects/utils/argutils.py

@staticmethod
def type_parser(arg: str) -> int:
    """Validate argument is a valid terminal dimension.

    Args:
        arg (str): argument to validate

    Returns:
        int: validated terminal dimension

    """
    try:
        dimension = int(arg)
        if dimension < 0:
            msg = f"invalid terminal dimensions: '{arg}' is not a valid terminal dimension. Must be >= 0."
            raise argparse.ArgumentTypeError(msg)

    except ValueError:
        msg = f"invalid terminal dimensions: '{arg}' is not a valid terminal dimension. Must be >= 0."
        raise argparse.ArgumentTypeError(msg) from None

    else:
        return dimension

TupleAction

Bases: Action

Custom action to convert a list of values into a tuple.

Used for arguments which utilize the nargs argument to specify multiple values.

Source code in terminaltexteffects/utils/argutils.py

class TupleAction(argparse.Action):
    """Custom action to convert a list of values into a tuple.

    Used for arguments which utilize the `nargs` argument to
    specify multiple values.
    """

    def __call__(
        self,
        _: argparse.ArgumentParser,
        namespace: argparse.Namespace,
        values: typing.Sequence[typing.Any] | None,
        __: str | None = None,
    ) -> None:
        """Convert a list of values into a tuple."""
        if values is None:
            setattr(namespace, self.dest, ())
            return
        setattr(namespace, self.dest, tuple(values))

__call__(_, namespace, values, __=None)

Convert a list of values into a tuple.

Source code in terminaltexteffects/utils/argutils.py

def __call__(
    self,
    _: argparse.ArgumentParser,
    namespace: argparse.Namespace,
    values: typing.Sequence[typing.Any] | None,
    __: str | None = None,
) -> None:
    """Convert a list of values into a tuple."""
    if values is None:
        setattr(namespace, self.dest, ())
        return
    setattr(namespace, self.dest, tuple(values))

Example Usage

The following example demonstrates using the PositiveFloat class to provide a type_parser and metavar to the RandomSequenceConfig.speed argument. This will validate that the argument passed as --speed is a float > 0.

class RandomSequenceConfig(ArgsDataClass):
    speed: float = ArgField(
        cmd_name=["--speed"],
        type_parser=argutils.PositiveFloat.type_parser,
        default=0.004,
        metavar=argutils.PositiveFloat.METAVAR,
        help="Speed of the animation as a percentage of the total number of characters to reveal in each tick.",
    )  # type: ignore[assignment]