Updating package files (#35)

Updating some package files and adding docstrings for `to_xarray` and
`STACBackend.open_dataset`.

Author: jsignell

.gitignore

@@ -5,4 +5,5 @@ dist
 .direnv
 .mypy_cache
 .pytest_cache
-.ruff_cache
+.ruff_cache
+*.egg-info/

environment.yaml

@@ -1,4 +1,4 @@
-name: xpystac-broken
+name: xpystac
 channels:
   - conda-forge
   - nodefaults

setup.cfg

@@ -13,11 +13,26 @@ def to_xarray(
     stacking_library: Union[Literal["odc.stac", "stackstac"], None] = None,
     **kwargs,
 ) -> xarray.Dataset:
-    """Given a pystac object return an xarray dataset
-
-    When stacking multiple items, an optional ``stacking_library`` argument
-    is accepted. It defaults to ``odc.stac`` if available and otherwise ``stackstac``.
-    Control the behavior by setting ``stacking_library``
+    """Given a PySTAC object return an xarray dataset.
+
+    The behavior of this method depends on the type of PySTAC object:
+
+    * Asset: if the asset points to a kerchunk file or a zarr file,
+      reads the metadata in that file to construct the coordinates of the
+      dataset. If the asset points to a COG, read that.
+    * Item: stacks all the assets into a dataset with 1 more dimension than
+      any given asset.
+    * ItemCollection (output of pystac_client.search): stacks all the
+      assets in all the items into a dataset with 2 more dimensions than
+      any given asset.
+
+    Parameters
+    ----------
+    obj : PySTAC object (Item, ItemCollection, Asset)
+        The object from which to read data.
+    stacking_library : "odc.stac", "stackstac", optional
+        When stacking multiple items, this argument determines which library
+        to use. Defaults to ``odc.stac`` if available and otherwise ``stackstac``.
     """
     if _is_item_search(obj):
         item_collection = obj.item_collection()

xpystac/core.py

@@ -1,4 +1,4 @@
-from typing import Any, Iterable, Union
+from typing import Any, Iterable, Literal, Union
 
 import pystac
 from xarray.backends import BackendEntrypoint
@@ -8,17 +8,44 @@
 
 
 class STACBackend(BackendEntrypoint):
-    description = "Open pystac objects in Xarray"
+    description = "Open STAC objects in Xarray"
     open_dataset_parameters = ("filename_or_obj", "drop_variables")
     url = "https://github.com/stac-utils/xpystac"
 
     def open_dataset(
         self,
         filename_or_obj: Any,
         drop_variables: Union[str, Iterable[str], None] = None,
+        stacking_library: Union[Literal["odc.stac", "stackstac"], None] = None,
         **kwargs,
     ):
-        return to_xarray(filename_or_obj, drop_variables=drop_variables, **kwargs)
+        """Given a PySTAC object return an xarray dataset
+
+        The behavior of this method depends on the type of PySTAC object:
+
+        * Asset: if the asset points to a kerchunk file or a zarr file,
+          reads the metadata in that file to construct the coordinates of the
+          dataset. If the asset points to a COG, read that.
+        * Item: stacks all the assets into a dataset with 1 more dimension than
+          any given asset.
+        * ItemCollection (output of pystac_client.search): stacks all the
+          assets in all the items into a dataset with 2 more dimensions than
+          any given asset.
+
+        Parameters
+        ----------
+        filename_or_obj : PySTAC object (Item, ItemCollection, Asset)
+            The object from which to read data.
+        stacking_library : "odc.stac", "stackstac", optional
+            When stacking multiple items, this argument determines which library
+            to use. Defaults to ``odc.stac`` if available and otherwise ``stackstac``.
+        """
+        return to_xarray(
+            filename_or_obj,
+            drop_variables=drop_variables,
+            stacking_library=stacking_library,
+            **kwargs,
+        )
 
     def guess_can_open(self, filename_or_obj: Any):
         return isinstance(