typewire 0.1.0__py3-none-any.whl

typewire/__init__.py

@@ -0,0 +1,3 @@
+from .caster import as_type, is_iterable, is_mapping, is_union, TypeHint
+
+__all__ = ["as_type", "is_iterable", "is_mapping", "is_union", "TypeHint"]

typewire/caster.py

@@ -0,0 +1,181 @@
+from collections.abc import Iterable, Mapping
+from contextlib import suppress
+import inspect
+import types
+from typing import Annotated, Any, get_args, get_origin, Literal, TypeAlias, TypeVar, Union
+
+TypeHint: TypeAlias = Any
+
+
+def is_union(type_hint: TypeHint) -> bool:
+    """Determine whether the given type represents a union type."""
+    return type_hint is Union or (hasattr(types, "UnionType") and isinstance(type_hint, types.UnionType))
+
+
+def is_mapping(type_hint: TypeHint) -> bool:
+    """Determine whether the given type represents a mapping type."""
+    origin = get_origin(type_hint)
+    real_type = origin if origin is not None else type_hint
+    return isinstance(real_type, type) and issubclass(real_type, Mapping)
+
+
+def is_iterable(type_hint: TypeHint) -> bool:
+    """Determine whether the given type represents an iterable type."""
+    origin = get_origin(type_hint)
+    real_type = origin if origin is not None else type_hint
+    return isinstance(real_type, type) and issubclass(real_type, Iterable) and real_type not in (str, bytes)
+
+
+def as_type(value: Any, to: TypeHint, *, transparent_int: bool = False, semantic_bool: bool = False) -> Any:
+    """Cast a value to the given type hint.
+
+    :param value:
+        The raw input value to cast.
+    :param to:
+        The type hint to cast to.
+    :param transparent_int:
+        Whether to allow more transparent casting to int.
+        For example, int("1.0") raises a ValueError, so as_type("1.0", int) raises a ValueError as well.
+        However, as_type("1.0", int, transparent_int=True) will return 1.
+        This passes the conversion to float, then int, so as_type("1.3", int, transparent_int=True) returns 1.
+    :param semantic_bool:
+        Whether to allow for more semantic casting to bool.
+        For example, bool("false") returns True, so as_type("false", bool) returns True.
+        However, as_type("false", bool, semantic_bool=True) returns False.
+
+    :return: The casted value.
+    """
+
+    # We can't cast to Any or an unbound TypeVar, so just return the value as-is
+    if to is Any or isinstance(to, TypeVar):
+        return value
+
+    origin: Any = get_origin(to)
+    args: Any = get_args(to)
+
+    # reach into Annotated
+    if origin is Annotated:
+        to = get_args(to)[0]
+        origin = get_origin(to)
+        args = get_args(to)
+
+    # handle unions
+    if is_union(to):
+        for type_hint in get_args(to):
+            if type_hint is type(None) and value is None:
+                return None
+
+            with suppress(ValueError, TypeError):
+                return as_type(value, type_hint, transparent_int=transparent_int, semantic_bool=semantic_bool)
+        else:
+            raise ValueError(f"Value {value!r} does not match any type in {to}")
+
+    # handle literals
+    if origin is Literal:
+        if value in args:
+            return value
+
+        raise ValueError(f"Value {value!r} does not match any literal in {to}")
+
+    # If `to` is a plain type (e.g., int), then origin is None. But we want something we can actually call.
+    real_type = origin if origin is not None else to
+
+    # handle unions (e.g., int | float | None)
+    if is_union(real_type):
+        for type_hint in args:
+            # if value is None, then we can allow None in the union
+            if type_hint is type(None):
+                if value is None:
+                    return None
+                continue
+
+            # otherwise, try to find the first matching type
+            with suppress(ValueError, TypeError):
+                return as_type(value, type_hint, transparent_int=transparent_int, semantic_bool=semantic_bool)
+        else:
+            # none of the types match
+            raise ValueError(f"Value {value!r} does not match any type in {to}")
+
+    # handle mappings
+    if is_mapping(real_type):
+        if not isinstance(value, Mapping):
+            # input is a list of pairs like [("a", 1), ("b", 2)]
+            try:
+                value = dict(value)
+            except ValueError:
+                raise ValueError(f"Value {value!r} is not a mapping")
+
+        key_type = args[0] if args else Any
+        val_type = args[1] if len(args) > 1 else Any
+
+        dct = {
+            as_type(key, key_type, transparent_int=transparent_int, semantic_bool=semantic_bool): as_type(
+                val, val_type, transparent_int=transparent_int, semantic_bool=semantic_bool
+            )
+            for key, val in value.items()
+        }
+
+        if inspect.isabstract(real_type) and isinstance(value, real_type):
+            # We can't cast to an abstract container, so just return the dict that we have
+            return dct
+
+        return real_type(dct)
+
+    # handle containers
+    if is_iterable(real_type):
+        if isinstance(value, (str, bytes)) and isinstance(value, real_type):
+            # specifically handle Iterable[str] and Iterable[bytes] as simply str and bytes
+            return value
+
+        # default to str if the inner type is not set, e.g. x: list
+        inner_type = args[0] if args else Any
+
+        # if tuple[T, T] fixed length
+        if origin is tuple and args and Ellipsis not in args:
+            if len(args) != len(value):
+                raise ValueError(f"Expected tuple of length {len(args)}, got {len(value)}")
+
+            return tuple(
+                as_type(v, t, transparent_int=transparent_int, semantic_bool=semantic_bool) for v, t in zip(value, args)
+            )
+
+        # otherwise, it's a variadic container
+        vals = (
+            as_type(
+                v,
+                inner_type,
+                transparent_int=transparent_int,
+                semantic_bool=semantic_bool,
+            )
+            for v in value
+        )
+
+        if inspect.isabstract(real_type):
+            # We can't cast to an abstract container, so just return the value as a list
+            return list(vals)
+
+        return real_type(vals)
+
+    # handle possible semantic conversions
+    if to is int and transparent_int:
+        with suppress(ValueError, TypeError):
+            return int(float(value))
+
+    if to is bool and semantic_bool and isinstance(value, str):
+        normalized = value.lower()
+
+        if normalized in ("true", "yes", "1", "on"):
+            return True
+
+        if normalized in ("false", "no", "0", "off"):
+            return False
+
+    if isinstance(real_type, type) and callable(real_type):
+        if inspect.isabstract(real_type):
+            # We can't instantiate an abstract class, so just return the value
+            return value
+
+        return real_type(value)
+
+    # fallback
+    return to(value)

