structtype 0.3.0__cp313-cp313-win_amd64.whl

structtype/_utils.py

@@ -0,0 +1,410 @@
+# type: ignore
+import collections
+import sys
+import types
+import typing
+from typing import Any, _AnnotatedAlias, _GenericAlias  # noqa: F401
+
+try:
+    from typing_extensions import get_type_hints as _get_type_hints
+except Exception:
+    from typing import get_type_hints as _get_type_hints
+
+try:
+    from typing_extensions import NotRequired, Required
+except Exception:
+    try:
+        from typing import NotRequired, Required
+    except Exception:
+        Required = NotRequired = None
+
+
+def get_type_hints(obj):
+    return _get_type_hints(obj, include_extras=True)
+
+
+PY_312PLUS = sys.version_info >= (3, 12)
+
+# The `is_class` argument was new in 3.11, but was backported to 3.9 and 3.10.
+# It's _likely_ to be available for 3.9/3.10, but may not be. Easiest way to
+# check is to try it and see. This check can be removed when we drop support
+# for Python 3.10.
+try:
+    typing.ForwardRef("Foo", is_class=True)
+except TypeError:
+
+    def _forward_ref(value):
+        return typing.ForwardRef(value, is_argument=False)
+
+else:
+
+    def _forward_ref(value):
+        return typing.ForwardRef(value, is_argument=False, is_class=True)
+
+
+# Python 3.13 adds a new mandatory type_params kwarg to _eval_type
+if sys.version_info >= (3, 13):
+
+    def _eval_type(t, globalns, localns):
+        return typing._eval_type(t, globalns, localns, ())
+
+else:
+    _eval_type = typing._eval_type
+
+
+if sys.version_info >= (3, 14):
+    from annotationlib import get_annotations as _get_class_annotations
+else:
+
+    def _get_class_annotations(cls):
+        return cls.__dict__.get("__annotations__", {})
+
+
+def _apply_params(obj, mapping):
+    if isinstance(obj, typing.TypeVar):
+        return mapping.get(obj, obj)
+
+    try:
+        parameters = tuple(obj.__parameters__)
+    except Exception:
+        # Not parameterized or __parameters__ is invalid, ignore
+        return obj
+
+    if not parameters:
+        # Not parametrized
+        return obj
+
+    # Parametrized
+    args = tuple(mapping.get(p, p) for p in parameters)
+    return obj[args]
+
+
+def _get_class_mro_and_typevar_mappings(obj):
+    mapping = {}
+
+    # in Python 3.10 a natively produced 'types.GenericAlias' (e.g. 'list[int]', or the
+    # 'Base[int]' produced when a 'Generic' subclass inherits a builtin's
+    # '__class_getitem__') satisfies 'isinstance(_, type)', unlike on 3.11+. we still
+    # want to treat those as parametrised aliases, not bare classes
+    if isinstance(obj, type) and not isinstance(obj, types.GenericAlias):
+        cls = obj
+    else:
+        cls = obj.__origin__
+
+    def inner(c, scope):
+        if isinstance(c, type) and not isinstance(c, types.GenericAlias):
+            cls = c
+            new_scope = {}
+        else:
+            cls = typing.get_origin(c)
+            if cls in (None, object, typing.Generic) or cls in mapping:
+                return
+
+            if hasattr(cls, "__parameters__"):
+                # 'cls' carries its own type vars. This covers both ordinary
+                # 'typing._GenericAlias' bases and the 'types.GenericAlias' that
+                # get produced when a user-defined 'Generic' subclass inherits a
+                # builtin's '__class_getitem__' (e.g. 'class Base(Mapping[str, T])',
+                # whose 'Base[...]' is a 'types.GenericAlias'). Map cls's own
+                # type vars onto the resolved args, applying '_apply_params' so any
+                # outer bindings in 'scope' (e.g. 'U -> int') are propagated.
+                params = cls.__parameters__
+                args = tuple(_apply_params(a, scope) for a in typing.get_args(c))
+                assert len(params) == len(args)
+                new_scope = dict(zip(params, args))
+            else:
+                # a true built-in generic (e.g. 'collections.abc.Mapping[str, T]')
+                # whose '__origin__' has no '__parameters__'; the unresolved type
+                # vars and args live on the alias itself, not the origin.
+                new_scope = dict(zip(c.__parameters__, typing.get_args(c)))
+            mapping[cls] = new_scope
+
+        if issubclass(cls, typing.Generic):
+            bases = getattr(cls, "__orig_bases__", cls.__bases__)
+            for b in bases:
+                inner(b, new_scope)
+
+    inner(obj, {})
+    return cls.__mro__, mapping
+
+
+def get_class_annotations(obj):
+    """Get the annotations for a class.
+
+    This is similar to ``typing.get_type_hints``, except:
+
+    - We maintain it
+    - It leaves extras like ``Annotated``/``ClassVar`` alone
+    - It resolves any parametrized generics in the class mro. The returned
+      mapping may still include ``TypeVar`` values, but those should be treated
+      as their unparametrized variants (i.e. equal to ``Any`` for the common case).
+
+    Note that this function doesn't check that Generic types are being used
+    properly - invalid uses of `Generic` may slip through without complaint.
+
+    The assumption here is that the user is making use of a static analysis
+    tool like ``mypy``/``pyright`` already, which would catch misuse of these
+    APIs.
+    """
+    hints = {}
+    mro, typevar_mappings = _get_class_mro_and_typevar_mappings(obj)
+
+    for cls in mro:
+        if cls in (typing.Generic, object):
+            continue
+
+        mapping = typevar_mappings.get(cls)
+        cls_locals = dict(vars(cls))
+
+        if PY_312PLUS:
+            # resolve type parameters (e.g. class Foo[T]: pass)
+            cls_locals.update({p.__name__: p for p in cls.__type_params__})
+
+        try:
+            cls_module = cls.__module__
+        except AttributeError:
+            cls_globals = {}
+        else:
+            cls_globals = getattr(sys.modules.get(cls_module, None), "__dict__", {})
+
+        ann = _get_class_annotations(cls)
+        for name, value in ann.items():
+            if name in hints:
+                continue
+            if isinstance(value, str):
+                value = _forward_ref(value)
+            value = _eval_type(value, cls_locals, cls_globals)
+            if mapping is not None:
+                value = _apply_params(value, mapping)
+            if value is None:
+                value = type(None)
+            hints[name] = value
+    return hints
+
+
+# A mapping from a type annotation (or annotation __origin__) to the concrete
+# python type that structtype will use when decoding. THIS IS PRIVATE FOR A
+# REASON. DON'T MUCK WITH THIS.
+_CONCRETE_TYPES = {
+    list: list,
+    tuple: tuple,
+    set: set,
+    frozenset: frozenset,
+    dict: dict,
+    typing.List: list,
+    typing.Tuple: tuple,
+    typing.Set: set,
+    typing.FrozenSet: frozenset,
+    typing.Dict: dict,
+    typing.Collection: list,
+    typing.MutableSequence: list,
+    typing.Sequence: list,
+    typing.MutableMapping: dict,
+    typing.Mapping: dict,
+    typing.MutableSet: set,
+    typing.AbstractSet: set,
+    collections.abc.Collection: list,
+    collections.abc.MutableSequence: list,
+    collections.abc.Sequence: list,
+    collections.abc.MutableSet: set,
+    collections.abc.Set: set,
+    collections.abc.MutableMapping: dict,
+    collections.abc.Mapping: dict,
+}
+if sys.version_info >= (3, 15):
+    _CONCRETE_TYPES.update({frozendict: frozendict})  # noqa: F821
+
+
+def get_typeddict_info(obj):
+    if isinstance(obj, type):
+        cls = obj
+    else:
+        cls = obj.__origin__
+
+    raw_hints = get_class_annotations(obj)
+
+    if hasattr(cls, "__required_keys__"):
+        required = set(cls.__required_keys__)
+    elif cls.__total__:
+        required = set(raw_hints)
+    else:
+        required = set()
+
+    # Both `typing.TypedDict` and `typing_extensions.TypedDict` have a bug
+    # where `Required`/`NotRequired` aren't properly detected at runtime when
+    # `__future__.annotations` is enabled, meaning the `__required_keys__`
+    # isn't correct. This code block works around this issue by amending the
+    # set of required keys as needed, while also stripping off any
+    # `Required`/`NotRequired` wrappers.
+    hints = {}
+    for k, v in raw_hints.items():
+        origin = getattr(v, "__origin__", False)
+        if origin is Required:
+            required.add(k)
+            hints[k] = v.__args__[0]
+        elif origin is NotRequired:
+            required.discard(k)
+            hints[k] = v.__args__[0]
+        else:
+            hints[k] = v
+
+    # This can happen if there is a bug in the TypedDict implementation;
+    # such a bug was present in Python 3.14.
+    if not all(k in hints for k in required):
+        raise RuntimeError(
+            f"Required set {required} contains keys that are no in hints: {hints.keys()}"
+        )
+    return hints, required
+
+
+def get_dataclass_info(obj):
+    if isinstance(obj, type):
+        cls = obj
+    else:
+        cls = obj.__origin__
+    hints = get_class_annotations(obj)
+    required = []
+    optional = []
+    defaults = []
+
+    if hasattr(cls, "__dataclass_fields__"):
+        from dataclasses import _FIELD, _FIELD_INITVAR, MISSING
+
+        for field in cls.__dataclass_fields__.values():
+            if field._field_type is not _FIELD:
+                if field._field_type is _FIELD_INITVAR:
+                    raise TypeError(
+                        "dataclasses with `InitVar` fields are not supported"
+                    )
+                continue
+            name = field.name
+            typ = hints[name]
+            if field.default is not MISSING:
+                defaults.append(field.default)
+                optional.append((name, typ, False))
+            elif field.default_factory is not MISSING:
+                defaults.append(field.default_factory)
+                optional.append((name, typ, True))
+            else:
+                required.append((name, typ, False))
+
+        required.extend(optional)
+
+        pre_init = None
+        post_init = getattr(cls, "__post_init__", None)
+    else:
+        from attrs import NOTHING, Factory
+
+        fields_with_validators = []
+
+        for field in cls.__attrs_attrs__:
+            name = field.name
+            typ = hints[name]
+            default = field.default
+            if default is not NOTHING:
+                if isinstance(default, Factory):
+                    if default.takes_self:
+                        raise NotImplementedError(
+                            "Support for default factories with `takes_self=True` "
+                            "is not implemented. File a GitHub issue if you need "
+                            "this feature!"
+                        )
+                    defaults.append(default.factory)
+                    optional.append((name, typ, True))
+                else:
+                    defaults.append(default)
+                    optional.append((name, typ, False))
+            else:
+                required.append((name, typ, False))
+
+            if field.validator is not None:
+                fields_with_validators.append(field)
+
+        required.extend(optional)
+
+        pre_init = getattr(cls, "__attrs_pre_init__", None)
+        post_init = getattr(cls, "__attrs_post_init__", None)
+
+        if fields_with_validators:
+            post_init = _wrap_attrs_validators(fields_with_validators, post_init)
+
+    return cls, tuple(required), tuple(defaults), pre_init, post_init
+
+
+def get_pydantic_info(obj):
+    """Extract field info from a Pydantic v2 BaseModel."""
+    if isinstance(obj, type):
+        cls = obj
+    else:
+        cls = obj.__origin__
+    hints = get_class_annotations(obj)
+    required = []
+    optional = []
+    defaults = []
+
+    for name, field_info in cls.model_fields.items():
+        typ = hints.get(name, Any)
+        if field_info.is_required():
+            required.append((name, typ, False))
+        else:
+            df = field_info.default_factory
+            if df is not None:
+                defaults.append(df)
+                optional.append((name, typ, True))
+            else:
+                defaults.append(field_info.default)
+                optional.append((name, typ, False))
+
+    required.extend(optional)
+    return cls, tuple(required), tuple(defaults)
+
+
+def _wrap_attrs_validators(fields, post_init):
+    def inner(obj):
+        for field in fields:
+            field.validator(obj, field, getattr(obj, field.name))
+        if post_init is not None:
+            post_init(obj)
+
+    return inner
+
+
+def rebuild(cls, kwargs):
+    """Used to unpickle Structs with keyword-only fields"""
+    return cls(**kwargs)
+
+
+def convert_generic_alias(origin, args):
+    # subscribed typing._GenericAlias instances are cached within the typing module
+    # we make use of this fact, by storing a __structtype_cache__ attribute on the
+    # subscribed instance. only subscribed types are cached, so
+    # 'typing._GenericAlias(list, int) is typing._GenericAlias(list, int)' would be
+    # false.
+    # to achieve the same behaviour when re-creating a typing._GenericAlias from a
+    # types.GenericAlias, we first construct a temporary *unbound*
+    # typing._GenericAlias, on which we then call __getattr__. effectively doing
+    # typing._GenericAlias(list, T)[int], for which
+    # 'typing._GenericAlias(list, T)[int] is typing._GenericAlias(list, T)[int]'
+    # holds true
+    try:
+        params = origin.__parameters__
+    except AttributeError:
+        if not isinstance(origin, type):
+            # a special form such as 'typing.Literal', whose args are values rather than
+            # type parameters. Ordinary subscription yields the canonical, interned
+            # alias of the right subclass (e.g. 'typing.Literal[...]' -> '_LiteralGenericAlias').
+            return origin[args]
+
+        # a non-generic class with type arguments. only reachable for e.g.
+        # manually-built 'types.GenericAlias' instances and is probably nonsense or at
+        # least not somthing we can meaningfully represent, so complain about it here,
+        # rather than silently dropping the arguments.
+        raise TypeError(f"{origin.__name__!r} is not a generic type")
+
+    # a regularly-parametrised generic. Create a new typing._GenericAlias with the
+    # origin's unbound type params (e.g. for a 'Mapping[str, int]' this is a
+    # '_GenericAlias(Mapping, (~K, ~V))'), then bind it to the concrete args by
+    # subscripting with the args *tuple* (i.e. 'alias[(int, str)]', not
+    # 'alias[int, str]'), so generics with more than one type var work
+    alias = _GenericAlias(origin, params)
+    return alias[args]

