pax_global_header00006660000000000000000000000064146227401160014515gustar00rootroot0000000000000052 comment=0735cd3d4c272b88405b6b04009716b691115210 annotated-types-0.7.0/000077500000000000000000000000001462274011600146405ustar00rootroot00000000000000annotated-types-0.7.0/.github/000077500000000000000000000000001462274011600162005ustar00rootroot00000000000000annotated-types-0.7.0/.github/workflows/000077500000000000000000000000001462274011600202355ustar00rootroot00000000000000annotated-types-0.7.0/.github/workflows/ci.yml000066400000000000000000000034551462274011600213620ustar00rootroot00000000000000name: CI on: push: branches: - main tags: - '**' pull_request: types: [opened, synchronize] jobs: test: name: test py-${{ matrix.python-version }} strategy: fail-fast: false matrix: python-version: ['3.8', '3.9', '3.10', '3.11', '3.12'] runs-on: ubuntu-latest env: PYTHON: ${{ matrix.python-version }} steps: - uses: actions/checkout@v3 - name: set up python uses: actions/setup-python@v4 with: python-version: ${{ matrix.python-version }} - run: pip install -r requirements/all.txt - run: pip install . - run: make test - run: coverage xml - uses: codecov/codecov-action@v3 with: file: ./coverage.xml env_vars: PYTHON lint: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - uses: actions/setup-python@v4 with: python-version: '3.10' - run: pip install -r requirements/all.txt - uses: pre-commit/action@v3.0.0 with: extra_args: --all-files --verbose deploy: needs: - test - lint if: "success() && startsWith(github.ref, 'refs/tags/')" runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: set up python uses: actions/setup-python@v4 with: python-version: '3.10' - run: pip install -U twine build - name: check GITHUB_REF matches package version uses: samuelcolvin/check-python-version@v3 with: version_file_path: annotated_types/__init__.py - name: build run: python -m build - run: twine check dist/* - name: upload to pypi run: twine upload dist/* env: TWINE_USERNAME: __token__ TWINE_PASSWORD: ${{ secrets.pypi_token }} annotated-types-0.7.0/.gitignore000066400000000000000000000003301462274011600166240ustar00rootroot00000000000000*.py[cod] .idea/ env/ env37/ env38/ env39/ env310/ .coverage .cache/ htmlcov/ media/ sandbox/ .pytest_cache/ *.egg-info/ /build/ /dist/ npm-debug.log* yarn-debug.log* yarn-error.log* /TODO.md /.mypy_cache/ /scratch/ annotated-types-0.7.0/.pre-commit-config.yaml000066400000000000000000000010531462274011600211200ustar00rootroot00000000000000repos: - repo: https://github.com/pre-commit/pre-commit-hooks rev: v4.3.0 hooks: - id: check-yaml - id: check-toml - id: end-of-file-fixer - id: trailing-whitespace - repo: local hooks: - id: lint name: Lint entry: make lint types: [python] language: system pass_filenames: false - id: mypy name: Mypy entry: make mypy types: [python] language: system pass_filenames: false - repo: https://github.com/asottile/pyupgrade rev: v2.38.2 hooks: - id: pyupgrade entry: pyupgrade --py37-plus annotated-types-0.7.0/LICENSE000066400000000000000000000020731462274011600156470ustar00rootroot00000000000000The MIT License (MIT) Copyright (c) 2022 the contributors 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. annotated-types-0.7.0/Makefile000066400000000000000000000016711462274011600163050ustar00rootroot00000000000000.DEFAULT_GOAL := all paths = annotated_types tests .PHONY: install install: pip install -r requirements/all.txt pre-commit install .PHONY: generate-dependencies generate-dependencies: pip-compile --output-file=requirements/all.txt --resolver=backtracking requirements/all.in .PHONY: format format: isort $(paths) black $(paths) .PHONY: lint lint: flake8 $(paths) isort $(paths) --check-only --df black $(paths) --check .PHONY: test test: coverage run -m pytest .PHONY: testcov testcov: test @coverage report --show-missing @coverage html .PHONY: mypy mypy: mypy annotated_types tests .PHONY: all all: lint mypy testcov .PHONY: clean clean: rm -rf `find . -name __pycache__` rm -f `find . -type f -name '*.py[co]' ` rm -f `find . -type f -name '*~' ` rm -f `find . -type f -name '.*~' ` rm -rf .cache rm -rf .pytest_cache rm -rf .mypy_cache rm -rf htmlcov rm -rf *.egg-info rm -f .coverage rm -f .coverage.* rm -rf build annotated-types-0.7.0/README.md000066400000000000000000000325031462274011600161220ustar00rootroot00000000000000# annotated-types [![CI](https://github.com/annotated-types/annotated-types/workflows/CI/badge.svg?event=push)](https://github.com/annotated-types/annotated-types/actions?query=event%3Apush+branch%3Amain+workflow%3ACI) [![pypi](https://img.shields.io/pypi/v/annotated-types.svg)](https://pypi.python.org/pypi/annotated-types) [![versions](https://img.shields.io/pypi/pyversions/annotated-types.svg)](https://github.com/annotated-types/annotated-types) [![license](https://img.shields.io/github/license/annotated-types/annotated-types.svg)](https://github.com/annotated-types/annotated-types/blob/main/LICENSE) [PEP-593](https://peps.python.org/pep-0593/) added `typing.Annotated` as a way of adding context-specific metadata to existing types, and specifies that `Annotated[T, x]` _should_ be treated as `T` by any tool or library without special logic for `x`. This package provides metadata objects which can be used to represent common constraints such as upper and lower bounds on scalar values and collection sizes, a `Predicate` marker for runtime checks, and descriptions of how we intend these metadata to be interpreted. In some cases, we also note alternative representations which do not require this package. ## Install ```bash pip install annotated-types ``` ## Examples ```python from typing import Annotated from annotated_types import Gt, Len, Predicate class MyClass: age: Annotated[int, Gt(18)] # Valid: 19, 20, ... # Invalid: 17, 18, "19", 19.0, ... factors: list[Annotated[int, Predicate(is_prime)]] # Valid: 2, 3, 5, 7, 11, ... # Invalid: 4, 8, -2, 5.0, "prime", ... my_list: Annotated[list[int], Len(0, 10)] # Valid: [], [10, 20, 30, 40, 50] # Invalid: (1, 2), ["abc"], [0] * 20 ``` ## Documentation _While `annotated-types` avoids runtime checks for performance, users should not construct invalid combinations such as `MultipleOf("non-numeric")` or `Annotated[int, Len(3)]`. Downstream implementors may choose to raise an error, emit a warning, silently ignore a metadata item, etc., if the metadata objects described below are used with an incompatible type - or for any other reason!_ ### Gt, Ge, Lt, Le Express inclusive and/or exclusive bounds on orderable values - which may be numbers, dates, times, strings, sets, etc. Note that the boundary value need not be of the same type that was annotated, so long as they can be compared: `Annotated[int, Gt(1.5)]` is fine, for example, and implies that the value is an integer x such that `x > 1.5`. We suggest that implementors may also interpret `functools.partial(operator.le, 1.5)` as being equivalent to `Gt(1.5)`, for users who wish to avoid a runtime dependency on the `annotated-types` package. To be explicit, these types have the following meanings: * `Gt(x)` - value must be "Greater Than" `x` - equivalent to exclusive minimum * `Ge(x)` - value must be "Greater than or Equal" to `x` - equivalent to inclusive minimum * `Lt(x)` - value must be "Less Than" `x` - equivalent to exclusive maximum * `Le(x)` - value must be "Less than or Equal" to `x` - equivalent to inclusive maximum ### Interval `Interval(gt, ge, lt, le)` allows you to specify an upper and lower bound with a single metadata object. `None` attributes should be ignored, and non-`None` attributes treated as per the single bounds above. ### MultipleOf `MultipleOf(multiple_of=x)` might be interpreted in two ways: 1. Python semantics, implying `value % multiple_of == 0`, or 2. [JSONschema semantics](https://json-schema.org/draft/2020-12/json-schema-validation.html#rfc.section.6.2.1), where `int(value / multiple_of) == value / multiple_of`. We encourage users to be aware of these two common interpretations and their distinct behaviours, especially since very large or non-integer numbers make it easy to cause silent data corruption due to floating-point imprecision. We encourage libraries to carefully document which interpretation they implement. ### MinLen, MaxLen, Len `Len()` implies that `min_length <= len(value) <= max_length` - lower and upper bounds are inclusive. As well as `Len()` which can optionally include upper and lower bounds, we also provide `MinLen(x)` and `MaxLen(y)` which are equivalent to `Len(min_length=x)` and `Len(max_length=y)` respectively. `Len`, `MinLen`, and `MaxLen` may be used with any type which supports `len(value)`. Examples of usage: * `Annotated[list, MaxLen(10)]` (or `Annotated[list, Len(max_length=10))`) - list must have a length of 10 or less * `Annotated[str, MaxLen(10)]` - string must have a length of 10 or less * `Annotated[list, MinLen(3))` (or `Annotated[list, Len(min_length=3))`) - list must have a length of 3 or more * `Annotated[list, Len(4, 6)]` - list must have a length of 4, 5, or 6 * `Annotated[list, Len(8, 8)]` - list must have a length of exactly 8 #### Changed in v0.4.0 * `min_inclusive` has been renamed to `min_length`, no change in meaning * `max_exclusive` has been renamed to `max_length`, upper bound is now **inclusive** instead of **exclusive** * The recommendation that slices are interpreted as `Len` has been removed due to ambiguity and different semantic meaning of the upper bound in slices vs. `Len` See [issue #23](https://github.com/annotated-types/annotated-types/issues/23) for discussion. ### Timezone `Timezone` can be used with a `datetime` or a `time` to express which timezones are allowed. `Annotated[datetime, Timezone(None)]` must be a naive datetime. `Timezone[...]` ([literal ellipsis](https://docs.python.org/3/library/constants.html#Ellipsis)) expresses that any timezone-aware datetime is allowed. You may also pass a specific timezone string or [`tzinfo`](https://docs.python.org/3/library/datetime.html#tzinfo-objects) object such as `Timezone(timezone.utc)` or `Timezone("Africa/Abidjan")` to express that you only allow a specific timezone, though we note that this is often a symptom of fragile design. #### Changed in v0.x.x * `Timezone` accepts [`tzinfo`](https://docs.python.org/3/library/datetime.html#tzinfo-objects) objects instead of `timezone`, extending compatibility to [`zoneinfo`](https://docs.python.org/3/library/zoneinfo.html) and third party libraries. ### Unit `Unit(unit: str)` expresses that the annotated numeric value is the magnitude of a quantity with the specified unit. For example, `Annotated[float, Unit("m/s")]` would be a float representing a velocity in meters per second. Please note that `annotated_types` itself makes no attempt to parse or validate the unit string in any way. That is left entirely to downstream libraries, such as [`pint`](https://pint.readthedocs.io) or [`astropy.units`](https://docs.astropy.org/en/stable/units/). An example of how a library might use this metadata: ```python from annotated_types import Unit from typing import Annotated, TypeVar, Callable, Any, get_origin, get_args # given a type annotated with a unit: Meters = Annotated[float, Unit("m")] # you can cast the annotation to a specific unit type with any # callable that accepts a string and returns the desired type T = TypeVar("T") def cast_unit(tp: Any, unit_cls: Callable[[str], T]) -> T | None: if get_origin(tp) is Annotated: for arg in get_args(tp): if isinstance(arg, Unit): return unit_cls(arg.unit) return None # using `pint` import pint pint_unit = cast_unit(Meters, pint.Unit) # using `astropy.units` import astropy.units as u astropy_unit = cast_unit(Meters, u.Unit) ``` ### Predicate `Predicate(func: Callable)` expresses that `func(value)` is truthy for valid values. Users should prefer the statically inspectable metadata above, but if you need the full power and flexibility of arbitrary runtime predicates... here it is. For some common constraints, we provide generic types: * `IsLower = Annotated[T, Predicate(str.islower)]` * `IsUpper = Annotated[T, Predicate(str.isupper)]` * `IsDigit = Annotated[T, Predicate(str.isdigit)]` * `IsFinite = Annotated[T, Predicate(math.isfinite)]` * `IsNotFinite = Annotated[T, Predicate(Not(math.isfinite))]` * `IsNan = Annotated[T, Predicate(math.isnan)]` * `IsNotNan = Annotated[T, Predicate(Not(math.isnan))]` * `IsInfinite = Annotated[T, Predicate(math.isinf)]` * `IsNotInfinite = Annotated[T, Predicate(Not(math.isinf))]` so that you can write e.g. `x: IsFinite[float] = 2.0` instead of the longer (but exactly equivalent) `x: Annotated[float, Predicate(math.isfinite)] = 2.0`. Some libraries might have special logic to handle known or understandable predicates, for example by checking for `str.isdigit` and using its presence to both call custom logic to enforce digit-only strings, and customise some generated external schema. Users are therefore encouraged to avoid indirection like `lambda s: s.lower()`, in favor of introspectable methods such as `str.lower` or `re.compile("pattern").search`. To enable basic negation of commonly used predicates like `math.isnan` without introducing introspection that makes it impossible for implementers to introspect the predicate we provide a `Not` wrapper that simply negates the predicate in an introspectable manner. Several of the predicates listed above are created in this manner. We do not specify what behaviour should be expected for predicates that raise an exception. For example `Annotated[int, Predicate(str.isdigit)]` might silently skip invalid constraints, or statically raise an error; or it might try calling it and then propagate or discard the resulting `TypeError: descriptor 'isdigit' for 'str' objects doesn't apply to a 'int' object` exception. We encourage libraries to document the behaviour they choose. ### Doc `doc()` can be used to add documentation information in `Annotated`, for function and method parameters, variables, class attributes, return types, and any place where `Annotated` can be used. It expects a value that can be statically analyzed, as the main use case is for static analysis, editors, documentation generators, and similar tools. It returns a `DocInfo` class with a single attribute `documentation` containing the value passed to `doc()`. This is the early adopter's alternative form of the [`typing-doc` proposal](https://github.com/tiangolo/fastapi/blob/typing-doc/typing_doc.md). ### Integrating downstream types with `GroupedMetadata` Implementers may choose to provide a convenience wrapper that groups multiple pieces of metadata. This can help reduce verbosity and cognitive overhead for users. For example, an implementer like Pydantic might provide a `Field` or `Meta` type that accepts keyword arguments and transforms these into low-level metadata: ```python from dataclasses import dataclass from typing import Iterator from annotated_types import GroupedMetadata, Ge @dataclass class Field(GroupedMetadata): ge: int | None = None description: str | None = None def __iter__(self) -> Iterator[object]: # Iterating over a GroupedMetadata object should yield annotated-types # constraint metadata objects which describe it as fully as possible, # and may include other unknown objects too. if self.ge is not None: yield Ge(self.ge) if self.description is not None: yield Description(self.description) ``` Libraries consuming annotated-types constraints should check for `GroupedMetadata` and unpack it by iterating over the object and treating the results as if they had been "unpacked" in the `Annotated` type. The same logic should be applied to the [PEP 646 `Unpack` type](https://peps.python.org/pep-0646/), so that `Annotated[T, Field(...)]`, `Annotated[T, Unpack[Field(...)]]` and `Annotated[T, *Field(...)]` are all treated consistently. Libraries consuming annotated-types should also ignore any metadata they do not recongize that came from unpacking a `GroupedMetadata`, just like they ignore unrecognized metadata in `Annotated` itself. Our own `annotated_types.Interval` class is a `GroupedMetadata` which unpacks itself into `Gt`, `Lt`, etc., so this is not an abstract concern. Similarly, `annotated_types.Len` is a `GroupedMetadata` which unpacks itself into `MinLen` (optionally) and `MaxLen`. ### Consuming metadata We intend to not be prescriptive as to _how_ the metadata and constraints are used, but as an example of how one might parse constraints from types annotations see our [implementation in `test_main.py`](https://github.com/annotated-types/annotated-types/blob/f59cf6d1b5255a0fe359b93896759a180bec30ae/tests/test_main.py#L94-L103). It is up to the implementer to determine how this metadata is used. You could use the metadata for runtime type checking, for generating schemas or to generate example data, amongst other use cases. ## Design & History This package was designed at the PyCon 2022 sprints by the maintainers of Pydantic and Hypothesis, with the goal of making it as easy as possible for end-users to provide more informative annotations for use by runtime libraries. It is deliberately minimal, and following PEP-593 allows considerable downstream discretion in what (if anything!) they choose to support. Nonetheless, we expect that staying simple and covering _only_ the most common use-cases will give users and maintainers the best experience we can. If you'd like more constraints for your types - follow our lead, by defining them and documenting them downstream! annotated-types-0.7.0/annotated_types/000077500000000000000000000000001462274011600200415ustar00rootroot00000000000000annotated-types-0.7.0/annotated_types/__init__.py000066400000000000000000000327731462274011600221660ustar00rootroot00000000000000import math import sys import types from dataclasses import dataclass from datetime import tzinfo from typing import TYPE_CHECKING, Any, Callable, Iterator, Optional, SupportsFloat, SupportsIndex, TypeVar, Union if sys.version_info < (3, 8): from typing_extensions import Protocol, runtime_checkable else: from typing import Protocol, runtime_checkable if sys.version_info < (3, 9): from typing_extensions import Annotated, Literal else: from typing import Annotated, Literal if sys.version_info < (3, 10): EllipsisType = type(Ellipsis) KW_ONLY = {} SLOTS = {} else: from types import EllipsisType KW_ONLY = {"kw_only": True} SLOTS = {"slots": True} __all__ = ( 'BaseMetadata', 'GroupedMetadata', 'Gt', 'Ge', 'Lt', 'Le', 'Interval', 'MultipleOf', 'MinLen', 'MaxLen', 'Len', 'Timezone', 'Predicate', 'LowerCase', 'UpperCase', 'IsDigits', 'IsFinite', 'IsNotFinite', 'IsNan', 'IsNotNan', 'IsInfinite', 'IsNotInfinite', 'doc', 'DocInfo', '__version__', ) __version__ = '0.7.0' T = TypeVar('T') # arguments that start with __ are considered # positional only # see https://peps.python.org/pep-0484/#positional-only-arguments class SupportsGt(Protocol): def __gt__(self: T, __other: T) -> bool: ... class SupportsGe(Protocol): def __ge__(self: T, __other: T) -> bool: ... class SupportsLt(Protocol): def __lt__(self: T, __other: T) -> bool: ... class SupportsLe(Protocol): def __le__(self: T, __other: T) -> bool: ... class SupportsMod(Protocol): def __mod__(self: T, __other: T) -> T: ... class SupportsDiv(Protocol): def __div__(self: T, __other: T) -> T: ... class BaseMetadata: """Base class for all metadata. This exists mainly so that implementers can do `isinstance(..., BaseMetadata)` while traversing field annotations. """ __slots__ = () @dataclass(frozen=True, **SLOTS) class Gt(BaseMetadata): """Gt(gt=x) implies that the value must be greater than x. It can be used with any type that supports the ``>`` operator, including numbers, dates and times, strings, sets, and so on. """ gt: SupportsGt @dataclass(frozen=True, **SLOTS) class Ge(BaseMetadata): """Ge(ge=x) implies that the value must be greater than or equal to x. It can be used with any type that supports the ``>=`` operator, including numbers, dates and times, strings, sets, and so on. """ ge: SupportsGe @dataclass(frozen=True, **SLOTS) class Lt(BaseMetadata): """Lt(lt=x) implies that the value must be less than x. It can be used with any type that supports the ``<`` operator, including numbers, dates and times, strings, sets, and so on. """ lt: SupportsLt @dataclass(frozen=True, **SLOTS) class Le(BaseMetadata): """Le(le=x) implies that the value must be less than or equal to x. It can be used with any type that supports the ``<=`` operator, including numbers, dates and times, strings, sets, and so on. """ le: SupportsLe @runtime_checkable class GroupedMetadata(Protocol): """A grouping of multiple objects, like typing.Unpack. `GroupedMetadata` on its own is not metadata and has no meaning. All of the constraints and metadata should be fully expressable in terms of the `BaseMetadata`'s returned by `GroupedMetadata.__iter__()`. Concrete implementations should override `GroupedMetadata.__iter__()` to add their own metadata. For example: >>> @dataclass >>> class Field(GroupedMetadata): >>> gt: float | None = None >>> description: str | None = None ... >>> def __iter__(self) -> Iterable[object]: >>> if self.gt is not None: >>> yield Gt(self.gt) >>> if self.description is not None: >>> yield Description(self.gt) Also see the implementation of `Interval` below for an example. Parsers should recognize this and unpack it so that it can be used both with and without unpacking: - `Annotated[int, Field(...)]` (parser must unpack Field) - `Annotated[int, *Field(...)]` (PEP-646) """ # noqa: trailing-whitespace @property def __is_annotated_types_grouped_metadata__(self) -> Literal[True]: return True def __iter__(self) -> Iterator[object]: ... if not TYPE_CHECKING: __slots__ = () # allow subclasses to use slots def __init_subclass__(cls, *args: Any, **kwargs: Any) -> None: # Basic ABC like functionality without the complexity of an ABC super().__init_subclass__(*args, **kwargs) if cls.__iter__ is GroupedMetadata.__iter__: raise TypeError("Can't subclass GroupedMetadata without implementing __iter__") def __iter__(self) -> Iterator[object]: # noqa: F811 raise NotImplementedError # more helpful than "None has no attribute..." type errors @dataclass(frozen=True, **KW_ONLY, **SLOTS) class Interval(GroupedMetadata): """Interval can express inclusive or exclusive bounds with a single object. It accepts keyword arguments ``gt``, ``ge``, ``lt``, and/or ``le``, which are interpreted the same way as the single-bound constraints. """ gt: Union[SupportsGt, None] = None ge: Union[SupportsGe, None] = None lt: Union[SupportsLt, None] = None le: Union[SupportsLe, None] = None def __iter__(self) -> Iterator[BaseMetadata]: """Unpack an Interval into zero or more single-bounds.""" if self.gt is not None: yield Gt(self.gt) if self.ge is not None: yield Ge(self.ge) if self.lt is not None: yield Lt(self.lt) if self.le is not None: yield Le(self.le) @dataclass(frozen=True, **SLOTS) class MultipleOf(BaseMetadata): """MultipleOf(multiple_of=x) might be interpreted in two ways: 1. Python semantics, implying ``value % multiple_of == 0``, or 2. JSONschema semantics, where ``int(value / multiple_of) == value / multiple_of`` We encourage users to be aware of these two common interpretations, and libraries to carefully document which they implement. """ multiple_of: Union[SupportsDiv, SupportsMod] @dataclass(frozen=True, **SLOTS) class MinLen(BaseMetadata): """ MinLen() implies minimum inclusive length, e.g. ``len(value) >= min_length``. """ min_length: Annotated[int, Ge(0)] @dataclass(frozen=True, **SLOTS) class MaxLen(BaseMetadata): """ MaxLen() implies maximum inclusive length, e.g. ``len(value) <= max_length``. """ max_length: Annotated[int, Ge(0)] @dataclass(frozen=True, **SLOTS) class Len(GroupedMetadata): """ Len() implies that ``min_length <= len(value) <= max_length``. Upper bound may be omitted or ``None`` to indicate no upper length bound. """ min_length: Annotated[int, Ge(0)] = 0 max_length: Optional[Annotated[int, Ge(0)]] = None def __iter__(self) -> Iterator[BaseMetadata]: """Unpack a Len into zone or more single-bounds.""" if self.min_length > 0: yield MinLen(self.min_length) if self.max_length is not None: yield MaxLen(self.max_length) @dataclass(frozen=True, **SLOTS) class Timezone(BaseMetadata): """Timezone(tz=...) requires a datetime to be aware (or ``tz=None``, naive). ``Annotated[datetime, Timezone(None)]`` must be a naive datetime. ``Timezone[...]`` (the ellipsis literal) expresses that the datetime must be tz-aware but any timezone is allowed. You may also pass a specific timezone string or tzinfo object such as ``Timezone(timezone.utc)`` or ``Timezone("Africa/Abidjan")`` to express that you only allow a specific timezone, though we note that this is often a symptom of poor design. """ tz: Union[str, tzinfo, EllipsisType, None] @dataclass(frozen=True, **SLOTS) class Unit(BaseMetadata): """Indicates that the value is a physical quantity with the specified unit. It is intended for usage with numeric types, where the value represents the magnitude of the quantity. For example, ``distance: Annotated[float, Unit('m')]`` or ``speed: Annotated[float, Unit('m/s')]``. Interpretation of the unit string is left to the discretion of the consumer. It is suggested to follow conventions established by python libraries that work with physical quantities, such as - ``pint`` : - ``astropy.units``: For indicating a quantity with a certain dimensionality but without a specific unit it is recommended to use square brackets, e.g. `Annotated[float, Unit('[time]')]`. Note, however, ``annotated_types`` itself makes no use of the unit string. """ unit: str @dataclass(frozen=True, **SLOTS) class Predicate(BaseMetadata): """``Predicate(func: Callable)`` implies `func(value)` is truthy for valid values. Users should prefer statically inspectable metadata, but if you need the full power and flexibility of arbitrary runtime predicates... here it is. We provide a few predefined predicates for common string constraints: ``IsLower = Predicate(str.islower)``, ``IsUpper = Predicate(str.isupper)``, and ``IsDigits = Predicate(str.isdigit)``. Users are encouraged to use methods which can be given special handling, and avoid indirection like ``lambda s: s.lower()``. Some libraries might have special logic to handle certain predicates, e.g. by checking for `str.isdigit` and using its presence to both call custom logic to enforce digit-only strings, and customise some generated external schema. We do not specify what behaviour should be expected for predicates that raise an exception. For example `Annotated[int, Predicate(str.isdigit)]` might silently skip invalid constraints, or statically raise an error; or it might try calling it and then propagate or discard the resulting exception. """ func: Callable[[Any], bool] def __repr__(self) -> str: if getattr(self.func, "__name__", "") == "": return f"{self.__class__.__name__}({self.func!r})" if isinstance(self.func, (types.MethodType, types.BuiltinMethodType)) and ( namespace := getattr(self.func.__self__, "__name__", None) ): return f"{self.__class__.__name__}({namespace}.{self.func.__name__})" if isinstance(self.func, type(str.isascii)): # method descriptor return f"{self.__class__.__name__}({self.func.__qualname__})" return f"{self.__class__.__name__}({self.func.__name__})" @dataclass class Not: func: Callable[[Any], bool] def __call__(self, __v: Any) -> bool: return not self.func(__v) _StrType = TypeVar("_StrType", bound=str) LowerCase = Annotated[_StrType, Predicate(str.islower)] """ Return True if the string is a lowercase string, False otherwise. A string is lowercase if all cased characters in the string are lowercase and there is at least one cased character in the string. """ # noqa: E501 UpperCase = Annotated[_StrType, Predicate(str.isupper)] """ Return True if the string is an uppercase string, False otherwise. A string is uppercase if all cased characters in the string are uppercase and there is at least one cased character in the string. """ # noqa: E501 IsDigit = Annotated[_StrType, Predicate(str.isdigit)] IsDigits = IsDigit # type: ignore # plural for backwards compatibility, see #63 """ Return True if the string is a digit string, False otherwise. A string is a digit string if all characters in the string are digits and there is at least one character in the string. """ # noqa: E501 IsAscii = Annotated[_StrType, Predicate(str.isascii)] """ Return True if all characters in the string are ASCII, False otherwise. ASCII characters have code points in the range U+0000-U+007F. Empty string is ASCII too. """ _NumericType = TypeVar('_NumericType', bound=Union[SupportsFloat, SupportsIndex]) IsFinite = Annotated[_NumericType, Predicate(math.isfinite)] """Return True if x is neither an infinity nor a NaN, and False otherwise.""" IsNotFinite = Annotated[_NumericType, Predicate(Not(math.isfinite))] """Return True if x is one of infinity or NaN, and False otherwise""" IsNan = Annotated[_NumericType, Predicate(math.isnan)] """Return True if x is a NaN (not a number), and False otherwise.""" IsNotNan = Annotated[_NumericType, Predicate(Not(math.isnan))] """Return True if x is anything but NaN (not a number), and False otherwise.""" IsInfinite = Annotated[_NumericType, Predicate(math.isinf)] """Return True if x is a positive or negative infinity, and False otherwise.""" IsNotInfinite = Annotated[_NumericType, Predicate(Not(math.isinf))] """Return True if x is neither a positive or negative infinity, and False otherwise.""" try: from typing_extensions import DocInfo, doc # type: ignore [attr-defined] except ImportError: @dataclass(frozen=True, **SLOTS) class DocInfo: # type: ignore [no-redef] """ " The return value of doc(), mainly to be used by tools that want to extract the Annotated documentation at runtime. """ documentation: str """The documentation string passed to doc().""" def doc( documentation: str, ) -> DocInfo: """ Add documentation to a type annotation inside of Annotated. For example: >>> def hi(name: Annotated[int, doc("The name of the user")]) -> None: ... """ return DocInfo(documentation) annotated-types-0.7.0/annotated_types/py.typed000066400000000000000000000000001462274011600215260ustar00rootroot00000000000000annotated-types-0.7.0/annotated_types/test_cases.py000066400000000000000000000144251462274011600225560ustar00rootroot00000000000000import math import sys from datetime import date, datetime, timedelta, timezone from decimal import Decimal from typing import Any, Dict, Iterable, Iterator, List, NamedTuple, Set, Tuple if sys.version_info < (3, 9): from typing_extensions import Annotated else: from typing import Annotated import annotated_types as at class Case(NamedTuple): """ A test case for `annotated_types`. """ annotation: Any valid_cases: Iterable[Any] invalid_cases: Iterable[Any] def cases() -> Iterable[Case]: # Gt, Ge, Lt, Le yield Case(Annotated[int, at.Gt(4)], (5, 6, 1000), (4, 0, -1)) yield Case(Annotated[float, at.Gt(0.5)], (0.6, 0.7, 0.8, 0.9), (0.5, 0.0, -0.1)) yield Case( Annotated[datetime, at.Gt(datetime(2000, 1, 1))], [datetime(2000, 1, 2), datetime(2000, 1, 3)], [datetime(2000, 1, 1), datetime(1999, 12, 31)], ) yield Case( Annotated[datetime, at.Gt(date(2000, 1, 1))], [date(2000, 1, 2), date(2000, 1, 3)], [date(2000, 1, 1), date(1999, 12, 31)], ) yield Case( Annotated[datetime, at.Gt(Decimal('1.123'))], [Decimal('1.1231'), Decimal('123')], [Decimal('1.123'), Decimal('0')], ) yield Case(Annotated[int, at.Ge(4)], (4, 5, 6, 1000, 4), (0, -1)) yield Case(Annotated[float, at.Ge(0.5)], (0.5, 0.6, 0.7, 0.8, 0.9), (0.4, 0.0, -0.1)) yield Case( Annotated[datetime, at.Ge(datetime(2000, 1, 1))], [datetime(2000, 1, 2), datetime(2000, 1, 3)], [datetime(1998, 1, 1), datetime(1999, 12, 31)], ) yield Case(Annotated[int, at.Lt(4)], (0, -1), (4, 5, 6, 1000, 4)) yield Case(Annotated[float, at.Lt(0.5)], (0.4, 0.0, -0.1), (0.5, 0.6, 0.7, 0.8, 0.9)) yield Case( Annotated[datetime, at.Lt(datetime(2000, 1, 1))], [datetime(1999, 12, 31), datetime(1999, 12, 31)], [datetime(2000, 1, 2), datetime(2000, 1, 3)], ) yield Case(Annotated[int, at.Le(4)], (4, 0, -1), (5, 6, 1000)) yield Case(Annotated[float, at.Le(0.5)], (0.5, 0.0, -0.1), (0.6, 0.7, 0.8, 0.9)) yield Case( Annotated[datetime, at.Le(datetime(2000, 1, 1))], [datetime(2000, 1, 1), datetime(1999, 12, 31)], [datetime(2000, 1, 2), datetime(2000, 1, 3)], ) # Interval yield Case(Annotated[int, at.Interval(gt=4)], (5, 6, 1000), (4, 0, -1)) yield Case(Annotated[int, at.Interval(gt=4, lt=10)], (5, 6), (4, 10, 1000, 0, -1)) yield Case(Annotated[float, at.Interval(ge=0.5, le=1)], (0.5, 0.9, 1), (0.49, 1.1)) yield Case( Annotated[datetime, at.Interval(gt=datetime(2000, 1, 1), le=datetime(2000, 1, 3))], [datetime(2000, 1, 2), datetime(2000, 1, 3)], [datetime(2000, 1, 1), datetime(2000, 1, 4)], ) yield Case(Annotated[int, at.MultipleOf(multiple_of=3)], (0, 3, 9), (1, 2, 4)) yield Case(Annotated[float, at.MultipleOf(multiple_of=0.5)], (0, 0.5, 1, 1.5), (0.4, 1.1)) # lengths yield Case(Annotated[str, at.MinLen(3)], ('123', '1234', 'x' * 10), ('', '1', '12')) yield Case(Annotated[str, at.Len(3)], ('123', '1234', 'x' * 10), ('', '1', '12')) yield Case(Annotated[List[int], at.MinLen(3)], ([1, 2, 3], [1, 2, 3, 4], [1] * 10), ([], [1], [1, 2])) yield Case(Annotated[List[int], at.Len(3)], ([1, 2, 3], [1, 2, 3, 4], [1] * 10), ([], [1], [1, 2])) yield Case(Annotated[str, at.MaxLen(4)], ('', '1234'), ('12345', 'x' * 10)) yield Case(Annotated[str, at.Len(0, 4)], ('', '1234'), ('12345', 'x' * 10)) yield Case(Annotated[List[str], at.MaxLen(4)], ([], ['a', 'bcdef'], ['a', 'b', 'c']), (['a'] * 5, ['b'] * 10)) yield Case(Annotated[List[str], at.Len(0, 4)], ([], ['a', 'bcdef'], ['a', 'b', 'c']), (['a'] * 5, ['b'] * 10)) yield Case(Annotated[str, at.Len(3, 5)], ('123', '12345'), ('', '1', '12', '123456', 'x' * 10)) yield Case(Annotated[str, at.Len(3, 3)], ('123',), ('12', '1234')) yield Case(Annotated[Dict[int, int], at.Len(2, 3)], [{1: 1, 2: 2}], [{}, {1: 1}, {1: 1, 2: 2, 3: 3, 4: 4}]) yield Case(Annotated[Set[int], at.Len(2, 3)], ({1, 2}, {1, 2, 3}), (set(), {1}, {1, 2, 3, 4})) yield Case(Annotated[Tuple[int, ...], at.Len(2, 3)], ((1, 2), (1, 2, 3)), ((), (1,), (1, 2, 3, 4))) # Timezone yield Case( Annotated[datetime, at.Timezone(None)], [datetime(2000, 1, 1)], [datetime(2000, 1, 1, tzinfo=timezone.utc)] ) yield Case( Annotated[datetime, at.Timezone(...)], [datetime(2000, 1, 1, tzinfo=timezone.utc)], [datetime(2000, 1, 1)] ) yield Case( Annotated[datetime, at.Timezone(timezone.utc)], [datetime(2000, 1, 1, tzinfo=timezone.utc)], [datetime(2000, 1, 1), datetime(2000, 1, 1, tzinfo=timezone(timedelta(hours=6)))], ) yield Case( Annotated[datetime, at.Timezone('Europe/London')], [datetime(2000, 1, 1, tzinfo=timezone(timedelta(0), name='Europe/London'))], [datetime(2000, 1, 1), datetime(2000, 1, 1, tzinfo=timezone(timedelta(hours=6)))], ) # Quantity yield Case(Annotated[float, at.Unit(unit='m')], (5, 4.2), ('5m', '4.2m')) # predicate types yield Case(at.LowerCase[str], ['abc', 'foobar'], ['', 'A', 'Boom']) yield Case(at.UpperCase[str], ['ABC', 'DEFO'], ['', 'a', 'abc', 'AbC']) yield Case(at.IsDigit[str], ['123'], ['', 'ab', 'a1b2']) yield Case(at.IsAscii[str], ['123', 'foo bar'], ['£100', '😊', 'whatever 👀']) yield Case(Annotated[int, at.Predicate(lambda x: x % 2 == 0)], [0, 2, 4], [1, 3, 5]) yield Case(at.IsFinite[float], [1.23], [math.nan, math.inf, -math.inf]) yield Case(at.IsNotFinite[float], [math.nan, math.inf], [1.23]) yield Case(at.IsNan[float], [math.nan], [1.23, math.inf]) yield Case(at.IsNotNan[float], [1.23, math.inf], [math.nan]) yield Case(at.IsInfinite[float], [math.inf], [math.nan, 1.23]) yield Case(at.IsNotInfinite[float], [math.nan, 1.23], [math.inf]) # check stacked predicates yield Case(at.IsInfinite[Annotated[float, at.Predicate(lambda x: x > 0)]], [math.inf], [-math.inf, 1.23, math.nan]) # doc yield Case(Annotated[int, at.doc("A number")], [1, 2], []) # custom GroupedMetadata class MyCustomGroupedMetadata(at.GroupedMetadata): def __iter__(self) -> Iterator[at.Predicate]: yield at.Predicate(lambda x: float(x).is_integer()) yield Case(Annotated[float, MyCustomGroupedMetadata()], [0, 2.0], [0.01, 1.5]) annotated-types-0.7.0/pyproject.toml000066400000000000000000000044571462274011600175660ustar00rootroot00000000000000[project] name = "annotated-types" description = "Reusable constraint types to use with typing.Annotated" authors = [ {name = "Adrian Garcia Badaracco", email = "1755071+adriangb@users.noreply.github.com"}, {name = "Samuel Colvin", email = "s@muelcolvin.com"}, {name = "Zac Hatfield-Dodds", email = "zac@zhd.dev"}, ] readme = "README.md" repository = "https://github.com/annotated-types/annotated-types" license-files = { paths = ['LICENSE'] } classifiers = [ "Development Status :: 4 - Beta", "Intended Audience :: Developers", "Intended Audience :: Information Technology", "Operating System :: Unix", "Operating System :: POSIX :: Linux", "Environment :: Console", "Environment :: MacOS X", "License :: OSI Approved :: MIT License", "Programming Language :: Python :: 3 :: Only", "Programming Language :: Python :: 3.8", "Programming Language :: Python :: 3.9", "Programming Language :: Python :: 3.10", "Programming Language :: Python :: 3.11", "Programming Language :: Python :: 3.12", "Topic :: Software Development :: Libraries :: Python Modules", "Typing :: Typed", ] requires-python = ">=3.8" dependencies = ["typing-extensions>=4.0.0; python_version<'3.9'"] dynamic = ["version"] [project.urls] Homepage = "https://github.com/annotated-types/annotated-types" Source = "https://github.com/annotated-types/annotated-types" Changelog = "https://github.com/annotated-types/annotated-types/releases" [build-system] requires = ["hatchling"] build-backend = "hatchling.build" [tool.hatch.version] path = "annotated_types/__init__.py" [tool.pytest.ini_options] testpaths = "tests" filterwarnings = "error" [tool.flake8] max_line_length = 120 max_complexity = 10 ignore = ["E203", "W503"] [tool.coverage.run] source = ["annotated_types"] branch = true [tool.coverage.report] precision = 2 exclude_lines = [ "pragma: no cover", "raise NotImplementedError", "raise NotImplemented", "if TYPE_CHECKING:", "@overload", ] [tool.black] color = true line-length = 120 target-version = ["py310"] skip-string-normalization = true [tool.isort] line_length = 120 multi_line_output = 3 include_trailing_comma = true force_grid_wrap = 0 combine_as_imports = true color_output = true [tool.mypy] strict = true warn_return_any = false show_error_codes = true annotated-types-0.7.0/requirements/000077500000000000000000000000001462274011600173635ustar00rootroot00000000000000annotated-types-0.7.0/requirements/all.in000066400000000000000000000000401462274011600204550ustar00rootroot00000000000000-r ./linting.in -r ./testing.in annotated-types-0.7.0/requirements/all.txt000066400000000000000000000031731462274011600207000ustar00rootroot00000000000000# # This file is autogenerated by pip-compile with Python 3.11 # by the following command: # # pip-compile --output-file=requirements/all.txt requirements/all.in # black==23.7.0 # via -r requirements/./linting.in cfgv==3.4.0 # via pre-commit click==8.1.7 # via black colorama==0.4.6 # via isort coverage==7.3.0 # via -r requirements/./testing.in distlib==0.3.7 # via virtualenv filelock==3.12.2 # via virtualenv flake8==6.1.0 # via # -r requirements/./linting.in # flake8-pyproject flake8-pyproject==1.2.3 # via -r requirements/./linting.in identify==2.5.27 # via pre-commit iniconfig==2.0.0 # via pytest isort[colors]==5.12.0 # via -r requirements/./linting.in mccabe==0.7.0 # via flake8 mypy==1.5.1 # via -r requirements/./linting.in mypy-extensions==1.0.0 # via # black # mypy nodeenv==1.8.0 # via pre-commit packaging==23.1 # via # black # pytest # pytest-sugar pathspec==0.11.2 # via black platformdirs==3.10.0 # via # black # virtualenv pluggy==1.3.0 # via pytest pre-commit==3.3.3 # via -r requirements/./linting.in pycodestyle==2.11.0 # via flake8 pyflakes==3.1.0 # via flake8 pytest==7.4.0 # via # -r requirements/./linting.in # -r requirements/./testing.in # pytest-sugar pytest-sugar==0.9.7 # via -r requirements/./testing.in pyyaml==6.0.1 # via pre-commit termcolor==2.3.0 # via pytest-sugar typing-extensions==4.7.1 # via mypy virtualenv==20.24.3 # via pre-commit # The following packages are considered to be unsafe in a requirements file: # setuptools annotated-types-0.7.0/requirements/linting.in000066400000000000000000000001031462274011600213510ustar00rootroot00000000000000black flake8 flake8-pyproject isort[colors] mypy pre-commit pytest annotated-types-0.7.0/requirements/testing.in000066400000000000000000000000351462274011600213660ustar00rootroot00000000000000coverage pytest pytest-sugar annotated-types-0.7.0/tests/000077500000000000000000000000001462274011600160025ustar00rootroot00000000000000annotated-types-0.7.0/tests/__init__.py000066400000000000000000000000001462274011600201010ustar00rootroot00000000000000annotated-types-0.7.0/tests/test_grouped_metadata.py000066400000000000000000000015711462274011600227240ustar00rootroot00000000000000import sys from typing import Iterator import pytest if sys.version_info < (3, 9): from typing_extensions import Literal else: from typing import Literal from annotated_types import BaseMetadata, GroupedMetadata, Gt def test_subclass_without_implementing_iter() -> None: with pytest.raises(TypeError): class Foo1(GroupedMetadata): pass class Foo2(GroupedMetadata): def __iter__(self) -> Iterator[BaseMetadata]: raise NotImplementedError with pytest.raises(NotImplementedError): for _ in Foo2(): pass def test_non_subclass_implementer() -> None: class Foo: __is_annotated_types_grouped_metadata__: Literal[True] = True def __iter__(self) -> Iterator[BaseMetadata]: return yield Gt(0) _: GroupedMetadata = Foo() # type checker will fail if not valid annotated-types-0.7.0/tests/test_main.py000066400000000000000000000125241462274011600203430ustar00rootroot00000000000000import math import sys from datetime import datetime, timezone from typing import TYPE_CHECKING, Any, Callable, Dict, Iterable, Iterator, Type, Union if sys.version_info < (3, 9): from typing_extensions import Annotated, get_args, get_origin else: from typing import Annotated, get_args, get_origin import pytest if TYPE_CHECKING: from _pytest.mark import ParameterSet import annotated_types from annotated_types.test_cases import Case, cases Constraint = Union[annotated_types.BaseMetadata, slice] def check_gt(constraint: Constraint, val: Any) -> bool: assert isinstance(constraint, annotated_types.Gt) return val > constraint.gt def check_lt(constraint: Constraint, val: Any) -> bool: assert isinstance(constraint, annotated_types.Lt) return val < constraint.lt def check_ge(constraint: Constraint, val: Any) -> bool: assert isinstance(constraint, annotated_types.Ge) return val >= constraint.ge def check_le(constraint: Constraint, val: Any) -> bool: assert isinstance(constraint, annotated_types.Le) return val <= constraint.le def check_multiple_of(constraint: Constraint, val: Any) -> bool: assert isinstance(constraint, annotated_types.MultipleOf) return val % constraint.multiple_of == 0 def check_min_len(constraint: Constraint, val: Any) -> bool: assert isinstance(constraint, annotated_types.MinLen) return len(val) >= constraint.min_length def check_max_len(constraint: Constraint, val: Any) -> bool: assert isinstance(constraint, annotated_types.MaxLen) return len(val) <= constraint.max_length def check_predicate(constraint: Constraint, val: Any) -> bool: assert isinstance(constraint, annotated_types.Predicate) # this is a relatively pointless branch since Not is itself callable # but it serves to demonstrate that Not can be introspected # and the wrapped predicate can be extracted / matched if isinstance(constraint.func, annotated_types.Not): return not constraint.func.func(val) return constraint.func(val) def check_timezone(constraint: Constraint, val: Any) -> bool: assert isinstance(constraint, annotated_types.Timezone) assert isinstance(val, datetime) if isinstance(constraint.tz, str): return val.tzinfo is not None and constraint.tz == val.tzname() elif isinstance(constraint.tz, timezone): return val.tzinfo is not None and val.tzinfo == constraint.tz elif constraint.tz is None: return val.tzinfo is None # ellipsis return val.tzinfo is not None def check_quantity(constraint: Constraint, val: Any) -> bool: assert isinstance(constraint, annotated_types.Unit) return isinstance(val, (float, int)) Validator = Callable[[Constraint, Any], bool] VALIDATORS: Dict[Type[Constraint], Validator] = { annotated_types.Gt: check_gt, annotated_types.Lt: check_lt, annotated_types.Ge: check_ge, annotated_types.Le: check_le, annotated_types.MultipleOf: check_multiple_of, annotated_types.Predicate: check_predicate, annotated_types.MinLen: check_min_len, annotated_types.MaxLen: check_max_len, annotated_types.Timezone: check_timezone, annotated_types.Unit: check_quantity, } def get_constraints(tp: type) -> Iterator[Constraint]: origin = get_origin(tp) assert origin is Annotated args = iter(get_args(tp)) next(args) for arg in args: if isinstance(arg, annotated_types.BaseMetadata): yield arg elif isinstance(arg, annotated_types.GroupedMetadata): yield from arg # type: ignore elif isinstance(arg, slice): yield from annotated_types.Len(arg.start or 0, arg.stop) def is_valid(tp: type, value: Any) -> bool: for constraint in get_constraints(tp): if not VALIDATORS[type(constraint)](constraint, value): return False return True def extract_valid_testcases(case: Case) -> "Iterable[ParameterSet]": for example in case.valid_cases: yield pytest.param(case.annotation, example, id=f"{case.annotation} is valid for {repr(example)}") def extract_invalid_testcases(case: Case) -> "Iterable[ParameterSet]": for example in case.invalid_cases: yield pytest.param(case.annotation, example, id=f"{case.annotation} is invalid for {repr(example)}") @pytest.mark.parametrize( "annotation, example", [testcase for case in cases() for testcase in extract_valid_testcases(case)] ) def test_valid_cases(annotation: type, example: Any) -> None: assert is_valid(annotation, example) is True @pytest.mark.parametrize( "annotation, example", [testcase for case in cases() for testcase in extract_invalid_testcases(case)] ) def test_invalid_cases(annotation: type, example: Any) -> None: assert is_valid(annotation, example) is False def a_predicate_fn(x: object) -> bool: return not x @pytest.mark.parametrize( "pred, repr_", [ (annotated_types.Predicate(func=a_predicate_fn), "Predicate(a_predicate_fn)"), (annotated_types.Predicate(func=str.isascii), "Predicate(str.isascii)"), (annotated_types.Predicate(func=math.isfinite), "Predicate(math.isfinite)"), (annotated_types.Predicate(func=bool), "Predicate(bool)"), (annotated_types.Predicate(func := lambda _: True), f"Predicate({func!r})"), ], ) def test_predicate_repr(pred: annotated_types.Predicate, repr_: str) -> None: assert repr(pred) == repr_