[WIP] container-level validation, add docs

.github/workflows/ci.yaml

@@ -10,7 +10,7 @@ jobs:
       - uses: actions/checkout@v3
       - uses: actions/setup-python@v4
         with:
-          python-version: "3.9"
+          python-version: "3.10"
       - uses: abatilo/actions-poetry@v2
       - run: poetry install
       - run: poetry run pre-commit run --all-files
@@ -20,9 +20,9 @@ jobs:
       fail-fast: false
       matrix:
         python-version:
-          - "3.9"
           - "3.10"
-          - "3.11"
+          - "3.10"
+          - "3.12"
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v3

.pre-commit-config.yaml

@@ -5,18 +5,16 @@ default_stages: [commit, push]
 default_language_version:
   python: python3
 repos:
-  - repo: https://github.com/psf/black
-    rev: 22.12.0
-    hooks:
-    - id: black
-      language_version: python3.9
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v4.4.0
     hooks:
     - id: check-yaml
-  - repo: https://github.com/charliermarsh/ruff-pre-commit
+  - repo: https://github.com/astral-sh/ruff-pre-commit
     # Ruff version.
-    rev: 'v0.0.245'
+    rev: v0.1.8
     hooks:
+      # Run the linter.
       - id: ruff
-        args: [--fix, --exit-non-zero-on-fix]
+        args: [ --fix ]
+      # Run the formatter.
+      - id: ruff-format

docs/api/v04/axis.md

@@ -0,0 +1 @@
+::: pydantic_ome_ngff.v04.axis

docs/api/v04/label.md

@@ -0,0 +1 @@
+::: pydantic_ome_ngff.v04.label

docs/api/v04/multiscales.md

@@ -0,0 +1 @@
+::: pydantic_ome_ngff.v04.multiscales

docs/api/v04/plate.md

@@ -0,0 +1 @@
+::: pydantic_ome_ngff.v04.plate

docs/api/v04/transforms.md

@@ -0,0 +1 @@
+::: pydantic_ome_ngff.v04.transforms

docs/index.md