structtype/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.3.0'
+__version_tuple__ = version_tuple = (0, 3, 0)
+
+__commit_id__ = commit_id = None

structtype-0.3.0.dist-info/METADATA

@@ -0,0 +1,80 @@
+Metadata-Version: 2.4
+Name: structtype
+Version: 0.3.0
+Summary: Fast Struct type with validation and JSON serialization for Python.
+Maintainer-email: Wolfgang Langner <tds333@mailbox.org>
+License-Expression: BSD-3-Clause
+Project-URL: Homepage, https://github.com/tds333/structtype
+Project-URL: Issue Tracker, https://github.com/tds333/structtype/issues
+Project-URL: Source, https://github.com/tds333/structtype
+Keywords: JSON,schema,serialization,struct,validation
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: WebAssembly :: Emscripten
+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: Programming Language :: Python :: 3.15
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# structtype
+
+Fast Struct type with validation + JSON serialization for Python.
+
+- **High performance** — 5-60x faster than dataclasses, attrs, or pydantic for common operations
+- **Schema validation** — familiar Python type annotations, enforced at decode time
+- **No runtime dependencies** — built on a monolithic C extension based on msgspec
+- **Rich type support** — nested Structs, dataclasses, TypedDicts, enums, UUID, Decimal, datetime, and more
+- **JSON Schema generation** — auto-generate JSON Schema 2020-12 / OpenAPI 3.1 specs
+
+## Install
+
+```bash
+pip install structtype
+```
+
+```bash
+uv add structtype
+```
+
+Requires Python ≥ 3.10.
+
+## Quick Example
+
+```python
+from structtype import Struct
+
+class User(Struct):
+    name: str
+    groups: set[str] = set()
+    email: str | None = None
+
+alice = User("alice", groups={"admin", "engineering"})
+
+# Serialize to JSON
+alice.struct_dump_json()
+# b'{"name":"alice","groups":["admin","engineering"],"email":null}'
+
+# Deserialize and validate
+User.struct_validate_json(
+    b'{"name":"alice","groups":["admin","engineering"],"email":null}'
+)
+# User(name='alice', groups={"admin", "engineering"}, email=None)
+```
+
+## Documentation
+
+Full documentation is available at **https://tds333.github.io/structtype/**.
+
+## Benchmarks
+
+structtype is as fast as msgspec and about 3-5x faster than pydantic.
+
+## License
+
+New BSD. See the [License File](LICENSE).
+The core is based on the work of Jim Crist-Harif from msgspec.

