{"id":15441983,"url":"https://github.com/caniko/pydantic-numpy","last_synced_at":"2025-04-05T06:02:13.852Z","repository":{"id":133440078,"uuid":"611217978","full_name":"caniko/pydantic-numpy","owner":"caniko","description":"Package that integrates NumPy Arrays into Pydantic","archived":false,"fork":false,"pushed_at":"2025-02-22T17:17:26.000Z","size":358,"stargazers_count":41,"open_issues_count":0,"forks_count":7,"subscribers_count":1,"default_branch":"trunk","last_synced_at":"2025-03-29T05:01:41.511Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-4-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/caniko.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-03-08T11:18:21.000Z","updated_at":"2025-03-13T18:19:13.000Z","dependencies_parsed_at":"2023-11-10T15:04:40.521Z","dependency_job_id":"26f9f392-158f-4197-b16d-225f84d9ed74","html_url":"https://github.com/caniko/pydantic-numpy","commit_stats":{"total_commits":85,"total_committers":7,"mean_commits":"12.142857142857142","dds":0.5294117647058824,"last_synced_commit":"aeccd661ff517e509c173f38d346568b45905edc"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caniko%2Fpydantic-numpy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caniko%2Fpydantic-numpy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caniko%2Fpydantic-numpy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caniko%2Fpydantic-numpy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/caniko","download_url":"https://codeload.github.com/caniko/pydantic-numpy/tar.gz/refs/heads/trunk","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247294514,"owners_count":20915340,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-01T19:24:43.990Z","updated_at":"2025-04-05T06:02:13.822Z","avatar_url":"https://github.com/caniko.png","language":"Python","funding_links":[],"categories":["Object Mapping"],"sub_categories":[],"readme":"# pydantic-numpy\n\n![Python 3.10-3.13](https://img.shields.io/badge/python-3.9--3.13-blue.svg)\n[![Packaged with Poetry](https://img.shields.io/badge/packaging-poetry-cyan.svg)](https://python-poetry.org/)\n![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)\n![Imports: isort](https://img.shields.io/badge/%20imports-isort-%231674b1?style=flat\u0026labelColor=ef8336)\n![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)\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(\u003cpath\u003e)\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) -\u003e 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","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcaniko%2Fpydantic-numpy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcaniko%2Fpydantic-numpy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcaniko%2Fpydantic-numpy/lists"}