msgspex 1.0.0__tar.gz

msgspex-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 luwqz1
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

msgspex-1.0.0/PKG-INFO

@@ -0,0 +1,97 @@
+Metadata-Version: 2.4
+Name: msgspex
+Version: 1.0.0
+Summary: An extra msgspec collection of custom types, casters, encode hooks and decode hooks.
+Author-email: luwqz1 <howluwqz1@gmail.com>
+Maintainer-email: luwqz1 <howluwqz1@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 luwqz1
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Source, https://github.com/luwqz1/msgspextra
+Project-URL: Bug Tracker, https://github.com/luwqz1/msgspextra/issues
+Keywords: msgspec,custom types,decode hooks,encode hooks,msgspex,fast model,dataclasses,kungfu
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: kungfu-fp>=1.0.0
+Requires-Dist: msgspec>=0.20.0
+Dynamic: license-file
+
+# msgspex
+
+A collection of `msgspec` extensions: custom types, cast helpers, `decode hooks`, and `encode hooks`.
+
+## Quick Start
+
+```python
+import msgspex
+from msgspex.custom_types import Email, datetime
+
+value = msgspex.decoder.decode('"user@example.com"', type=Email)
+dt = msgspex.decoder.decode('"2024-01-02T03:04:05Z"', type=datetime)
+payload = msgspex.encoder.encode(dt)
+```
+
+After `import msgspex`, all hooks and types are registered automatically.
+
+## Custom Types
+
+### 1. Types from kungfu
+
+- `Option[T]` — optional value type based on `kungfu` (`Some | Nothing | msgspec.UnsetType`).
+
+There is also decode-hook integration for `kungfu.Sum` (not a custom type, but supported by the decoder).
+
+### 2. Types Derived from stdlib
+
+- `date` — re-export of `datetime.date`.
+- `datetime` — meta-type that covers `StringTimestampDatetime`, `IntTimestampDatetime`, `FloatTimestampDatetime`, `ISODatetime` (alias: `isodatetime`), and `datetime.datetime`.
+- `timedelta` — subclass of `datetime.timedelta` with cast support.
+- `StrEnum`, `IntEnum`, `FloatEnum`, `BaseEnumMeta` — `enum` extensions for stable handling of unknown values.
+- `Literal` — runtime type conceptually compatible with `typing.Literal`.
+
+### 3. OpenAPI-Oriented Types
+
+- `Email` — `format: email`
+- `IDNEmail` — `format: idn-email`
+- `URI` — `format: uri`
+- `URIReference` — `format: uri-reference`
+- `IRI` — `format: iri`
+- `IRIReference` — `format: iri-reference`
+- `Hostname` — `format: hostname`
+- `IDNHostname` — `format: idn-hostname`
+- `IPv4` — `format: ipv4`
+- `IPv6` — `format: ipv6`
+- `JsonPointer` — `format: json-pointer`
+- `RelativeJsonPointer` — `format: relative-json-pointer`
+- `Regex` — `format: regex`
+- `Int32`, `Int64` — range-limited integer types
+- `Float32`, `Float64` — finite, range-limited floating-point types
+
+`UUID` is not redefined here, because it is already supported by `msgspec`.

msgspex-1.0.0/README.md

