derivepassphrase._internals.cli_machinery ¶

Command-line machinery for derivepassphrase.

Warning

Non-public module (implementation detail), provided for didactical and educational purposes only. Subject to change without notice, including removal.

ClickEchoStderrHandler ¶

Bases: Handler

A logging.Handler for click applications.

Outputs log messages to sys.stderr via click.echo.

emit ¶

emit(record: LogRecord) -> None

Emit a log record.

Format the log record, then emit it via click.echo to sys.stderr.

CLIofPackageFormatter ¶

CLIofPackageFormatter(
    *,
    prog_name: str = PROG_NAME,
    package_name: str | None = None
)

Bases: Formatter

A logging.LogRecord formatter for the CLI of a Python package.

Assuming a package PKG and loggers within the same hierarchy PKG, format all log records from that hierarchy for proper user feedback on the console. Intended for use with click and when PKG provides a command-line tool PKG and when logs from that package should show up as output of the command-line tool.

Essentially, this prepends certain short strings to the log message lines to make them readable as standard error output.

Because this log output is intended to be displayed on standard error as high-level diagnostic output, you are strongly discouraged from changing the output format to include more tokens besides the log message. Use a dedicated log file handler instead, without this formatter.

format ¶

format(record: LogRecord) -> str

Format a log record suitably for standard error console output.

Prepend the formatted string "PROG_NAME: LABEL" to each line of the message, where PROG_NAME is the program name, and LABEL depends on the record’s level and on the logger name as follows:

For records at level logging.DEBUG, LABEL is "Debug: ".
For records at level logging.INFO, LABEL is the empty string.
For records at level logging.WARNING, LABEL is "Deprecation warning: " if the logger is named PKG.deprecation (where PKG is the package name), else "Warning: ".
For records at level logging.ERROR and logging.CRITICAL "Error: ", LABEL is the empty string.

The level indication strings at level WARNING or above are highlighted. Use click.echo to output them and remove color output if necessary.

Parameters:

Name	Type	Description	Default
`record`	`LogRecord`	A log record.	required

Returns:

Type	Description
`str`	A formatted log record.

Raises:

Type	Description
`AssertionError`	The log level is not supported.

StandardCLILogging ¶

Set up CLI logging handlers upon instantiation.

ensure_standard_logging `classmethod` ¶

ensure_standard_logging() -> StandardLoggingContextManager

Return a context manager to ensure standard logging is set up.

ensure_standard_warnings_logging `classmethod` ¶

ensure_standard_warnings_logging() -> (
    StandardWarningsLoggingContextManager
)

Return a context manager to ensure warnings logging is set up.

StandardLoggingContextManager ¶

StandardLoggingContextManager(
    handler: Handler, root_logger: str | None = None
)

A reentrant context manager setting up standard CLI logging.

Ensures that the given handler (defaulting to the CLI logging handler) is added to the named logger (defaulting to the root logger), and if it had to be added, then that it will be removed upon exiting the context.

Reentrant, but not thread safe, because it temporarily modifies global state.

StandardWarningsLoggingContextManager ¶

StandardWarningsLoggingContextManager(handler: Handler)

Bases: StandardLoggingContextManager

A reentrant context manager setting up standard warnings logging.

Ensures that warnings are being diverted to the logging system, and that the given handler (defaulting to the CLI logging handler) is added to the warnings logger. If the handler had to be added, then it will be removed upon exiting the context.

Reentrant, but not thread safe, because it temporarily modifies global state.

OptionGroupOption ¶

OptionGroupOption(*args: Any, **kwargs: Any)

Bases: Option

A click.Option with an associated group name and group epilog.

Used by CommandWithHelpGroups to print help sections. Each subclass contains its own group name and epilog.

Attributes:

Name	Type	Description
`option_group_name`	`object`	The name of the option group. Used as a heading on the help text for options in this section.
`epilog`	`object`	An epilog to print after listing the options in this section.

option_group_name `class-attribute` `instance-attribute` ¶

option_group_name: object = ''

epilog `class-attribute` `instance-attribute` ¶

epilog: object = ''

CommandWithHelpGroups ¶

Bases: Command

A click.Command with support for some help text customizations.

Supports help/option groups, group epilogs, and help text objects (objects that stringify to help texts). The latter is primarily used to implement translations.

Inspired by a comment on pallets/click#373 for help/option group support, and further modified to include group epilogs and help text objects.

collect_usage_pieces ¶

collect_usage_pieces(ctx: Context) -> list[str]

