{"id":18295841,"url":"https://github.com/astropenguin/xarray-dataclasses","last_synced_at":"2026-02-20T04:03:38.855Z","repository":{"id":37958870,"uuid":"296823477","full_name":"astropenguin/xarray-dataclasses","owner":"astropenguin","description":":zap: xarray data creation by data classes","archived":false,"fork":false,"pushed_at":"2025-01-04T17:27:59.000Z","size":3562,"stargazers_count":81,"open_issues_count":12,"forks_count":7,"subscribers_count":3,"default_branch":"main","last_synced_at":"2026-01-29T01:53:10.059Z","etag":null,"topics":["dataclasses","python","specifications","typing","xarray"],"latest_commit_sha":null,"homepage":"https://astropenguin.github.io/xarray-dataclasses/v2.0.0","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/astropenguin.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-09-19T08:38:24.000Z","updated_at":"2026-01-05T15:05:29.000Z","dependencies_parsed_at":"2023-12-22T14:07:24.318Z","dependency_job_id":"98fdcf36-4f21-4654-a508-0b2cf4e504e1","html_url":"https://github.com/astropenguin/xarray-dataclasses","commit_stats":{"total_commits":626,"total_committers":5,"mean_commits":125.2,"dds":"0.011182108626198062","last_synced_commit":"433e67e1ec1b9ffddba6a4b8953eaa84da37e428"},"previous_names":[],"tags_count":28,"template":false,"template_full_name":null,"purl":"pkg:github/astropenguin/xarray-dataclasses","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/astropenguin%2Fxarray-dataclasses","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/astropenguin%2Fxarray-dataclasses/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/astropenguin%2Fxarray-dataclasses/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/astropenguin%2Fxarray-dataclasses/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/astropenguin","download_url":"https://codeload.github.com/astropenguin/xarray-dataclasses/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/astropenguin%2Fxarray-dataclasses/sbom","scorecard":{"id":213717,"data":{"date":"2025-08-11","repo":{"name":"github.com/astropenguin/xarray-dataclasses","commit":"75fbff4cb296b21a8e25aa5fbbd54fd3ba07299b"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":3.7,"checks":[{"name":"Code-Review","score":0,"reason":"Found 0/4 approved changesets -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"Dangerous-Workflow","score":10,"reason":"no dangerous workflow patterns detected","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"Maintained","score":0,"reason":"0 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"Token-Permissions","score":0,"reason":"detected GitHub workflow tokens with excessive permissions","details":["Warn: no topLevel permission defined: .github/workflows/docs.yaml:1","Warn: no topLevel permission defined: .github/workflows/pypi.yaml:1","Warn: no topLevel permission defined: .github/workflows/tests.yaml:1","Info: no jobLevel write permissions found"],"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"Pinned-Dependencies","score":0,"reason":"dependency not pinned by hash detected -- score normalized to 0","details":["Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/docs.yaml:16: update your workflow using https://app.stepsecurity.io/secureworkflow/astropenguin/xarray-dataclasses/docs.yaml/main?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/docs.yaml:21: update your workflow using https://app.stepsecurity.io/secureworkflow/astropenguin/xarray-dataclasses/docs.yaml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/pypi.yaml:17: update your workflow using https://app.stepsecurity.io/secureworkflow/astropenguin/xarray-dataclasses/pypi.yaml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/tests.yaml:29: update your workflow using https://app.stepsecurity.io/secureworkflow/astropenguin/xarray-dataclasses/tests.yaml/main?enable=pin","Info:   0 out of   3 GitHub-owned GitHubAction dependencies pinned","Info:   0 out of   1 third-party GitHubAction dependencies pinned"],"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"Vulnerabilities","score":10,"reason":"0 existing vulnerabilities detected","details":null,"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Info: FSF or OSI recognized license: MIT License: LICENSE:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"Branch-Protection","score":3,"reason":"branch protection is not maximal on development and all release branches","details":["Info: 'allow deletion' disabled on branch 'main'","Info: 'force pushes' disabled on branch 'main'","Warn: 'branch protection settings apply to administrators' is disabled on branch 'main'","Warn: 'stale review dismissal' is disabled on branch 'main'","Warn: branch 'main' does not require approvers","Warn: codeowners review is not required on branch 'main'","Warn: 'last push approval' is disabled on branch 'main'","Warn: 'up-to-date branches' is disabled on branch 'main'","Info: status check found to merge onto on branch 'main'","Info: PRs are required in order to make changes on branch 'main'"],"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"SAST","score":0,"reason":"SAST tool is not run on all commits -- score normalized to 0","details":["Warn: 0 commits out of 30 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}}]},"last_synced_at":"2025-08-17T01:13:35.030Z","repository_id":37958870,"created_at":"2025-08-17T01:13:35.030Z","updated_at":"2025-08-17T01:13:35.030Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29640861,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-20T03:21:14.183Z","status":"ssl_error","status_checked_at":"2026-02-20T03:18:24.455Z","response_time":59,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["dataclasses","python","specifications","typing","xarray"],"created_at":"2024-11-05T14:38:32.243Z","updated_at":"2026-02-20T04:03:33.845Z","avatar_url":"https://github.com/astropenguin.png","language":"Python","readme":"# xarray-dataclasses\n\n[![Release](https://img.shields.io/pypi/v/xarray-dataclasses?label=Release\u0026color=cornflowerblue\u0026style=flat-square)](https://pypi.org/project/xarray-dataclasses/)\n[![Python](https://img.shields.io/pypi/pyversions/xarray-dataclasses?label=Python\u0026color=cornflowerblue\u0026style=flat-square)](https://pypi.org/project/xarray-dataclasses/)\n[![Downloads](https://img.shields.io/pypi/dm/xarray-dataclasses?label=Downloads\u0026color=cornflowerblue\u0026style=flat-square)](https://pepy.tech/project/xarray-dataclasses)\n[![DOI](https://img.shields.io/badge/DOI-10.5281/zenodo.4624819-cornflowerblue?style=flat-square)](https://doi.org/10.5281/zenodo.4624819)\n[![Tests](https://img.shields.io/github/actions/workflow/status/astropenguin/xarray-dataclasses/tests.yml?label=Tests\u0026style=flat-square)](https://github.com/astropenguin/xarray-dataclasses/actions)\n\nxarray data creation by data classes\n\n## Overview\n\nxarray-dataclasses is a Python package that makes it easy to create [xarray]'s DataArray and Dataset objects that are \"typed\" (i.e. fixed dimensions, data type, coordinates, attributes, and name) using [the Python's dataclass]:\n\n```python\nfrom dataclasses import dataclass\nfrom typing import Literal\nfrom xarray_dataclasses import AsDataArray, Coord, Data\n\n\nX = Literal[\"x\"]\nY = Literal[\"y\"]\n\n\n@dataclass\nclass Image(AsDataArray):\n    \"\"\"2D image as DataArray.\"\"\"\n\n    data: Data[tuple[X, Y], float]\n    x: Coord[X, int] = 0\n    y: Coord[Y, int] = 0\n```\n\n### Features\n\n- Typed DataArray or Dataset objects can easily be created:\n  ```python\n  image = Image.new([[0, 1], [2, 3]], [0, 1], [0, 1])\n  ```\n- NumPy-like filled-data creation is also available:\n  ```python\n  image = Image.zeros([2, 2], x=[0, 1], y=[0, 1])\n  ```\n- Support for features by [the Python's dataclass] (`field`, `__post_init__`, ...).\n- Support for static type check by [Pyright].\n\n### Installation\n\n```shell\npip install xarray-dataclasses\n```\n\n## Basic usage\n\nxarray-dataclasses uses [the Python's dataclass].\nData (or data variables), coordinates, attributes, and a name of DataArray or Dataset objects will be defined as dataclass fields by special type hints (`Data`, `Coord`, `Attr`, `Name`), respectively.\nNote that the following code is supposed in the examples below.\n\n```python\nfrom dataclasses import dataclass\nfrom typing import Literal\nfrom xarray_dataclasses import AsDataArray, AsDataset\nfrom xarray_dataclasses import Attr, Coord, Data, Name\n\n\nX = Literal[\"x\"]\nY = Literal[\"y\"]\n```\n\n### Data field\n\nData field is a field whose value will become the data of a DataArray object or a data variable of a Dataset object.\nThe type hint `Data[TDims, TDtype]` fixes the dimensions and the data type of the object.\nHere are some examples of how to specify them.\n\nType hint | Inferred dimensions\n--- | ---\n`Data[tuple[()], ...]` | `()`\n`Data[Literal[\"x\"], ...]` | `(\"x\",)`\n`Data[tuple[Literal[\"x\"]], ...]` | `(\"x\",)`\n`Data[tuple[Literal[\"x\"], Literal[\"y\"]], ...]` | `(\"x\", \"y\")`\n\nType hint | Inferred data type\n--- | ---\n`Data[..., Any]` | `None`\n`Data[..., None]` | `None`\n`Data[..., float]` | `numpy.dtype(\"float64\")`\n`Data[..., numpy.float128]` | `numpy.dtype(\"float128\")`\n`Data[..., Literal[\"datetime64[ns]\"]]` | `numpy.dtype(\"\u003cM8[ns]\")`\n\n### Coordinate field\n\nCoordinate field is a field whose value will become a coordinate of a DataArray or a Dataset object.\nThe type hint `Coord[TDims, TDtype]` fixes the dimensions and the data type of the object.\n\n### Attribute field\n\nAttribute field is a field whose value will become an attribute of a DataArray or a Dataset object.\nThe type hint `Attr[TAttr]` specifies the type of the value, which is used only for static type check.\n\n### Name field\n\nName field is a field whose value will become the name of a DataArray object.\nThe type hint `Name[TName]` specifies the type of the value, which is used only for static type check.\n\n### DataArray class\n\nDataArray class is a dataclass that defines typed DataArray specifications.\nExactly one data field is allowed in a DataArray class.\nThe second and subsequent data fields are just ignored in DataArray creation.\n\n```python\n@dataclass\nclass Image(AsDataArray):\n    \"\"\"2D image as DataArray.\"\"\"\n\n    data: Data[tuple[X, Y], float]\n    x: Coord[X, int] = 0\n    y: Coord[Y, int] = 0\n    units: Attr[str] = \"cd / m^2\"\n    name: Name[str] = \"luminance\"\n```\n\nA DataArray object will be created by a class method `new()`:\n\n```python\nImage.new([[0, 1], [2, 3]], x=[0, 1], y=[0, 1])\n\n\u003cxarray.DataArray \"luminance\" (x: 2, y: 2)\u003e\narray([[0., 1.],\n       [2., 3.]])\nCoordinates:\n  * x        (x) int64 0 1\n  * y        (y) int64 0 1\nAttributes:\n    units:    cd / m^2\n```\n\nNumPy-like class methods (`zeros()`, `ones()`, ...) are also available:\n\n```python\nImage.ones((3, 3))\n\n\u003cxarray.DataArray \"luminance\" (x: 3, y: 3)\u003e\narray([[1., 1., 1.],\n       [1., 1., 1.],\n       [1., 1., 1.]])\nCoordinates:\n  * x        (x) int64 0 0 0\n  * y        (y) int64 0 0 0\nAttributes:\n    units:    cd / m^2\n```\n\n### Dataset class\n\nDataset class is a dataclass that defines typed Dataset specifications.\nMultiple data fields are allowed to define the data variables of the object.\n\n```python\n@dataclass\nclass ColorImage(AsDataset):\n    \"\"\"2D color image as Dataset.\"\"\"\n\n    red: Data[tuple[X, Y], float]\n    green: Data[tuple[X, Y], float]\n    blue: Data[tuple[X, Y], float]\n    x: Coord[X, int] = 0\n    y: Coord[Y, int] = 0\n    units: Attr[str] = \"cd / m^2\"\n```\n\nA Dataset object will be created by a class method `new()`:\n\n```python\nColorImage.new(\n    [[0, 0], [0, 0]],  # red\n    [[1, 1], [1, 1]],  # green\n    [[2, 2], [2, 2]],  # blue\n)\n\n\u003cxarray.Dataset\u003e\nDimensions:  (x: 2, y: 2)\nCoordinates:\n  * x        (x) int64 0 0\n  * y        (y) int64 0 0\nData variables:\n    red      (x, y) float64 0.0 0.0 0.0 0.0\n    green    (x, y) float64 1.0 1.0 1.0 1.0\n    blue     (x, y) float64 2.0 2.0 2.0 2.0\nAttributes:\n    units:    cd / m^2\n```\n\n## Advanced usage\n\n### Coordof and Dataof type hints\n\nxarray-dataclasses provides advanced type hints, `Coordof` and `Dataof`.\nUnlike `Data` and `Coord`, they specify a dataclass that defines a DataArray class.\nThis is useful when users want to add metadata to dimensions for [plotting].\nFor example:\n\n```python\nfrom xarray_dataclasses import Coordof\n\n\n@dataclass\nclass XAxis:\n    data: Data[X, int]\n    long_name: Attr[str] = \"x axis\"\n    units: Attr[str] = \"pixel\"\n\n\n@dataclass\nclass YAxis:\n    data: Data[Y, int]\n    long_name: Attr[str] = \"y axis\"\n    units: Attr[str] = \"pixel\"\n\n\n@dataclass\nclass Image(AsDataArray):\n    \"\"\"2D image as DataArray.\"\"\"\n\n    data: Data[tuple[X, Y], float]\n    x: Coordof[XAxis] = 0\n    y: Coordof[YAxis] = 0\n```\n\n### General data variable names in Dataset creation\n\nDue to the limitation of Python's parameter names, it is not possible to define data variable names that contain white spaces, for example.\nIn such cases, please define DataArray classes of each data variable so that they have name fields and specify them by `Dataof` in a Dataset class.\nThen the values of the name fields will be used as data variable names.\nFor example:\n\n```python\n@dataclass\nclass Red:\n    data: Data[tuple[X, Y], float]\n    name: Name[str] = \"Red image\"\n\n\n@dataclass\nclass Green:\n    data: Data[tuple[X, Y], float]\n    name: Name[str] = \"Green image\"\n\n\n@dataclass\nclass Blue:\n    data: Data[tuple[X, Y], float]\n    name: Name[str] = \"Blue image\"\n\n\n@dataclass\nclass ColorImage(AsDataset):\n    \"\"\"2D color image as Dataset.\"\"\"\n\n    red: Dataof[Red]\n    green: Dataof[Green]\n    blue: Dataof[Blue]\n```\n\n```python\nColorImage.new(\n    [[0, 0], [0, 0]],\n    [[1, 1], [1, 1]],\n    [[2, 2], [2, 2]],\n)\n\n\u003cxarray.Dataset\u003e\nDimensions:      (x: 2, y: 2)\nDimensions without coordinates: x, y\nData variables:\n    Red image    (x, y) float64 0.0 0.0 0.0 0.0\n    Green image  (x, y) float64 1.0 1.0 1.0 1.0\n    Blue image   (x, y) float64 2.0 2.0 2.0 2.0\n```\n\n### Customization of DataArray or Dataset creation\n\nFor customization, users can add a special class attribute, `__dataoptions__`, to a DataArray or Dataset class.\nA custom factory for DataArray or Dataset creation is only supported in the current implementation.\n\n\n```python\nimport xarray as xr\nfrom xarray_dataclasses import DataOptions\n\n\nclass Custom(xr.DataArray):\n    \"\"\"Custom DataArray.\"\"\"\n\n    __slots__ = ()\n\n    def custom_method(self) -\u003e bool:\n        \"\"\"Custom method.\"\"\"\n        return True\n\n\n@dataclass\nclass Image(AsDataArray):\n    \"\"\"2D image as DataArray.\"\"\"\n\n    data: Data[tuple[X, Y], float]\n    x: Coord[X, int] = 0\n    y: Coord[Y, int] = 0\n\n    __dataoptions__ = DataOptions(Custom)\n\n\nimage = Image.ones([3, 3])\nisinstance(image, Custom)  # True\nimage.custom_method()  # True\n```\n\n### DataArray and Dataset creation without shorthands\n\nxarray-dataclasses provides functions, `asdataarray` and `asdataset`.\nThis is useful when users do not want to inherit the mix-in class (`AsDataArray` or `AsDataset`) in a DataArray or Dataset dataclass.\nFor example:\n\n```python\nfrom xarray_dataclasses import asdataarray\n\n\n@dataclass\nclass Image:\n    \"\"\"2D image as DataArray.\"\"\"\n\n    data: Data[tuple[X, Y], float]\n    x: Coord[X, int] = 0\n    y: Coord[Y, int] = 0\n\n\nimage = asdataarray(Image([[0, 1], [2, 3]], [0, 1], [0, 1]))\n```\n\n\n\u003c!-- References --\u003e\n[Pyright]: https://github.com/microsoft/pyright\n[the Python's dataclass]: https://docs.python.org/3/library/dataclasses.html\n[xarray]: https://xarray.pydata.org/en/stable/index.html\n[plotting]: https://xarray.pydata.org/en/stable/user-guide/plotting.html#simple-example\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fastropenguin%2Fxarray-dataclasses","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fastropenguin%2Fxarray-dataclasses","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fastropenguin%2Fxarray-dataclasses/lists"}