TSArP

Type-Safe Argument Parser

Copyright 2026 Ian Pilcher <arequipeno@gmail.com>

class Schema

Abstract base class for top-level and subcommand schemas.

The schema for a top-level or subcommand parser is created by defining a subclass of this class.

For example:

class StartCmdSchema(Schema, description="Start the server"):
    foreground: bool = flag(...)

class StopCmdSchema(Schema, description="Stop the server"):
    force: bool = flag(...)

class ServerCtlSchema(Schema, description="Control the server"):
    verbose: bool = flag(...)
    log_dest_grp = group(title="Log destination", ...)
    log_dest_mx = mxgroup(group="log_dest_grp", ...)
    stderr: bool = flag(group="log_dest_mx", ...)
    syslog: bool = flag(group="log_dest_mx", ...)
    file: str = opt(group="log_dest_mx", ...)
    cmd: str | None = subcommands(...)
    start: StartCmdSchema | None = subcmd(StartCmdSchema, ...)
    stop: StopCmdSchema | None = subcmd(StopCmdSchema, ...)

Class Parameters:

• custom_types (Iterable[Type[Any]]) – Custom types to be registered with the schema’s parsers. (See Registering custom types or actions.)

• kwargs (Unpack[ArgParserKwargs]) – Keyword arguments that will be passed to the schema’s parser constructors. (A parser constructor is either ArgumentParser() or add_parser().

group(title=None, description=None)

Creates an argument group descriptor.

Important

This function should only be called inside a Schema subclass definition.

Parameters:

• title (str | None) – The argument group title.

• description (str | None) – The argument group description.

Returns:

A new argument group descriptor.

Return type:

ArgumentGroup

mxgroup(*, required=False, group=None)

Creates a mutually exclusive group descriptor.

Important

This function should only be called inside a Schema subclass definition.

Parameters:

• required (bool) – If True, one of the options in the group must be provided.

• group (str | None) – Name of the argument group to which the mutually exclusive group will be added. (If None, the mutually exclusive group will be added directly to the top-level or subcommand parser.)

Returns:

A new mutually exclusive group descriptor.

Return type:

MXGroup

param[T](*, default=NoDefaultType.NO_DEFAULT, type=None, choices=None, group=None, help=None, metavar=None, deprecated=False)

Define a parameter (positional argument).

Important

This function should only be called inside a Schema subclass definition.

Note

• When the type argument is not provided, its value can sometimes be inferred from the parameter’s type hint. This is only possible if the type hint is either a single concrete type (int, float, ipaddress.IPv4Address, etc.) or a union containing a single concrete type and a sentinel type. NoneType (None) and EllipsisType (...) are recognized as sentinel types.

  If the type hint does not conform to this requirement, the type argument is required.

• A parameter’s destination (the name of its targeted Schema subclass attribute) is used verbatim as its display name. I.e., no underscore-to-hyphen replacement is performed. The display name can be overridden by setting the parameter’s metavar.

  (In contrast, the names of flags and options are constructed by replacing non-leading underscores in their destination with hyphens and prepending --. For example, debug_level becomes --debug-level.)

Parameters:

• default (T | NoDefaultType) – See https://docs.python.org/3/library/argparse.html#default.

• type (Callable[[str], T] | Type | None) – See https://docs.python.org/3/library/argparse.html#type. (As noted, this can be inferred from the argument’s type hint in most cases.)

• choices (Iterable | None) – See https://docs.python.org/3/library/argparse.html#choices.

• group (str | None) – The name of the argument group to which the parameter will be added (if any).

• help (str | None) – See https://docs.python.org/3/library/argparse.html#help.

• metavar (str | None) – See https://docs.python.org/3/library/argparse.html#metavar.

• deprecated (bool) – See https://docs.python.org/3/library/argparse.html#deprecated.

Returns:

An opaque descriptor that represents the parameter.

Return type:

T

Note

The stated return type (T) represents the type of the target attribute in a parsed schema instance, not the runtime type of the descriptor.

opt[T](*, default=NoDefaultType.NO_DEFAULT, type=None, choices=None, group=None, short=None, help=None, metavar=None, deprecated=False)

Define an option (a non-positional argument that takes a value).

Important

This function should only be called inside a Schema subclass definition.

Note

When the type argument is not provided, its value can sometimes be inferred from the option’s type hint. This is only possible if the type hint is either a single concrete type (int, float, ipaddress.IPv4Address, etc.) or a union containing a single concrete type and a sentinel type. NoneType (None) and EllipsisType (...) are recognized as sentinel types.

If the type hint does not conform to this requirement, the type argument is required.

Parameters:

• default (T | NoDefaultType) – See https://docs.python.org/3/library/argparse.html#default.

• type (Callable[[str], T] | Type | None) – See https://docs.python.org/3/library/argparse.html#type. (As noted, this can be inferred from the option’s type hint in most cases.)

• choices (Iterable | None) – See https://docs.python.org/3/library/argparse.html#choices.

• group (str | None) – The name of the argument group to which the option will be added (if any).

• short (str | None) – The short form of the option name (a hyphen followed by a single alphanumeric character).

• help (str | None) – See https://docs.python.org/3/library/argparse.html#help.

• metavar (str | None) – See https://docs.python.org/3/library/argparse.html#metavar.

• deprecated (bool) – See https://docs.python.org/3/library/argparse.html#deprecated.

Returns:

An opaque descriptor that represents the option.

Return type:

T

Note

The stated return type (T) represents the type of the target attribute in a parsed schema instance, not the runtime type of the descriptor.

flag(*, group=None, short=None, help=None, deprecated=False)

Define a boolean flag.

Important

This function should only be called inside a Schema subclass definition.

Parameters:

• group (str | None) – The name of the argument group to which the flag will be added (if any).

• short (str | None) – The short form of the flag name (a hyphen followed by a single alphanumeric character).

• help (str | None) – See https://docs.python.org/3/library/argparse.html#help.

• deprecated (bool) – See https://docs.python.org/3/library/argparse.html#deprecated.

Returns:

An opaque descriptor that represents the flag.

Return type:

bool

Note

The stated return type (bool) represents the type of the target attribute in a parsed schema instance, not the runtime type of the descriptor.

subcommands(**kwargs)

Enable subcommands in a schema.

Assigning the result of this function to an attribute designates that attribute as the destination, which will hold the name of the chosen subcommand (or None).

Important

This function should only be called inside a Schema subclass definition, and it can only be called once per schema.

Parameters:

kwargs (Unpack[AddSubparsersKwargs]) – Arguments that will be passed to add_subparsers().

Returns:

An opaque descriptor that represents the schema’s subcommand registry.

Return type:

str | None

Note

The stated return type (str | None) represents the type of the target attribute in a parsed schema instance, not the runtime type of the descriptor.

subcmd[T](schema_cls)

Use a schema as a subcommand.

Important

This function should only be called inside a Schema subclass definition.

Parameters:

schema_cls (type[T]) – A schema (a subclass of Schema) to be used as a subcommand.

Returns:

An opaque descriptor that represents the schema.

Return type:

T | None

Note

The stated return type (T | None) represents the type of the target attribute in a parsed schema instance, not the runtime type of the descriptor.

parse[T](schema_cls, args=None)

Parse a command line with a schema.

Parameters:

• schema_cls (type[T]) – A schema (a subclass of Schema) to be used as a top-level parser.

• args (Sequence[str] | None) – The command-line arguments to parse. If None, sys.argv is parsed.

Returns:

An instance of schema_cls, with its attributes set to the parsed values.

Return type:

T

class Type[T](name, factory)

A custom argument type.

Instances are passed in the custom_types parameter of a Schema subclass definition and are registered via argparse.ArgumentParser.register().

See also

• https://docs.python.org/3/library/argparse.html#registering-custom-types-or-actions

Return type:

Self

name: str

The name under which the type is registered with the schema.

Passed as the value argument to register() and used as the type keyword argument to add_argument().

factory: Callable[[str], T]

A callable that converts a command-line string to the desired type.

Passed as the object argument to register().

class ArgParserKwargs

Keyword arguments passed to the argparse.ArgumentParser constructor.

See also

• https://docs.python.org/3/library/argparse.html#argumentparser-objects

prog: str

See https://docs.python.org/3/library/argparse.html#prog.

usage: str

See https://docs.python.org/3/library/argparse.html#usage.

description: str

See https://docs.python.org/3/library/argparse.html#description.

epilog: str

See https://docs.python.org/3/library/argparse.html#epilog.

formatter_class: type[HelpFormatter]

See https://docs.python.org/3/library/argparse.html#formatter-class.

fromfile_prefix_chars: str

See https://docs.python.org/3/library/argparse.html#fromfile-prefix-chars.

add_help: bool

See https://docs.python.org/3/library/argparse.html#add-help.

allow_abbrev: bool

See https://docs.python.org/3/library/argparse.html#allow-abbrev.

exit_on_error: bool

See https://docs.python.org/3/library/argparse.html#exit-on-error.

suggest_on_error: bool

See https://docs.python.org/3/library/argparse.html#suggest-on-error.

color: bool

See https://docs.python.org/3/library/argparse.html#color.

class AddSubparsersKwargs

Keyword arguments passed to the argparse add_subparsers() method.

See also

• https://docs.python.org/3/library/argparse.html#argparse.ArgumentParser.add_subparsers

title: str

See https://docs.python.org/3/library/argparse.html#argparse.ArgumentParser.add_subparsers.

description: str

See https://docs.python.org/3/library/argparse.html#argparse.ArgumentParser.add_subparsers.

prog: str

See https://docs.python.org/3/library/argparse.html#argparse.ArgumentParser.add_subparsers.

required: bool

See https://docs.python.org/3/library/argparse.html#argparse.ArgumentParser.add_subparsers.

help: str

See https://docs.python.org/3/library/argparse.html#argparse.ArgumentParser.add_subparsers.

metavar: str

See https://docs.python.org/3/library/argparse.html#argparse.ArgumentParser.add_subparsers.

class ArgumentGroup

An opaque descriptor that describes an argument group.

See also

• https://docs.python.org/3/library/argparse.html#argument-groups

• group()

class MXGroup

An opaque descriptor that describes a mutually exclusive group.

See also

• https://docs.python.org/3/library/argparse.html#mutual-exclusion

• mxgroup()

class NoDefaultType(*values)

A singleton sentinel type, used to signify that an argument has no default value.

NO_DEFAULT = 'NO_DEFAULT'

The NoDefaultType singleton value.