Return the pieces for the usage string.

Parameters:

Name	Type	Description	Default
`ctx`	`Context`	The click context.	required

get_help_option ¶

get_help_option(ctx: Context) -> Option | None

Return a standard help option object.

Parameters:

Name	Type	Description	Default
`ctx`	`Context`	The click context.	required

get_short_help_str ¶

get_short_help_str(limit: int = 45) -> str

Return the short help string for a command.

If only a long help string is given, shorten it.

Parameters:

Name	Type	Description	Default
`limit`	`int`	The maximum width of the short help string.	`45`

format_help_text ¶

format_help_text(
    ctx: Context, formatter: HelpFormatter
) -> None

Format the help text prologue, if any.

Parameters:

Name	Type	Description	Default
`ctx`	`Context`	The click context.	required
`formatter`	`HelpFormatter`	The formatter for the `--help` listing.	required

format_options ¶

format_options(
    ctx: Context, formatter: HelpFormatter
) -> None

Format options on the help listing, grouped into sections.

This is a callback for click.Command.get_help that implements the --help listing, by calling appropriate methods of the formatter. We list all options (like the base implementation), but grouped into sections according to the concrete click.Option subclass being used. If the option is an instance of some subclass of OptionGroupOption, then the section heading and the epilog are taken from the option_group_name and epilog attributes; otherwise, the section heading is “Options” (or “Other options” if there are other option groups) and the epilog is empty.

We unconditionally call format_commands, and rely on it to act as a no-op if we aren’t actually a click.MultiCommand.

Parameters:

Name	Type	Description	Default
`ctx`	`Context`	The click context.	required
`formatter`	`HelpFormatter`	The formatter for the `--help` listing.	required

format_commands ¶

format_commands(
    ctx: Context, formatter: HelpFormatter
) -> None

Format the subcommands, if any.

If called on a command object that isn’t derived from click.Group, then do nothing.

Parameters:

Name	Type	Description	Default
`ctx`	`Context`	The click context.	required
`formatter`	`HelpFormatter`	The formatter for the `--help` listing.	required

format_epilog ¶

format_epilog(
    ctx: Context, formatter: HelpFormatter
) -> None

Format the epilog, if any.

Parameters:

Name	Type	Description	Default
`ctx`	`Context`	The click context.	required
`formatter`	`HelpFormatter`	The formatter for the `--help` listing.	required

DefaultToVaultGroup ¶

Bases: CommandWithHelpGroups, Group

A helper class to implement the default-to-“vault”-subcommand behavior.

Modifies internal click.MultiCommand methods, and thus is both an implementation detail and a kludge.

resolve_command ¶

resolve_command(
    ctx: Context, args: list[str]
) -> tuple[str | None, Command | None, list[str]]

Resolve a command, defaulting to “vault” instead of erroring out.

TopLevelCLIEntryPoint ¶

Bases: DefaultToVaultGroup

A minor variation of DefaultToVaultGroup for the top-level command.

When called as a function, this sets up the environment properly before invoking the actual callbacks. Currently, this means setting up the logging subsystem and the delegation of Python warnings to the logging subsystem.

The environment setup can be bypassed by calling the .main method directly.

call ¶

__call__(*args: Any, **kwargs: Any) -> Any

PassphraseGenerationOption ¶

PassphraseGenerationOption(*args: Any, **kwargs: Any)

Bases: OptionGroupOption

Passphrase generation options for the CLI.

ConfigurationOption ¶

ConfigurationOption(*args: Any, **kwargs: Any)

Bases: OptionGroupOption

Configuration options for the CLI.

StorageManagementOption ¶

StorageManagementOption(*args: Any, **kwargs: Any)

Bases: OptionGroupOption

Storage management options for the CLI.

CompatibilityOption ¶

CompatibilityOption(*args: Any, **kwargs: Any)

Bases: OptionGroupOption

Compatibility and incompatibility options for the CLI.

LoggingOption ¶

LoggingOption(*args: Any, **kwargs: Any)

Bases: OptionGroupOption

Logging options for the CLI.

ZshComplete ¶

Bases: ZshComplete

Zsh completion class that supports colons.

click’s Zsh completion class (at least v8.1.7 and v8.1.8) uses some completion helper functions (provided by Zsh) that parse each completion item into value-description pairs, separated by a colon. Other completion helper functions don’t. Correspondingly, any internal colons in the completion item’s value sometimes need to be escaped, and sometimes don’t.

