Command Line Interface

aidoc:

is a click application. This module provides all of our useful click

extensions. It also provides our Display adapters such that we can have rich command-lines but also easily pipe results into other Unix functions. We even have a Display to return tables as Pandas data frames to utilise in Jupyter notebooks if you desire.

class lbn.aidoc.cmd.BannerHelpCommand(name: str | None, context_settings: MutableMapping[str, Any] | None = None, callback: Callable[[...], Any] | None = None, params: list[Parameter] | None = None, help: str | None = None, epilog: str | None = None, short_help: str | None = None, options_metavar: str | None = '[OPTIONS]', add_help_option: bool = True, no_args_is_help: bool = False, hidden: bool = False, deprecated: bool | str = False)

Bases: Command

get_help(ctx)

Formats the help into a string and returns it.

Calls format_help() internally.

class lbn.aidoc.cmd.BannerHelpGroup(help_headers_color: str | None = None, help_options_color: str | None = None, help_options_custom_colors: Mapping[str, str] | None = None, *args: Any, **kwargs: Any)

Bases: HelpColorsGroup

format_help(ctx, formatter)

Writes the help into the formatter if it exists.

This is a low-level method called by get_help().

This calls the following methods:

  • format_usage()

  • format_help_text()

  • format_options()

  • format_epilog()

lbn.aidoc.cmd.DATE_TOKENS(ctx, param, value)

Official Click Parameter Callback: Evaluates the raw terminal text stream, strictly blocks empty entries with a BadParameter exception, and triggers coerce.

class lbn.aidoc.cmd.EmailParamType

Bases: ParamType

convert(value, param, ctx)

Convert the value to the correct type. This is not called if the value is None (the missing value).

This must accept string values from the command line, as well as values that are already the correct type. It may also convert other compatible types.

The param and ctx arguments may be None in certain situations, such as when converting prompt input.

If the value cannot be converted, call fail() with a descriptive message.

Parameters:

  • value – The value to convert.

  • param – The parameter that is using this type to convert its value. May be None.

  • ctx – The current context that arrived at this value. May be None.

name: str = 'email'

the descriptive name of this type

lbn.aidoc.cmd.FLATTEN_ID_RANGE(ctx, param, value)

Click Callback: Flattens the nargs=-1 tuple transparently.

class lbn.aidoc.cmd.HumanisedDateTimeType(prefer_future: bool = False)

Bases: ParamType

type any vaguely date

coerce(tokens)

The Pure Coercion Engine: Accepts a token collection, unifies them, and uses dateparser to guarantee a single datetime object.

convert(value, param, ctx)

DUMMY PASS-THROUGH: Strips quotes and returns the raw string piece. Never executes dateparser or returns a datetime object.

name: str = 'human_datetime'

the descriptive name of this type

class lbn.aidoc.cmd.IdRangeParamType

Bases: ParamType

convert(value, param, ctx)

Processes raw single-string tokens into standard list fragments.

name: str = 'id_range'

the descriptive name of this type

value_from_envvar(rv)

Native Click value pipeline hook. Flattens multi-token data streams cleanly using itertools right before the final return.

class lbn.aidoc.cmd.PhoneNumberParamType(default_region='NZ')

Bases: ParamType

convert(value, param, ctx)

Convert the value to the correct type. This is not called if the value is None (the missing value).

This must accept string values from the command line, as well as values that are already the correct type. It may also convert other compatible types.

The param and ctx arguments may be None in certain situations, such as when converting prompt input.

If the value cannot be converted, call fail() with a descriptive message.

Parameters:

  • value – The value to convert.

  • param – The parameter that is using this type to convert its value. May be None.

  • ctx – The current context that arrived at this value. May be None.

name: str = 'phone_number'

the descriptive name of this type

class lbn.aidoc.cmd.TimeZoneParamType

Bases: ParamType

convert(value, param, ctx)

Convert the value to the correct type. This is not called if the value is None (the missing value).

This must accept string values from the command line, as well as values that are already the correct type. It may also convert other compatible types.

The param and ctx arguments may be None in certain situations, such as when converting prompt input.

If the value cannot be converted, call fail() with a descriptive message.

Parameters:

  • value – The value to convert.

  • param – The parameter that is using this type to convert its value. May be None.

  • ctx – The current context that arrived at this value. May be None.

name: str = 'timezone'

the descriptive name of this type

lbn.aidoc.cmd.banner(ai_colour='blue', doc_colour='white', version_colour='red', version='1.3.9')
lbn.aidoc.cmd.main()
lbn.aidoc.cmd.register_all()

Surgical Discovery: High-visibility for compiler errors. Borked pluggy modules scream; working ones plug in seamlessly.