hbllmutils.template.matcher

File pattern matching module for extracting structured information from filenames.

This module provides a metaclass-based pattern matching system that allows defining file matchers using template patterns with typed placeholders. It supports automatic field extraction, type conversion, and file discovery in directories.

The main components are: - MatcherMeta: Metaclass that processes pattern templates and generates regex patterns - BaseMatcher: Base class for creating custom file matchers with pattern matching capabilities

Example::

>>> class ImageMatcher(BaseMatcher):
...     __pattern__ = "image_<id>_<name>.png"
...     id: int
...     name: str
>>> matcher = ImageMatcher.match("/path/to/images")
>>> print(matcher.id, matcher.name)

BaseMatcher

class hbllmutils.template.matcher.BaseMatcher(full_path: str, **kwargs)

Base class for file pattern matchers.

This class provides functionality to match files based on template patterns and automatically extract typed fields from filenames. Subclasses should define __pattern__ and type-annotated fields.

Variables:

• __pattern__ (str) – Template pattern with placeholders (e.g., “file_<id>_<name>.txt”)

• __recursively__ (bool) – Whether to search directories recursively

Example::

>>> class LogMatcher(BaseMatcher):
...     __pattern__ = "log_<date>_<level>.txt"
...     date: str
...     level: str
>>> matcher = LogMatcher.match("/var/logs")
>>> if matcher:
...     print(f"Found log: {matcher.date} - {matcher.level}")

__hash__()

Get hash value of the matcher instance.

Returns:

Hash value based on field values

Return type:

int

__init__(full_path: str, **kwargs)

Initialize matcher instance with extracted field values.

Parameters:

• full_path (str) – Complete path to the matched file

• kwargs (Any) – Extracted field values from the filename

Raises:

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

Example::

>>> matcher = ImageMatcher("/path/image_001_test.png", id=1, name="test")
>>> print(matcher.id, matcher.name)
1 test

__repr__() → str

Get representation string of the matcher instance.

Returns:

Representation string

Return type:

str

__str__() → str

Get string representation of the matcher instance.

Returns:

String representation showing field values and full path

Return type:

str

dict()

Get field values as a dictionary.

Returns:

Dictionary mapping field names to values

Return type:

dict

Example::

>>> matcher = ImageMatcher("/path/image_001_test.png", id=1, name="test")
>>> matcher.dict()
{'id': 1, 'name': 'test'}

classmethod exists(directory: str | Path) → bool

Check if any file matching the pattern exists in the specified directory.

Parameters:

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

Returns:

True if matching file exists, False otherwise

Return type:

bool

Example::

>>> if ImageMatcher.exists("/path/to/images"):
...     print("Images found!")

classmethod match(directory: str | Path) → BaseMatcher | None

Match the first file that conforms to the pattern in the specified directory.

Parameters:

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

Returns:

Matched file instance, or None if not found

Return type:

Optional[BaseMatcher]

Example::

>>> matcher = ImageMatcher.match("/path/to/images")
>>> if matcher:
...     print(f"Found: {matcher.full_path}")

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

Match all files that conform to the pattern in the specified directory.

Parameters:

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

Returns:

List of matched file instances

Return type:

List[BaseMatcher]

Example::

>>> matchers = ImageMatcher.match_all("/path/to/images")
>>> print(f"Found {len(matchers)} images")

tuple()

Get field values as a tuple.

Returns:

Tuple of field values in definition order

Return type:

tuple

Example::

>>> matcher = ImageMatcher("/path/image_001_test.png", id=1, name="test")
>>> matcher.tuple()
(1, 'test')