confattr.quickstart module — confattr v1.4.0 documentation

# confattr.quickstart module

Importing this module defines several settings which are useful in many applications and provides the `ConfigManager` class. This allows for an easy configuration setup in exchange for flexibility. If you want more flexibility you can either subclass `ConfigManager` and override specific methods or you do not import this module at all and use `ConfigFile` and `Config` directly.

class confattr.quickstart.ConfigManager(appname: str, version: str, doc: str | None)

  Bases: `object`

  Defines two `ConfigFile` instances with separately configurable notification levels for `load()` and `parse_line()`. This object also provides `create_argument_parser()` to create an `argparse.ArgumentParser` with commonly needed arguments. Note that all `Config` instances must be created before instantiating this class.

  Parameters:

    - appname – The name of the app, used to initialize `ConfigFile` and when printing the version number

    - version – The version of the app, used when printing the version number

    - doc – The package doc string, used as description when creating an `ArgumentParser`

  add_config_help_argument(p: ArgumentParser) → ArgumentParser

    Add a `--help-config` argument to an `argparse.ArgumentParser`.

    This is not part of `add_config_related_arguments()` so that this argument can be insterted between `--help` and `--version`.

    Returns:

      The same object that has been passed in

  add_config_related_arguments(p: ArgumentParser) → ArgumentParser

    Add arguments related to the config file to an `argparse.ArgumentParser`.

    Returns:

      The same object that has been passed in

  add_version_argument(p: ArgumentParser) → ArgumentParser

    Add an argument to print the version and exit to an `argparse.ArgumentParser`.

    Returns:

      The same object that has been passed in

  create_argument_parser() → ArgumentParser

    Create an `argparse.ArgumentParser` with arguments to display the version, edit the config file and choose a config file by calling `create_empty_argument_parser()`, `add_config_help_argument()`, `add_version_argument()` and `add_config_related_arguments()`.

  create_empty_argument_parser() → ArgumentParser

    Create an `argparse.ArgumentParser` with the `doc` passed to the constructor as description and `HelpFormatter` as formatter_class but without custom arguments.

  edit_config(*, context: Callable[[SubprocessCommand], ContextManager[SubprocessCommand]] | None, update: bool = False) → None

    Open the config file in a text editor.

    If the config file does not exist it is created first. The text editor can be configured with `editor`.

    Parameters:

      - context – Returns a context manager which can be used to stop and start an urwid screen. It takes the command to be executed as argument so that it can log the command and it returns the command to be executed so that it can modify the command, e.g. processing and intercepting some environment variables.

      - update – Load and rewrite the config file if it is already existing.

  edit_config_and_exit() → None

    edit the config file and exit

  editor

    A setting allowing the user to specify how to open text files, e.g. the config file

  get_save_path() → str
    Returns:

      The first existing and writable file returned by `iter_config_paths()` or the first path if none of the files are existing and writable.

  load() → bool

    Load settings from config file and environment variables.

    Returns:

      true if no errors have occurred, false if one or more errors have occurred

  notification_level_config

    A setting allowing the user to specify which messages they want to see when loading a config file with `load()`

  notification_level_ui

    A setting allowing the user to specify which messages they want to see when parsing a line with `parse_line()`

  parse_line(ln: str) → bool

    Parse a line from the user interface.

    Returns:

      true if no errors have occurred, false if one or more errors have occurred

  print_config_help_and_exit() → None

    show the config help and exit

  print_errors_without_ui() → None

    Call `set_ui_callback()` with `print()` so that all messages are printed to the terminal.

  print_version_and_exit() → None

    show the version and exit

  save(if_not_existing: bool = False) → str

    Save the current values of all settings to the file returned by `get_save_path()`. Directories are created as necessary.

    Parameters:

      if_not_existing – Do not overwrite the file if it is already existing.

    Returns:

      The path to the file which has been written

  select_config_file(path: str) → None

    use this config file instead of the default

  set_ui_callback(callback: Callable[[Message], None]) → None

    Register a user interface notification callback function to all `ConfigFile` instances created by this object.

    See `ConfigFile.set_ui_callback()`.

  ui_notifier: UiNotifier

    Can be used to print messages to the user interface, uses `notification_level_ui`

  update_config_and_exit() → None

    rewrite the config file, open it for editing and exit