msgspec-extras 0.1.0__py3-none-any.whl

msgspec_extras/__init__.py

@@ -0,0 +1,33 @@
+__all__ = [
+    "FutureDate",
+    "FutureDatetime",
+    "HttpUrl",
+    "NegativeFloat",
+    "NegativeInt",
+    "NonNegativeFloat",
+    "NonNegativeInt",
+    "NonPositiveFloat",
+    "NonPositiveInt",
+    "PastDate",
+    "PastDatetime",
+    "PositiveFloat",
+    "PositiveInt",
+    "__version__",
+    "dec_hook",
+    "enc_hook",
+]
+__version__ = "0.1.0"
+
+from msgspec_extras._hooks import dec_hook, enc_hook
+from msgspec_extras.datetime import FutureDate, FutureDatetime, PastDate, PastDatetime
+from msgspec_extras.numeric import (
+    NegativeFloat,
+    NegativeInt,
+    NonNegativeFloat,
+    NonNegativeInt,
+    NonPositiveFloat,
+    NonPositiveInt,
+    PositiveFloat,
+    PositiveInt,
+)
+from msgspec_extras.string import HttpUrl

msgspec_extras/_hooks.py

@@ -0,0 +1,17 @@
+__all__ = ["dec_hook", "enc_hook"]
+
+from typing import Any
+
+from msgspec_extras.datetime import FutureDate, FutureDatetime, PastDate, PastDatetime
+
+
+def dec_hook(typ: type, obj: Any) -> Any:  # noqa: ANN401
+    if typ in (PastDate, FutureDate, PastDatetime, FutureDatetime):
+        return typ(obj)
+    raise NotImplementedError(f"Type {typ.__name__} unsupported in dec_hook")
+
+
+def enc_hook(obj: Any) -> Any:  # noqa: ANN401
+    if isinstance(obj, (PastDate, FutureDate, PastDatetime, FutureDatetime)):
+        return obj.isoformat()
+    raise NotImplementedError(f"Encoding objects of type {type(obj).__name__} is unsupported")

msgspec_extras/datetime.py

@@ -0,0 +1,106 @@
+__all__ = ["FutureDate", "FutureDatetime", "PastDate", "PastDatetime"]
+
+from datetime import date, datetime
+
+from msgspec import ValidationError
+
+try:
+    from typing import Self  # ty:ignore[unresolved-import]
+except ImportError:
+    from typing_extensions import Self
+
+
+class PastDate(date):
+    __slots__ = ()
+
+    def __new__(cls, value: date | str) -> Self:
+        if isinstance(value, date):
+            tmp: date = super().__new__(cls, value.year, value.month, value.day)
+        elif isinstance(value, str):
+            try:
+                tmp: date = date.fromisoformat(value)
+            except ValueError as err:
+                raise ValueError(f"Invalid date format: {value}") from err
+        else:
+            raise TypeError(f"PastDate must be a date or string, got {type(value).__name__}")
+        if tmp < date.today():
+            return tmp
+        raise ValidationError(f"PastDate must be in the past, got {tmp}")
+
+
+class FutureDate(date):
+    __slots__ = ()
+
+    def __new__(cls, value: date | str) -> Self:
+        if isinstance(value, date):
+            tmp: date = super().__new__(cls, value.year, value.month, value.day)
+        elif isinstance(value, str):
+            try:
+                tmp: date = date.fromisoformat(value)
+            except ValueError as err:
+                raise ValueError(f"Invalid date format: {value}") from err
+        else:
+            raise TypeError(f"FutureDate must be a date or string, got {type(value).__name__}")
+        if tmp > date.today():
+            return tmp
+        raise ValidationError(f"FutureDate must be in the future, got {tmp}")
+
+
+class PastDatetime(datetime):
+    __slots__ = ()
+
+    def __new__(cls, value: datetime | str) -> Self:
+        if isinstance(value, datetime):
+            tmp: datetime = super().__new__(
+                cls,
+                value.year,
+                value.month,
+                value.day,
+                value.hour,
+                value.minute,
+                value.second,
+                value.microsecond,
+                value.tzinfo,
+            )
+        elif isinstance(value, str):
+            try:
+                tmp: datetime = datetime.fromisoformat(value)
+            except ValueError as err:
+                raise ValueError(f"Invalid datetime format: {value}") from err
+        else:
+            raise TypeError(
+                f"PastDatetime must be a datetime or string, got {type(value).__name__}"
+            )
+        if tmp < datetime.now():
+            return tmp
+        raise ValidationError(f"PastDatetime must be in the past, got {tmp}")
+
+
+class FutureDatetime(datetime):
+    __slots__ = ()
+
+    def __new__(cls, value: datetime | str) -> Self:
+        if isinstance(value, datetime):
+            tmp: datetime = super().__new__(
+                cls,
+                value.year,
+                value.month,
+                value.day,
+                value.hour,
+                value.minute,
+                value.second,
+                value.microsecond,
+                value.tzinfo,
+            )
+        elif isinstance(value, str):
+            try:
+                tmp: datetime = datetime.fromisoformat(value)
+            except ValueError as err:
+                raise ValueError(f"Invalid datetime format: {value}") from err
+        else:
+            raise TypeError(
+                f"FutureDatetime must be a datetime or string, got {type(value).__name__}"
+            )
+        if tmp > datetime.now():
+            return tmp
+        raise ValidationError(f"FutureDatetime must be in the future, got {tmp}")