@@ -0,0 +1,52 @@
+# msgspex
+
+A collection of `msgspec` extensions: custom types, cast helpers, `decode hooks`, and `encode hooks`.
+
+## Quick Start
+
+```python
+import msgspex
+from msgspex.custom_types import Email, datetime
+
+value = msgspex.decoder.decode('"user@example.com"', type=Email)
+dt = msgspex.decoder.decode('"2024-01-02T03:04:05Z"', type=datetime)
+payload = msgspex.encoder.encode(dt)
+```
+
+After `import msgspex`, all hooks and types are registered automatically.
+
+## Custom Types
+
+### 1. Types from kungfu
+
+- `Option[T]` — optional value type based on `kungfu` (`Some | Nothing | msgspec.UnsetType`).
+
+There is also decode-hook integration for `kungfu.Sum` (not a custom type, but supported by the decoder).
+
+### 2. Types Derived from stdlib
+
+- `date` — re-export of `datetime.date`.
+- `datetime` — meta-type that covers `StringTimestampDatetime`, `IntTimestampDatetime`, `FloatTimestampDatetime`, `ISODatetime` (alias: `isodatetime`), and `datetime.datetime`.
+- `timedelta` — subclass of `datetime.timedelta` with cast support.
+- `StrEnum`, `IntEnum`, `FloatEnum`, `BaseEnumMeta` — `enum` extensions for stable handling of unknown values.
+- `Literal` — runtime type conceptually compatible with `typing.Literal`.
+
+### 3. OpenAPI-Oriented Types
+
+- `Email` — `format: email`
+- `IDNEmail` — `format: idn-email`
+- `URI` — `format: uri`
+- `URIReference` — `format: uri-reference`
+- `IRI` — `format: iri`
+- `IRIReference` — `format: iri-reference`
+- `Hostname` — `format: hostname`
+- `IDNHostname` — `format: idn-hostname`
+- `IPv4` — `format: ipv4`
+- `IPv6` — `format: ipv6`
+- `JsonPointer` — `format: json-pointer`
+- `RelativeJsonPointer` — `format: relative-json-pointer`
+- `Regex` — `format: regex`
+- `Int32`, `Int64` — range-limited integer types
+- `Float32`, `Float64` — finite, range-limited floating-point types
+
+`UUID` is not redefined here, because it is already supported by `msgspec`.

msgspex-1.0.0/msgspex/__init__.py

@@ -0,0 +1,14 @@
+"""An extra `msgspec` collection of custom types, casters, encode hooks and decode hooks."""
+
+# ruff: noqa: F401, F403
+# type: ignore
+
+from msgspex.caster import *
+from msgspex.casters import *
+from msgspex.custom_types import *
+from msgspex.decode_hooks import *
+from msgspex.decoder import *
+from msgspex.encode_hooks import *
+from msgspex.encoder import *
+from msgspex.model import *
+from msgspex.tools import *

msgspex-1.0.0/msgspex/caster.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+import abc
+import typing
+
+
+def is_supports_cast(obj: typing.Any, /) -> typing.TypeGuard[SupportsCast]:
+    return isinstance(obj, SupportsCast)
+
+
+@typing.runtime_checkable
+class SupportsCast(typing.Protocol):
+    @classmethod
+    @abc.abstractmethod
+    def cast(cls, obj: typing.Any) -> typing.Self: ...
+
+
+__all__ = ("SupportsCast", "is_supports_cast")

msgspex-1.0.0/msgspex/casters/__init__.py

@@ -0,0 +1,3 @@
+from msgspex.casters.datetime import datetime, timedelta
+
+__all__ = ("datetime", "timedelta")

msgspex-1.0.0/msgspex/casters/datetime.py

@@ -0,0 +1,12 @@
+import datetime as dt
+import typing
+
+from msgspex.caster import SupportsCast
+from msgspex.custom_types.datetime import datetime, timedelta
+from msgspex.encoder import encoder
+
+encoder.add_cast_type(dt.datetime, typing.cast("type[SupportsCast]", datetime))
+encoder.add_cast_type(dt.timedelta, typing.cast("type[SupportsCast]", timedelta))
+
+
+__all__ = ("datetime", "timedelta")

msgspex-1.0.0/msgspex/custom_types/__init__.py

