hbllmutils.template.matcher_pair

This module provides a matcher pair system for matching and organizing files based on multiple matcher criteria.

The module implements a metaclass-based system that allows defining matcher pairs with multiple matcher fields and value fields. It enables matching files in directories using multiple matchers simultaneously and organizing the results into structured pair objects.

Classes:

_MatcherPairMeta: Metaclass for creating matcher pair classes with field validation BaseMatcherPair: Base class for defining and working with matcher pairs

Example::

>>> class MyMatcherPair(BaseMatcherPair):
...     matcher1: SomeMatcher
...     matcher2: AnotherMatcher
>>> pairs = MyMatcherPair.match_all('/path/to/directory')
>>> for pair in pairs:
...     print(pair.values_dict())

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 (e.g., same ID, version, etc.). 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__()

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])

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()

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()

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()

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()

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')