rebulk 4.2.2__tar.gz → 4.3.0__tar.gz

{rebulk-4.2.2 → rebulk-4.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rebulk
-Version: 4.2.2
+Version: 4.3.0
 Summary: Rebulk - Define simple search patterns in bulk to perform advanced matching on any string.
 Keywords: re,regexp,regular expression,search,pattern,string,match
 Author: Rémi Alvergnat
@@ -533,7 +533,10 @@ It has the following additional methods and properties on it.
     `Match.value` as value.
 
     if `enforce_list` is `True`, all values will be wrapped to a list,
-    even if a single value is found.
+    even if a single value is found. This form has a predictable, typed
+    shape (`MatchesDict[list]`), unlike the default which is a scalar *or*
+    a list per name. For fully typed access, prefer the typed retrieval
+    API above (`Key` and `Matches.to(...)`).
 
     If `details` is True, `Match.value` objects are replaced with
     complete `Match` object.
@@ -567,6 +570,17 @@ returns `T | None`, and `matches.all(key)` returns `list[T]`.
 
 ```
 
+For values that aren't built straight from a string, pass an explicit
+`formatter` (a `(str) -> T` converter); the key stays fully typed as `T`.
+
+```python
+>>> from datetime import date
+>>> released = Key("released", date, formatter=date.fromisoformat)
+>>> Rebulk().regex(r'\d{4}-\d{2}-\d{2}', key=released).matches("on 2008-01-02")[released]
+datetime.date(2008, 1, 2)
+
+```
+
 You can also project the matches onto a typed dataclass with `to`. Each field
 is filled from matches sharing its name: a `list[...]` field collects all
 values, any other field takes the first, and unmatched fields fall back to

{rebulk-4.2.2 → rebulk-4.3.0}/README.md

@@ -508,7 +508,10 @@ It has the following additional methods and properties on it.
     `Match.value` as value.
 
     if `enforce_list` is `True`, all values will be wrapped to a list,
-    even if a single value is found.
+    even if a single value is found. This form has a predictable, typed
+    shape (`MatchesDict[list]`), unlike the default which is a scalar *or*
+    a list per name. For fully typed access, prefer the typed retrieval
+    API above (`Key` and `Matches.to(...)`).
 
     If `details` is True, `Match.value` objects are replaced with
     complete `Match` object.
@@ -542,6 +545,17 @@ returns `T | None`, and `matches.all(key)` returns `list[T]`.
 
 ```
 
+For values that aren't built straight from a string, pass an explicit
+`formatter` (a `(str) -> T` converter); the key stays fully typed as `T`.
+
+```python
+>>> from datetime import date
+>>> released = Key("released", date, formatter=date.fromisoformat)
+>>> Rebulk().regex(r'\d{4}-\d{2}-\d{2}', key=released).matches("on 2008-01-02")[released]
+datetime.date(2008, 1, 2)
+
+```
+
 You can also project the matches onto a typed dataclass with `to`. Each field
 is filled from matches sharing its name: a `list[...]` field collects all
 values, any other field takes the first, and unmatched fields fall back to

{rebulk-4.2.2 → rebulk-4.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "rebulk"
-version = "4.2.2"
+version = "4.3.0"
 description = "Rebulk - Define simple search patterns in bulk to perform advanced matching on any string."
 readme = "README.md"
 requires-python = ">=3.10"

{rebulk-4.2.2 → rebulk-4.3.0}/rebulk/__version__.py

@@ -3,4 +3,4 @@
 Version module
 """
 
-__version__ = "4.2.2"
+__version__ = "4.3.0"

{rebulk-4.2.2 → rebulk-4.3.0}/rebulk/builder.py

@@ -27,12 +27,13 @@ log = getLogger(__name__).log
 
 def _apply_key(key: Key[Any] | None, kwargs: dict[str, Any]) -> dict[str, Any]:
     """
-    Inject a typed :class:`~rebulk.key.Key`'s name and value type (used as
-    formatter) into pattern kwargs, without overriding explicit values.
+    Inject a typed :class:`~rebulk.key.Key`'s name and converter (its explicit
+    ``formatter`` or its ``value_type``) into pattern kwargs, without overriding
+    explicit values.
     """
     if key is not None:
         kwargs.setdefault("name", key.name)
-        kwargs.setdefault("formatter", key.value_type)
+        kwargs.setdefault("formatter", key.converter)
     return kwargs
 
 

{rebulk-4.2.2 → rebulk-4.3.0}/rebulk/chain.py

@@ -324,7 +324,7 @@ class ChainPart(BasePattern):
         if max_match_index + 1 < self.repeater_start:
             raise _InvalidChainException
 
-    def chain(self) -> Any:
+    def chain(self) -> Chain:
         """
         Add patterns chain, using configuration from this chain
 
@@ -354,7 +354,7 @@ class ChainPart(BasePattern):
         """
         return self._hidden
 
-    def regex(self, *pattern: Any, **kwargs: Any) -> Any:
+    def regex(self, *pattern: Any, **kwargs: Any) -> ChainPart:
         """
         Add re pattern
 
