moczarr 0.1.0__tar.gz

moczarr-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+site/
+.venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+coverage.xml
+src/moczarr/_version.py
+.DS_Store
+uv.lock
+.cache/

moczarr-0.1.0/CHANGELOG.md

@@ -0,0 +1,53 @@
+# Changelog
+
+## 0.1.0
+
+First release — the complete phase 0–7 reader from the plan issue
+([#1](https://github.com/espg/moczarr/issues/1)).
+
+**`open_hive` defaults to the lazy index**: `index_kind="moc"` is the
+default posture — a whole-store or AOI open reads *no* coordinate chunks,
+holding the row domain as an interval set and fabricating the `morton`
+coordinate on demand. The result is value-identical to the materialized
+open; pass `index_kind="pandas"` to materialize instead. One workflow
+difference to know: `xr.concat` of moc-indexed opens is supported for
+disjoint, ascending domains (the batch-sweep case); overlapping or
+out-of-order concat raises `NotImplementedError` and should open with
+`index_kind="pandas"`.
+
+- Scaffold + the morton-hive convention core: hive paths, manifest
+  parsing, node invariant, morton decimal↔word helpers
+  ([#2](https://github.com/espg/moczarr/pull/2)).
+- Store layer (obstore-backed) + `open_hive()`: manifest bootstrap,
+  coverage-MOC ∩ AOI shard selection, stamped-leaf opens, discovery-walk
+  fallback, time-windowed (`morton-hive/2`) stores; the SERC test fixture
+  generated by zagg's real writer
+  ([#3](https://github.com/espg/moczarr/pull/3)).
+- xdggs integration (`[xdggs]` extra): `grid_name: "morton"` registered
+  via `register_dggs` — `ds.dggs.sel_latlon`, `cell_boundaries`,
+  `zoom_to` on `open_hive` results
+  ([#6](https://github.com/espg/moczarr/pull/6)).
+- Exact NESTED `cell_ids` fabrication from packed morton words
+  (`fabricate_cell_ids="auto"`) — the reader-side gate for zagg's
+  morton-only writer flip (englacial/zagg#262)
+  ([#7](https://github.com/espg/moczarr/pull/7)).
+- Shared store handle + concurrent metadata: one obstore/zarr pair per
+  open, batched stamp GETs and walk LISTs (`concurrency=32`), issue
+  [#5](https://github.com/espg/moczarr/issues/5)
+  ([#9](https://github.com/espg/moczarr/pull/9)).
+- MOC-backed lazy index (`index_kind="moc"`): the row domain held as a
+  rank-space interval set (`MortonRanges`) behind a `MortonMocIndex`
+  (plain `xarray.Index`, core) — zero coordinate-chunk reads, value-
+  identical to the materialized open
+  ([#10](https://github.com/espg/moczarr/pull/10)).
+- Cross-resolution truncation join: `parent_cells` (fine→coarse groupby
+  coordinate) and `join_coarse` (coarse→fine lookup), any index-kind
+  pairing ([#12](https://github.com/espg/moczarr/pull/12)).
+- Empty-AOI contract: an AOI/window intersecting no coverage returns a
+  schema-correct empty dataset + `UserWarning`; only a store with no
+  stamped coverage anywhere raises `NoCoverageError`, issue
+  [#4](https://github.com/espg/moczarr/issues/4)
+  ([#13](https://github.com/espg/moczarr/pull/13)).
+- Documentation site (quickstart, concepts, API reference), the
+  binder-runnable example notebook, and the tag-driven publish pipeline
+  (TestPyPI → PyPI via trusted publishing).

moczarr-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shane
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

moczarr-0.1.0/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.4
+Name: moczarr
+Version: 0.1.0
+Summary: Sparse-DGGS xarray reader for morton-hive zarr stores (MOC domain, lazy dense views)
+Project-URL: Homepage, https://github.com/espg/moczarr
+Project-URL: Documentation, https://espg.github.io/moczarr/
+Project-URL: Repository, https://github.com/espg/moczarr
+Project-URL: Issues, https://github.com/espg/moczarr/issues
+Project-URL: Changelog, https://github.com/espg/moczarr/blob/main/CHANGELOG.md
+Author-email: Shane Grigsby <refuge@rocktalus.com>
+License: MIT License
+        
+        Copyright (c) 2026 Shane
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: GIS
+Requires-Python: >=3.12
+Requires-Dist: mortie>=0.9.0
+Requires-Dist: numcodecs>=0.14
+Requires-Dist: numpy>=2.0
+Requires-Dist: obstore>=0.8.2
+Requires-Dist: pandas
+Requires-Dist: xarray
+Requires-Dist: zarr>=3.1.5
+Provides-Extra: test
+Requires-Dist: pytest-cov; extra == 'test'
+Requires-Dist: pytest>=8.0; extra == 'test'
+Provides-Extra: xdggs
+Requires-Dist: shapely; extra == 'xdggs'
+Requires-Dist: xdggs>=0.6; extra == 'xdggs'
+Description-Content-Type: text/markdown
+
+# moczarr
+
+[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/espg/moczarr/main?labpath=docs%2Fexamples%2Fquickstart.ipynb)
+
+Sparse-DGGS xarray reader for **morton-hive** zarr stores: MOC-declared
+domains, arithmetic shard paths, lazy dense views.
+
+`moczarr` opens stores written by [zagg](https://github.com/englacial/zagg)
+under the morton-hive layout convention: a digit tree of self-describing
+zarr v3 leaves keyed by morton decimal ids, with a static manifest and
+hierarchical coverage MOCs declaring where data exists — so a reader
+intersects an area of interest *arithmetically* instead of listing objects
+or materializing a global grid.
+
+```python
+import moczarr
+
+ds = moczarr.open_hive("s3://bucket/prefix", aoi=["433142"], anonymous=True)
+```
+
+## Features
+
+- **`open_hive()`** — one call from store root (local path or
+  `s3://bucket/prefix`) to a lazy `xarray.Dataset`; AOI covers (packed
+  morton words or decimal strings, mixed orders) and time-window scoping
+  resolve through coverage metadata, not object listings. An AOI over no
+  coverage is a data answer: a schema-correct empty dataset, not an error.
+- **A MOC-backed lazy index** (the default) — the row domain held as a
+  rank-space interval set built from the same coverage arithmetic that
+  selected the leaves; the on-disk cell arrays are never read, and the
+  `morton` coordinate is fabricated on demand (`sel`/`isel`/alignment as
+  interval arithmetic; `index_kind="pandas"` materializes instead).
+- **Exact NESTED fabrication** — HEALPix NESTED `cell_ids` derived exactly
+  from the packed morton words ("NESTED is fabricated, never stored").
+- **Cross-resolution joins** — morton truncation makes coarse↔fine work a
+  vectorized lookup: `parent_cells` for fine→coarse groupby aggregation,
+  `join_coarse` for the coarse→fine broadcast, no I/O.
+- **xdggs integration** (`moczarr[xdggs]`) — a registered `"morton"` grid,
+  so `ds.dggs.sel_latlon`, `cell_boundaries`, `zoom_to` work on any
+  `open_hive` result.
+
+Docs: [espg.github.io/moczarr](https://espg.github.io/moczarr/) —
+quickstart, concepts, API reference, and the
+[example notebook](https://espg.github.io/moczarr/examples/quickstart/)
+(runnable on binder via the badge above).
+
+## Install
+
+```sh
+pip install moczarr            # core reader
+pip install 'moczarr[xdggs]'   # + the ds.dggs accessor integration
+```
+
+Until the first PyPI release lands, install from git:
+
+```sh
+pip install 'moczarr[xdggs] @ git+https://github.com/espg/moczarr'
+```
+
+Development (uses [uv](https://docs.astral.sh/uv/)):
+
+```sh
+uv sync --extra test --extra xdggs
+uv run pytest -v
+```
+
+## The convention
+
+moczarr is the read side of a convention owned elsewhere: the morton-hive
+layout and morton decimal ids are specified in the
+[mortie specification](https://github.com/espg/mortie/blob/main/docs/specification.md),
+and the coverage tiers, commit-stamp semantics, and reader architecture in
+[zagg's `sparse_coverage.md`](https://github.com/englacial/zagg/blob/main/docs/design/sparse_coverage.md)
+(§4 coverage, §5 reader, §6 xarray extension). Plan and progress:
+[espg/moczarr#1](https://github.com/espg/moczarr/issues/1).
+
+## License
+
+MIT

moczarr-0.1.0/README.md

@@ -0,0 +1,79 @@
+# moczarr
+
+[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/espg/moczarr/main?labpath=docs%2Fexamples%2Fquickstart.ipynb)
+
+Sparse-DGGS xarray reader for **morton-hive** zarr stores: MOC-declared
+domains, arithmetic shard paths, lazy dense views.
+
+`moczarr` opens stores written by [zagg](https://github.com/englacial/zagg)
+under the morton-hive layout convention: a digit tree of self-describing
+zarr v3 leaves keyed by morton decimal ids, with a static manifest and
+hierarchical coverage MOCs declaring where data exists — so a reader
+intersects an area of interest *arithmetically* instead of listing objects
+or materializing a global grid.
+
+```python
+import moczarr
+
+ds = moczarr.open_hive("s3://bucket/prefix", aoi=["433142"], anonymous=True)
+```
+
+## Features
+
+- **`open_hive()`** — one call from store root (local path or
+  `s3://bucket/prefix`) to a lazy `xarray.Dataset`; AOI covers (packed
+  morton words or decimal strings, mixed orders) and time-window scoping
+  resolve through coverage metadata, not object listings. An AOI over no
+  coverage is a data answer: a schema-correct empty dataset, not an error.
+- **A MOC-backed lazy index** (the default) — the row domain held as a
+  rank-space interval set built from the same coverage arithmetic that
+  selected the leaves; the on-disk cell arrays are never read, and the
+  `morton` coordinate is fabricated on demand (`sel`/`isel`/alignment as
+  interval arithmetic; `index_kind="pandas"` materializes instead).
+- **Exact NESTED fabrication** — HEALPix NESTED `cell_ids` derived exactly
+  from the packed morton words ("NESTED is fabricated, never stored").
+- **Cross-resolution joins** — morton truncation makes coarse↔fine work a
+  vectorized lookup: `parent_cells` for fine→coarse groupby aggregation,
+  `join_coarse` for the coarse→fine broadcast, no I/O.
+- **xdggs integration** (`moczarr[xdggs]`) — a registered `"morton"` grid,
+  so `ds.dggs.sel_latlon`, `cell_boundaries`, `zoom_to` work on any
+  `open_hive` result.
+
+Docs: [espg.github.io/moczarr](https://espg.github.io/moczarr/) —
+quickstart, concepts, API reference, and the
+[example notebook](https://espg.github.io/moczarr/examples/quickstart/)
+(runnable on binder via the badge above).
+
+## Install
+
+```sh
+pip install moczarr            # core reader
+pip install 'moczarr[xdggs]'   # + the ds.dggs accessor integration
+```
+
+Until the first PyPI release lands, install from git:
+
+```sh
+pip install 'moczarr[xdggs] @ git+https://github.com/espg/moczarr'
+```
+
+Development (uses [uv](https://docs.astral.sh/uv/)):
+
+```sh
+uv sync --extra test --extra xdggs
+uv run pytest -v
+```
+
+## The convention
+
+moczarr is the read side of a convention owned elsewhere: the morton-hive
+layout and morton decimal ids are specified in the
+[mortie specification](https://github.com/espg/mortie/blob/main/docs/specification.md),
+and the coverage tiers, commit-stamp semantics, and reader architecture in
+[zagg's `sparse_coverage.md`](https://github.com/englacial/zagg/blob/main/docs/design/sparse_coverage.md)
+(§4 coverage, §5 reader, §6 xarray extension). Plan and progress:
+[espg/moczarr#1](https://github.com/espg/moczarr/issues/1).
+
+## License
+
+MIT

moczarr-0.1.0/pyproject.toml

@@ -0,0 +1,115 @@
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[project]
+name = "moczarr"
+dynamic = ["version"]
+description = "Sparse-DGGS xarray reader for morton-hive zarr stores (MOC domain, lazy dense views)"
+readme = "README.md"
+requires-python = ">=3.12"
+license = {file = "LICENSE"}
+authors = [
+    {name = "Shane Grigsby", email = "refuge@rocktalus.com"},
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: GIS",
+]
+
+dependencies = [
+    "numpy>=2.0",
+    # Morton/HEALPix kernels: decimal<->word, hive_path, MOC algebra
+    # (moc_and), clip2order/children/parents. The layout convention itself is
+    # owned by the mortie spec (espg/mortie#62).
+    "mortie>=0.9.0",
+    # mortie's MortonIndexArray (.decimal_repr()/.hive_path()) imports pandas;
+    # a direct runtime dep the reader calls into, not just transitive via xarray.
+    "pandas",
+    "xarray",
+    "zarr>=3.1.5",
+    "obstore>=0.8.2",
+    # Zstd for the coverage-bitmap sidecar decode (O8 encoding).
+    "numcodecs>=0.14",
+]
+
+[project.optional-dependencies]
+# xdggs integration (MortonInfo/MortonIndex via register_dggs) is an EXTRA:
+# xdggs hard-requires lonboard/matplotlib/h3ronpy/cdshealpix — too heavy for
+# the core reader (see xarray-contrib/xdggs#128).
+xdggs = [
+    # Floor 0.6: the surface MortonInfo/MortonIndex ride on
+    # (translate_parameters, DGGSInfo.ellipsoid, the conventions decoder)
+    # is what 0.6.0 ships; developed and verified against 0.6.0.
+    "xdggs>=0.6",
+    # xdggs leaves shapely to the caller (all its shapely paths are lazy
+    # imports); cell_boundaries returns shapely polygons, so the extra
+    # carries it explicitly.
+    "shapely",
+]
+test = [
+    "pytest>=8.0",
+    "pytest-cov",
+]
+
+[project.urls]
+Homepage = "https://github.com/espg/moczarr"
+Documentation = "https://espg.github.io/moczarr/"
+Repository = "https://github.com/espg/moczarr"
+Issues = "https://github.com/espg/moczarr/issues"
+Changelog = "https://github.com/espg/moczarr/blob/main/CHANGELOG.md"
+
+[tool.hatch.version]
+source = "vcs"
+
+[tool.hatch.build.hooks.vcs]
+version-file = "src/moczarr/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/moczarr"]
+
+[tool.hatch.build.targets.sdist]
+only-include = [
+    "src/moczarr",
+    "tests",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "pyproject.toml",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+lint.select = ["E", "F", "W", "I", "N"]
+lint.ignore = ["E501"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["moczarr"]
+
+[tool.mypy]
+python_version = "3.12"
+ignore_missing_imports = true
+
+[dependency-groups]
+dev = [
+    "pre-commit>=4.5.1",
+    "pytest",
+    "pytest-cov",
+    "ruff",
+]
+docs = [
+    "mkdocs>=1.6.1",
+    "mkdocs-jupyter>=0.26.3",
+    "mkdocs-material>=9.6.14",
+    "mkdocstrings>=0.29.1",
+    "mkdocstrings-python>=1.16.10",
+]

moczarr-0.1.0/src/moczarr/__init__.py

@@ -0,0 +1,101 @@
+"""moczarr: sparse-DGGS xarray reader for morton-hive zarr stores."""
+
+from moczarr.convention import (
+    COMMIT_ATTR,
+    COVERAGE_SIDECAR,
+    HIVE_SPEC,
+    HIVE_SPEC_V2,
+    MANIFEST_NAME,
+    MORTON_CONVENTION_ENTRY,
+    MORTON_CONVENTION_UUID,
+    ROOT_COVERAGE_NAME,
+    check_node_invariant,
+    is_point_word,
+    leaf_path,
+    morton_decimal,
+    morton_word,
+    parse_manifest,
+    split_leaf_name,
+)
+from moczarr.coverage import (
+    COVERAGE_SPEC,
+    aoi_mask,
+    box_and,
+    box_words,
+    decode_bitmap,
+    parse_leaf_coverage,
+    parse_root_coverage,
+    ranges_contain,
+    ranges_words,
+    root_coverage_and,
+)
+from moczarr.exceptions import NoCoverageError
+from moczarr.fabricate import FLOAT64_EXACT_MAX_ORDER, fabricate_cell_ids
+from moczarr.join import join_coarse, parent_cells
+from moczarr.open import open_hive
+from moczarr.ranges import MortonRanges
+
+# moczarr.moc_index (MortonMocIndex) is imported by module path, not here:
+# the package root stays xarray-import-free (the repo's lazy-import posture),
+# and the index reaches most users through open_hive(index_kind="moc").
+from moczarr.store import (
+    bitmap_and,
+    load_root_coverage,
+    open_object_store,
+    read_commit,
+    read_coverage_bitmap,
+    read_leaf_coverage,
+    read_manifest,
+    walk_leaves,
+    warn_if_stale,
+)
+
+try:
+    from moczarr._version import __version__
+except ImportError:  # pragma: no cover - version file is generated at build time
+    __version__ = "0.0.0+unknown"
+
+__all__ = [
+    "COMMIT_ATTR",
+    "COVERAGE_SIDECAR",
+    "COVERAGE_SPEC",
+    "FLOAT64_EXACT_MAX_ORDER",
+    "HIVE_SPEC",
+    "HIVE_SPEC_V2",
+    "MANIFEST_NAME",
+    "MORTON_CONVENTION_ENTRY",
+    "MORTON_CONVENTION_UUID",
+    "MortonRanges",
+    "NoCoverageError",
+    "ROOT_COVERAGE_NAME",
+    "__version__",
+    "aoi_mask",
+    "bitmap_and",
+    "box_and",
+    "box_words",
+    "check_node_invariant",
+    "decode_bitmap",
+    "fabricate_cell_ids",
+    "is_point_word",
+    "join_coarse",
+    "leaf_path",
+    "load_root_coverage",
+    "morton_decimal",
+    "morton_word",
+    "open_hive",
+    "open_object_store",
+    "parent_cells",
+    "parse_leaf_coverage",
+    "parse_manifest",
+    "parse_root_coverage",
+    "ranges_contain",
+    "ranges_words",
+    "read_commit",
+    "read_coverage_bitmap",
+    "read_leaf_coverage",
+    "read_manifest",
+    "root_coverage_and",
+    "split_leaf_name",
+    "walk_leaves",
+    "warn_if_stale",
+]

moczarr-0.1.0/src/moczarr/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.1.0'
+__version_tuple__ = version_tuple = (0, 1, 0)
+
+__commit_id__ = commit_id = None