temparse 1.0.0__tar.gz → 1.1.0__tar.gz

{temparse-1.0.0 → temparse-1.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: temparse
-Version: 1.0.0
+Version: 1.1.0
 Summary: temparse is template + parse
 Author: jiang-zhexin
 Author-email: jiang-zhexin <162887873+jiang-zhexin@users.noreply.github.com>
@@ -116,6 +116,59 @@ assert parser.parse("foo + 3 = 3.14") == ("foo", 3, 3.14)
 assert parser.parse("bar + 7 = 2.72") == ("bar", 7, 2.72)
 ```
 
+## `Matcher` (Pattern Matching & Structured Parsing)
+
+Subclass `Matcher` with a `Parser` to match strings in `match/case` statements or parse strings directly into structured instances:
+
+```python
+from temparse import Matcher, MatchStr, Parser
+
+
+class OkResp(Matcher, parser=Parser(t'code={int};message="{str}";')):
+    code: int
+    message: str
+
+
+class ErrResp(Matcher, parser=Parser(t'code={int};error="{str}";')):
+    code: int
+    error: str
+
+
+def handle_response(raw: str) -> str:
+    # Wrap the string with MatchStr to enable pattern matching
+    match MatchStr(raw):
+        case OkResp(code, message):
+            return f"OK ({code}): {message}"
+        case ErrResp(code, error):
+            return f"Error ({code}): {error}"
+        case _:
+            return "Unknown response"
+
+
+assert handle_response('code=200;message="success";') == "OK (200): success"
+assert handle_response('code=400;error="bad request";') == "Error (400): bad request"
+```
+
+`Matcher` subclasses are also dataclasses that support keyword matching and `.parse()`:
+
+```python
+from temparse import Matcher, MatchStr, Parser
+
+
+class Point(Matcher, parser=Parser(t"x={int}, y={int}")):
+    x: int
+    y: int
+
+
+p = Point.parse("x=1, y=2")
+assert p == Point(x=1, y=2)
+
+# Wrap the string with MatchStr to enable pattern matching
+match MatchStr("x=0, y=5"):
+    case Point(x=0, y=y):
+        assert y == 5
+```
+
 ## License
 
 MIT

{temparse-1.0.0 → temparse-1.1.0}/README.md

@@ -100,6 +100,59 @@ assert parser.parse("foo + 3 = 3.14") == ("foo", 3, 3.14)
 assert parser.parse("bar + 7 = 2.72") == ("bar", 7, 2.72)
 ```
 
+## `Matcher` (Pattern Matching & Structured Parsing)
+
+Subclass `Matcher` with a `Parser` to match strings in `match/case` statements or parse strings directly into structured instances:
+
+```python
+from temparse import Matcher, MatchStr, Parser
+
+
+class OkResp(Matcher, parser=Parser(t'code={int};message="{str}";')):
+    code: int
+    message: str
+
+
+class ErrResp(Matcher, parser=Parser(t'code={int};error="{str}";')):
+    code: int
+    error: str
+
+
+def handle_response(raw: str) -> str:
+    # Wrap the string with MatchStr to enable pattern matching
+    match MatchStr(raw):
+        case OkResp(code, message):
+            return f"OK ({code}): {message}"
+        case ErrResp(code, error):
+            return f"Error ({code}): {error}"
+        case _:
+            return "Unknown response"
+
+
+assert handle_response('code=200;message="success";') == "OK (200): success"
+assert handle_response('code=400;error="bad request";') == "Error (400): bad request"
+```
+
+`Matcher` subclasses are also dataclasses that support keyword matching and `.parse()`:
+
+```python
+from temparse import Matcher, MatchStr, Parser
+
+
+class Point(Matcher, parser=Parser(t"x={int}, y={int}")):
+    x: int
+    y: int
+
+
+p = Point.parse("x=1, y=2")
+assert p == Point(x=1, y=2)
+
+# Wrap the string with MatchStr to enable pattern matching
+match MatchStr("x=0, y=5"):
+    case Point(x=0, y=y):
+        assert y == 5
+```
+
 ## License
 
 MIT

temparse-1.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[project]
+name = "temparse"
+version = "1.1.0"
+description = "temparse is template + parse"
+readme = "README.md"
+requires-python = ">=3.14"
+license = "MIT"
+classifiers = [
+    "Environment :: Web Environment",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Code Generators",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = []
+
+[[project.authors]]
+name = "jiang-zhexin"
+email = "162887873+jiang-zhexin@users.noreply.github.com"
+
+[project.urls]
+homepage = "https://github.com/jiang-zhexin/temparse"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.1.1",
+    "ruff>=0.17.2",
+    "ty>=0.0.92",
+]
+
+[build-system]
+requires = ["uv_build>=0.13.0,<0.14"]
+build-backend = "uv_build"

temparse-1.0.0/pyproject.toml → temparse-1.1.0/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "temparse"
-version = "1.0.0"
+version = "1.1.0"
 description = "temparse is template + parse"
 readme = "README.md"
 requires-python = ">=3.14"
@@ -24,10 +24,10 @@ homepage = "https://github.com/jiang-zhexin/temparse"
 [dependency-groups]
 dev = [
   "pytest>=9.1.1",
-  "ruff>=0.15.22",
-  "ty>=0.0.61",
+  "ruff>=0.17.2",
+  "ty>=0.0.92",
 ]
 
 [build-system]
-requires = ["uv_build>=0.11.15,<0.12.0"]
+requires = ["uv_build>=0.13.0,<0.14"]
 build-backend = "uv_build"

temparse-1.1.0/src/temparse/__init__.py

@@ -0,0 +1,276 @@
+import builtins
+import dataclasses
+import datetime
+import functools
+import json
+import re
+from collections.abc import Callable
+from string.templatelib import Interpolation, Template
+from typing import (
+    Any,
+    Literal,
+    Self,
+    cast,
+    dataclass_transform,
+    final,
+    get_origin,
+    is_typeddict,
+    overload,
+)
+
+__all__ = ["Conversion", "FormatConversion", "MatchStr", "Matcher", "Parser", "parse"]
+
+
+@final
+class Parser[*T]:
+    """
+    A compiled template parser that can be reused to parse multiple strings.
+
+    example:
+    ```python
+    parser = Parser[str, int, float](t"{str} + {int} = {float}")
+
+    parser.parse("foo + 3 = 3.14")
+    ```
+    """
+
+    def __init__(self, template: Template, flags: re.RegexFlag = re.NOFLAG) -> None:
+        if len(template.interpolations) == 0:
+            raise ValueError("template must contain at least one interpolation")
+
+        self._template = template
+        self._flags = flags
+        self._expression = "".join(
+            re.escape(item) if isinstance(item, str) else r"(.+?)" for item in template
+        )
+
+    @functools.cached_property
+    def _match_re(self) -> re.Pattern[str]:
+        return re.compile(self._expression, self._flags)
+
+    @overload
+    def parse(self, s: str, *, return_none: Literal[False] = False) -> tuple[*T]: ...
+
+    @overload
+    def parse(self, s: str, *, return_none: bool) -> tuple[*T] | None: ...
+
+    def parse(self, s: str, *, return_none: bool = False) -> tuple[*T] | None:
+        m = self._match_re.fullmatch(s)
+        if m is None:
+            if return_none:
+                return None
+            raise ValueError(f"invalid format: {s!r}")
+
+        return cast(
+            tuple[*T],
+            tuple(
+                _convert(text, interpolation)
+                for text, interpolation in zip(
+                    m.groups(), self._template.interpolations
+                )
+            ),
+        )
+
+
+@final
+class parse[*T]:
+    """
+    Parse string by template.
+
+    example:
+    ```python
+    city, year = parse[str, int](
+        t"I live in {str}, since {int}", "I live in Tokyo, since 2010"
+    )
+    assert city == "Tokyo"
+    assert year == 2010
+    ```
+    """
+
+    def __new__(cls, t: Template, s: str, flags: re.RegexFlag = re.NOFLAG) -> tuple[*T]:
+        """
+        Used to replace this function until [PEP 718](https://peps.python.org/pep-0718/) is accepted.
+
+        ```python
+        def parse[*T](t: Template, s: str, flags: re.RegexFlag = re.NOFLAG) -> tuple[*T]:
+            return Parser(t).parse(s)
+        ```
+        """
+        return Parser[*T](t, flags).parse(s)
+
+
+@dataclass_transform()
+class _MatcherMeta(type):
+    _parser: Parser
+    __match_args__: tuple[str, ...]
+
+    def __instancecheck__(cls, instance: object) -> bool:
+        if super().__instancecheck__(instance):
+            return True
+        return isinstance(instance, MatchStr) and instance._match(cls)
+
+
+class Matcher(metaclass=_MatcherMeta):
+    """
+    Base class for structural pattern matching and structured template parsing.
+
+    example:
+    ```python
+    class OkResp(Matcher, parser=Parser(t'code={int};message="{str}";')):
+        code: int
+        message: str
+
+
+    class ErrResp(Matcher, parser=Parser(t'code={int};error="{str}";')):
+        code: int
+        error: str
+
+
+    match MatchStr('code=400;error="bad request";'):
+        case OkResp(code, message):
+            print(f"OK ({code}): {message}")
+        case ErrResp(code, error):
+            print(f"Error ({code}): {error}")
+    ```
+    """
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None: ...
+
+    def __init_subclass__(cls, parser: Parser) -> None:
+        super().__init_subclass__()
+        dataclasses.dataclass(cls)
+        cls._parser = parser
+        if len(cls.__match_args__) != len(parser._template.interpolations):
+            raise ValueError("number of fields must match template interpolations")
+
+    @classmethod
+    def parse(cls, s: str) -> Self:
+        """
+        Parse a string using the class's parser and return an instance of the class.
+
+        example:
+        ```python
+        p = Point.parse("x=1, y=2")
+        assert p == Point(x=1, y=2)
+        ```
+        """
+        return cls(*cls._parser.parse(s))
+
+
+class MatchStr(str):
+    """
+    A `str` subclass that enables structural pattern matching with `Matcher` subclasses.
+
+    example:
+    ```python
+    match MatchStr("x=1, y=2"):
+        case Point(x, y):
+            assert x == 1 and y == 2
+    ```
+    """
+
+    def __init__(self, _: str, /) -> None:
+        self._cache: dict[_MatcherMeta, dict[str, Any] | None] = {}
+
+    def _match(self, cls: _MatcherMeta) -> bool:
+        if cls not in self._cache:
+            res = cls._parser.parse(self, return_none=True)
+            self._cache[cls] = (
+                dict(zip(cls.__match_args__, res)) if res is not None else None
+            )
+        if (fields := self._cache[cls]) is None:
+            return False
+        self.__dict__.update(fields)
+        return True
+
+
+@final
+class Conversion[T]:
+    """
+    Convert the string to your object.
+
+    example:
+    ```python
+    @Conversion
+    def percent(s: str) -> float:
+        return float(s.rstrip("%")) / 100
+
+
+    (result,) = parse[float](t"x = {percent}", "x = 30%")
+    assert result == 0.3
+    ```
+    """
+
+    def __init__(self, func: Callable[[str], T]) -> None:
+        self._convert = func
+        functools.update_wrapper(self, func)
+
+    def __call__(self, s: str) -> T:
+        return self._convert(s)
+
+
+@final
+class FormatConversion[T]:
+    """
+    Convert the string to your object with format.
+
+    example:
+    ```python
+    @FormatConversion
+    def between(s: str, spec: str) -> str:
+        lo, hi = spec.split(",")
+        return s[int(lo) : int(hi)]
+
+    (result,) = parse[str](t"{between:2,5}", "abcdefg")
+    assert result == "cde"
+    ```
+    """
+
+    def __init__(self, func: Callable[[str, str], T]) -> None:
+        self._convert = func
+        functools.update_wrapper(self, func)
+
+    def __call__(self, s: str, format: str) -> T:
+        return self._convert(s, format)
+
+
+def _convert(s: str, interp: Interpolation[Any]) -> Any:
+    origin = get_origin(interp.value) or interp.value
+    match origin:
+        case Conversion():
+            return interp.value(s)
+
+        case FormatConversion():
+            return interp.value(s, interp.format_spec)
+
+        case datetime.datetime:
+            return datetime.datetime.strptime(s, interp.format_spec).astimezone(
+                datetime.UTC
+            )
+
+        case datetime.date:
+            return datetime.date.strptime(s, interp.format_spec)
+
+        case datetime.time:
+            return datetime.time.strptime(s, interp.format_spec)
+
+        case builtins.int:
+            return int(s, base=int(interp.format_spec) if interp.format_spec else 0)
+
+        case builtins.float:
+            return float(s)
+
+        case builtins.complex:
+            return complex(s)
+
+        case builtins.str:
+            return s
+
+        case builtins.list | builtins.dict:
+            return json.loads(s)
+
+        case _ if origin is json or is_typeddict(origin):
+            return json.loads(s)
+
+        case _:
+            raise TypeError(f"unkown object: {interp.value}")

temparse-1.0.0/src/temparse/__init__.py

@@ -1,174 +0,0 @@
-import datetime
-import functools
-import json
-import re
-from collections.abc import Callable
-from string.templatelib import Interpolation, Template
-from typing import Any, cast, final, get_origin, is_typeddict
-
-__all__ = ["Conversion", "FormatConversion", "Parser", "parse"]
-
-
-@final
-class Parser[*T]:
-    """
-    A compiled template parser that can be reused to parse multiple strings.
-
-    example:
-    ```python
-    parser = Parser[str, int, float](t"{str} + {int} = {float}")
-
-    parser.parse("foo + 3 = 3.14")
-    ```
-    """
-
-    def __init__(self, template: Template, flags: re.RegexFlag = re.NOFLAG) -> None:
-        if len(template.interpolations) == 0:
-            raise ValueError("template must contain at least one interpolation")
-
-        self._template = template
-        self._flags = flags
-        self._expression = "".join(
-            re.escape(item) if isinstance(item, str) else r"(.+?)" for item in template
-        )
-
-    @functools.cached_property
-    def _match_re(self) -> re.Pattern[str]:
-        return re.compile(self._expression, self._flags)
-
-    def parse(self, s: str) -> tuple[*T]:
-        m = self._match_re.fullmatch(s)
-        if m is None:
-            raise ValueError(f"invalid format: {s!r}")
-
-        return cast(
-            tuple[*T],
-            tuple(
-                _convert(text, interpolation)
-                for text, interpolation in zip(
-                    m.groups(), self._template.interpolations
-                )
-            ),
-        )
-
-
-@final
-class parse[*T]:
-    """
-    Parse string by template.
-
-    example:
-    ```python
-    city, year = parse[str, int](
-        t"I live in {str}, since {int}", "I live in Tokyo, since 2010"
-    )
-    assert city == "Tokyo"
-    assert year == 2010
-    ```
-    """
-
-    def __new__(cls, t: Template, s: str, flags: re.RegexFlag = re.NOFLAG) -> tuple[*T]:
-        """
-        Used to replace this function until [PEP 718](https://peps.python.org/pep-0718/) is accepted.
-
-        ```python
-        def parse[*T](t: Template, s: str, flags: re.RegexFlag = re.NOFLAG) -> tuple[*T]:
-            return Parser(t).parse(s)
-        ```
-        """
-        return Parser[*T](t, flags).parse(s)
-
-
-@final
-class Conversion[T]:
-    """
-    Convert the string to your object.
-
-    example:
-    ```python
-    @Conversion
-    def percent(s: str) -> float:
-        return float(s.rstrip("%")) / 100
-
-
-    (result,) = parse[float](t"x = {percent}", "x = 30%")
-    assert result == 0.3
-    ```
-    """
-
-    __name__: str
-    __qualname__: str
-
-    def __init__(self, func: Callable[[str], T]) -> None:
-        self._convert = func
-        functools.update_wrapper(self, func)
-
-    def __call__(self, s: str) -> T:
-        return self._convert(s)
-
-
-@final
-class FormatConversion[T]:
-    """
-    Convert the string to your object with format.
-
-    example:
-    ```python
-    @FormatConversion
-    def between(s: str, spec: str) -> str:
-        lo, hi = spec.split(",")
-        return s[int(lo) : int(hi)]
-
-    (result,) = parse[str](t"{between:2,5}", "abcdefg")
-    assert result == "cde"
-    ```
-    """
-
-    __name__: str
-    __qualname__: str
-
-    def __init__(self, func: Callable[[str, str], T]) -> None:
-        self._convert = func
-        functools.update_wrapper(self, func)
-
-    def __call__(self, s: str, format: str) -> T:
-        return self._convert(s, format)
-
-
-def _convert(s: str, i: Interpolation[Any]) -> Any:
-    origin = get_origin(i.value) or i.value
-    match origin:
-        case Conversion():
-            return i.value(s)
-
-        case FormatConversion():
-            return i.value(s, i.format_spec)
-
-        case datetime.datetime:
-            return datetime.datetime.strptime(s, i.format_spec).astimezone(datetime.UTC)
-
-        case datetime.date:
-            return datetime.date.strptime(s, i.format_spec)
-
-        case datetime.time:
-            return datetime.time.strptime(s, i.format_spec)
-
-        case _ if origin is int:
-            return int(s, base=int(i.format_spec) if i.format_spec else 0)
-
-        case _ if origin is float:
-            return float(s)
-
-        case _ if origin is complex:
-            return complex(s)
-
-        case _ if origin is str:
-            return s
-
-        case _ if (
-            origin is list or origin is dict or origin is json or is_typeddict(origin)
-        ):
-            return json.loads(s)
-
-        case _:
-            raise TypeError(f"unkown object: {i.value}")