pydantic-collections

pydantic-collections provides a BaseCollectionModel class that lets you work with collections of Pydantic models (and any other Pydantic-supported types) as first-class, validated objects. You subclass BaseCollectionModel[YourModel] to get a list-like container that parses raw input, validates every element, and serializes back out.

The collection behaves like a Python list while enforcing Pydantic validation on construction and on mutation, with strict assignment checks that coerce or reject appended items. It supports both Pydantic v1 and v2 through separate internal implementations, exposing the familiar dict/json and model_dump/model_dump_json serialization methods.

What You Get

• A generic BaseCollectionModel[T] you subclass to type a collection of models
• Automatic parsing and validation of raw list input into model instances
• Strict assignment validation on append and item assignment
• Familiar serialization via dict()/json() (v1) and model_dump()/model_dump_json() (v2)

Common Use Cases

• Validating and parsing a JSON array of records into typed model instances
• Holding a mutable, validated list of models as a field or standalone object
• Serializing a collection of models back to plain dicts or JSON

Under The Hood

Architecture - The package is compact: init.py selects between _v1.py (215 lines) and _v2.py (178 lines) based on the installed Pydantic major version, each defining a BaseCollectionModel that combines Pydantic’s model machinery with list-like semantics. Construction parses and validates incoming items, and mutating operations (append, index assignment) route through Pydantic validators so the collection never holds unvalidated elements. A init.pyi provides typing stubs for the generic subscript API.

Tech Stack - Pure Python (3.7+) with Pydantic (>=1.8.2,<3.0) as the sole runtime dependency, packaged via setup.py/pyproject.toml. CI runs through GitHub Actions with Codecov coverage reporting.

Code Quality - The dual v1/v2 split keeps version-specific behavior isolated and readable, the codebase is small and focused, and a tests/ directory plus reported coverage back the validation behavior. Typing stubs signal attention to static-analysis ergonomics.

API Design - Usage is idiomatic: subclass BaseCollectionModel[User] and you immediately get a validated, serializable list. The API mirrors both Python list operations and Pydantic’s dict/json/model_dump methods, so there is essentially no new vocabulary to learn, giving it a very shallow learning curve for anyone already using Pydantic.