# pydantic-numpy
[](https://python-poetry.org/)
## Usage
Package that integrates NumPy Arrays into Pydantic!
- `pydantic_numpy.typing` provides many typings such as `NpNDArrayFp64`, `Np3DArrayFp64` (float64 that must be 3D)! Works with both `pydantic.BaseModel` and `pydantic.dataclass`
- `NumpyModel` (derived from `pydantic.BaseModel`) make it possible to dump and load `np.ndarray` within model fields alongside other fields that are not instances of `np.ndarray`!
See the [`test.helper.testing_groups`](https://github.com/caniko/pydantic-numpy/blob/trunk/tests/helper/testing_groups.py) to see types that are defined explicitly.
### Examples
For more examples see [test_ndarray.py](./tests/test_typing.py)
```python
import numpy as np
from pydantic import BaseModel
import pydantic_numpy.typing as pnd
from pydantic_numpy import np_array_pydantic_annotated_typing
from pydantic_numpy.model import NumpyModel, MultiArrayNumpyFile
class MyBaseModelDerivedModel(BaseModel):
any_array_dtype_and_dimension: pnd.NpNDArray
# Must be numpy float32 as dtype
k: np_array_pydantic_annotated_typing(data_type=np.float32)
shorthand_for_k: pnd.NpNDArrayFp32
must_be_1d_np_array: np_array_pydantic_annotated_typing(dimensions=1)
class MyDemoNumpyModel(NumpyModel):
k: np_array_pydantic_annotated_typing(data_type=np.float32)
# Instantiate from array
cfg = MyDemoModel(k=[1, 2])
# Instantiate from numpy file
cfg = MyDemoModel(k="path_to/array.npy")
# Instantiate from npz file with key
cfg = MyDemoModel(k=MultiArrayNumpyFile(path="path_to/array.npz", key="k"))
cfg.k # np.ndarray[np.float32]
cfg.dump("path_to_dump_dir", "object_id")
cfg.load("path_to_dump_dir", "object_id")
```
`NumpyModel.load` requires the original model:
```python
MyNumpyModel.load(<path>)
```
Use `model_agnostic_load` when you have several models that may be the correct model:
```python
from pydantic_numpy.model import model_agnostic_load
cfg.dump("path_to_dump_dir", "object_id")
equals_cfg = model_agnostic_load("path_to_dump_dir", "object_id", models=[MyNumpyModel, MyDemoModel])
```
### Custom type
There are two ways to define. Function derived types with `pydantic_numpy.helper.annotation.np_array_pydantic_annotated_typing`.
Function derived types don't work with static type checkers like Pyright and MyPy. In case you need the support,
just create the types yourself:
```python
NpStrict1DArrayInt64 = Annotated[
np.ndarray[tuple[int], np.dtype[np.int64]],
NpArrayPydanticAnnotation.factory(data_type=np.int64, dimensions=1, strict_data_typing=True),
]
```
#### Custom serialization
If the default serialization of NumpyDataDict, as outlined in [typing.py](https://github.com/caniko/pydantic-numpy/blob/trunk/pydantic_numpy/helper/typing.py), doesn't meet your requirements, you have the option to define a custom type with its own serializer. This can be achieved using the NpArrayPydanticAnnotation.factory method, which accepts a custom serialization function through its serialize_numpy_array_to_json parameter. This parameter expects a function of the form `Callable[[npt.ArrayLike], Iterable]`, allowing you to tailor the serialization process to your specific needs.
Example below illustrates definition of 1d-array of `float32` type that serializes to flat Python list (without nested dict as in default `NumpyDataDict` case):
```python
def _serialize_numpy_array_to_float_list(array_like: npt.ArrayLike) -> Iterable:
return np.array(array_like).astype(float).tolist()
Np1DArrayFp32 = Annotated[
np.ndarray[tuple[int], np.dtype[np.float32]],
NpArrayPydanticAnnotation.factory(
data_type=np.float32,
dimensions=1,
strict_data_typing=False,
serialize_numpy_array_to_json=_serialize_numpy_array_to_float_list,
),
]
```
### Install
```shell
pip install pydantic-numpy
```
### History
The original idea originates from [this discussion](https://gist.github.com/danielhfrank/00e6b8556eed73fb4053450e602d2434), and forked from [cheind's](https://github.com/cheind/pydantic-numpy) repository.
Raw data
{
"_id": null,
"home_page": "https://github.com/caniko/pydantic-numpy",
"name": "pydantic_numpy",
"maintainer": "Can H. Tartanoglu",
"docs_url": null,
"requires_python": "<3.13,>=3.9",
"maintainer_email": "python@rotas.mozmail.com",
"keywords": "pydantic, numpy, typing, validation",
"author": "Can H. Tartanoglu",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/28/a0/2db334048f085626b2b5b57af50963864894352e174df762beb727b016c6/pydantic_numpy-5.0.1.tar.gz",
"platform": null,
"description": "# pydantic-numpy\n\n\n[](https://python-poetry.org/)\n\n\n\n\n\n## Usage\n\nPackage that integrates NumPy Arrays into Pydantic!\n\n- `pydantic_numpy.typing` provides many typings such as `NpNDArrayFp64`, `Np3DArrayFp64` (float64 that must be 3D)! Works with both `pydantic.BaseModel` and `pydantic.dataclass`\n- `NumpyModel` (derived from `pydantic.BaseModel`) make it possible to dump and load `np.ndarray` within model fields alongside other fields that are not instances of `np.ndarray`!\n\nSee the [`test.helper.testing_groups`](https://github.com/caniko/pydantic-numpy/blob/trunk/tests/helper/testing_groups.py) to see types that are defined explicitly.\n\n### Examples\n\nFor more examples see [test_ndarray.py](./tests/test_typing.py)\n\n```python\nimport numpy as np\nfrom pydantic import BaseModel\n\nimport pydantic_numpy.typing as pnd\nfrom pydantic_numpy import np_array_pydantic_annotated_typing\nfrom pydantic_numpy.model import NumpyModel, MultiArrayNumpyFile\n\n\nclass MyBaseModelDerivedModel(BaseModel):\n any_array_dtype_and_dimension: pnd.NpNDArray\n\n # Must be numpy float32 as dtype\n k: np_array_pydantic_annotated_typing(data_type=np.float32)\n shorthand_for_k: pnd.NpNDArrayFp32\n\n must_be_1d_np_array: np_array_pydantic_annotated_typing(dimensions=1)\n\n\nclass MyDemoNumpyModel(NumpyModel):\n k: np_array_pydantic_annotated_typing(data_type=np.float32)\n\n\n# Instantiate from array\ncfg = MyDemoModel(k=[1, 2])\n# Instantiate from numpy file\ncfg = MyDemoModel(k=\"path_to/array.npy\")\n# Instantiate from npz file with key\ncfg = MyDemoModel(k=MultiArrayNumpyFile(path=\"path_to/array.npz\", key=\"k\"))\n\ncfg.k # np.ndarray[np.float32]\n\ncfg.dump(\"path_to_dump_dir\", \"object_id\")\ncfg.load(\"path_to_dump_dir\", \"object_id\")\n```\n\n`NumpyModel.load` requires the original model:\n```python\nMyNumpyModel.load(<path>)\n```\nUse `model_agnostic_load` when you have several models that may be the correct model:\n\n```python\nfrom pydantic_numpy.model import model_agnostic_load\n\ncfg.dump(\"path_to_dump_dir\", \"object_id\")\nequals_cfg = model_agnostic_load(\"path_to_dump_dir\", \"object_id\", models=[MyNumpyModel, MyDemoModel])\n```\n\n### Custom type\nThere are two ways to define. Function derived types with `pydantic_numpy.helper.annotation.np_array_pydantic_annotated_typing`.\n\nFunction derived types don't work with static type checkers like Pyright and MyPy. In case you need the support,\njust create the types yourself:\n \n```python\nNpStrict1DArrayInt64 = Annotated[\n np.ndarray[tuple[int], np.dtype[np.int64]],\n NpArrayPydanticAnnotation.factory(data_type=np.int64, dimensions=1, strict_data_typing=True),\n]\n```\n\n#### Custom serialization\n\nIf the default serialization of NumpyDataDict, as outlined in [typing.py](https://github.com/caniko/pydantic-numpy/blob/trunk/pydantic_numpy/helper/typing.py), doesn't meet your requirements, you have the option to define a custom type with its own serializer. This can be achieved using the NpArrayPydanticAnnotation.factory method, which accepts a custom serialization function through its serialize_numpy_array_to_json parameter. This parameter expects a function of the form `Callable[[npt.ArrayLike], Iterable]`, allowing you to tailor the serialization process to your specific needs.\n\nExample below illustrates definition of 1d-array of `float32` type that serializes to flat Python list (without nested dict as in default `NumpyDataDict` case):\n\n```python\ndef _serialize_numpy_array_to_float_list(array_like: npt.ArrayLike) -> Iterable:\n return np.array(array_like).astype(float).tolist()\n\n\nNp1DArrayFp32 = Annotated[\n np.ndarray[tuple[int], np.dtype[np.float32]],\n NpArrayPydanticAnnotation.factory(\n data_type=np.float32,\n dimensions=1,\n strict_data_typing=False,\n serialize_numpy_array_to_json=_serialize_numpy_array_to_float_list,\n ),\n]\n```\n\n### Install\n```shell\npip install pydantic-numpy\n```\n\n### History\nThe original idea originates from [this discussion](https://gist.github.com/danielhfrank/00e6b8556eed73fb4053450e602d2434), and forked from [cheind's](https://github.com/cheind/pydantic-numpy) repository.\n",
"bugtrack_url": null,
"license": "BSD-4",
"summary": "Pydantic Model integration of the NumPy array",
"version": "5.0.1",
"project_urls": {
"Homepage": "https://github.com/caniko/pydantic-numpy"
},
"split_keywords": [
"pydantic",
" numpy",
" typing",
" validation"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2a9809100ae963b1e536e86b585c3ee398a363465892dd5f9102febd87c84bf4",
"md5": "d7fe18d613bfc772228d1add1e54f0e6",
"sha256": "788c8d443aedd7ce0a998e397b909b830f04f71a21c1b28cd63806bc7a055df5"
},
"downloads": -1,
"filename": "pydantic_numpy-5.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d7fe18d613bfc772228d1add1e54f0e6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.13,>=3.9",
"size": 19808,
"upload_time": "2024-04-19T06:33:06",
"upload_time_iso_8601": "2024-04-19T06:33:06.792220Z",
"url": "https://files.pythonhosted.org/packages/2a/98/09100ae963b1e536e86b585c3ee398a363465892dd5f9102febd87c84bf4/pydantic_numpy-5.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "28a02db334048f085626b2b5b57af50963864894352e174df762beb727b016c6",
"md5": "1376748e7213a5a34133d87a53467e1a",
"sha256": "092c0f64bd021a5036cb49bd6263ee69a224ddebf628f4d268b8cd6193c0f2f5"
},
"downloads": -1,
"filename": "pydantic_numpy-5.0.1.tar.gz",
"has_sig": false,
"md5_digest": "1376748e7213a5a34133d87a53467e1a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.13,>=3.9",
"size": 15668,
"upload_time": "2024-04-19T06:33:09",
"upload_time_iso_8601": "2024-04-19T06:33:09.002557Z",
"url": "https://files.pythonhosted.org/packages/28/a0/2db334048f085626b2b5b57af50963864894352e174df762beb727b016c6/pydantic_numpy-5.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-19 06:33:09",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "caniko",
"github_project": "pydantic-numpy",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pydantic_numpy"
}
JSON