msgspec_extras/numeric.py

@@ -0,0 +1,24 @@
+__all__ = [
+    "NegativeFloat",
+    "NegativeInt",
+    "NonNegativeFloat",
+    "NonNegativeInt",
+    "NonPositiveFloat",
+    "NonPositiveInt",
+    "PositiveFloat",
+    "PositiveInt",
+]
+
+from typing import Annotated
+
+from msgspec import Meta
+
+PositiveInt = Annotated[int, Meta(gt=0, description="Integer greater than 0")]
+NegativeInt = Annotated[int, Meta(lt=0, description="Integer less than 0")]
+NonNegativeInt = Annotated[int, Meta(ge=0, description="Integer greater than or equal to 0")]
+NonPositiveInt = Annotated[int, Meta(le=0, description="Integer less than or equal to 0")]
+
+PositiveFloat = Annotated[float, Meta(gt=0.0, description="Float greater than 0.0")]
+NegativeFloat = Annotated[float, Meta(lt=0.0, description="Float less than 0.0")]
+NonNegativeFloat = Annotated[float, Meta(ge=0.0, description="Float greater than or equal to 0.0")]
+NonPositiveFloat = Annotated[float, Meta(le=0.0, description="Float less than or equal to 0.0")]

msgspec_extras/string.py

@@ -0,0 +1,7 @@
+__all__ = ["HttpUrl"]
+
+from typing import Annotated
+
+from msgspec import Meta
+
+HttpUrl = Annotated[str, Meta(max_length=2083, pattern=r"^https?://[^\s/$.?#].[^\s]*$")]

msgspec_extras-0.1.0.dist-info/METADATA

