open_virtual()

.codespellignore

@@ -1,2 +1,3 @@
 ges
 cach
+fo

.github/workflows/integration-test.yml

@@ -142,8 +142,8 @@ jobs:
           EARTHDATA_USERNAME: ${{ secrets.EDL_USERNAME }}
           EARTHDATA_PASSWORD: ${{ secrets.EDL_PASSWORD }}
         run: |
-          # -rxXs: Show provided (r)eason in summary for (x)fail, (X)pass, and (s)kipped tests
           uv run pytest tests/integration \
+            -n logical \
             -rxXs \
             --cov=earthaccess \
             --cov-report=term-missing \

docs/.nav.yml

@@ -22,6 +22,8 @@ nav:
               - "Store": "api/store/store.md"
           - Auth:
               - "Auth": "api/auth/auth.md"
+          - Virtual:
+              - "Virtual": "api/virtual/virtual.md"
 
   - User guide:
       - "user/index.md"

docs/api/virtual/virtual.md

@@ -0,0 +1,16 @@
+# Documentation for `earthaccess.virtual`
+
+::: earthaccess.virtual
+    options:
+      inherited_members: true
+    show_root_heading: true
+    show_source: false
+
+---
+
+## Internal helpers
+
+::: earthaccess.virtual._parser.homogenize_dataset_codec_level
+    options:
+      show_root_heading: true
+      show_source: false

earthaccess/__init__.py

@@ -1,5 +1,4 @@
 import logging
-import threading
 
 from .api import (
     auth_environ,
@@ -24,7 +23,7 @@
 from .services import DataServices
 from .store import Store
 from .system import PROD, UAT
-from .virtual import virtualize
+from .virtual import open_virtual, virtualize
 
 logger = logging.getLogger(__name__)
 
@@ -55,11 +54,12 @@
     "granule_query",
     "login",
     "open",
+    # virtual
+    "open_virtual",
     "search_data",
     "search_datasets",
     "search_services",
     "status",
-    # virtual
     "virtualize",
 ]
 
@@ -72,7 +72,6 @@
 
 _auth = Auth()
 _store: Store | None = None
-_lock = threading.Lock()
 
 
 def __getattr__(name):  # type: ignore[no-untyped-def]

earthaccess/auth.py

@@ -58,7 +58,6 @@ def __init__(self, hostname: str, auth: tuple[str, str]) -> None:
         self.auth = auth
 
     def __call__(self, r: requests.Response, **kwargs: Any) -> requests.Response:
-
         # If the response's URL is not for the EDL system we're authenticating
         # against, then simply return the response unchanged.  Otherwise, we'll
         # prepare a new request below with the user's EDL credentials.

earthaccess/results.py

@@ -5,6 +5,7 @@
 from typing import Any, ClassVar
 
 import requests
+import s3fs
 
 import earthaccess
 
@@ -290,6 +291,54 @@ def s3_bucket(self) -> dict[str, Any]:
 
         return self["umm"].get("DirectDistributionInformation", {})
 
