typely 0.1.0__tar.gz

typely-0.1.0/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 2.4
+Name: typely
+Version: 0.1.0
+Summary: Runtime type validation for Python — lightweight, fast, decorator-based
+Author: Teja
+License: MIT
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: hypothesis; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"

typely-0.1.0/README.md

@@ -0,0 +1,36 @@
+# typely
+
+Runtime type validation for Python — lightweight, fast, decorator-based.
+
+## Install
+
+```bash
+pip install -e .
+```
+
+## Quick Start
+
+```python
+from typely import validate
+
+@validate
+def create_user(name: str, age: int) -> dict:
+    return {"name": name, "age": age}
+
+create_user("Alice", 30)  # ✅
+create_user("Alice", "30")  # TypeError: age must be int, got str
+```
+
+## Features
+
+- **Decorator validation** — `@validate` validates args and return values at call time
+- **Advanced types** — `Optional`, `Union`, `Literal`, generics (`list[int]`, `dict[str, float]`)
+- **Custom validators** — `@validator(int)` to add custom checks
+- **Coercion** — `Coerce.SAFE` for str→int, str→float, etc.
+- **Schema validation** — `Schema({field: Field(...)})` for dict validation
+- **Standalone checks** — `typely.check(value, type_hint)` and `typely.is_valid()`
+- **Zero dependencies** — stdlib only
+
+## License
+
+MIT

typely-0.1.0/pyproject.toml

@@ -0,0 +1,14 @@
+[project]
+name = "typely"
+version = "0.1.0"
+description = "Runtime type validation for Python — lightweight, fast, decorator-based"
+license = {text = "MIT"}
+requires-python = ">=3.10"
+authors = [{name = "Teja"}]
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0", "hypothesis", "pytest-cov"]
+
+[tool.setuptools.packages.find]
+where = ["src"]

typely-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

typely-0.1.0/src/typely/__init__.py

@@ -0,0 +1,21 @@
+"""typely — Runtime type validation for Python."""
+
+from typely.errors import ValidationError, SchemaError
+from typely.validate import validate
+from typely.validators import validator
+from typely.check import check, is_valid
+from typely.schema import Schema, Field
+from typely.coerce import Coerce
+
+__all__ = [
+    "validate",
+    "validator",
+    "check",
+    "is_valid",
+    "Schema",
+    "Field",
+    "ValidationError",
+    "SchemaError",
+    "Coerce",
+]
+__version__ = "0.1.0"

typely-0.1.0/src/typely/check.py

@@ -0,0 +1,22 @@
+"""Type checking utilities."""
+
+from typing import Any
+from typely.types import _check_type
+
+
+def check(value: Any, type_hint: Any) -> bool:
+    """Check if value matches type_hint. Returns bool."""
+    errors = []
+    try:
+        _check_type(value, type_hint, field="", errors=errors)
+    except Exception:
+        return False
+    return len(errors) == 0
+
+
+def is_valid(value: Any, type_hint: Any) -> bool:
+    """Check if value matches type_hint. Never raises. Returns bool."""
+    try:
+        return check(value, type_hint)
+    except Exception:
+        return False

typely-0.1.0/src/typely/coerce.py

@@ -0,0 +1,8 @@
+"""Safe type coercion."""
+
+from enum import IntEnum
+
+
+class Coerce(IntEnum):
+    STRICT = 0
+    SAFE = 1

typely-0.1.0/src/typely/errors.py

@@ -0,0 +1,23 @@
+"""Validation errors."""
+
+
+class ValidationError(TypeError):
+    """Raised when type validation fails."""
+
+    def __init__(self, errors):
+        self.errors = errors
+        parts = [e.get("message", str(e)) for e in errors]
+        super().__init__("\n".join(parts))
+
+    def pretty(self):
+        lines = []
+        for e in self.errors:
+            field = e.get("field", "?")
+            msg = e.get("message", "")
+            lines.append(f"{field}: {msg}")
+        return "\n".join(lines)
+
+
+class SchemaError(ValidationError):
+    """Raised when schema validation fails."""
+    pass

typely-0.1.0/src/typely/schema.py