@@ -365,9 +365,11 @@ class ChainPart(BasePattern):
         :return:
         :rtype:
         """
-        return self._chain.regex(*pattern, **kwargs)
+        # The builder's regex/string/functional are typed `-> Self` (Chain), but
+        # Chain.pattern() yields a ChainPart, which is what is actually returned.
+        return cast("ChainPart", self._chain.regex(*pattern, **kwargs))
 
-    def functional(self, *pattern: Any, **kwargs: Any) -> Any:
+    def functional(self, *pattern: Any, **kwargs: Any) -> ChainPart:
         """
         Add functional pattern
 
@@ -378,9 +380,9 @@ class ChainPart(BasePattern):
         :return:
         :rtype:
         """
-        return self._chain.functional(*pattern, **kwargs)
+        return cast("ChainPart", self._chain.functional(*pattern, **kwargs))
 
-    def string(self, *pattern: Any, **kwargs: Any) -> Any:
+    def string(self, *pattern: Any, **kwargs: Any) -> ChainPart:
         """
         Add string pattern
 
@@ -391,7 +393,7 @@ class ChainPart(BasePattern):
         :return:
         :rtype:
         """
-        return self._chain.string(*pattern, **kwargs)
+        return cast("ChainPart", self._chain.string(*pattern, **kwargs))
 
     def close(self) -> Any:
         """

rebulk-4.3.0/rebulk/key.py

@@ -0,0 +1,58 @@
+#!/usr/bin/env python
+"""
+Typed keys binding a match name to its value type for type-safe retrieval.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, is_dataclass
+from typing import TYPE_CHECKING, Generic, TypeVar, is_typeddict
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+T = TypeVar("T")
+
+
+@dataclass(frozen=True)
+class Key(Generic[T]):
+    r"""
+    A typed handle for a named match.
+
+    ``name`` is the match name to declare and look up; ``value_type`` is the type
+    of the match value (e.g. ``int``, ``str``, ``float``). ``formatter``, if
+    given, is the ``(str) -> T`` converter applied to the matched substring; when
+    omitted it defaults to ``value_type`` itself (so ``Key("year", int)`` casts
+    with ``int``). Use ``formatter`` for values not constructible straight from a
+    string, e.g. ``Key("released", date, formatter=date.fromisoformat)``.
+
+    Passing a key to a builder method (``key=...``) wires up both the match
+    ``name`` and the formatter, so that ``matches[key]`` and ``matches.all(key)``
+    return precise types instead of ``Any``.
+
+    ``value_type`` must be a scalar type (it/the formatter is applied to a single
+    matched substring). Structured types (``dataclass`` / ``TypedDict``) cannot
+    be built from one string and are rejected here; assemble them from several
+    named matches with :meth:`Matches.to` instead.
+
+    >>> from rebulk import Rebulk, Key
+    >>> year = Key("year", int)
+    >>> Rebulk().regex(r"\d{4}", key=year).matches("born in 1984")[year]
+    1984
+    """
+
+    name: str
+    value_type: type[T]
+    formatter: Callable[[str], T] | None = None
+
+    def __post_init__(self) -> None:
+        if is_dataclass(self.value_type) or is_typeddict(self.value_type):
+            raise TypeError(
+                f"Key value_type must be a scalar type, not {self.value_type!r}; "
+                "build structured types from several matches with Matches.to(...) instead"
+            )
+
+    @property
+    def converter(self) -> Callable[[str], T]:
+        """The ``(str) -> T`` converter: the explicit ``formatter`` or ``value_type``."""
+        return self.formatter if self.formatter is not None else self.value_type

{rebulk-4.2.2 → rebulk-4.3.0}/rebulk/match.py

@@ -10,7 +10,18 @@ import dataclasses
 import itertools
 from collections import OrderedDict, defaultdict
 from collections.abc import Callable, Iterable, KeysView, MutableSequence
-from typing import TYPE_CHECKING, Any, TypeVar, cast, get_args, get_origin, get_type_hints, is_typeddict, overload
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Literal,
+    TypeVar,
+    cast,
+    get_args,
+    get_origin,
+    get_type_hints,
+    is_typeddict,
+    overload,
+)
 
 from .debug import defined_at
 from .key import Key
@@ -22,11 +33,17 @@ if TYPE_CHECKING:
 
 T = TypeVar("T")
 M = TypeVar("M")
+_V = TypeVar("_V")
 
 
-class MatchesDict(OrderedDict):  # type: ignore[type-arg]
+class MatchesDict(OrderedDict[str | None, _V]):
     """
     A custom dict with matches property.
+
+    Generic over the value type: ``to_dict(enforce_list=True)`` returns a
+    ``MatchesDict[list[Any]]`` (every name maps to a list), the other modes a
+    ``MatchesDict[Any]`` (a name maps to a single value or a list, depending on
+    the matches).
     """
 
     def __init__(self) -> None:
@@ -714,7 +731,13 @@ class _BaseMatches(MutableSequence):  # type: ignore[type-arg]
         """
         return self._tag_dict.keys()
 
