scientific_pydantic
scientific_pydantic is an extension module to
pydantic that adds support for a number
of common data types in scientific computing.
Installation
This project can be installed from either PyPI or conda-forge via the
scientific-pydantic package.
Motivation
Let's say with only pydantic, you wanted to put a numpy.ndarray object into
one of your models:
import numpy as np
import pydantic
class MyModel(pydantic.BaseModel):
arr: np.ndarray
this will produce the following error:
pydantic.errors.PydanticSchemaGenerationError: Unable to generate pydantic-core schema for <class 'numpy.ndarray'>. Set `arbitrary_types_allowed=True` in the model_config to ignore this error or implement `__get_pydantic_core_schema__` on your type to fully support it.
Specifying arbitrary_types_allowed=True can work, but disables JSON
serialization and validation and does not support lax parsing and input
conversions, which are a powerful feature of pydantic. This library takes the
approach of implementing __get_pydantic_core_schema__ in adapter objects and
using Annotated, as described
here.
With scientific_pydantic, this example looks like:
import typing as ty
import numpy as np
import pydantic
from scientific_pydantic.numpy import NDArrayAdapter
class MyModel(pydantic.BaseModel):
arr: ty.Annotated[np.ndarray, NDArrayAdapter()]
Using this pattern, you can embed scientific data types into your models and get
the full pydantic experience with serialization and input conversions.
Usage
In general, it is recommended to use from-style imports with this library. The
import path for an adapter is normally akin to the import path of the type it is
adapting. For instance, the adapter for scipy.spatial.transform.Rotation would
be:
from scientific_pydantic.scipy.spatial.transform import RotationAdapter
Adapters are used via the Annotated pattern, as was shown in the Motivation
section. This allows for typecheckers that support pydantic, such as
pyrefly to understand the type of the fields.
A number of adapters provided with this library also take parameters that define
common validation operations. This takes inspiration from pydantic.Field. For
instance,
import pydantic
class MyModel(pydantic.BaseModel):
a: int = pydantic.Field(ge=0)
defines a non-negative integer. In scientific_pydantic, this style of
validation logic can be accomplished via:
import typing as ty
import numpy as np
import pydantic
from scientific_pydantic.numpy import NDArrayAdapter
class MyModel(pydantic.BaseModel):
a: ty.Annotated[np.ndarray, NDArrayAdapter(shape=(None, 3), ge=0)]
which constrains a to be an N x 3 ndarray where all elements are
non-negative. See the individual adapters in the API documentation for a
description of the parameters each one takes.
Customization
All type adapters in this library come bundled with a default Encoding, which describes how the type is serialized and validated from JSON-serializable types.
While these defaults should work for many use cases, it may be desirable to
customize this encoding. Many adapters will support an encoding= keyword
argument in their constructors for doing just this. See the Encoding
documentation for an example.
Design Philosophy
This library has an interesting conundrum from a dependency standpoint. Since the goal is to provide adapters for common types that come from many different libraries, there are a few options for how dependency management can work:
- Depend on all packages being supported and enforce version constraints. This would violate the "pay for what you use" principle and is thus not a good option.
- Split the package into
Ndifferent, but related, packages (e.g.scientific_pydantic_shapely) that enforce version constraints individually. This is tractable, but leads to a large number of packages to maintain and version together. - Have 1 package and only depend on
pydantic(andpydantic_core). Users will bring their own versions of the packages they want to use.
This library takes approach #3. This puts the burden of version compatibility
onto this library. For instance, scipy.spatial.transform.Rotation objects
gained the ability to support N-D arrays of rotation transforms in version
1.17.0. Thus, validation features related to this must be disabled if the user
brings their own scipy version that is < 1.17.0. This adds complexity to
this library, but prevents either the dependency bloat from option 1 or the
package bloat from option 2.
By only depending on pydantic, the library must not import anything from a
third-party library at global scope. This is accomplished via liberal use of
delayed and nested import statments and enforced via a unit test.
Metadata
Release files for scientific-pydantic 0.5.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| scientific_pydantic-0.5.0.tar.gz | 32.0 kB | With provenance | Details for scientific_pydantic-0.5.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| scientific_pydantic-0.5.0-py3-none-any.whl | Python 3 | none | any | Details for scientific_pydantic-0.5.0-py3-none-any.whl |
Total release size: 82.0 kB
Release files / scientific_pydantic-0.5.0.tar.gz
| Download URL | scientific_pydantic-0.5.0.tar.gz |
|---|---|
| Size | 32.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a58b9bbd91671ec21bed1efa2295ad67d50b47583f04889d9d709b01e3942196
|
|
BLAKE2b-256 checksum How to use checksums |
3a00964094cbe6d37a251901eda8a31d56c5a20326334d8d6d06269292981d10
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 30, 2026.
Transparency logRelease files / scientific_pydantic-0.5.0-py3-none-any.whl
| Download URL | scientific_pydantic-0.5.0-py3-none-any.whl |
|---|---|
| Size | 50.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
5d0e0f91a84dfa0d106b87a94699b9349324eb2aa3d23adb426e8d0728054a6e
|
|
BLAKE2b-256 checksum How to use checksums |
46add7408fade6c2788e88808ab3051d76d4ca5e5b09fd5019e801f4020976cc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 30, 2026.
Transparency logSecurity for scientific-pydantic 0.5.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for scientific_pydantic-0.5.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 30, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.