hbllmutils.template.matcher

Template-based file matcher utilities for extracting structured metadata from filenames.

This module implements a metaclass-driven pattern matching system that turns template patterns with typed placeholders into compiled regular expressions. It provides a convenient way to scan directories, match file names, and automatically convert captured fields into their declared Python types.

The module contains the following public component:

• BaseMatcher - Base class for defining file matchers using __pattern__ templates and type annotations.

Note

The metaclass _MatcherMeta is an internal implementation detail. It is intentionally not part of the public API.

Example:

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

BaseMatcher

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

Base class for file pattern matchers.

Subclasses define a __pattern__ template and annotate fields with their intended types. Instances represent matched files and provide convenient access to field values and file paths.

Variables:

• __pattern__ (str) – Template pattern with placeholders, such as "file_<id>.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__() → int

Get hash value of the matcher instance.

Returns:

Hash value based on field values

Return type:

int

__init__(full_path: str, **kwargs: Any) → None

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() → Dict[str, Any]

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 a 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() → Tuple[Any, ...]

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