typewire-0.1.0.dist-info/METADATA

@@ -0,0 +1,186 @@
+Metadata-Version: 2.4
+Name: typewire
+Version: 0.1.0
+Summary: A single-file utility to allow better runtime handling of types by providing a predictable way of transforming data into the shape of a given type hint.
+Project-URL: repository, https://github.com/lilellia/typewire
+Project-URL: Bug Tracker, https://github.com/lilellia/typewire/issues
+Author-email: Lily Ellington <lilell_@outlook.com>
+License-File: LICENSE
+Keywords: annotated,casting,runtime-types,type-casting,type-hints,typing
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+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: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# typewire
+
+A single-file utility to allow better runtime handling of types by providing a predictable way of transforming data into the shape of a given type hint.
+
+## Why?
+
+Python's standard library provides tools for describing types via type hints, but it doesn't provide a unified way of actually enforcing those type hints at runtime, even buried deep in the `typing` module.
+
+Our goal is to allow for `x: T` to behave transparently as usual whilst also allowing the user to convert to that type, regardless of whether that is `x: int` or `x: float | None` or `x: dict[str, list[int | dict[float, User]]]`. Just like `int(x)` will (to the best of its ability) turn `x` into an `int`, `typewire.as_type(x, int)` will do the same, but with the added benefit of working on type hints that aren't callable (like `list[float]`).
+
+```py
+>>> from typewire import as_type
+
+>>> as_type("3.2", float)
+3.2
+
+>>> as_type(78.1, int)
+78
+
+>>> as_type("3.2", int, transparent_int=True)
+3
+
+>>> as_type(["13.2", "18", "-1.2"], list[int | float])
+[13.2, 18, -1.2]
+
+>>> as_type([("a", "1"), ("b", "2"), ("c", "3"), ("z", "26")], dict[str, float])
+{'a': 1.0, 'b': 2.0, 'c': 3.0, 'z': 26.0}
+
+>>> from pathlib import Path
+>>> data = {"logs": ["/tmp/app.log", "123"]}
+>>> hint = dict[str, list[Path | int]]
+>>> as_type(data, hint)
+{'logs': [Path('/tmp/app.log'), 123]}
+```
+
+## Installation
+
+`typewire` is supported on Python 3.10 and onward and can be easily installed with a package manager such as:
+
+```bash
+# using pip
+$ pip install typewire
+
+# using uv
+$ uv add typewire
+```
+
+`typewire` does not have any additional dependencies.
+
+## Documentation
+
+### `TypeHint`
+
+`TypeHint` is provided as a top-level alias for `typing.Any`.
+
+### `is_union`, `is_mapping`, `is_iterable`
+
+These three functions check whether a given type hint is a union type (e.g., `int | str | bytes`), a mapping type (e.g., `dict[str, Any]`), or an iterable type (`e.g., list[str]`).
+
+Note that `is_iterable` specifically excludes `str` and `bytes`: `is_iterable(str) == False` as, while `str` does support iteration, for the purposes of type casting, it's not really an iterable/container type.
+
+### `as_type`
+
+The signature is
+
+```py
+def as_type(value: Any, to: TypeHint, *, transparent_int: bool = False, semantic_bool: False = False) -> Any:
+  ...
+```
+
+In particular, it casts the given `value` to the given `to` type, regardless of whether `to` is:
+
+```py
+
+# a plain type
+>>> as_type(3.2, int)
+3
+
+# typing.Literal, returning the value as-is if it's a valid entry
+>>> as_type("abc", Literal["abc", "def"])
+'abc'
+
+>>> as_type("80", Literal[80, 443])
+ValueError(...)
+
+# a union type, casting to the first valid type
+>>> as_type("3", float | int)
+3.0
+
+>>> as_type("3", int | float)
+3
+
+# an optional type
+>>> as_type(43, int | None)
+43
+
+>>> as_type(None, int | None)
+None
+
+# a mapping type
+>>> as_type({"a": "1", "b": "2.0"}, dict[str, float])
+{'a': 1.0, 'b': 2.0}
+
+# a container/iterable type
+>>> as_type([1.2, -3, 449], list[str])
+['1.2', '-3', '449']
+
+>>> as_type([1.2, -3, 449], tuple[str, ...])
+('1.2', '-3', '449')
+
+# typing.Annotated, treating it as the bare type
+>>> as_type("3", Annotated[int, "some metadata"])
+3
+
+# an abstract collections.abc.Iterable/Mapping, cast as concrete list/dict
+>>> as_type([1.2, -3, 449], Iterable[str])
+['1.2', '-3', '449']
+
+>>> as_type({"a": "1", "b": "2.0"}, Mapping[str, float])
+{'a': 1.0, 'b': 2.0}
+
+# ...unless it's a string being cast as Iterable[str]
+>>> as_type("hello world", Iterable[str])
+'hello world'
+```
+
+On a failure, `ValueError` is raised.
+
+#### `transparent_int`
+
+This flag (default = False) allows for a nonstrict cast to `int`.
+
+```py
+>>> int("3.2", int)
+ValueError # invalid literal for int() with base 10: '3.2'
+
+>>> as_type("3.2", int)
+ValueError # invalid literal for int() with base 10: '3.2'
+
+>>> as_type("3.2", int, transparent_int = True)
+3
+```
+
+In practice, this flag results in a call of `int(float(value))` instead of just `int(value)`.
+
+#### `semantic_bool`
+
+This flag (default = False) allows for a nonstrict cast to `bool`.
+
+```py
+>>> bool("false")  # non-empty string
+True
+
+>>> as_type("false", bool)
+True
+
+>>> as_type("false", bool, semantic_bool = True)
+False
+```
+
+In practice, if `value` is a string and is one of `["false", "no", "0", "off"]` (case-insensitive), then it will be cast as `False` with this flag enabled.

typewire-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+typewire/__init__.py,sha256=j6T9wa5TbKAfZmB_7PqbYGQ3Miu63JRzvHaEoKIgMiE,149
+typewire/caster.py,sha256=RaiIZg5ClhnJDBFwh1GXsnGKN7ZglWx1EwANF2KsXic,6613
+typewire/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+typewire-0.1.0.dist-info/METADATA,sha256=kXGOByc2kqf21ZpN_cHNYNgR0zTle0af8x6B2HVZZxo,5541
+typewire-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+typewire-0.1.0.dist-info/licenses/LICENSE,sha256=jYMMQTZU3uN4XkybqyCDbjVfv9wWQRGPDkBebAxS-SQ,1065
+typewire-0.1.0.dist-info/RECORD,,

typewire-0.1.0.dist-info/WHEEL

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

typewire-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 lilellia
+
+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.