dir_content_diff¶
dir-content-diff package.
Simple tool to compare directory contents.
Functions
|
Raise an |
|
Compare 2 files and return the difference. |
|
Compare all files from 2 different directory trees and return the differences. |
|
Format a data file and export it. |
Return a copy of the comparator registry. |
|
|
Add a comparator to the registry. |
Reset the comparator registry to the default values. |
|
|
Remove a comparator from the registry. |
- dir_content_diff.assert_equal_trees(*args, export_formatted_files=False, **kwargs)¶
Raise an
AssertionError
if differences are found in the two directory trees.Note
This function has a specific behavior when run with pytest. See the doc of the
dir_content_diff.pytest_plugin
.- Parameters:
*args – passed to the
compare_trees()
function.export_formatted_files (bool, or str) – If set to
True
, the formatted files are exported to the directory with the default suffix. If set to a string, it is used as suffix for the new directory.**kwargs – passed to the
compare_trees()
function.
- Returns:
(bool)
True
if the trees are equal. If they are not, anAssertionError
is raised.
- dir_content_diff.compare_files(ref_file, comp_file, comparator, *args, return_raw_diffs=False, **kwargs)¶
Compare 2 files and return the difference.
- Parameters:
ref_file (str) – Path to the reference file.
comp_file (str) – Path to the compared file.
comparator (callable) – The comparator to use (see in
register_comparator()
for the comparator signature).return_raw_diffs (bool) – If set to
True
, only the raw differences are returned instead of a formatted report.*args – passed to the comparator.
**kwargs – passed to the comparator.
- Returns:
False
if the files are equal or a string with a message explaining the differences if they are different.- Return type:
- dir_content_diff.compare_trees(ref_path, comp_path, comparators=None, specific_args=None, return_raw_diffs=False, export_formatted_files=False)¶
Compare all files from 2 different directory trees and return the differences.
Note
The comparison only considers the files found in the reference directory. So if there are files in the compared directory that do not exist in the reference directory, they are just ignored.
- Parameters:
ref_path (str) – Path to the reference directory.
comp_path (str) – Path to the directory that must be compared against the reference.
comparators (dict) – A
dict
to override the registered comparators.specific_args (dict) –
A
dict
with the args/kwargs that should be given to the comparator for a given file. Thisdict
should be like the following:{ <relative_file_path>: { comparator: ComparatorInstance, args: [arg1, arg2, ...], kwargs: { kwarg_name_1: kwarg_value_1, kwarg_name_2: kwarg_value_2, } }, <another_file_path>: {...}, <a name for this category>: { "patterns": ["regex1", "regex2", ...], ... (other arguments) } }
If the “patterns” entry is present, then the name is not considered and is only used as a helper for the user. When a “patterns” entry is detected, the other arguments are applied to all files whose relative name matches one of the given regular expression patterns. If a file could match multiple patterns of different groups, only the first one is considered.
Note that all entries in this
dict
are optional.return_raw_diffs (bool) – If set to
True
, only the raw differences are returned instead of a formatted report.export_formatted_files (bool or str) – If set to
True
or a not empty string, create a new directory with formatted compared data files. If a string is passed, this string is used as suffix for the new directory. If True is passed, the suffix is_FORMATTED
.
- Returns:
A
dict
in which the keys are the relative file paths and the values are the difference messages. If the directories are considered as equal, an emptydict
is returned.- Return type:
- dir_content_diff.export_formatted_file(file, formatted_file, comparator, **kwargs)¶
Format a data file and export it.
Note
A new file is created only if the corresponding comparator has saving capability.
- Parameters:
file (str) – Path to the compared file.
formatted_file (str) – Path to the formatted file.
comparator (callable) – The comparator to use (see in
register_comparator()
for the comparator signature).**kwargs – Can contain the following dictionaries: ‘load_kwargs’, ‘format_data_kwargs’ and ‘save_kwargs’.
- dir_content_diff.get_comparators()¶
Return a copy of the comparator registry.
- dir_content_diff.register_comparator(ext, comparator, force=False)¶
Add a comparator to the registry.
- Parameters:
Note
It is possible to create and register custom comparators. The easiest way to do it is to derive a class from
dir_content_diff.BaseComparator
.Otherwise, the given comparator should be a callable with the following signature:
comparator( ref_file: str, comp_file: str, *diff_args: Sequence[Any], return_raw_diffs: bool=False, **diff_kwargs: Mapping[str, Any], ) -> Union[False, str]
The return type can be Any when used with return_raw_diffs == True, else it should be a string object.
- dir_content_diff.reset_comparators()¶
Reset the comparator registry to the default values.