annotated-types

annotated-types provides a lightweight set of constraint types (Gt, Le, MinLen, MaxLen, etc.) that work beautifully with typing.Annotated. The library's brilliance is in what it doesn't do—it defines constraint markers without enforcing them, letting validation libraries like Pydantic interpret them. This separation keeps it focused and universally compatible.

The API is extremely intuitive with excellent IDE support. Types like `Annotated[int, Gt(0), Le(100)]` are self-documenting and autocomplete perfectly. The constraint classes are simple dataclasses with clear attributes, making introspection straightforward. Error messages are minimal since this library doesn't validate, but when you misuse the API, Python's native type errors are clear enough.

The main friction point is documentation—while the README covers basics, there's little guidance on combining constraints or edge cases. You'll find yourself reading Pydantic docs to understand behavior since annotated-types itself is just markers. The package does its job well but feels incomplete without a validation layer, which is intentional but requires understanding that division of responsibility.

This library provides simple constraint types (Gt, Le, Len, etc.) for use with PEP 593's Annotated. In practice, it's a thin layer that defines standardized constraint objects - nothing more. The package itself has zero runtime dependencies and minimal surface area for security concerns, which is reassuring from a supply chain perspective.

The library doesn't actually validate anything on its own - it just provides the constraint objects that other libraries like Pydantic consume. This separation of concerns is good for security since validation logic lives elsewhere. Error handling is straightforward since there's barely any runtime behavior beyond object instantiation. Input validation patterns are delegated to consuming libraries, which means you need to understand that annotated-types alone won't protect you.

From a security standpoint, the minimal codebase (a few hundred lines) is easy to audit. No crypto, no network calls, no file I/O - just dataclass-like constraint objects. The main risk is assuming these annotations provide runtime protection when they don't without a consuming validator.

In practice, annotated-types serves as a clean abstraction layer for defining validation constraints that work across multiple validation libraries. The API is minimal and intuitive—you import constraints like `Gt`, `Le`, `MaxLen` and attach them to `Annotated` types. The real value emerges when using it with Pydantic v2, where these constraints are automatically understood and enforced without additional configuration.

The type definitions are excellent with proper generic support, making IDE autocompletion reliable. Error messages are descriptive enough to understand what went wrong during validation. The package stays in its lane—it only provides the metadata structures, delegating actual validation to consumers like Pydantic. This separation of concerns is architecturally sound but means you can't use these constraints standalone without a validation framework.

Documentation is sparse but sufficient given the simplicity. The main challenge is understanding that this is infrastructure—you're defining constraints that other libraries interpret. Migration from raw metadata dicts to annotated-types is straightforward, though the package's utility is limited if you're not using a compatible validation library.