@@ -0,0 +1,75 @@
+"""Schema and Field for dict validation."""
+
+from typing import Any, Callable, Optional
+from typely.errors import SchemaError
+from typely.types import _check_type, _type_name
+from typely.coerce import Coerce
+
+
+class Field:
+    """A field definition for Schema validation."""
+
+    def __init__(self, type_hint: Any, *, required: bool = False, default: Any = None,
+                 validators: list = None):
+        self.type_hint = type_hint
+        self.required = required
+        self.default = default
+        self.validators = validators or []
+
+
+class Schema:
+    """Dict/data validation schema."""
+
+    def __init__(self, fields: dict, *, coerce=Coerce.STRICT):
+        self.fields = fields  # name -> Field
+        self.coerce = coerce
+
+    def validate(self, data: dict) -> dict:
+        """Validate data against schema. Returns (possibly coerced) data dict."""
+        if not isinstance(data, dict):
+            raise SchemaError([{
+                "field": "data",
+                "expected": "dict",
+                "got": type(data).__name__,
+                "value": data,
+                "message": f"expected dict, got {type(data).__name__}",
+            }])
+
+        errors = []
+        result = {}
+
+        # Check required fields and validate present fields
+        for name, field in self.fields.items():
+            if name not in data:
+                if field.required:
+                    errors.append({
+                        "field": name,
+                        "expected": _type_name(field.type_hint),
+                        "got": "missing",
+                        "value": None,
+                        "message": f"required field '{name}' is missing",
+                    })
+                else:
+                    result[name] = field.default
+            else:
+                value = data[name]
+                checked = _check_type(value, field.type_hint, name, errors, self.coerce)
+                if not errors:
+                    for vfn in field.validators:
+                        try:
+                            checked = vfn(checked)
+                        except (ValueError, TypeError) as e:
+                            errors.append({
+                                "field": name,
+                                "expected": vfn.__name__,
+                                "got": type(checked).__name__,
+                                "value": checked,
+                                "message": str(e),
+                            })
+                            break
+                result[name] = checked
+
+        if errors:
+            raise SchemaError(errors)
+
+        return result

typely-0.1.0/src/typely/types.py