+    def virtual_collection_url(self) -> str | None:
+        """Return the VIRTUAL COLLECTION URL from the collection's RelatedUrls.
+
+        Returns:
+            The URL of the virtual store reference file (e.g. a .json or
+            .icechunk file), or ``None`` if no such link exists.
+        """
+        for link in self["umm"].get("RelatedUrls", []):
+            if (
+                link.get("Type") == "GET DATA"
+                and link.get("Subtype") == "VIRTUAL COLLECTION"
+            ):
+                return link["URL"]
+        return None
+
+    def get_s3_credentials(self) -> dict[str, str]:
+        """Return temporary S3 credentials for this collection.
+
+        Returns:
+            A dictionary with ``accessKeyId``, ``secretAccessKey``,
+            and ``sessionToken``.
+
+        Raises:
+            ValueError: If the collection has no ``S3CredentialsAPIEndpoint``.
+        """
+        dd = self["umm"].get("DirectDistributionInformation", {})
+        endpoint = dd.get("S3CredentialsAPIEndpoint")
+        if not endpoint:
+            msg = "This collection does not provide an S3CredentialsAPIEndpoint."
+            raise ValueError(
+                msg,
+            )
+        return earthaccess.__auth__.get_s3_credentials(endpoint=endpoint)
+
+    def get_s3_filesystem(self) -> s3fs.S3FileSystem:
+        """Return an authenticated ``s3fs.S3FileSystem`` for this collection.
+
+        Returns:
+            An ``s3fs.S3FileSystem`` configured with temporary S3 credentials
+            from the collection's credentials endpoint.
+        """
+        creds = self.get_s3_credentials()
+        return s3fs.S3FileSystem(
+            key=creds["accessKeyId"],
+            secret=creds["secretAccessKey"],
+            token=creds["sessionToken"],
+        )
+
     def services(self) -> dict[Any, list[dict[str, Any]]]:
         """Return list of services available for this collection."""
         warnings.warn(

earthaccess/store.py

@@ -49,7 +49,7 @@ def _is_interactive() -> bool:
     Interactive sessions include Jupyter Notebooks, IPython REPL, and default Python REPL.
     """
     try:
-        from IPython import (  # type: ignore[import-not-found]  # noqa: PLC0415
+        from IPython import (  # type: ignore[import-not-found]
             get_ipython,
         )
 

earthaccess/virtual/__init__.py

@@ -1,11 +1,16 @@
 """Virtual dataset utilities for cloud-native access to NASA Earthdata granules.
 
 This subpackage provides tools for creating virtual xarray Datasets from
-NASA Earthdata granules without downloading data, using VirtualiZarr parsers.
+NASA Earthdata granules without downloading data, using VirtualiZarr parsers,
+and for opening existing virtual stores (Icechunk / kerchunk references).
 
 Public API
 ----------
 - ``virtualize`` — create a virtual (or loaded) xarray Dataset from granules.
+- ``open_virtual`` — open an existing virtual store (Icechunk, kerchunk .parquet
+  or .json references) from a URI.
+- ``homogenize_dataset_codec_level`` — patch Zlib codec levels on all
+  ``ManifestArray`` objects in a virtual dataset (power-users).
 - ``SUPPORTED_PARSERS`` — frozenset of recognised parser name strings.
 - ``get_granule_credentials_endpoint_and_region`` — resolve S3 credentials
   for a granule (useful for advanced direct-access workflows).
@@ -18,11 +23,16 @@
 from earthaccess.virtual._credentials import (
     get_granule_credentials_endpoint_and_region,
 )
-from earthaccess.virtual._parser import SUPPORTED_PARSERS
-from earthaccess.virtual.core import virtualize
+from earthaccess.virtual._parser import (
+    SUPPORTED_PARSERS,
+    homogenize_dataset_codec_level,
+)
+from earthaccess.virtual.core import open_virtual, virtualize
 
 __all__ = [
     "SUPPORTED_PARSERS",
     "get_granule_credentials_endpoint_and_region",
+    "homogenize_dataset_codec_level",
+    "open_virtual",
     "virtualize",
 ]

earthaccess/virtual/_credentials.py

@@ -111,11 +111,11 @@ def build_obstore_registry(
         ImportError: If ``earthaccess[virtualizarr]`` is not installed.
     """
     try:
-        from obstore.auth.earthdata import (  # noqa: PLC0415
+        from obstore.auth.earthdata import (
             NasaEarthdataCredentialProvider,
         )
-        from obstore.store import HTTPStore, S3Store  # noqa: PLC0415
-        from virtualizarr.registry import ObjectStoreRegistry  # noqa: PLC0415
+        from obstore.store import HTTPStore, S3Store
+        from virtualizarr.registry import ObjectStoreRegistry
     except ImportError:
         msg = (
             "earthaccess.virtualize() requires `pip install earthaccess[virtualizarr]`"

earthaccess/virtual/_parser.py

@@ -12,6 +12,8 @@
 from earthaccess.virtual._types import AccessType, ParserType
 
 if TYPE_CHECKING:
+    import xarray as xr
+
     import earthaccess
     from earthaccess.virtual._types import AccessType, ParserType
 
@@ -70,7 +72,7 @@ def resolve_parser(
         return parser
 
     try:
-        from virtualizarr.parsers import (  # noqa: PLC0415
+        from virtualizarr.parsers import (
             DMRPPParser,
             HDFParser,
             KerchunkJSONParser,
@@ -133,3 +135,75 @@ def get_urls_for_parser(
             url = url + ".dmrpp"
         urls.append(url)
     return urls
+
+
+def homogenize_dataset_codec_level(ds: xr.Dataset, target_level: int = 7) -> xr.Dataset:
+    """Patch Zlib codec levels on all ManifestArrays in *ds* to *target_level*."""
+    try:
+        import xarray as xr
+        from virtualizarr.manifests import ManifestArray
+    except ImportError:
+        msg = (
+            "earthaccess.virtualize() requires `pip install earthaccess[virtualizarr]`"
+        )
+        raise ImportError(
+            msg,
+        ) from None
+
+    def _patch_ma(ma: ManifestArray, level: int) -> ManifestArray:
+        if not isinstance(ma, ManifestArray):
+            return ma
+
+        meta = ma.metadata
+        codecs = list(meta.codecs)
+        modified = False
+
+        for i, codec in enumerate(codecs):
+            if not hasattr(codec, "to_dict"):
+                continue
+            cd = codec.to_dict()
+            if cd.get("name") != "numcodecs.zlib":
+                continue
+            cfg = cd.get("configuration", {})
+            if isinstance(cfg, dict):
+                if cfg.get("level") == level:
+                    continue
+                cd["configuration"] = {**cfg, "level": level}
+            else:
+                cd["configuration"] = {"level": level}
+            codecs[i] = type(codec).from_dict(cd)
+            modified = True
+
+        if not modified:
+            return ma
+
+        import zarr
+
+        new_meta = zarr.core.metadata.v3.ArrayV3Metadata(
+            shape=meta.shape,
+            data_type=meta.data_type,
+            chunk_grid=meta.chunk_grid,
+            chunk_key_encoding=meta.chunk_key_encoding,
+            fill_value=meta.fill_value,
+            codecs=tuple(codecs),
+            attributes=meta.attributes,
+            dimension_names=meta.dimension_names,
+            storage_transformers=meta.storage_transformers,
+        )
+        return ManifestArray(new_meta, ma.manifest)
+
+    new_vars = {
+        name: (
+            xr.DataArray(
+                _patch_ma(var.data, target_level),
+                dims=var.dims,
+                attrs=var.attrs,
+                name=name,
+            )
+            if isinstance(var.data, ManifestArray)
+            else var
+        )
+        for name, var in ds.data_vars.items()
+    }
+
+    return xr.Dataset(new_vars, coords=ds.coords, attrs=ds.attrs)