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: 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.
As the doc string of
argparse.HelpFormatter
statesOnly 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:
- 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:
formatter_class¶ –
argparse.HelpFormatter
or any of it’s subclasses (argparse.RawDescriptionHelpFormatter
,argparse.RawTextHelpFormatter
,argparse.ArgumentDefaultsHelpFormatter
,argparse.MetavarTypeHelpFormatter
orHelpFormatter
)prog¶ – The name of the program
indent_increment¶ – The number of spaces by which to indent the contents of a section
max_help_position¶ – The maximal indentation of the help of arguments. If argument names + meta vars + separators are longer than this the help starts on the next line.
width¶ – Maximal number of characters per line
- 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 withadd_start_list()
and ended withadd_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()
andadd_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()
andadd_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(value, names=None, *, 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 orderTHREE='three'; TWO='two'; ONE='one'
you can passdescending = True
to the subclass. This requires Python 3.10.0a4 or newer. On older versions it causes aTypeError: __prepare__() got an unexpected keyword argument 'descending'
. This was fixed in commit 6ec0adefad.