dir_content_diff

dir-content-diff package.

Simple tool to compare directory contents.

Functions

assert_equal_trees(*args[, ...])

Raise an AssertionError if differences are found in the two directory trees.

compare_files(ref_file, comp_file, ...[, ...])

Compare 2 files and return the difference.

compare_trees(ref_path, comp_path[, ...])

Compare all files from 2 different directory trees and return the differences.

export_formatted_file(file, formatted_file, ...)

Format a data file and export it.

get_comparators()

Return a copy of the comparator registry.

register_comparator(ext, comparator[, force])

Add a comparator to the registry.

reset_comparators()

Reset the comparator registry to the default values.

unregister_comparator(ext[, quiet])

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, an AssertionError 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:

bool or str

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. This dict 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 empty dict is returned.

Return type:

dict

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:
  • ext (str) – The extension to register.

  • comparator (callable) – The comparator that should be associated with the given extension.

  • force (bool) – If set to True, no exception is raised if the given ext is already registered and the comparator is replaced.

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.

dir_content_diff.unregister_comparator(ext, quiet=False)

Remove a comparator from the registry.

Parameters:
  • ext (str) – The extension to unregister.

  • quiet (bool) – If set to True, no exception is raised if the given ext is not registered.

Returns:

The removed comparator.