The “right” way to fix this is to modify the Zsh completion script to only use one type of serialization: either escaped, or unescaped. However, the Zsh completion script itself may already be installed in the user’s Zsh settings, and we have no way of knowing that. Therefore, it is better to change the format_completion method to adaptively and “smartly” emit colon-escaped output or not, based on whether the completion script will be using it.

format_completion ¶

format_completion(item: CompletionItem) -> str

Return a suitable serialization of the CompletionItem.

This serialization ensures colons in the item value are properly escaped if and only if the completion script will attempt to pass a colon-separated key/description pair to the underlying Zsh machinery. This is the case if and only if the help text is non-degenerate.

adjust_logging_level ¶

adjust_logging_level(
    ctx: Context,
    /,
    param: Parameter | None = None,
    value: int | None = None,
) -> None

Change the logs that are emitted to standard error.

This modifies the StandardCLILogging settings such that log records at the respective level are emitted, based on the param and the value.

color_forcing_callback ¶

color_forcing_callback(
    ctx: Context, param: Parameter, value: Any
) -> None

Disable automatic color (and text highlighting).

Ideally, we would default to color and text styling if outputting to a TTY, or monochrome/unstyled otherwise. We would also support the NO_COLOR and FORCE_COLOR environment variables to override this auto-detection, and perhaps the TTY_COMPATIBLE variable too.

Alas, this is not sensible to support at the moment, because the conventions are still in flux. And settling on a specific interpretation of the conventions would likely prove very difficult to change later on in a backward-compatible way. We thus opt for a conservative approach and use device-indepedendent text output without any color or text styling whatsoever.

validate_occurrence_constraint ¶

validate_occurrence_constraint(
    ctx: Context, param: Parameter, value: Any
) -> int | None

Check that the occurrence constraint is valid (int, 0 or larger).

Parameters:

Name	Type	Description	Default
`ctx`	`Context`	The `click` context.	required
`param`	`Parameter`	The current command-line parameter.	required
`value`	`Any`	The parameter value to be checked.	required

Returns:

Type	Description
`int \| None`	The parsed parameter value.

Raises:

Type	Description
`BadParameter`	The parameter value is invalid.

validate_length ¶

validate_length(
    ctx: Context, param: Parameter, value: Any
) -> int | None

Check that the length is valid (int, 1 or larger).

Parameters:

Name	Type	Description	Default
`ctx`	`Context`	The `click` context.	required
`param`	`Parameter`	The current command-line parameter.	required
`value`	`Any`	The parameter value to be checked.	required

Returns:

Type	Description
`int \| None`	The parsed parameter value.

Raises:

Type	Description
`BadParameter`	The parameter value is invalid.

standard_logging_options ¶

standard_logging_options(
    f: Callable[P, R],
) -> Callable[P, R]

Decorate the function with standard logging click options.

Adds the three click options -v/--verbose, -q/--quiet and --debug, which calls back into the adjust_logging_level function (with different argument values).

Parameters:

Name	Type	Description	Default
`f`	`Callable[P, R]`	A callable to decorate.	required

Returns:

Type	Description
`Callable[P, R]`	The decorated callable.

derivepassphrase._internals.cli_machinery ¶

ClickEchoStderrHandler ¶

emit ¶

CLIofPackageFormatter ¶

format ¶

StandardCLILogging ¶

ensure_standard_logging classmethod ¶

ensure_standard_warnings_logging classmethod ¶

StandardLoggingContextManager ¶

StandardWarningsLoggingContextManager ¶

OptionGroupOption ¶

option_group_name class-attribute instance-attribute ¶

epilog class-attribute instance-attribute ¶

CommandWithHelpGroups ¶

collect_usage_pieces ¶

get_help_option ¶

get_short_help_str ¶

format_help_text ¶

format_options ¶

format_commands ¶

format_epilog ¶

DefaultToVaultGroup ¶

resolve_command ¶

TopLevelCLIEntryPoint ¶

__call__ ¶

PassphraseGenerationOption ¶

ConfigurationOption ¶

StorageManagementOption ¶

CompatibilityOption ¶

LoggingOption ¶

ZshComplete ¶

format_completion ¶

adjust_logging_level ¶

color_forcing_callback ¶

validate_occurrence_constraint ¶

validate_length ¶

standard_logging_options ¶

ensure_standard_logging `classmethod` ¶

ensure_standard_warnings_logging `classmethod` ¶

option_group_name `class-attribute` `instance-attribute` ¶

epilog `class-attribute` `instance-attribute` ¶

call ¶