@@ -0,0 +1,52 @@
+from msgspex.custom_types.datetime import (
+    FloatTimestampDatetime,
+    IntTimestampDatetime,
+    StringTimestampDatetime,
+    date,
+    datetime,
+    isodatetime,
+    timedelta,
+)
+from msgspex.custom_types.email import Email, IDNEmail
+from msgspex.custom_types.enum import BaseEnumMeta, FloatEnum, IntEnum, StrEnum
+from msgspex.custom_types.hostname import Hostname, IDNHostname
+from msgspex.custom_types.ip import IPv4, IPv6
+from msgspex.custom_types.json_pointer import JsonPointer, RelativeJsonPointer
+from msgspex.custom_types.literal import Literal
+from msgspex.custom_types.numeric import Float32, Float64, Int32, Int64
+from msgspex.custom_types.option import Option
+from msgspex.custom_types.regex import Regex
+from msgspex.custom_types.uri import IRI, URI, IRIReference, URIReference
+
+__all__ = (
+    "IRI",
+    "URI",
+    "BaseEnumMeta",
+    "Email",
+    "Float32",
+    "Float64",
+    "FloatEnum",
+    "FloatTimestampDatetime",
+    "Hostname",
+    "IDNEmail",
+    "IDNHostname",
+    "IPv4",
+    "IPv6",
+    "IRIReference",
+    "Int32",
+    "Int64",
+    "IntEnum",
+    "IntTimestampDatetime",
+    "JsonPointer",
+    "Literal",
+    "Option",
+    "Regex",
+    "RelativeJsonPointer",
+    "StrEnum",
+    "StringTimestampDatetime",
+    "URIReference",
+    "date",
+    "datetime",
+    "isodatetime",
+    "timedelta",
+)

msgspex-1.0.0/msgspex/custom_types/datetime.py

@@ -0,0 +1,79 @@
+import datetime as dt
+import typing
+from datetime import date
+
+from msgspex.caster import SupportsCast
+
+
+class Datetime(dt.datetime, SupportsCast):
+    @classmethod
+    def cast(cls, obj: dt.datetime) -> typing.Self:
+        return cls.fromtimestamp(timestamp=obj.timestamp(), tz=obj.tzinfo)
+
+
+class StringTimestampDatetime(Datetime):
+    """String timestamp datetime."""
+
+    is_from_digits_string: bool = False
+    is_from_float_string: bool = False
+
+    @classmethod
+    def from_digits_string(cls, digits: str, /) -> typing.Self:
+        obj = cls.fromtimestamp(timestamp=int(digits), tz=dt.timezone.utc)
+        obj.is_from_digits_string = True
+        return obj
+
+    @classmethod
+    def from_float_string(cls, float_str: str, /) -> typing.Self:
+        obj = cls.fromtimestamp(timestamp=float(float_str), tz=dt.timezone.utc)
+        obj.is_from_float_string = True
+        return obj
+
+
+class IntTimestampDatetime(Datetime):
+    """Integer timestamp datetime."""
+
+
+class FloatTimestampDatetime(Datetime):
+    """Float timestamp datetime."""
+
+
+class ISODatetime(Datetime):
+    """ISO datetime."""
+
+
+isodatetime = ISODatetime
+
+
+class timedelta(dt.timedelta, SupportsCast):  # noqa: N801  # type: ignore
+    @classmethod
+    def cast(cls, obj: dt.timedelta) -> typing.Self:
+        return cls(seconds=obj.total_seconds())
+
+
+DT: typing.TypeAlias = StringTimestampDatetime | IntTimestampDatetime | FloatTimestampDatetime | ISODatetime | dt.datetime
+
+
+if typing.TYPE_CHECKING:
+    from datetime import datetime, timedelta  # type: ignore
+
+else:
+
+    class datetimemeta(type):  # noqa: N801
+        def __instancecheck__(cls, __instance: typing.Any) -> bool:
+            return isinstance(__instance, DT)
+
+    class datetime(metaclass=datetimemeta):  # noqa: N801
+        pass
+
+
+__all__ = (
+    "FloatTimestampDatetime",
+    "ISODatetime",
+    "IntTimestampDatetime",
+    "StringTimestampDatetime",
+    "date",
+    "datetime",
+    "isodatetime",
+    "timedelta",
+)

msgspex-1.0.0/msgspex/custom_types/email.py

