ci_exec.patch

Various utilities for patching files.

filter_file(path, pattern, repl[, count, …])

Filter the contents of a file.

unified_diff(from_path, to_path[, n, …])

Return the unified_diff between two files.
filter_file(path, pattern, repl, count=0, flags=0, backup_extension='.orig', line_based=False, demand_different=True, encoding=None)[source]

Filter the contents of a file.

  1. Backup path to {path} + {backup_extension}. Typically, this would mean copying e.g., file.txt to file.txt.orig.

  2. Perform filtering using re.sub().

  3. If demand_different=True (default), verify that replacements were actually made. If not, fail().

The only required arguments are path, pattern, and repl. If any errors occur, including invalid input, this function will fail().

Parameters

  • path (pathlib.Path or str) – The file that needs to be filtered.

  • pattern (str) – The pattern to replace. Pass-through parameter to re.sub().

  • repl (Callable[[Match], str] or str) – The replacement to be made. Pass-through parameter to re.sub().

  • count (int) – The number of replacements to make (default 0 means replace all). Pass-through parameter to re.sub().

  • flags (int) – Any flags such as re.IGNORECASE or re.MULTILINE (default 0 means no special flags). Pass-through parameter to re.sub().

  • backup_extension (str) – The name to tack onto the back of path to make a backup with. Must be a non-empty string. Default: ".orig".

  • line_based (bool) – Whether or not replacements should be made on the entirety of the file, or on a per-line basis. Default: False, do re.sub() on the entire contents. Setting line_based=True can make for simpler or more restrictive regular expressions depending on the replacement needed.

  • demand_different (bool) – Whether or not this function should fail() if no changes were actually made. Default: True, fail() if no filtering was performed.

  • encoding (str or None) – The encoding to open files with. Default: None implies default. Pass-through parameter to open().

Returns

The path to the backup file that was created with the original contents.

Return type

pathlib.Path

unified_diff(from_path, to_path, n=3, lineterm='\n', encoding=None, no_pygments=False)[source]

Return the unified_diff between two files.

Any errors, such as not being able to read a file, will fail() the application abruptly.

Parameters

  • from_path (pathlib.Path or str) – The file to diff from (the “original” file).

  • to_path (pathlib.Path or str) – The file to diff to (the “changed” file).

  • n (int) – Number of context lines. Default: 3. Pass-through parameter to difflib.unified_diff().

  • lineterm (str) – Default: "\n". Pass-through parameter to difflib.unified_diff().

  • encoding (str or None) – The encoding to open files with. Default: None implies default. Pass-through parameter to open().

  • no_pygments (bool) –

    Whether or not an attempt to colorize the output using Pygments using the console formatter. If Pygments is not installed, no errors will ensue.

    Default: False, always try and make pretty output. Set to True if you need to enforce that the returned string does not have colors.

Returns

A string ready to be printed to the console.

Return type

str

Tests

Tests for the ci_exec.patch module.

test_filter_file(capsys)[source]

Validate that filter_file() patches / errors as expected.

test_unified_diff(capsys)[source]

Validate that unified_diff() diffs / errors as expected.