hbllmutils.template.matcher_pair

Matcher pair utilities for organizing matched files into structured groups.

This module builds on hbllmutils.template.matcher.BaseMatcher to define pairing structures that group multiple matchers by shared value fields. It provides a metaclass that validates matcher field compatibility and a base pair class that can collect matching files from a directory.

The module contains the following main components:

• BaseMatcherPair - Base class for grouping multiple matchers by shared identifier fields.

Note

Pair classes rely on consistent value field definitions across all matcher types in the pair. If value fields differ between matchers, class creation will fail with TypeError.

Example:

>>> from hbllmutils.template.matcher import BaseMatcher
>>> from hbllmutils.template.matcher_pair import BaseMatcherPair
>>>
>>> class ImageMatcher(BaseMatcher):
...     __pattern__ = "image_<id>.png"
...     id: int
...
>>> class ThumbMatcher(BaseMatcher):
...     __pattern__ = "thumb_<id>.png"
...     id: int
...
>>> class ImagePair(BaseMatcherPair):
...     image: ImageMatcher
...     thumb: ThumbMatcher
...
>>> pairs = ImagePair.match_all("/path/to/images")
>>> for pair in pairs:
...     print(pair.values_dict(), pair.image.full_path, pair.thumb.full_path)

BaseMatcherPair

class hbllmutils.template.matcher_pair.BaseMatcherPair(values: Dict[str, Any], instances: Dict[str, BaseMatcher])

Base class for matcher pairs that group multiple matchers with shared value fields.

A matcher pair represents a collection of matchers that all match files with the same set of identifying values (for example, an ID or version). This class provides functionality to match files in directories and organize them into structured pairs.

Variables:

• __fields__ (Dict[str, Type[BaseMatcher]]) – Dictionary mapping field names to matcher types.

• __field_names__ (List[str]) – List of matcher field names.

• __value_fields__ (Dict[str, type]) – Dictionary mapping value field names to types.

• __value_field_names__ (List[str]) – List of value field names.

Example:

>>> class ImagePair(BaseMatcherPair):
...     image: ImageMatcher
...     thumbnail: ThumbnailMatcher
>>> pairs = ImagePair.match_all('/path/to/images')
>>> for pair in pairs:
...     print(f"ID: {pair.id}, Image: {pair.image}, Thumbnail: {pair.thumbnail}")

__hash__() → int

Get hash value of the matcher pair instance.

Returns:

Hash value based on all field values.

Return type:

int

Example:

>>> hash(pair)
123456789

__init__(values: Dict[str, Any], instances: Dict[str, BaseMatcher]) → None

Initialize a matcher pair with values and matcher instances.

Parameters:

• values (Dict[str, Any]) – Dictionary of value field names to their values.

• instances (Dict[str, BaseMatcher]) – Dictionary of matcher field names to matcher instances.

Raises:

ValueError – If unknown fields are provided or required fields are missing.

Example:

>>> pair = ImagePair(
...     values={'id': '001'},
...     instances={'image': image_matcher, 'thumbnail': thumb_matcher}
... )

__repr__() → str

Get detailed string representation of the matcher pair.

Returns:

String representation showing all value and matcher fields.

Return type:

str

__str__() → str

Get string representation of the matcher pair.

Returns:

String representation showing all value and matcher fields.

Return type:

str

Example:

>>> str(pair)
'ImagePair(id='001', image=ImageMatcher(...), thumbnail=ThumbnailMatcher(...))'

dict() → Dict[str, Any]

Get dictionary of all field names to values (both value fields and matcher fields).

Returns:

Dictionary mapping all field names to their values.

Return type:

dict

Example:

>>> pair.dict()
{'id': '001', 'version': 'v1', 'image': ImageMatcher(...), 'thumbnail': ThumbnailMatcher(...)}

classmethod match_all(directory: str | Path) → List[BaseMatcherPair]

Match all files in a directory and group them into matcher pairs.

This method uses all defined matchers to find matching files in the directory, then groups files with the same identifying values into pairs.

Parameters:

directory (Union[str, Path]) – Path to the directory to search.

Returns:

List of matcher pairs found in the directory, sorted naturally.

Return type:

List[BaseMatcherPair]

Example:

>>> pairs = ImagePair.match_all('/path/to/images')
>>> print(f"Found {len(pairs)} image pairs")
Found 5 image pairs

tuple() → Tuple[Any, ...]

Get tuple of all field values (both value fields and matcher fields).

Returns:

Tuple containing all field values in order.

Return type:

tuple

Example:

>>> pair.tuple()
('001', 'v1', ImageMatcher(...), ThumbnailMatcher(...))

values_dict() → Dict[str, Any]

Get dictionary of value field names to values.

Returns:

Dictionary mapping value field names to their values.

Return type:

dict

Example:

>>> pair.values_dict()
{'id': '001', 'version': 'v1'}

values_tuple() → Tuple[Any, ...]

Get tuple of value field values.

Returns:

Tuple containing values of all value fields in order.

Return type:

tuple

Example:

>>> pair.values_tuple()
('001', 'v1')