@@ -0,0 +1,156 @@
+import re
+import typing
+from annotationlib import type_repr
+
+LOCAL_PART_PATTERN: typing.Final = re.compile(r"^[A-Za-z0-9!#$%&'*+/=?^_`{|}~.-]+$")
+LABEL_PATTERN: typing.Final = re.compile(r"^[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?$")
+
+
+def validate_email(email: typing.Any, /) -> str:
+    if not isinstance(email, str):
+        raise TypeError(f"Email must be `str`, got `{type_repr(email.__class__)}`.")
+
+    if not email:
+        raise TypeError("Email must be non-empty.")
+
+    if any(ch.isspace() for ch in email):
+        raise TypeError("Email must not contain whitespace.")
+
+    if email.count("@") != 1:
+        raise TypeError("Email must contain exactly one `@`.")
+
+    local, domain = email.split("@", 1)
+
+    if len(email) > 254:
+        raise TypeError("Email is too long (max 254 characters).")
+
+    if len(local) == 0 or len(local) > 64:
+        raise TypeError("Local-part length must be 1..64 characters.")
+
+    if len(domain) == 0 or len(domain) > 253:
+        raise TypeError("Domain length must be 1..253 characters.")
+
+    if not LOCAL_PART_PATTERN.fullmatch(local):
+        raise TypeError("Local-part contains invalid characters (ASCII subset expected).")
+
+    if local[0] == "." or local[-1] == ".":
+        raise TypeError("Local-part must not start or end with `.`.")
+
+    if ".." in local:
+        raise TypeError("Local-part must not contain consecutive dots `..`.")
+
+    if domain[0] == "." or domain[-1] == ".":
+        raise TypeError("Domain must not start or end with `.`.")
+
+    if ".." in domain:
+        raise TypeError("Domain must not contain consecutive dots `..`.")
+
+    labels = domain.split(".")
+    if len(labels) < 2:
+        raise TypeError("Domain must contain a dot (e.g. `example.com`).")
+
+    for label in labels:
+        if not label:
+            raise TypeError("Domain contains an empty label.")
+
+        if len(label) > 63:
+            raise TypeError("Domain label is too long (max 63 characters).")
+
+        if not LABEL_PATTERN.fullmatch(label):
+            raise TypeError(f"Domain label is invalid: {label!r}.")
+
+    if labels[-1].isdigit():
+        raise TypeError("Top-level domain must not be all numeric.")
+
+    return email
+
+
+def validate_idn_email(email: typing.Any, /) -> str:
+    if not isinstance(email, str):
+        raise TypeError(f"IDNEmail must be `str`, got `{type_repr(email.__class__)}`.")
+
+    if not email:
+        raise TypeError("IDNEmail must be non-empty.")
+
+    if any(ch.isspace() for ch in email):
+        raise TypeError("IDNEmail must not contain whitespace.")
+
+    if email.count("@") != 1:
+        raise TypeError("IDNEmail must contain exactly one `@`.")
+
+    local, domain = email.split("@", 1)
+
+    if len(local) == 0 or len(local) > 64:
+        raise TypeError("Local-part length must be 1..64 characters.")
+
+    if local[0] == "." or local[-1] == ".":
+        raise TypeError("Local-part must not start or end with `.`.")
+
+    if ".." in local:
+        raise TypeError("Local-part must not contain consecutive dots `..`.")
+
+    if any(ord(ch) < 0x20 for ch in local):
+        raise TypeError("Local-part must not contain control characters.")
+
+    if len(domain) == 0:
+        raise TypeError("Domain must be non-empty.")
+
+    if domain[0] == "." or domain[-1] == ".":
+        raise TypeError("Domain must not start or end with `.`.")
+
+    if ".." in domain:
+        raise TypeError("Domain must not contain consecutive dots `..`.")
+
+    labels = domain.split(".")
+    if len(labels) < 2:
+        raise TypeError("Domain must contain a dot (e.g. `example.com`).")
+
+    ascii_labels: list[str] = []
+    for label in labels:
+        if not label:
+            raise TypeError("Domain contains an empty label.")
+
+        try:
+            ascii_label = label.encode("idna").decode("ascii")
+        except UnicodeError as ex:
+            raise TypeError(f"Domain label is invalid: {label!r}.") from ex
+
+        if len(ascii_label) > 63:
+            raise TypeError("Domain label is too long (max 63 characters).")
+
+        if not LABEL_PATTERN.fullmatch(ascii_label):
+            raise TypeError(f"Domain label is invalid: {label!r}.")
+
+        ascii_labels.append(ascii_label)
+
+    ascii_domain = ".".join(ascii_labels)
+
+    if len(ascii_domain) > 253:
+        raise TypeError("Domain length must be <= 253 characters in IDNA ASCII form.")
+
+    if ascii_labels[-1].isdigit():
+        raise TypeError("Top-level domain must not be all numeric.")
+
+    if len(local) + 1 + len(ascii_domain) > 254:
+        raise TypeError("IDNEmail is too long (max 254 characters in IDNA ASCII form).")
+
+    return email
+
+
+class Email(str):
+    def __new__(cls, email: str, /) -> typing.Self:
+        return super().__new__(cls, validate_email(email))
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}({super().__repr__()})"
+
+
+class IDNEmail(str):
+    def __new__(cls, email: str, /) -> typing.Self:
+        return super().__new__(cls, validate_idn_email(email))
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}({super().__repr__()})"
+
+
+__all__ = ("Email", "IDNEmail")

