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.CallAction(option_strings: Sequence[str], dest: str, callback: Callable[[], None], help: str | None = None, nargs: int | str = 0)

Bases: Action

An action which can be used when adding an argument to an argparse.ArgumentParser. It immediately calls the function passed to callback without checking if all command line arguments have been passed. If you omit the help parameter the function must have a doc string which is used instead.

For example:

import sys
import argparse
from confattr.utils import CallAction

__version__ = '0.1.0'

def print_version_and_exit() -> None:
	'''show the version and exit'''
	print(__version__)
	sys.exit()

p = argparse.ArgumentParser()
p.add_argument('-v', '--version', action=CallAction, callback=print_version_and_exit)

args = p.parse_args()
class confattr.utils.HelpFormatter(prog: str, indent_increment: int = 2, max_help_position: int = 24, width: int | None = 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.

Non breaking spaces can be used to prevent line breaks. They will be replaced with normal spaces after line breaking.

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 without an argparse.ArgumentParser 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().

class confattr.utils.SortedEnum(new_class_name, /, names, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

By default it is assumed that the values are defined in ascending order ONE='one'; TWO='two'; THREE='three'. If you want to define them in descending order THREE='three'; TWO='two'; ONE='one' you can pass descending = True to the subclass. This requires Python 3.10.0a4 or newer. On older versions it causes a TypeError: __prepare__() got an unexpected keyword argument 'descending'. This was fixed in commit 6ec0adefad.

descending: bool
confattr.utils.readable_quote(value: str) → str

This function has the same goal like shlex.quote() but tries to generate better readable output.

Parameters:

value – A value which is intended to be used as a command line argument

Returns:

A POSIX compliant quoted version of value