# 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`

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` 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:

    - formatter_class – `argparse.HelpFormatter` or any of it’s subclasses (`argparse.RawDescriptionHelpFormatter`, `argparse.RawTextHelpFormatter`, `argparse.ArgumentDefaultsHelpFormatter`, `argparse.MetavarTypeHelpFormatter` or `HelpFormatter`)

    - 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 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(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 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`