Numeric Module

Custom numeric input handlers for Parameters

author:

Doug Skrypa

class cli_command_parser.inputs.numeric.NumericInput(fix_default: bool | Any = True)[source]

Bases: _FixedInputType[NT], ABC

class cli_command_parser.inputs.numeric.Range(range: range | int | Sequence[int], snap: bool | Any = False, type: Callable[[str | float | int], NT] = None, fix_default: bool | Any = True)[source]

Bases: _RangeInput[NT]

A range of integers that uses the builtin range. If a range object is passed to a Parameter as the type= value, it will automatically be wrapped by this class.

Parameters:

  • range – A range object

  • snap – If True and a provided value is outside the allowed range, snap to the nearest bound. The min or max of the provided range (not necessarily the start/stop values) will be used, depending on which one the provided value is closer to.

  • type – Callable that returns a numeric type, to be used on parsed values before validating whether they are in the allowed range. Defaults to int.

  • fix_default – Whether default values should be normalized using fix_default().

snap: bool
range: range | None
type

alias of int

__call__(value: str) → NT[source]
class cli_command_parser.inputs.numeric.NumRange(type: Callable[[str | float | int], NT] = None, snap: bool | Any = False, *, min: NT | None = None, max: NT | None = None, include_min: bool | Any = True, include_max: bool | Any = False, fix_default: bool | Any = True)[source]

Bases: RangeMixin, _RangeInput[NT]

A range of integers or floats, optionally only bounded on one side.

By default, the min and max behave like the builtin range - the min is inclusive, and the max is exclusive.

Parameters:

  • type – The type for values, or any callable that returns an int/float

  • snap – If True and a provided value is outside the allowed range, snap to the nearest bound. Respects inclusivity/exclusivity of the bound. Not supported for floats since there is not an obviously correct behavior for handling them in this context.

  • min – The minimum allowed value, or None to have no lower bound

  • max – The maximum allowed value, or None to have no upper bound

  • include_min – Whether the minimum is inclusive (default: True)

  • include_max – Whether the maximum is inclusive (default: False)

  • fix_default – Whether default values should be normalized using fix_default().

type
snap: bool
min
max
include_min
include_max
handle_invalid(bound: NT | None, inclusive: bool, snap_dir: int) → NT | None[source]

Handle calculating / returning a snap value or raise an exception if snapping to the bound is not allowed.

May be overridden in a subclass to support snapping for float values or other behavior.

Parameters:

  • bound – The bound (min or max) that was violated

  • inclusive – True if the bound is inclusive, False if it is exclusive

  • snap_dir – The direction to adjust the bound if it is exclusive as +1 or -1

Returns:

The snap value if snap is True, otherwise a ValueError is raised

__call__(value: str) → NT[source]
class cli_command_parser.inputs.numeric.Bytes(base: Literal[2, 10] = 10, *, short: bool | Any = True, fractions: bool | Any = False, negative: bool | Any = False, fix_default: bool | Any = True)[source]

Bases: NumericInput[NT]

A byte count/size.

Types of user inputs that are accepted:

  • Simple integer representing an exact byte count

  • Number with a unit (KB, MiB, etc.), which will result in the processed value being the raw byte count after scaling based on the provided unit

Base:

Whether 2-character units (MB, GB, etc.) are treated as base 2 (historical interpretation) or base 10 (the default) (following the International System of Units (SI) definition). Regardless of the base specified here, user-provided units that explicitly use an i to indicate binary (MiB, GiB, etc.) will always be treated as base 2.

Short:

Whether single-letter units (other than B, which is always valid) are accepted (default: True). When accepted, they use the base parameter to determine which base to use.

Fractions:

Whether fractional values are allowed (e.g., 1.2 MB). By default, only integers / whole numbers are accepted.

Negative:

Whether negative numeric values are accepted.

base
short
fractions
negative
classmethod is_valid_type(value: str) → bool[source]

Called during parsing when ParamAction.would_accept() is called to determine if the value would be accepted later for processing / conversion when called.

Parameters:

value – The parsed argument to validate

Returns:

True if this input would accept it for processing later (where it may still be rejected), False if it should be rejected before attempting to process / convert / store it.

format_metavar(choice_delim: str = ',', sort_choices: bool = False) → str[source]
__call__(value: str) → NT[source]