unravel.core.help_formatter module#

This script enhances the formatting and handling of argparse arguments by defining custom classes that improve the readability and usability of help messages, with a focus on suppressing metavar display and leveraging the Rich library for styled terminal output.

Classes:
  • SuppressMetavar: A custom HelpFormatter class that suppresses the display of metavar for arguments and

    customizes the formatting of action invocations and epilog text.

  • SM: A custom argparse.Action class that manages argument values while suppressing metavar display across

    all nargs configurations.

  • RichArgumentParser: An enhanced ArgumentParser that integrates custom help message formatting and

    handling, including filtering and styling of argparse help text.

  • CustomHelpAction: An argparse Action that displays a richly formatted help message, integrating the script’s

    docstring.

Functions:
  • format_argparse_help: Processes and applies custom styles to argparse help text, highlighting flags,

    default values, and section headers with specific colors and styles.

  • format_docstring_for_terminal: Formats the script’s docstring with Rich’s styled output, improving readability

    by highlighting sections, command names, and other key elements.

Usage:

The custom classes and functions can be used in any argparse-based script to suppress metavar display, format help messages with Rich’s styled output, and enhance the overall user experience.

Example

import argparse from unravel.core.help_formatter import SuppressMetavar, SM, CustomArgumentRich

parser = RichArgumentParser(formatter_class=SuppressMetavar, add_help=False, docstring=__doc__)

reqs = parser.add_argument_group(‘Required arguments’) parser.add_argument(‘-e’, ‘–example’, help=’Example argument’, action=SM) args = parser.parse_args()

Note

  • The SuppressMetavar class is designed to suppress metavar display and improve the formatting of epilog text.

  • The SM action ensures that metavar is consistently suppressed across different nargs configurations.

  • The CustomArgumentRich and CustomHelpAction provide enhanced help message handling, integrating formatted docstrings and filtering out unwanted lines.

  • nargs=’+’ with action=SM: This combination causes issues when the terminal window is small.

  • Use nargs=’*’ with action=SM if zero arguments are acceptable, or drop action=SM to avoid conflicts.

class unravel.core.help_formatter.SuppressMetavar(prog)[source]#

Bases: HelpFormatter

class unravel.core.help_formatter.CustomHelpAction(option_strings, dest='==SUPPRESS==', default='==SUPPRESS==', help=None, docstring=None)[source]#

Bases: Action

class unravel.core.help_formatter.RichArgumentParser(*args, docstring=None, **kwargs)[source]#

Bases: ArgumentParser

print_help(file=None)[source]#
filter_help_output(help_output)[source]#
format_usage()[source]#
class unravel.core.help_formatter.SM(option_strings, dest, nargs=None, **kwargs)[source]#

Bases: Action

unravel.core.help_formatter.format_argparse_help(help_text)[source]#

Apply rich formatting to the argparse help message.

This function processes the help text generated by argparse and applies custom styles using the Rich library. It colors the flags according to the section they belong to (e.g., purple3 for “Required arguments:”).

grey50 style is applied to lines containing “Default:” to make them less prominent.

Parameters:

help_text (str) – The help text generated by argparse.

Returns:

A rich.text.Text object containing the formatted help text.

Return type:

Text

unravel.core.help_formatter.format_docstring_for_terminal(docstring)[source]#

Apply rich formatting to a docstring for enhanced terminal display.

This function processes a docstring by applying various formatting styles using the Rich library. It handles sections like script descriptions, usage examples, command arguments, and specific keywords like “Input:”, “Output”, “Note”, “Prereq”, and “Next”. Additionally, it applies special styles to text enclosed in double backticks and command-line flags.

Parameters:

docstring (str) – The original docstring to be formatted.

Returns:

A rich.text.Text object containing the formatted text.

Return type:

Text

Notes

The function applies the following styles: - “UNRAVEL” is styled with a custom multi-colored format. - Script description lines are styled as bold. - Section headers starting with “Prereq”, “Input”, “Output”, “Note”, “Next”, and “Usage” are colored. - Command names enclosed in double backticks or appearing in usage examples are styled as bold bright magenta. - Required arguments (before the first optional argument) are styled as purple3. - Optional arguments (within square brackets) are styled as bright blue. - Required command-line flags (e.g., -m, –input) are styled as bold in the required arg section. - General arguments like [-d list of paths], [-p sample??], and [-v] in the Usage section are styled as green. - The Usage section should be last and is separated by a horizontal line.

On this page
Show Source