From 1c30386f52be209c14ef00a6bc80205f3c5949d8 Mon Sep 17 00:00:00 2001 From: Maitri Upadhyay Date: Fri, 26 Jun 2026 00:38:37 +0530 Subject: [PATCH 01/10] feat(accessor): add nrefs() method to VirtualiZarrDatasetAccessor Add method to count total virtual chunk references in dataset. --- virtualizarr/accessor.py | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/virtualizarr/accessor.py b/virtualizarr/accessor.py index 5a63e733..72af8334 100644 --- a/virtualizarr/accessor.py +++ b/virtualizarr/accessor.py @@ -286,6 +286,27 @@ def nbytes(self) -> int: ) + def nrefs(self) -> int: + """Count the total number of virtual chunk references in the dataset. + + Ignores non-virtual variables (i.e. those not backed by a ManifestArray). + + Returns + ------- + int + Total number of virtual references across all virtual variables. + + Examples + -------- + >>> vds.vz.nrefs + 42 + """ + return sum( + len(var.data.manifest) + for var in self.ds.variables.values() + if isinstance(var.data, ManifestArray) + ) + @xr.register_dataset_accessor("vz") class VirtualiZarrDatasetAccessor(_VirtualiZarrDatasetAccessor): pass From de4d50fa690be53c18408c05fb3c4ab4afd75aec Mon Sep 17 00:00:00 2001 From: Maitri Upadhyay Date: Fri, 26 Jun 2026 00:40:12 +0530 Subject: [PATCH 02/10] test(accessor): add test_nrefs for VirtualiZarrDatasetAccessor Add test for nrefs in open_virtual_dataset with HDFParser. --- virtualizarr/tests/test_xarray.py | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/virtualizarr/tests/test_xarray.py b/virtualizarr/tests/test_xarray.py index 05ccca23..6f3a26b0 100644 --- a/virtualizarr/tests/test_xarray.py +++ b/virtualizarr/tests/test_xarray.py @@ -1163,3 +1163,25 @@ def test_isel_iterative_append_simulation(self, array_v3_metadata): # every original chunk should have been visited exactly once assert sorted(seen_refs) == [0, 100, 200, 300] + + +@requires_hdf5plugin +@requires_imagecodecs +def test_nrefs(simple_netcdf4, local_registry): + parser = HDFParser() + with open_virtual_dataset( + url=simple_netcdf4, + registry=local_registry, + parser=parser, + ) as vds: + # simple_netcdf4 has one virtual variable 'air' with a single chunk + assert vds.vz.nrefs == 1 + + with open_virtual_dataset( + url=simple_netcdf4, + registry=local_registry, + parser=parser, + loadable_variables=["air"], + ) as vds: + # when the only variable is loadable (non-virtual), nrefs should be 0 + assert vds.vz.nrefs == 0 From c9d1e41d70dd647d6b3154bf2291bb0e90b2f734 Mon Sep 17 00:00:00 2001 From: Maitri Upadhyay Date: Fri, 26 Jun 2026 00:41:31 +0530 Subject: [PATCH 03/10] docs(api): add nrefs to virtualizarr.md API reference Added nrefs property to VirtualiZarrDatasetAccessor documentation. --- docs/api/virtualizarr.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/api/virtualizarr.md b/docs/api/virtualizarr.md index d7cb28af..36125eb7 100644 --- a/docs/api/virtualizarr.md +++ b/docs/api/virtualizarr.md @@ -16,6 +16,8 @@ Users can use xarray for every step apart from reading and serializing virtual r ::: virtualizarr.accessor.VirtualiZarrDatasetAccessor.nbytes +::: virtualizarr.accessor.VirtualiZarrDatasetAccessor.nrefs + ## Renaming paths ::: virtualizarr.accessor.VirtualiZarrDatasetAccessor.rename_paths From 2b5fccce5934e3c9d9d090bf42fcad46ef0bfb2b Mon Sep 17 00:00:00 2001 From: Maitri Upadhyay Date: Fri, 26 Jun 2026 00:42:44 +0530 Subject: [PATCH 04/10] docs(changelog): add nrefs to v2.7.1 release notes Added a new feature to return the total number of virtual chunk references in the dataset. --- docs/about/releases.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/about/releases.md b/docs/about/releases.md index 26c9cd7f..31f671e7 100644 --- a/docs/about/releases.md +++ b/docs/about/releases.md @@ -3,6 +3,7 @@ ## v2.7.1 (unreleased) ### New Features +- Added [VirtualiZarrDatasetAccessor.nrefs][virtualizarr.accessor.VirtualiZarrDatasetAccessor.nrefs] — a method that returns the total number of virtual chunk references in the dataset, ignoring non-virtual variables. Closes #573. ### Breaking changes From 3537b7d6ebff7d0e6ebc8558fe9512ad55aa2128 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Thu, 25 Jun 2026 19:19:17 +0000 Subject: [PATCH 05/10] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- virtualizarr/accessor.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/virtualizarr/accessor.py b/virtualizarr/accessor.py index 72af8334..41ec9b31 100644 --- a/virtualizarr/accessor.py +++ b/virtualizarr/accessor.py @@ -285,7 +285,6 @@ def nbytes(self) -> int: for var in self.ds.variables.values() ) - def nrefs(self) -> int: """Count the total number of virtual chunk references in the dataset. @@ -307,6 +306,7 @@ def nrefs(self) -> int: if isinstance(var.data, ManifestArray) ) + @xr.register_dataset_accessor("vz") class VirtualiZarrDatasetAccessor(_VirtualiZarrDatasetAccessor): pass From 33f059b36e5bdb461a4df534e390777d88589b9d Mon Sep 17 00:00:00 2001 From: Maitri Upadhyay Date: Fri, 26 Jun 2026 00:55:50 +0530 Subject: [PATCH 06/10] fix(accessor): mark nrefs doctest example as +SKIP Updated doctest to skip for nrefs property. --- virtualizarr/accessor.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/virtualizarr/accessor.py b/virtualizarr/accessor.py index 41ec9b31..6bee82c4 100644 --- a/virtualizarr/accessor.py +++ b/virtualizarr/accessor.py @@ -297,7 +297,7 @@ def nrefs(self) -> int: Examples -------- - >>> vds.vz.nrefs + >>> vds.vz.nrefs # doctest: +SKIP 42 """ return sum( From 327bf4320d18bbd54ab70bb8297659262aa85489 Mon Sep 17 00:00:00 2001 From: Maitri Upadhyay Date: Fri, 26 Jun 2026 00:56:38 +0530 Subject: [PATCH 07/10] fix(tests): use correct fixture variable name 'foo' in test_nrefs --- virtualizarr/tests/test_xarray.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/virtualizarr/tests/test_xarray.py b/virtualizarr/tests/test_xarray.py index 6f3a26b0..11bff255 100644 --- a/virtualizarr/tests/test_xarray.py +++ b/virtualizarr/tests/test_xarray.py @@ -1174,14 +1174,14 @@ def test_nrefs(simple_netcdf4, local_registry): registry=local_registry, parser=parser, ) as vds: - # simple_netcdf4 has one virtual variable 'air' with a single chunk + # simple_netcdf4 has one virtual variable 'foo' with a single chunk assert vds.vz.nrefs == 1 with open_virtual_dataset( url=simple_netcdf4, registry=local_registry, parser=parser, - loadable_variables=["air"], + loadable_variables=["foo"], ) as vds: # when the only variable is loadable (non-virtual), nrefs should be 0 assert vds.vz.nrefs == 0 From aeb6cab70ad4e8a352560cf54b202c7754fa9bf8 Mon Sep 17 00:00:00 2001 From: Maitri Upadhyay Date: Fri, 26 Jun 2026 01:35:17 +0530 Subject: [PATCH 08/10] fix: add parentheses to nrefs() calls in tests Co-authored-by: Tom Nicholas --- virtualizarr/tests/test_xarray.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/virtualizarr/tests/test_xarray.py b/virtualizarr/tests/test_xarray.py index 11bff255..c3a34605 100644 --- a/virtualizarr/tests/test_xarray.py +++ b/virtualizarr/tests/test_xarray.py @@ -1175,7 +1175,7 @@ def test_nrefs(simple_netcdf4, local_registry): parser=parser, ) as vds: # simple_netcdf4 has one virtual variable 'foo' with a single chunk - assert vds.vz.nrefs == 1 + assert vds.vz.nrefs() == 1 with open_virtual_dataset( url=simple_netcdf4, From 916c8805934654c3d6cc36e92ec318a7a5bdb4e1 Mon Sep 17 00:00:00 2001 From: Maitri Upadhyay Date: Fri, 26 Jun 2026 01:37:39 +0530 Subject: [PATCH 09/10] fix(accessor): add () to nrefs docstring example --- virtualizarr/accessor.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/virtualizarr/accessor.py b/virtualizarr/accessor.py index 6bee82c4..5f51833f 100644 --- a/virtualizarr/accessor.py +++ b/virtualizarr/accessor.py @@ -297,7 +297,7 @@ def nrefs(self) -> int: Examples -------- - >>> vds.vz.nrefs # doctest: +SKIP + >>> vds.vz.nrefs() # doctest: +SKIP 42 """ return sum( From cbb718feb51df13ff3f443541f0a6bdfdfdaa24b Mon Sep 17 00:00:00 2001 From: Maitri Upadhyay Date: Fri, 26 Jun 2026 01:39:36 +0530 Subject: [PATCH 10/10] fix(tests): add () to remaining nrefs() call in test_nrefs --- virtualizarr/tests/test_xarray.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/virtualizarr/tests/test_xarray.py b/virtualizarr/tests/test_xarray.py index c3a34605..1c882bf6 100644 --- a/virtualizarr/tests/test_xarray.py +++ b/virtualizarr/tests/test_xarray.py @@ -1184,4 +1184,4 @@ def test_nrefs(simple_netcdf4, local_registry): loadable_variables=["foo"], ) as vds: # when the only variable is loadable (non-virtual), nrefs should be 0 - assert vds.vz.nrefs == 0 + assert vds.vz.nrefs() == 0