confattr.types module — confattr v1.4.0 documentation

# confattr.types module

class confattr.types.AbstractType(value: str)

  Bases: `ABC`

  This class is merely for documentation purposes. It shows which special methods and attributes are considered by this library for the data types which are used in a `Config`.

  The constructor must create an equal objet if it is passed the return value of `__str__()`. Optionally you may want to also accept another data type as argument for creating the default value.

  abstract __str__() → str

    This method must return a str representation of this object which is suitable to be written to a config file.

  abstract classmethod get_instances() → Sequence[Self]

    If this method is implemented it returns a sequence of the allowed values.

  help: str

    A help for this data type must be provided, either in this attribute or by adding it to `Primitive.help_dict`.

  type_name: str

    If this attribute is present it is used instead of the class name in the config file.

class confattr.types.CaseInsensitiveRegex(pattern: str)

  Bases: `Regex`

  help = '\n\tA case insensitive regular expression in python syntax.\n\tYou can make it case sensitive by wrapping the pattern in `(?-i:...)`.\n\thttps://docs.python.org/3/library/re.html#regular-expression-syntax\n\t'

class confattr.types.OptionalExistingDirectory(value: str)

  Bases: `object`

  expand() → str
  help = 'The path to an existing directory or an empty str to use a default path.'
  type_name = 'optional existing directory'

class confattr.types.Regex(pattern: str)

  Bases: `object`

  help = '\n\tA regular expression in python syntax.\n\tYou can specify flags by starting the regular expression with `(?aiLmsux)`.\n\thttps://docs.python.org/3/library/re.html#regular-expression-syntax\n\t'
  type_name = 'regular expression'

class confattr.types.SubprocessCommand(arg: SubprocessCommand | Sequence[str] | str, *, env: Mapping[str, str] | None = None)

  Bases: `object`

  classmethod has_python_callback(name: str) → bool
  help = '\tA command to be executed as a subprocess.\n\tThe command is executed without a shell so redirection or wildcard expansion is not possible.\n\tSetting environment variables and piping like in a POSIX shell, however, are implemented in python and should work platform independently.\n\tIf you need a shell write the command to a file, insert an appropriate shebang line, make the file executable and set this value to the file.\n\t'
  is_installed() → bool
  parse_str(arg: str) → None

    Parses a string as returned by `__str__()` and initializes this objcet accordingly

    Parameters:

      arg – The string to be parsed

    Raises:

      ValueError – if arg is invalid

    Example:

      If the input is `arg = 'ENVVAR1=val ENVVAR2= cmd --arg1 --arg2'` this function sets .. code-block:

          self.env = {'ENVVAR1' : 'val', 'ENVVAR2' : ''}
          self.cmd = ['cmd', '--arg1', '--arg2']

  python_callbacks: MutableMapping[str, Callable[[SubprocessCommand, Callable[[SubprocessCommand], ContextManager[SubprocessCommand]] | None], None]] = {}
  classmethod register_python_callback(name: str, func: Callable[[SubprocessCommand, Callable[[SubprocessCommand], ContextManager[SubprocessCommand]] | None], None]) → None
  replace(wildcard: str, replacement: str) → SubprocessCommand
  run(*, context: TYPE_CONTEXT | None) → CompletedProcess[bytes] | None

    Runs this command and returns when the command is finished.

    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.

    Returns:

      The completed process

    Raises:

      - OSError – e.g. if the program was not found

      - CalledProcessError – if the called program failed

  type_name = 'command'
  classmethod unregister_python_callback(name: str) → None

class confattr.types.SubprocessCommandWithAlternatives(commands: Sequence[SubprocessCommand | Sequence[str] | str] | str)

  Bases: `object`

  SEP = '||'
  WC_FILE_NAME = 'fn'

    The wild card used by `editor()` for the file name

  classmethod editor(*, visual: bool) → SubprocessCommandWithAlternatives

    Create a command to open a file in a text editor. The `EDITOR`/`VISUAL` environment variables are respected on non-Windows systems.

  get_preferred_command() → SubprocessCommand
  help = "\n\tOne or more commands separated by ||.\n\tThe first command where the program is installed is executed. The other commands are ignored.\n\n\tIf the command name starts with a '$' it is interpreted as an environment variable containing the name of the program to be executed.\n\tThis is useful to make use of environment variables like EDITOR.\n\tIf the environment variable is not set the program is considered to not be installed and the next command is tried instead.\n\n\tThe command is executed without a shell so redirection or wildcard expansion is not possible.\n\tSetting environment variables and piping like in a POSIX shell, however, are implemented in python and should work platform independently.\n\tIf you need a shell write the command to a file, insert an appropriate shebang line, make the file executable and set this value to the file.\n\t"
  replace(wildcard: str, replacement: str) → SubprocessCommand
  run(context: TYPE_CONTEXT | None = None) → CompletedProcess[bytes] | None
  type_name = 'command with alternatives'

confattr.types.TYPE_CONTEXT: TypeAlias = 'Callable[[SubprocessCommand], typing.ContextManager[SubprocessCommand]] | None'

  The data type of a context manager factory which can be passed to `SubprocessCommand.run()` and `SubprocessCommandWithAlternatives.run()`