@@ -0,0 +1,320 @@
+"""Type handling: Union, Optional, Literal, generics."""
+
+import types
+from typing import Any, Union, get_origin, get_args
+
+# Python 3.10+ these are builtins, but we need the typing module versions too
+try:
+    from types import UnionType
+except ImportError:
+    UnionType = None
+
+
+def _type_name(type_hint: Any) -> str:
+    """Get a readable name for a type hint."""
+    if type_hint is Any:
+        return "Any"
+    if type_hint is None or type_hint is type(None):
+        return "None"
+    if type_hint is int:
+        return "int"
+    if type_hint is float:
+        return "float"
+    if type_hint is str:
+        return "str"
+    if type_hint is bool:
+        return "bool"
+    if type_hint is list:
+        return "list"
+    if type_hint is dict:
+        return "dict"
+    if type_hint is tuple:
+        return "tuple"
+    if type_hint is set:
+        return "set"
+
+    origin = get_origin(type_hint)
+    if origin is Union:
+        args = get_args(type_hint)
+        return " | ".join(_type_name(a) for a in args)
+    if origin is type(None):
+        return "None"
+    if origin is list:
+        args = get_args(type_hint)
+        if args:
+            return f"list[{', '.join(_type_name(a) for a in args)}]"
+        return "list"
+    if origin is dict:
+        args = get_args(type_hint)
+        if args:
+            return f"dict[{', '.join(_type_name(a) for a in args)}]"
+        return "dict"
+    if origin is tuple:
+        args = get_args(type_hint)
+        if args:
+            names = [_type_name(a) if a is not ... else "..." for a in args]
+            return f"tuple[{', '.join(names)}]"
+        return "tuple"
+    if origin is set:
+        args = get_args(type_hint)
+        if args:
+            return f"set[{', '.join(_type_name(a) for a in args)}]"
+        return "set"
+    try:
+        return getattr(type_hint, "__name__", str(type_hint))
+    except Exception:
+        return str(type_hint)
+
+
+def _is_optional(type_hint: Any) -> bool:
+    """Check if a type hint allows None."""
+    origin = get_origin(type_hint)
+    if origin is Union:
+        args = get_args(type_hint)
+        return type(None) in args
+    if UnionType is not None:
+        if isinstance(type_hint, UnionType):
+            args = type_hint.__args__
+            return type(None) in args
+    return type_hint is type(None) or type_hint is None
+
+
+def _is_union(type_hint: Any) -> bool:
+    origin = get_origin(type_hint)
+    if origin is Union:
+        return True
+    if UnionType is not None:
+        return isinstance(type_hint, UnionType)
+    return False
+
+
+def _union_args(type_hint: Any) -> tuple:
+    if UnionType is not None and isinstance(type_hint, UnionType):
+        return type_hint.__args__
+    return get_args(type_hint)
+
+
+def _is_literal(type_hint: Any) -> bool:
+    origin = get_origin(type_hint)
+    return origin is not None and getattr(origin, "__name__", "") == "Literal"
+
+
+def _literal_values(type_hint: Any) -> tuple:
+    return get_args(type_hint)
+
+
+def _check_type(value: Any, type_hint: Any, field: str, errors: list, coerce: int = 0) -> Any:
+    """
+    Check if value matches type_hint.
+    
+    Args:
+        value: The value to check
+        type_hint: The type hint to check against
+        field: Field name for error messages
+        errors: List to append errors to
+        coerce: Coercion mode (0=STRICT, 1=SAFE)
+    
+    Returns:
+        The (possibly coerced) value
+    """
+    if type_hint is Any:
+        return value
+
+    # None check
+    if value is None:
+        if _is_optional(type_hint):
+            return None
+        errors.append({
+            "field": field,
+            "expected": _type_name(type_hint),
+            "got": type(None).__name__,
+            "value": None,
+            "message": f"expected {_type_name(type_hint)}, got None",
+        })
+        return None
+
+    # Union
+    if _is_union(type_hint):
+        args = _union_args(type_hint)
+        for arg in args:
+            test_errors = []
+            try:
+                _check_type(value, arg, field, test_errors, coerce)
+                if not test_errors:
+                    return value
+            except Exception:
+                continue
+        errors.append({
+            "field": field,
+            "expected": _type_name(type_hint),
+            "got": type(value).__name__,
+            "value": value,
+            "message": f"expected {_type_name(type_hint)}, got {type(value).__name__}",
+        })
+        return value
+
+    # Literal
+    if _is_literal(type_hint):
+        allowed = _literal_values(type_hint)
+        if value in allowed:
+            return value
+        errors.append({
+            "field": field,
+            "expected": _type_name(type_hint),
+            "got": type(value).__name__,
+            "value": value,
+            "message": f"expected {_type_name(type_hint)}, got {value!r}",
+        })
+        return value
+
+    # Primitives
+    if type_hint is int:
+        if isinstance(value, bool):
+            errors.append({"field": field, "expected": "int", "got": "bool", "value": value,
+                           "message": f"expected int, got bool ({value!r})"})
+            return value
+        if isinstance(value, int):
+            return value
+        if coerce and isinstance(value, str):
+            try:
+                return int(value)
+            except (ValueError, TypeError):
+                pass
+        if coerce and isinstance(value, float):
+            return int(value)
+        errors.append({"field": field, "expected": "int", "got": type(value).__name__, "value": value,
+                       "message": f"expected int, got {type(value).__name__} ({value!r})"})
+        return value
+
+    if type_hint is float:
+        if isinstance(value, bool):
+            errors.append({"field": field, "expected": "float", "got": "bool", "value": value,
+                           "message": f"expected float, got bool ({value!r})"})
+            return value
+        if isinstance(value, float):
+            return value
+        if isinstance(value, int):
+            return float(value)
+        if coerce and isinstance(value, str):
+            try:
+                return float(value)
+            except (ValueError, TypeError):
+                pass
+        errors.append({"field": field, "expected": "float", "got": type(value).__name__, "value": value,
+                       "message": f"expected float, got {type(value).__name__} ({value!r})"})
+        return value
+
+    if type_hint is str:
+        if isinstance(value, str):
+            return value
+        if coerce and isinstance(value, (int, float, bool)):
+            return str(value)
+        errors.append({"field": field, "expected": "str", "got": type(value).__name__, "value": value,
+                       "message": f"expected str, got {type(value).__name__} ({value!r})"})
+        return value
+
+    if type_hint is bool:
+        if isinstance(value, bool):
+            return value
+        if coerce and isinstance(value, str):
+            if value.lower() in ("true", "1", "yes"):
+                return True
+            if value.lower() in ("false", "0", "no"):
+                return False
+        errors.append({"field": field, "expected": "bool", "got": type(value).__name__, "value": value,
+                       "message": f"expected bool, got {type(value).__name__} ({value!r})"})
+        return value
+
+    # Collections
+    origin = get_origin(type_hint)
+
+    if type_hint is list or origin is list:
+        if not isinstance(value, list):
+            errors.append({"field": field, "expected": _type_name(type_hint), "got": type(value).__name__,
+                           "value": value, "message": f"expected {_type_name(type_hint)}, got {type(value).__name__}"})
+            return value
+        args = get_args(type_hint)
+        if args:
+            item_hint = args[0]
+            result = []
+            for i, item in enumerate(value):
+                checked = _check_type(item, item_hint, f"{field}[{i}]", errors, coerce)
+                result.append(checked)
+            return result
+        return value
+
+    if type_hint is dict or origin is dict:
+        if not isinstance(value, dict):
+            errors.append({"field": field, "expected": _type_name(type_hint), "got": type(value).__name__,
+                           "value": value, "message": f"expected {_type_name(type_hint)}, got {type(value).__name__}"})
+            return value
+        args = get_args(type_hint)
+        if args and len(args) == 2:
+            key_hint, val_hint = args
+            result = {}
+            for k, v in value.items():
+                _check_type(k, key_hint, f"{field}.key({k!r})", errors, coerce)
+                checked_v = _check_type(v, val_hint, f"{field}[{k!r}]", errors, coerce)
+                result[k] = checked_v
+            return result
+        return value
+
+    if type_hint is tuple or origin is tuple:
+        if not isinstance(value, tuple):
+            errors.append({"field": field, "expected": _type_name(type_hint), "got": type(value).__name__,
+                           "value": value, "message": f"expected {_type_name(type_hint)}, got {type(value).__name__}"})
+            return value
+        args = get_args(type_hint)
+        if args:
+            if len(args) == 2 and args[1] is ...:
+                # tuple[T, ...]
+                item_hint = args[0]
+                result = []
+                for i, item in enumerate(value):
+                    checked = _check_type(item, item_hint, f"{field}[{i}]", errors, coerce)
+                    result.append(checked)
+                return tuple(result)
+            else:
+                # Fixed-length tuple
+                if len(value) != len(args):
+                    errors.append({"field": field, "expected": f"tuple of length {len(args)}",
+                                   "got": f"tuple of length {len(value)}", "value": value,
+                                   "message": f"expected tuple of length {len(args)}, got {len(value)}"})
+                    return value
+                result = []
+                for i, (item, hint) in enumerate(zip(value, args)):
+                    checked = _check_type(item, hint, f"{field}[{i}]", errors, coerce)
+                    result.append(checked)
+                return tuple(result)
+        return value
+
+    if type_hint is set or origin is set:
+        if not isinstance(value, set):
+            errors.append({"field": field, "expected": _type_name(type_hint), "got": type(value).__name__,
+                           "value": value, "message": f"expected {_type_name(type_hint)}, got {type(value).__name__}"})
+            return value
+        args = get_args(type_hint)
+        if args:
+            item_hint = args[0]
+            result = set()
+            for item in value:
+                checked = _check_type(item, item_hint, f"{field}.item", errors, coerce)
+                result.add(checked)
+            return result
+        return value
+
+    # Fallback: isinstance check
+    if isinstance(type_hint, type):
+        if isinstance(value, type_hint):
+            return value
+        if isinstance(value, bool) and type_hint is not bool:
+            errors.append({"field": field, "expected": type_hint.__name__, "got": "bool", "value": value,
+                           "message": f"expected {type_hint.__name__}, got bool ({value!r})"})
+            return value
+        errors.append({"field": field, "expected": type_hint.__name__, "got": type(value).__name__,
+                       "value": value, "message": f"expected {type_hint.__name__}, got {type(value).__name__}"})
+        return value
+
+    errors.append({"field": field, "expected": _type_name(type_hint), "got": type(value).__name__,
+                   "value": value, "message": f"expected {_type_name(type_hint)}, got {type(value).__name__}"})
+    return value