-    def to_dict(self, details: bool = False, first_value: bool = False, enforce_list: bool = False) -> MatchesDict:
+    @overload
+    def to_dict(
+        self, details: bool = ..., first_value: bool = ..., *, enforce_list: Literal[True]
+    ) -> MatchesDict[list[Any]]: ...
+    @overload
+    def to_dict(self, details: bool = ..., first_value: bool = ..., enforce_list: bool = ...) -> MatchesDict[Any]: ...
+    def to_dict(self, details: bool = False, first_value: bool = False, enforce_list: bool = False) -> MatchesDict[Any]:
         """
         Converts matches to a dict object.
         :param details if True, values will be complete Match object, else it will be only string Match.value property
@@ -728,7 +751,7 @@ class _BaseMatches(MutableSequence):  # type: ignore[type-arg]
         :return:
         :rtype: dict
         """
-        ret = MatchesDict()
+        ret: MatchesDict[Any] = MatchesDict()
         for match in sorted(self):
             value = match if details else match.value
             ret.matches[match.name].append(match)

{rebulk-4.2.2 → rebulk-4.3.0}/rebulk/test/test_key.py

@@ -6,6 +6,7 @@ Tests for typed Key retrieval (POC for type-safe value access).
 from __future__ import annotations
 
 from dataclasses import dataclass
+from datetime import date
 from typing import TYPE_CHECKING, TypedDict
 
 import pytest
@@ -31,6 +32,20 @@ def test_key_scalar_retrieval() -> None:
     assert matches[title] == "Big Buck Bunny"
 
 
+def test_key_converter_defaults_to_value_type() -> None:
+    assert Key("year", int).converter is int
+    fmt = date.fromisoformat
+    assert Key("released", date, formatter=fmt).converter is fmt
+
+
+def test_key_with_explicit_formatter() -> None:
+    released = Key("released", date, formatter=date.fromisoformat)
+    matches = Rebulk().regex(r"\d{4}-\d{2}-\d{2}", key=released).matches("on 2008-01-02 ...")
+
+    assert matches[released] == date(2008, 1, 2)
+    assert matches.all(released) == [date(2008, 1, 2)]
+
+
 def test_key_rejects_structured_value_type() -> None:
     @dataclass
     class Movie:
@@ -74,5 +89,8 @@ if TYPE_CHECKING:
         assert_type(matches[year], "int | None")
         assert_type(matches.all(year), list[int])
         assert_type(matches[title], "str | None")
+        # A formatter-based key keeps the precise value type.
+        released = Key("released", date, formatter=date.fromisoformat)
+        assert_type(matches[released], "date | None")
         # Existing integer / slice access stays intact.
         assert_type(matches[0], Match)

{rebulk-4.2.2 → rebulk-4.3.0}/rebulk/test/test_match.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Any
 
 import pytest
 
@@ -632,3 +632,7 @@ if TYPE_CHECKING:
         assert_type(matches.named("title", index=0), "Match | None")
         assert_type(matches.named("title", 0), "Match | None")
         assert_type(matches.named("title", lambda m: True), "list[Match]")
+
+    def _to_dict_reveal_types(matches: Matches) -> None:
+        # enforce_list=True -> every value is a list (predictable, typable)
+        assert_type(matches.to_dict(enforce_list=True)["x"], list[Any])

rebulk-4.2.2/rebulk/key.py

@@ -1,45 +0,0 @@
-#!/usr/bin/env python
-"""
-Typed keys binding a match name to its value type for type-safe retrieval.
-"""
-
-from __future__ import annotations
-
-from dataclasses import dataclass, is_dataclass
-from typing import Generic, TypeVar, is_typeddict
-
-T = TypeVar("T")
-
-
-@dataclass(frozen=True)
-class Key(Generic[T]):
-    r"""
-    A typed handle for a named match.
-
-    ``name`` is the match name to declare and look up; ``value_type`` is the type
-    of the match value and the ``(str) -> T`` converter applied to produce it
-    (e.g. ``int``, ``str``, ``float``). Passing a key to a builder method
-    (``key=...``) wires up both the match ``name`` and ``formatter``, so that
-    ``matches[key]`` and ``matches.all(key)`` return precise types instead of
-    ``Any``.
-
-    ``value_type`` must be a scalar ``(str) -> T`` converter: it is applied to a
-    single matched substring. Structured types (``dataclass`` / ``TypedDict``)
-    cannot be built from one string and are rejected here; assemble them from
-    several named matches with :meth:`Matches.to` instead.
-
-    >>> from rebulk import Rebulk, Key
-    >>> year = Key("year", int)
-    >>> Rebulk().regex(r"\d{4}", key=year).matches("born in 1984")[year]
-    1984
-    """
-
-    name: str
-    value_type: type[T]
-
-    def __post_init__(self) -> None:
-        if is_dataclass(self.value_type) or is_typeddict(self.value_type):
-            raise TypeError(
-                f"Key value_type must be a scalar (str) -> T converter, not {self.value_type!r}; "
-                "build structured types from several matches with Matches.to(...) instead"
-            )