multipackage.utilities.managed_section module

Helper class for managing a block of content inside a text file.

Summary

Classes:

ManagedFileSection A section of a text file that is managed by multipackage.

Reference

class multipackage.utilities.managed_section.ManagedFileSection(path, delimiter_start='# ', delimiter_end='')[source]

Bases: object

A section of a text file that is managed by multipackage.

This class helps define a block of lines inside a file with a fence around them. The contents of the fence are hashed so that modifications can be detected and the fence data can be versioned.

Parameters:
  • path (str) – The path to the file that we want to manage. This file does not need to exist and will be created when you try to update it with data if it does not currently exist.
  • delimiter_start (str) – The character string that starts a managed file section block header line. This is usually a comment character like ‘#’.
  • delimiter_end (str) – Optional charcter string that ends a managed file section block header line. This defaults to an emptry string but can be set to a value if comments need to be explicitly closed such as delimiter_start=”<!– “, delimiter_end=” –>”.
SECTION_START = 'BEGIN MULTIPACKAGE MANAGED SECTION, HASH='
SECTION_END = 'END MULTIPACKAGE MANAGED SECTION'
HASH_HEX_LENGTH = 32
MANAGE_ERROR = 'A file that needs to be managed by multipackage exists and is a directory, not a file'
MULTIPLE_SECTION_ERROR = 'A file that is managed by multipackage has been corrupted'
ensure_lines(lines, match=None, present=True, multi=False)[source]

Ensure that the given lines are present or absent in this file.

Each line is added independently and no order is assumed. This method is idempotent so that you can call it repeatedly and each line will only be added once. The lines must match exactly.

The lines must be distinct. If there are multiple copies of the same line in lines, only one copy will be added to the file.

If you need to perform fuzzy matching on a given line in order to properly update it, you can pass a list of regular expressions along with the lines

Parameters:
  • lines (list of str) – A list of lines to add to the file if they are not present or remove from the file if they are. Whether the lines are added or removed is controlled by the present parameter.
  • match (list of str) – A list of regular expressions to use to match against a line. If passed it must have the same length as lines and will be paired with each line in lines in order to determine which line matches.
  • present (bool) – If True, ensure lines are present (the default), if False, ensure lines are absent.
  • multi (bool) – If true, allow for matching and updating multiple lines for each line in lines. If False, InternalError is raised if there are multiple lines matching a given line.
update(lines=None)[source]

Update or add a managed section into the file.

This method will add a new managed section into the file or update the section that is currently there, replacing its contents with those specified in update. The resulting file will we written out to disk.

If the file does not currently exist, it will be created, otherwise its contents will be replaced.

Parameters:lines (list of str) – A list of lines to add to the file. If this is passed as None, then the current value of self.section_contents will be used instead.