msgspex-1.0.0/msgspex/custom_types/enum.py

@@ -0,0 +1,84 @@
+import enum
+import math
+import sys
+import typing
+
+NOT_SUPPORTED: typing.Final = "NOT_SUPPORTED"
+
+
+def _is_friend(bases: tuple[type[typing.Any], ...], /) -> bool:
+    return any(friend in bases for friend in ENUM_FRIENDS)
+
+
+class StrEnum(str, enum.Enum):
+    def __str__(self) -> str:
+        return self.value
+
+
+class IntEnum(int, enum.Enum):
+    def __int__(self) -> int:
+        return self.value
+
+    def __float__(self) -> float:
+        return float(self.value)
+
+    def __index__(self) -> int:
+        return self.value
+
+
+class FloatEnum(float, enum.Enum):
+    def __int__(self) -> int:
+        return int(self.value)
+
+    def __float__(self) -> float:
+        return self.value
+
+
+class BaseEnumMeta(enum.EnumMeta, type):
+    if typing.TYPE_CHECKING:
+
+        class _BaseEnumMeta(enum.Enum):  # noqa
+            NOT_SUPPORTED = enum.auto()
+
+        NOT_SUPPORTED: typing.Literal[_BaseEnumMeta.NOT_SUPPORTED]
+
+    else:
+
+        @staticmethod
+        def _member_missing(cls, value):
+            return cls._member_map_["NOT_SUPPORTED"]
+
+        def __new__(
+            metacls,
+            cls,
+            bases,
+            classdict,
+            *,
+            boundary=None,
+            _simple=False,
+            **kwds,
+        ):
+            if _is_friend(bases):
+                classdict["NOT_SUPPORTED"] = next(
+                    (value for base, value in NOT_SUPPORTED_VALUES.items() if base in bases),
+                    NOT_SUPPORTED,
+                )
+
+            classdict["_missing_"] = classmethod(BaseEnumMeta._member_missing)
+            return super().__new__(metacls, cls, bases, classdict, boundary=boundary, _simple=_simple, **kwds)
+
+
+ENUM_FRIENDS: typing.Final = (str, int, float, StrEnum, IntEnum, FloatEnum)
+NOT_SUPPORTED_VALUES: typing.Final = {
+    str: NOT_SUPPORTED,
+    int: sys.maxsize,
+    float: math.inf,
+    StrEnum: NOT_SUPPORTED,
+    IntEnum: sys.maxsize,
+    FloatEnum: math.inf,
+    enum.StrEnum: NOT_SUPPORTED,
+    enum.IntEnum: sys.maxsize,
+}
+
+
+__all__ = ("BaseEnumMeta", "FloatEnum", "IntEnum", "StrEnum")