Follow-ups: variant provenance, mypy 0 + py.typed, KuboCAS knobs, httpx consolidation (+ upstream review-commit merge)

DATASET_CATALOG_USAGE.md

@@ -85,15 +85,15 @@ datasets = list_available_datasets(catalog)
 # }
 
 # Resolve a specific dataset to its CID
-cid = resolve_dataset_cid_from_stac(
+resolved = resolve_dataset_cid_from_stac(
     catalog=catalog,
     collection="ecmwf_era5",
     dataset="temperature_2m",
     variant="finalized",  # Optional, only needed if dataset has multiple variants
     organization="ecmwf",
 )
 
-print(f"Dataset CID: {cid}")
+print(f"Dataset CID: {resolved.cid} (variant: {resolved.variant})")
 ```
 
 ## STAC Catalog Structure
@@ -317,7 +317,7 @@ def resolve_dataset_cid_from_stac(
     collection: str,
     dataset: str,
     variant: Optional[str] = None
-) -> str
+) -> ResolvedDataset
 ```
 
 **Parameters:**
@@ -327,7 +327,7 @@ def resolve_dataset_cid_from_stac(
 - `variant`: Optional variant name
 
 **Returns:**
-- `str`: IPFS CID (without "ipfs://" prefix)
+- `ResolvedDataset`: IPFS CID (without "ipfs://" prefix) and selected variant
 
 **Raises:**
 - `ValueError`: If collection, dataset, or variant is not found
@@ -340,14 +340,14 @@ from dclimate_client_py import load_stac_catalog, resolve_dataset_cid_from_stac
 catalog = load_stac_catalog("https://ipfs-gateway.dclimate.net")
 
 # Resolve dataset to CID
-cid = resolve_dataset_cid_from_stac(
+resolved = resolve_dataset_cid_from_stac(
     catalog=catalog,
     collection="ifs",
     dataset="temperature",
     variant="single"
 )
 
-print(f"Dataset CID: {cid}")
+print(f"Dataset CID: {resolved.cid} (variant: {resolved.variant})")
 ```
 
 ### `get_root_catalog_cid()`
@@ -362,7 +362,7 @@ def get_root_catalog_cid() -> str
 - `str`: The IPFS CID of the latest root STAC catalog
 
 **Raises:**
-- `requests.HTTPError`: If the API request fails
+- `httpx.HTTPError`: If the API request fails
 - `KeyError`: If response doesn't contain expected 'cid' field
 
 **Example:**

dclimate_client_py/__init__.py

@@ -13,6 +13,7 @@
     TemporalExtent,
 )
 from .stac_server import (
+    ResolvedDataset,
     resolve_cid_from_stac_server,
     list_available_datasets_from_stac_server,
     STAC_SERVER_URL,
@@ -74,6 +75,7 @@ def __dir__() -> list[str]:
     "TemporalExtent",
     "load_stac_catalog",
     "list_available_datasets",
+    "ResolvedDataset",
     "resolve_cid_from_stac_server",
     "list_available_datasets_from_stac_server",
     "STAC_SERVER_URL",

dclimate_client_py/client.py

@@ -36,21 +36,21 @@ def load_s3(
 def geo_temporal_query(
     dataset_name: str,
     source: typing.Literal["s3"] = "s3",
-    bucket_name: str = None,
-    var_name: str = None,
+    bucket_name: typing.Optional[str] = None,
+    var_name: typing.Optional[str] = None,
     gateway_uri_stem: str | None = None,
     rpc_uri_stem: str | None = None,
-    forecast_reference_time: str = None,
-    point_kwargs: dict = None,
-    circle_kwargs: dict = None,
-    rectangle_kwargs: dict = None,
-    polygon_kwargs: dict = None,
-    multiple_points_kwargs: dict = None,
+    forecast_reference_time: typing.Optional[str] = None,
+    point_kwargs: typing.Optional[dict] = None,
+    circle_kwargs: typing.Optional[dict] = None,
+    rectangle_kwargs: typing.Optional[dict] = None,
+    polygon_kwargs: typing.Optional[dict] = None,
+    multiple_points_kwargs: typing.Optional[dict] = None,
     bounds=None,
-    bounds_options: dict = None,
-    spatial_agg_kwargs: dict = None,
-    temporal_agg_kwargs: dict = None,
-    rolling_agg_kwargs: dict = None,
+    bounds_options: typing.Optional[dict] = None,
+    spatial_agg_kwargs: typing.Optional[dict] = None,
+    temporal_agg_kwargs: typing.Optional[dict] = None,
+    rolling_agg_kwargs: typing.Optional[dict] = None,
     time_range: typing.Optional[typing.List[datetime.datetime]] = None,
     # as_of: typing.Optional[datetime.datetime] = None, # Removed as_of
     point_limit: int = DEFAULT_POINT_LIMIT,