Jump to >

rbtools.utils.diffs

Utilities for generating or parsing diffs.

Functions

filename_match_any_patterns(filename, ...[, ...])

Check if the given filename matches any of the patterns.

filter_diff(diff, file_index_re, *, ...[, ...])

Filter through the lines of diff to exclude files.

normalize_patterns(patterns, *, base_dir[, cwd])

Normalize a list of patterns so that they are all absolute paths.

remove_filenames_matching_patterns(...)

Return an iterable of all filenames that do not match any patterns.

rbtools.utils.diffs.filename_match_any_patterns(filename: str, patterns: Iterable[str], *, base_dir: str = '') bool[source]

Check if the given filename matches any of the patterns.

If base_dir is not supplied, it will treat the filename as relative to the current working directory.

Changed in version 4.0: base_dir must now be provided as a keyword argument. This will be mandatory in RBTools 5.

Parameters:
  • filename (str) – The filename to match against.

  • patterns (list of str) – The list of patterns to try to match.

  • base_dir (str, optional) – An optional base directory to prepend to the filename.

Returns:

True if one of the patterns matched. False if no patterns matched.

Return type:

bool

rbtools.utils.diffs.filter_diff(diff: Iterable[bytes], file_index_re: Pattern[bytes], *, exclude_patterns: List[str], base_dir: str = '') Iterator[bytes][source]

Filter through the lines of diff to exclude files.

This function looks for lines that indicate the start of a new file in the diff and checks if the filename matches any of the given patterns. If it does, the diff lines corresponding to that file will not be yielded; if the filename does not match any patterns, the lines will be yielded as normal.

Changed in version 4.0: exclude_patterns, and base_dir must now be provided as keyword arguments. This will be mandatory in RBTools 5.

Parameters:
  • diff (list of bytes) – The list of lines in a diff.

  • file_index_re (re.Pattern) –

    A compiled regex used to match if and only if a new file’s diff is being started.

    This must have exactly one sub-group used to match the filename. For example: ^filename: (.+)$.

  • exclude_patterns (list of str) –

    The list of patterns to try to match against filenames.

    Any pattern matched will cause the file to be excluded from the diff.

  • base_dir (str, optional) –

    An optional base directory to prepend to each filename.

    If not provided, filenames should be relative to the root of the repository.

Yields:

bytes – A line of content from the diff.

rbtools.utils.diffs.normalize_patterns(patterns: Iterable[str], *, base_dir: str, cwd: Optional[str] = None) List[str][source]

Normalize a list of patterns so that they are all absolute paths.

Paths that begin with a path separator are interpreted as being relative to base_dir. All other paths are interpreted as being relative to the current working directory.

Changed in version 4.0: base_dir and cwd must now be provided as keyword arguments. This will be mandatory in RBTools 5.

Parameters:
  • patterns (list of str) – The list of patterns to normalize.

  • base_dir (str) – The base directory to compare pattern paths to.

  • cwd (str, optional) –

    The current working directory to use for normalization.

    If not provided, the current directory will be computed.

Returns:

The normalized list of patterns.

Return type:

list of str

rbtools.utils.diffs.remove_filenames_matching_patterns(filenames: Iterable[str], *, patterns: List[str], base_dir: str) Iterator[str][source]

Return an iterable of all filenames that do not match any patterns.

Changed in version 4.0: patterns and base_dir must now be provided as keyword arguments. This will be mandatory in RBTools 5.

Parameters:
  • filenames (list of str) – The list of filenames to filter.

  • patterns (list of str) – The list of patterns used to match filenames to include.

  • base_dir (str) – The base director that filenames are expected to be relative to.

Yields:

str – Each filename that has been excluded.