structtype-0.3.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+structtype/__init__.py,sha256=QcV_qQ6ybqunYrm9DTCpJjUAN3LYXD2v0RAjLd19Ops,387
+structtype/__init__.pyi,sha256=P52MMOcSyIcqq0vpRUwJ-A7Xs3_l3qNbkTsALkFzJYI,11101
+structtype/_adapter.py,sha256=ybqo8Bnk5qZaLeT4AjIyvGCm8gwIEaSUskaPY4c8JYY,4106
+structtype/_core.cp313-win_amd64.pyd,sha256=bp_YTrcoZ1GT22znbxp7iGY8EBWexQKj_nU-PNwKrPY,283648
+structtype/_inspect.py,sha256=ItEA54f13J3wOB4hdMVqFzyqLf4YL5Ozv7MyS6hWJFU,34523
+structtype/_json_schema.py,sha256=-KuNxyyc8YVI2o-ZH75VRbjAyc3EuZoBd_Q_TWP7ol0,19315
+structtype/_utils.py,sha256=fdXcdqu257GEHuhoB3WIIzt3yv4T7xr0lwDShMwLtaQ,14335
+structtype/_version.py,sha256=mOtRuCjwCaETSVM2o_uwyhF-FRPR1OeF-XL-EF6phZM,544
+structtype/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+structtype-0.3.0.dist-info/licenses/LICENSE,sha256=leWp9SAS7Rk9nG38qtpl86hT6BZYsog7p3xfMkTWSBg,1499
+structtype-0.3.0.dist-info/METADATA,sha256=HAzB5GRmPdZx0F2M5X7vA5oEbBLpA0AyX5p9NOOfi5Q,2528
+structtype-0.3.0.dist-info/WHEEL,sha256=AP_wkikJcUkDPUGvTNydv7g0R7BhW1u_fVHNKW7TJyI,101
+structtype-0.3.0.dist-info/top_level.txt,sha256=hQPg6sdg7t2YGfKJRsRLTGlfSNSvjW9FwXH-yQxfnyQ,11
+structtype-0.3.0.dist-info/RECORD,,

structtype-0.3.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: false
+Tag: cp313-cp313-win_amd64
+

structtype-0.3.0.dist-info/licenses/LICENSE

@@ -0,0 +1,27 @@
+Copyright (c) 2026, Wolfgang Langner
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors
+  may be used to endorse or promote products derived from this software
+  without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

structtype-0.3.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+structtype