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.
Backup
path
to{path} + {backup_extension}
. Typically, this would mean copying e.g.,file.txt
tofile.txt.orig
.Perform filtering using
re.sub()
.If
demand_different=True
(default), verify that replacements were actually made. If not,fail()
.
The only required arguments are
path
,pattern
, andrepl
. If any errors occur, including invalid input, this function willfail()
.- 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]
orstr
) – The replacement to be made. Pass-through parameter tore.sub()
.count (int) – The number of replacements to make (default
0
means replace all). Pass-through parameter tore.sub()
.flags (int) – Any flags such as
re.IGNORECASE
orre.MULTILINE
(default0
means no special flags). Pass-through parameter tore.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
, dore.sub()
on the entire contents. Settingline_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 toopen()
.
- Returns
The path to the backup file that was created with the original contents.
- Return type
- 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 todifflib.unified_diff()
.lineterm (str) – Default:
"\n"
. Pass-through parameter todifflib.unified_diff()
.encoding (str or None) – The encoding to open files with. Default:
None
implies default. Pass-through parameter toopen()
.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 toTrue
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
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.