@@ -0,0 +1,110 @@
+Metadata-Version: 2.4
+Name: msgspec-extras
+Version: 0.1.0
+Project-URL: Homepage, https://pypi.org/project/msgspec-extras
+Project-URL: Issues, https://codefloe.com/buriedincode/msgspec-extras/issues
+Project-URL: Source, https://codefloe.com/buriedincode/msgspec-extras
+Author-email: BuriedInCode <buriedincode@duckpond.nz>
+Maintainer-email: BuriedInCode <buriedincode@duckpond.nz>
+License-Expression: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: msgspec>=0.21.0
+Description-Content-Type: text/markdown
+
+# msgspec-extras
+
+[![PyPI - Python](https://img.shields.io/pypi/pyversions/msgspec-extras.svg?logo=Python&label=Python&style=flat-square)](https://pypi.org/p/msgspec-extras/)
+[![PyPI - Status](https://img.shields.io/pypi/status/msgspec-extras.svg?logo=Python&label=Status&style=flat-square)](https://pypi.org/p/msgspec-extras/)
+[![PyPI - Version](https://img.shields.io/pypi/v/msgspec-extras.svg?logo=Python&label=Version&style=flat-square)](https://pypi.org/p/msgspec-extras/)
+[![PyPI - License](https://img.shields.io/pypi/l/msgspec-extras.svg?logo=Python&label=License&style=flat-square)](https://opensource.org/licenses/MIT)
+
+[![prek](https://img.shields.io/badge/prek-enabled-informational?logo=prek&style=flat-square)](https://github.com/j178/prek)
+[![Ruff](https://img.shields.io/badge/Ruff-enabled-informational?logo=ruff&style=flat-square)](https://github.com/astral-sh/ruff)
+[![ty](https://img.shields.io/badge/ty-enabled-informational?logo=ruff&style=flat-square)](https://github.com/astral-sh/ty)
+
+[![status-badge](https://ci.codefloe.com/api/v1/badges/1187/status.svg)](https://ci.codefloe.com/repos/1187)
+
+A small collection of types that extend [msgspec](https://msgspec.dev)'s built-in type support.
+
+## Installation
+
+```sh
+pdm add msgspec-extras
+```
+
+## Type Support
+
+`msgspec-extras` supports **all msgspec native types** - see the full list in the [msgspec documentation](https://msgspec.dev/supported-types).
+It also adds the following custom types.
+
+### Datetime
+
+- `PastDate` - must be earlier than today
+- `PastDatetime` - must be earlier than now
+- `FutureDate` - must be later than today
+- `FutureDatetime` - must be later than now
+
+These types require the `enc_hook`/`dec_hook` to be passed to msgspec's encode/decode calls.
+
+```python
+from datetime import datetime, date
+
+import msgspec
+from msgspec_extras import PastDate, PastDatetime, FutureDate, FutureDatetime, enc_hook, dec_hook
+
+past_date = msgspec.json.decode('"2020-03-21"', type=PastDate, dec_hook=dec_hook)
+past_date_json = msgspec.json.encode(past_date, enc_hook=enc_hook)
+
+msgspec.json.decode('"2020-03-21"', type=FutureDate, dec_hook=dec_hook)
+# Raises `msgspec.ValidationError` as the date isn't in the future
+```
+
+### Numeric
+
+| Type               | Constraint |
+| ------------------ | ---------- |
+| `PositiveInt`      | `> 0`      |
+| `PositiveFloat`    | `> 0`      |
+| `NonNegativeInt`   | `>= 0`     |
+| `NonNegativeFloat` | `>= 0`     |
+| `NegativeInt`      | `< 0`      |
+| `NegativeFloat`    | `< 0`      |
+| `NonPositiveInt`   | `<= 0`     |
+| `NonPositiveFloat` | `<= 0`     |
+
+### String
+
+- `HttpUrl` - must be a valid HTTP or HTTPS URL
+
+## Usage
+
+The numeric and string types are just `Annotated` aliases over msgspec's native types (e.g. `Annotated[int, msgspec.Meta(gt=0)]`), so they need no hooks and work as drop-in replacements anywhere you'd use `int`, `float`, or `str`:
+
+```python
+import msgspec
+from msgspec_extras import PositiveFloat
+
+
+class Product(msgspec.Struct):
+    name: str
+    price: PositiveFloat
+
+
+product = msgspec.json.decode(b'{"name": "Widget", "price": 5.1}', type=Product)
+msgspec.json.encode(product)
+```
+
+## Socials
+
+[![Social - Matrix](https://img.shields.io/matrix/The-Dev-Environment:matrix.org?label=The-Dev-Environment&logo=matrix&style=for-the-badge)](https://matrix.to/#/#The-Dev-Environment:matrix.org)

msgspec_extras-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+msgspec_extras/__init__.py,sha256=xQYXPuLq2Zmfyd3iApxVEsFGvpEXiFHMVg0CBT9hw1A,728
+msgspec_extras/_hooks.py,sha256=j2zi2eWXkETou0D_WMBTm8cEhbYxOCe_hhx28DDfOE8,630
+msgspec_extras/datetime.py,sha256=a5cWqlS6cuf_IKCTRwzz9pAJOvC4csP-swzE8DWtK0c,3570
+msgspec_extras/numeric.py,sha256=ldUYGCEkiE9b3hLmpt8zOx1YO0FY2EKraw8A0Kr3_no,948
+msgspec_extras/string.py,sha256=FNMf6Epc2Qu6pK7qXvGSgMOO85qZErKDy2hdzJo2UVg,168
+msgspec_extras-0.1.0.dist-info/METADATA,sha256=jONtMT3J-x--MpWRmF-Icx78YnyAiJsaNQaTydrfc4o,4345
+msgspec_extras-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+msgspec_extras-0.1.0.dist-info/RECORD,,

msgspec_extras-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any