files

Tools for file and directory management.

patchwork.files.append(c, filename, text, partial=False, escape=True, sudo=False, runner_method='run', runner=None)

Append string (or list of strings) text to filename.

When a list is given, each string inside is handled independently (but in the order given.)

If text is already found in filename, the append is not run, and None is returned immediately. Otherwise, the given text is appended to the end of the given filename via e.g. echo '$text' >> $filename.

The test for whether text already exists defaults to a full line match, e.g. ^<text>$, as this seems to be the most sensible approach for the “append lines to a file” use case. You may override this and force partial searching (e.g. ^<text>) by specifying partial=True.

Because text is single-quoted, single quotes will be transparently backslash-escaped. This can be disabled with escape=False.

Parameters:
  • c – Context within to execute commands.
  • filename (str) – File path to append onto.
  • text (str) – Text to append.
  • partial (bool) – Whether to test partial line matches when determining if appending is necessary.
  • escape (bool) – Whether to perform regex-oriented escaping on text.
  • sudo (bool) – Whether to run shell commands via sudo.
  • runner_method (str) – Name of context method to use when running shell commands.
  • runner – Callable runner function or method. Should ideally be a bound method on the given context object!
patchwork.files.contains(c, filename, text, exact=False, escape=True, sudo=False, runner_method='run', runner=None)

Return True if filename contains text (which may be a regex.)

By default, this function will consider a partial line match (i.e. where text only makes up part of the line it’s on). Specify exact=True to change this behavior so that only a line containing exactly text results in a True return value.

This function leverages egrep on the remote end, so it may not follow Python regular expression syntax perfectly.

If escape is False, no extra regular expression related escaping is performed (this includes overriding exact so that no ^/$ is added.)

Parameters:
  • c – Context within to execute commands.
  • filename (str) – File path within which to check for text.
  • text (str) – Text to search for.
  • exact (bool) – Whether to expect an exact match.
  • escape (bool) – Whether to perform regex-oriented escaping on text.
  • sudo (bool) – Whether to run shell commands via sudo.
  • runner_method (str) – Name of context method to use when running shell commands.
  • runner – Callable runner function or method. Should ideally be a bound method on the given context object!
patchwork.files.directory(c, path, user=None, group=None, mode=None, sudo=False, runner_method='run', runner=None)

Ensure a directory exists and has given user and/or mode

Parameters:
  • c – Context within to execute commands.
  • path (str) – File path to directory.
  • user (str) – Username which should own the directory.
  • group (str) – Group which should own the directory; defaults to user.
  • mode (str) – chmod compatible mode string to apply to the directory.
  • sudo (bool) – Whether to run shell commands via sudo.
  • runner_method (str) – Name of context method to use when running shell commands.
  • runner – Callable runner function or method. Should ideally be a bound method on the given context object!
patchwork.files.exists(c, path, sudo=False, runner_method='run', runner=None)

Return True if given path exists on the current remote host.

Parameters:
  • c – Context within to execute commands.
  • path (str) – Path to check for existence.
  • sudo (bool) – Whether to run shell commands via sudo.
  • runner_method (str) – Name of context method to use when running shell commands.
  • runner – Callable runner function or method. Should ideally be a bound method on the given context object!