@@ -0,0 +1,19 @@
+# pydantic-ome-ngff
+
+[Pydantic](https://docs.pydantic.dev/latest/) models for [OME-NGFF](https://ngff.openmicroscopy.org/)
+
+# About
+
+This library aims to provide models for the the metadata objects and Zarr hierarchies described in the [OME-NGFF](https://ngff.openmicroscopy.org/) specifications.
+
+# Reading Multiscale metadata
+
+```python
+# example data on S3-compatible cloud storage
+from pydantic_ome_ngff.v04.multiscales import Group
+import zarr
+url = "https://uk1s3.embassy.ebi.ac.uk/idr/zarr/v0.4/idr0062A/6001240.zarr"
+zgroup = zarr.open(url)
+group = Group.from_zarr(zgroup)
+
+```

mkdocs.yml

@@ -0,0 +1,63 @@
+site_name: pydantic-ome-ngff
+site_url: https://janeliascicomp.github.io/pydantic-ome-ngff/
+site_author: Davis Bennett
+site_description: >-
+  Pydantic models for the OME-NGFF file format.
+
+# Repository
+repo_name: janeliascicomp/pydantic-ome-ngff
+repo_url: https://github.com/janeliascicomp/pydantic-zarr
+
+# Copyright
+copyright: Copyright © 2016 - 2023 HHMI / Janelia
+
+theme:
+  features:
+    - navigation.expand
+  name: material
+  palette: 
+  # Palette toggle for light mode
+  - scheme: default
+    toggle:
+      icon: material/brightness-7 
+      name: Switch to dark mode
+
+  # Palette toggle for dark mode
+  - scheme: slate
+    toggle:
+      icon: material/brightness-4
+      name: Switch to light mode
+
+nav:
+    - About: index.md
+    - API:
+      - v04:
+        - api/v04/multiscales.md
+        - api/v04/axis.md
+        - api/v04/transforms.md
+
+plugins:
+- mkdocstrings:
+    handlers:
+        python:
+          options:
+            docstring_style: numpy
+            members_order: source
+            separate_signature: true
+            filters: ["!^_"]
+            docstring_options:
+              ignore_init_summary: true
+            merge_init_into_class: true
+
+markdown_extensions:
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  - pymdownx.superfences
+  - toc:
+      baselevel: 2
+      toc_depth: 4
+      permalink: "#"

pyproject.toml

@@ -8,9 +8,9 @@ readme = "README.md"
 packages = [{include = "pydantic_ome_ngff", from="src"}]
 
 [tool.poetry.dependencies]
-python = "^3.9"
-pydantic = "^1.10.4"
-
+python = "^3.10"
+pydantic-zarr = "0.6.1"
+rich = "^13.6.0"
 
 [tool.poetry.group.dev.dependencies]
 pre-commit = "^3.0.4"
@@ -21,6 +21,12 @@ mypy = "^1.0.1"
 requests = "^2.28.2"
 pytest-cov = "^4.0.0"
 
+
+[tool.poetry.group.docs.dependencies]
+mkdocs-material = "^9.5.5"
+mkdocstrings = {extras = ["python"], version = "^0.24.0"}
+pytest-examples = "^0.0.9"
+
 [build-system]
 requires = ["poetry-core"]
 build-backend = "poetry.core.masonry.api"
@@ -44,4 +50,32 @@ disallow_untyped_defs = true
 init_forbid_extra = true
 init_typed = true
 warn_required_dynamic_aliases = true
-warn_untyped_fields = true
+warn_untyped_fields = true
+
+
+[tool.coverage.run]
+source = ['src']
+branch = true
+context = '${CONTEXT}'
+
+[tool.coverage.report]
+precision = 2
+exclude_lines = [
+    'pragma: no cover',
+    'raise NotImplementedError',
+    'if TYPE_CHECKING:',
+    'if typing.TYPE_CHECKING:',
+    '@overload',
+    '@typing.overload',
+    '\(Protocol\):$',
+    'typing.assert_never',
+    'assert_never',
+]
+
+[tool.coverage.paths]
+source = [
+    'src/'
+]
+
+[tool.coverage.html]
+directory = "htmlcov"

src/pydantic_ome_ngff/__about__.py

@@ -0,0 +1,4 @@
+# SPDX-FileCopyrightText: 2023-present Davis Vann Bennett <davis.v.bennett@gmail.com>
+#
+# SPDX-License-Identifier: MIT
+__version__ = "0.3.0"

src/pydantic_ome_ngff/base.py

@@ -1,14 +1,11 @@
-from pydantic import BaseModel, Extra
+from pydantic import BaseModel
 
 
-class StrictBase(BaseModel):
+class StrictBase(BaseModel, extra="forbid"):
     """
     A pydantic basemodel that refuses extra fields.
     """
 
-    class Config:
-        extra = Extra.forbid
-
 
 class VersionedBase(BaseModel):
     """
@@ -22,5 +19,3 @@ class StrictVersionedBase(VersionedBase, StrictBase):
     """
     An internally versioned pydantic basemodel that refuses extra fields.
     """
-
-    ...

src/pydantic_ome_ngff/latest/__init__.py

@@ -1,6 +1,6 @@
-from pydantic_ome_ngff.latest.axes import Axis  # noqa
-from pydantic_ome_ngff.latest.multiscales import Multiscale  # noqa
-from pydantic_ome_ngff.latest.imageLabel import ImageLabel  # noqa
-from pydantic_ome_ngff.latest.well import Well  # noqa
-from pydantic_ome_ngff.latest.plate import Plate  # noqa
+from pydantic_ome_ngff.latest.axis import Axis  # noqa
+from pydantic_ome_ngff.latest.multiscales import MultiscaleMetadata  # noqa
+from pydantic_ome_ngff.latest.label import ImageLabel  # noqa
+from pydantic_ome_ngff.latest.well import WellMeta  # noqa
+from pydantic_ome_ngff.latest.plate import PlateMeta  # noqa
 from pydantic_ome_ngff.latest.base import version  # noqa

src/pydantic_ome_ngff/latest/axis.py

@@ -0,0 +1,12 @@
+import pydantic_ome_ngff.v04.axis as axisV04
+
+AxisType = axisV04.AxisType
+
+
+class Axis(axisV04.Axis):
+    """
+    Axis metadata.
+    See https://ngff.openmicroscopy.org/latest/#axes-md
+
+    Note: this metadata is unchanged from version 0.4 of the spec.
+    """

src/pydantic_ome_ngff/latest/base.py

@@ -1 +1,7 @@
-version = "0.5-dev"
+from __future__ import annotations
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from typing import Literal
+
+version: Literal["0.5-dev"] = "0.5-dev"

src/pydantic_ome_ngff/latest/imageLabel.py → src/pydantic_ome_ngff/latest/label.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
-from typing import Optional
-from pydantic_ome_ngff.v04.imageLabel import ImageLabel as ImageLabelV04
+
 from pydantic_ome_ngff.latest.base import version
+from pydantic_ome_ngff.v04.label import ImageLabel as ImageLabelV04
 
 
 class ImageLabel(ImageLabelV04):
@@ -13,4 +13,4 @@ class ImageLabel(ImageLabelV04):
     # we need to put the version here as a private class attribute because the version
     # is not required by the spec...
     _version = version
-    version: Optional[str] = version
+    version: str | None = version