API Reference¶

Dykes is a tiny declarative argument parsing library.

The basic usage is to define a typed struct and pass that to dykes.processing.parse_args().

The public namespace includes parse_args(), build_parser(), and the various types for declaring various argparse options.

Warning

The API documentation is a complete description of all modules and members. If you’re using dykes to build a piece of software, this page describes the public API. Other pages under this heading contain information aimed at those developing dykes itself.

dykes.processing.parse_args(application_struct: type[ArgsType], *, args: list | None = None, development_mode: bool = False, prog: str | None = None) → ArgsType¶

Process arguments and conform them to an input type.

Supports dataclasses and NamedTuples.

Sample use:

from dataclasses import dataclass
from pathlib import Path

from dykes import parse_args, Count

@dataclass
class Application:
    input: Path
    dry_run: bool
    verbosity: dykes.Count

args = parse_args(Application)
print(args)

You can provide arguments just like parser.parse_args by supplying args=[…]

Example:

args = parse_args(Application, args=["some", "arguments"])

Activate development mode with development_mode=True:

Example:

args = parse_args(Application, development_mode=True)

Some error messages will change in development mode.

dykes.processing.build_parser(application_definition: type, prog: str | None = None) → ArgumentParser¶

Argument parser options.¶

All members of this module are exported to the dykes namespace, allowing you to reference them as dykes.Action instead of dykes.options.Action

The basic method of applying an option to your type is via the typing.Annotated type. Dykes will only allow one copy of each type per field. Dykes matches annotations by type and ignores annotations it does not support.

Custom help strings can be provided to Annotated as string literals, they will be displayed in the argparse generated help.

class dykes.options.Action(*values)¶

Actions for use with argparse.ArgumentParser.add_argument().

See https://docs.python.org/3/library/argparse.html#action for what each does.

Can be used directly with argparse:

parser = argparse.ArgumentParser
parser.add_argument("file_path", type=pathlib.Path, action=simple_parser.Action.STORE)

You can use an Action instance to tell dykes to change the default action for your option.

@dataclass
class Arguments:
    dry_run: Annotated[bool, Action.STORE_TRUE] = False

Hint

This sample is equivalent to using dykes.StoreTrue and that should be preferred.

APPEND = 'append'¶

APPEND_CONST = 'append_const'¶

COUNT = 'count'¶

EXTEND = 'extend'¶

HELP = 'help'¶

STORE = 'store'¶

STORE_CONST = 'store_const'¶

STORE_FALSE = 'store_false'¶

STORE_TRUE = 'store_true'¶

VERSION = 'version'¶

class dykes.options.Flags(*args: str)¶

Used to declare custom flag values for your command line option.

By default, Dykes will convert any kind of optional parameter into a flag using the name of the parameter. This gives you finer control over what the flags should be.

Use like:

@dataclasses
class CustomFlag:
    noisiness: typing.Annotated[dykes.Count, dykes.Flags("-v", "--verbose")]

class dykes.options.NArgs(value: int | Literal['*', '+', '?'])¶

Declare the number of arguments your option requires.

Example:

@dataclass
class TakeMany:
    paths: Annotated[Path, NArgs('*')]

type dykes.options.Count = Annotated[int, Action.COUNT]¶

A type alias for the COUNT action.

Use like:

@dataclass
class Counter:
    count: dykes.Count

type dykes.options.StoreFalse = Annotated[bool, Action.STORE_FALSE]¶

A type alias for using the STORE_FALSE action.

Use like:

@dataclass
class CommitOptional:
    commit: StoreFalse

type dykes.options.StoreTrue = Annotated[bool, Action.STORE_TRUE]¶

A type alias for using the STORE_TRUE action.

Use like:

@dataclass
class DryRun:
    dry_run: StoreTrue