confattr.utils module

This module contains classes and functions that confattr uses internally but which might be useful for other python projects, too.

class confattr.utils.HelpFormatter(prog: str, indent_increment: int = 2, max_help_position: int = 24, width: Optional[int] = None)

Bases: RawDescriptionHelpFormatter

A subclass of argparse.HelpFormatter which keeps paragraphs separated by an empty line as separate paragraphs and and which does not merge different list items to a single line.

Lines are wrapped to not exceed a length of max_width characters, although not strictly to prevent URLs from breaking.

If a line ends with a double backslash this line will not be merged with the following line and the double backslash (and spaces directly before it) will be removed.

As the doc string of argparse.HelpFormatter states

Only the name of this class is considered a public API. All the methods provided by the class are considered an implementation detail.

Therefore I may be forced to change the methods’ signatures if argparse.HelpFormatter is changed. But I hope that I can keep the class attributes backward compatible so that you can create your own formatter class by subclassing this class and changing the values of the class variables.

If you want to use this class pass it to the constructor of HelpFormatterWrapper and use that instead.

Parameters:
  • prog – The name of the program

  • width – Wrap lines so that they are no longer than this number of characters. If this value is None or bigger than max_width then max_width is used instead.

break_long_words = False

This value is assigned to textwrap.TextWrapper.break_long_words. This defaults to False to prevent URLs from breaking.

break_on_hyphens = False

This value is assigned to textwrap.TextWrapper.break_on_hyphens. This defaults to False to prevent URLs from breaking.

max_width = 70

Wrap lines so that they are no longer than this number of characters.

regex_linebreak = '\\\\\\\\(?:\n|$)'

If a match is found this line is not merged with the following and the match is removed. This may not contain any capturing groups.

regex_list_item = '(?:^|\n)(\\s*(?:[-+*!/.]|[0-9]+[.)])(?: \\[[ x~]\\])? )'

If a match is found this line is not merged with the preceeding line. This regular expression must contain exactly one capturing group. This group defines the indentation. Everything that is matched but not part of that group is removed.

class confattr.utils.HelpFormatterWrapper(formatter_class: type[argparse.HelpFormatter], **kw: Unpack[HelpFormatterKwargs])

Bases: object

The doc string of argparse.HelpFormatter states:

Only the name of this class is considered a public API. All the methods provided by the class are considered an implementation detail.

This is a wrapper which tries to stay backward compatible even if argparse.HelpFormatter changes.

Parameters:
add_end_list() None

End a list. This must be called after the last add_item().

add_end_section() None

End the last section which has been started with add_start_section().

add_item(text: str, bullet: str = '- ') None

Add a list item which will be formatted when calling format_help(). A list must be started with add_start_list() and ended with add_end_list().

add_start_list() None

Start a new list which can be filled with add_item().

add_start_section(heading: str) None

Start a new section.

This influences the formatting of following calls to add_text() and add_item().

You can call this method again before calling add_end_section() to create a subsection.

add_text(text: str) None

Add some text which will be formatted when calling format_help().

format_help() str

Format everything that has been added with add_start_section(), add_text() and add_item().

format_item(bullet: str, text: str) str

Format a list item and return it immediately without adding it to format_help().

format_text(text: str) str

Format a text and return it immediately without adding it to format_help().