typely-0.1.0/src/typely/validate.py

@@ -0,0 +1,141 @@
+"""@validate decorator."""
+
+import functools
+import inspect
+from typing import get_type_hints, Any
+from typely.errors import ValidationError
+from typely.types import _check_type, _is_optional, get_origin, get_args
+from typely.validators import run_validators, get_validators
+from typely.coerce import Coerce
+
+_ANNOTATED_MARKER = "__typely_validators__"
+
+
+def _extract_hint_and_validators(annotation, localns=None):
+    """Extract (base_type_hint, [validators]) from an annotation.
+    
+    Supports typing.Annotated[X, validator1, validator2] (Python 3.9+)
+    and plain type hints.
+    """
+    origin = get_origin(annotation)
+    if origin is not None and hasattr(origin, "__name__") and origin.__name__ == "Annotated":
+        args = get_args(annotation)
+        base_type = args[0]
+        validator_fns = [a for a in args[1:] if callable(a)]
+        return base_type, validator_fns
+    return annotation, []
+
+
+def _validate_return(result, annotations, coerce):
+    """Validate return value against annotations. Returns validated result."""
+    ret_hint = annotations.get("return")
+    if ret_hint is None:
+        return result
+    base_hint, validators = _extract_hint_and_validators(ret_hint)
+    ret_errors = []
+    coerced_result = _check_type(result, base_hint, "return", ret_errors, coerce)
+    if ret_errors:
+        raise ValidationError(ret_errors)
+    for vfn in validators:
+        coerced_result = vfn(coerced_result)
+    if not ret_errors:
+        coerced_result = run_validators(coerced_result, base_hint, "return", ret_errors)
+    if ret_errors:
+        raise ValidationError(ret_errors)
+    return coerced_result
+
+
+def validate(fn=None, *, coerce=Coerce.STRICT):
+    """Decorator for runtime type validation of function arguments and return value."""
+    
+    def decorator(func):
+        is_async = inspect.iscoroutinefunction(func)
+
+        def _validate_args(args, kwargs, annotations):
+            sig = inspect.signature(func)
+            params = list(sig.parameters.keys())
+            errors = []
+            new_args = list(args)
+
+            # Validate positional args
+            for i, arg_val in enumerate(args):
+                if i < len(params):
+                    param_name = params[i]
+                    if param_name in annotations:
+                        hint = annotations[param_name]
+                        base_hint, validators = _extract_hint_and_validators(hint)
+                        coerced = _check_type(arg_val, base_hint, param_name, errors, coerce)
+                        if not errors:
+                            for vfn in validators:
+                                try:
+                                    coerced = vfn(coerced)
+                                except (ValueError, TypeError) as e:
+                                    errors.append({
+                                        "field": param_name,
+                                        "expected": vfn.__name__,
+                                        "got": type(coerced).__name__,
+                                        "value": coerced,
+                                        "message": str(e),
+                                    })
+                                    break
+                            if not errors:
+                                coerced = run_validators(coerced, base_hint, param_name, errors)
+                        new_args[i] = coerced
+
+            # Validate keyword args
+            for key, arg_val in kwargs.items():
+                if key in annotations:
+                    hint = annotations[key]
+                    base_hint, validators = _extract_hint_and_validators(hint)
+                    coerced = _check_type(arg_val, base_hint, key, errors, coerce)
+                    if not errors:
+                        for vfn in validators:
+                            try:
+                                coerced = vfn(coerced)
+                            except (ValueError, TypeError) as e:
+                                errors.append({
+                                    "field": key,
+                                    "expected": vfn.__name__,
+                                    "got": type(coerced).__name__,
+                                    "value": coerced,
+                                    "message": str(e),
+                                })
+                                break
+                        if not errors:
+                            coerced = run_validators(coerced, base_hint, key, errors)
+                    kwargs[key] = coerced
+
+            if errors:
+                raise ValidationError(errors)
+            return new_args, kwargs
+
+        if is_async:
+            @functools.wraps(func)
+            async def wrapper(*args, **kwargs):
+                annotations = {}
+                try:
+                    annotations = get_type_hints(func, include_extras=True)
+                except Exception:
+                    annotations = getattr(func, "__annotations__", {})
+
+                new_args, kwargs = _validate_args(args, kwargs, annotations)
+                result = await func(*new_args, **kwargs)
+                return _validate_return(result, annotations, coerce)
+        else:
+            @functools.wraps(func)
+            def wrapper(*args, **kwargs):
+                annotations = {}
+                try:
+                    annotations = get_type_hints(func, include_extras=True)
+                except Exception:
+                    annotations = getattr(func, "__annotations__", {})
+
+                new_args, kwargs = _validate_args(args, kwargs, annotations)
+                result = func(*new_args, **kwargs)
+                return _validate_return(result, annotations, coerce)
+
+        return wrapper
+
+    if fn is not None:
+        return decorator(fn)
+    return decorator