Python API

xcube.core.store.new_data_store(data_store_id, extension_registry=None, **data_store_params)

Create a new data store instance for given data_store_id and data_store_params.

Parameters:

Name	Type	Description	Default
data_store_id	str	A data store identifier.	required
extension_registry	Optional[ExtensionRegistry]	Optional extension registry. If not given, the global extension registry will be used.	None
**data_store_params		Data store specific parameters.	{}

Returns:

Type	Description
Union[DataStore, MutableDataStore, PreloadDataStore]	A new data store instance

Source code in xcube/core/store/store.py

def new_data_store(
    data_store_id: str,
    extension_registry: Optional[ExtensionRegistry] = None,
    **data_store_params,
) -> Union["DataStore", "MutableDataStore", "PreloadDataStore"]:
    """Create a new data store instance for given
    *data_store_id* and *data_store_params*.

    Args:
        data_store_id: A data store identifier.
        extension_registry: Optional extension registry. If not given,
            the global extension registry will be used.
        **data_store_params: Data store specific parameters.

    Returns:
        A new data store instance
    """
    data_store_class = get_data_store_class(
        data_store_id, extension_registry=extension_registry
    )
    data_store_params_schema = data_store_class.get_data_store_params_schema()
    assert_valid_params(
        data_store_params, name="data_store_params", schema=data_store_params_schema
    )
    # noinspection PyArgumentList
    return data_store_class(**data_store_params)

xcube.core.store.list_data_store_ids(detail=False)

List the identifiers of installed xcube data stores.

Parameters:

Name	Type	Description	Default
detail	bool	Whether to return a dictionary with data store metadata or just a list of data store identifiers.	False

Returns:

Type	Description
Union[list[str], dict[str, Any]]	If detail is True a dictionary that maps data store identifiers
Union[list[str], dict[str, Any]]	to data store metadata. Otherwise, a list of data store identifiers.

Source code in xcube/core/store/store.py

def list_data_store_ids(detail: bool = False) -> Union[list[str], dict[str, Any]]:
    """List the identifiers of installed xcube data stores.

    Args:
        detail: Whether to return a dictionary with data store metadata or just
            a list of data store identifiers.

    Returns:
        If *detail* is ``True`` a dictionary that maps data store identifiers
        to data store metadata. Otherwise, a list of data store identifiers.
    """
    if detail:
        return {e.name: e.metadata for e in find_data_store_extensions()}
    else:
        return [e.name for e in find_data_store_extensions()]

xcube.core.store.get_data_store_params_schema(data_store_id, extension_registry=None)

Get the JSON schema for instantiating a new data store identified by data_store_id.

Parameters:

Name	Type	Description	Default
data_store_id	str	A data store identifier.	required
extension_registry	Optional[ExtensionRegistry]	Optional extension registry. If not given, the global extension registry will be used.	None

Returns:

Type	Description
JsonObjectSchema	The JSON schema for the data store's parameters.

Source code in xcube/core/store/store.py

def get_data_store_params_schema(
    data_store_id: str, extension_registry: Optional[ExtensionRegistry] = None
) -> JsonObjectSchema:
    """Get the JSON schema for instantiating a new data store
    identified by *data_store_id*.

    Args:
        data_store_id: A data store identifier.
        extension_registry: Optional extension registry. If not given,
            the global extension registry will be used.

    Returns:
        The JSON schema for the data store's parameters.
    """
    data_store_class = get_data_store_class(
        data_store_id, extension_registry=extension_registry
    )
    return data_store_class.get_data_store_params_schema()

xcube_eopf.store.EOPFZarrDataStore

Bases: DataStore

EOPF-Zarr implementation of the data store.

Source code in xcube_eopf/store.py

class EOPFZarrDataStore(DataStore):
    """EOPF-Zarr implementation of the data store."""

    def __init__(self):
        register_product_handlers()

    @classmethod
    def get_data_store_params_schema(cls) -> JsonObjectSchema:
        return JsonObjectSchema(
            description="Describes the parameters of the xcube data store 'eopf-zarr'.",
            properties=dict(),
            required=[],
            additional_properties=False,
        )

    @classmethod
    def get_data_types(cls) -> tuple[str, ...]:
        return (DATASET_TYPE.alias,)

    def get_data_types_for_data(self, data_id: str) -> tuple[str, ...]:
        self._assert_has_data(data_id)
        return (DATASET_TYPE.alias,)

    def get_data_ids(
        self,
        data_type: DataTypeLike = None,
        include_attrs: Container[str] | bool = False,
    ) -> Iterator[str | tuple[str, dict[str, Any]], None]:
        self._assert_valid_data_type(data_type)
        for data_id in SUPPORTED_STAC_COLLECTIONS:
            if not include_attrs:
                yield data_id
            else:
                yield data_id, dict()

    def has_data(self, data_id: str, data_type: DataTypeLike = None) -> bool:
        self._assert_valid_data_type(data_type)
        if data_id in SUPPORTED_STAC_COLLECTIONS:
            return True
        return False

    def get_data_opener_ids(
        self, data_id: str = None, data_type: DataTypeLike = None
    ) -> tuple[str, ...]:
        self._assert_valid_data_type(data_type)
        if data_id is not None:
            self._assert_has_data(data_id)
        return (EOPF_ZARR_OPENR_ID,)

    def get_open_data_params_schema(
        self, data_id: str = None, opener_id: str = None
    ) -> JsonObjectSchema:
        self._assert_valid_opener_id(opener_id)
        if data_id is not None:
            self._assert_has_data(data_id)
            product_handler = ProductHandler.guess(data_id)
            return product_handler.get_open_data_params_schema()
        else:
            return JsonObjectSchema(
                title="Opening parameters for all supported Sentinel products.",
                properties={
                    key: ph.get_open_data_params_schema()
                    for (key, ph) in zip(
                        ProductHandler.registry.keys(), ProductHandler.registry.values()
                    )
                },
            )

    def open_data(
        self,
        data_id: str,
        opener_id: str = None,
        data_type: DataTypeLike = None,
        **open_params,
    ) -> xr.Dataset | MultiLevelDataset:
        self._assert_has_data(data_id)
        self._assert_valid_data_type(data_type)
        self._assert_valid_opener_id(opener_id)
        product_handler = ProductHandler.guess(data_id)
        return product_handler.open_data(**open_params)

    def describe_data(
        self, data_id: str, data_type: DataTypeLike = None
    ) -> DatasetDescriptor:
        self._assert_has_data(data_id)
        self._assert_valid_data_type(data_type)
        raise NotImplementedError("`describe_data` is not implemented, yet.")

    def search_data(
        self, data_type: DataTypeLike = None, **search_params
    ) -> Iterator[DatasetDescriptor]:
        raise NotImplementedError(
            "Search is not supported. Only Sentinel-2 L1C and L2A products "
            "are currently handled."
        )

    def get_search_params_schema(
        self, data_type: DataTypeLike = None
    ) -> JsonObjectSchema:
        self._assert_valid_data_type(data_type)
        return JsonObjectSchema(
            properties=dict(),
            required=[],
            additional_properties=True,
        )

    # Auxiliary internal functions
    def _assert_has_data(self, data_id: str) -> None:
        if not self.has_data(data_id):
            raise DataStoreError(f"Data resource {data_id!r} is not available.")

    @staticmethod
    def _assert_valid_opener_id(opener_id: str) -> None:
        if opener_id is not None and opener_id is not EOPF_ZARR_OPENR_ID:
            raise DataStoreError(
                f"Data opener identifier must be {EOPF_ZARR_OPENR_ID!r}, "
                f"but got {opener_id!r}."
            )

    def _assert_valid_data_type(self, data_type: DataTypeLike) -> None:
        if not self._is_valid_data_type(data_type):
            raise DataStoreError(
                f"Data type must be {DATASET_TYPE.alias!r} "
                f"or None, but got {data_type!r}."
            )

    @staticmethod
    def _is_valid_data_type(data_type: DataTypeLike) -> bool:
        return data_type is None or DATASET_TYPE.is_super_type_of(data_type)

xcube.core.store.DataStore

Bases: DataOpener, DataSearcher, DataPreloader, ABC

A data store represents a collection of data resources that can be enumerated, queried, and opened in order to obtain in-memory representations of the data. The same data resource may be made available using different data types. Therefore, many methods allow specifying a data_type parameter.

A store implementation may use any existing openers/writers, or define its own, or not use any openers/writers at all.

Store implementers should follow the conventions outlined in https://xcube.readthedocs.io/en/latest/storeconv.html .

The :class:DataStore is an abstract base class that both read-only and mutable data stores must implement.

Source code in xcube/core/store/store.py

class DataStore(DataOpener, DataSearcher, DataPreloader, ABC):
    """A data store represents a collection of data resources that
    can be enumerated, queried, and opened in order to obtain
    in-memory representations of the data. The same data resource may be
    made available using different data types. Therefore, many methods
    allow specifying a *data_type* parameter.

    A store implementation may use any existing openers/writers,
    or define its own, or not use any openers/writers at all.

    Store implementers should follow the conventions outlined in
    https://xcube.readthedocs.io/en/latest/storeconv.html .

    The :class:`DataStore` is an abstract base class that both read-only and
    mutable data stores must implement.
    """

    @classmethod
    def get_data_store_params_schema(cls) -> JsonObjectSchema:
        """Get descriptions of parameters that must or can be used to
        instantiate a new DataStore object.
        Parameters are named and described by the properties of the
        returned JSON object schema.
        The default implementation returns JSON object schema that
        can have any properties.
        """
        return JsonObjectSchema()

    @classmethod
    @abstractmethod
    def get_data_types(cls) -> tuple[str, ...]:
        """Get alias names for all data types supported by this store.
        The first entry in the tuple represents this store's
        default data type.

        Returns:
            The tuple of supported data types.
        """

    @abstractmethod
    def get_data_types_for_data(self, data_id: str) -> tuple[str, ...]:
        """Get alias names for of data types that are supported
        by this store for the given *data_id*.

        Args:
            data_id: An identifier of data that is provided by this
                store

        Returns:
            A tuple of data types that apply to the given *data_id*.

        Raises:
            DataStoreError: If an error occurs.
        """

    @abstractmethod
    def get_data_ids(
        self,
        data_type: DataTypeLike = None,
        include_attrs: Container[str] | bool = False,
    ) -> Union[Iterator[str], Iterator[tuple[str, dict[str, Any]]]]:
        """Get an iterator over the data resource identifiers for the
        given type *data_type*. If *data_type* is omitted, all data
        resource identifiers are returned.

        If a store implementation supports only a single data type,
        it should verify that *data_type* is either None or
        compatible with the supported data type.

        If *include_attrs* is provided, it must be a sequence of names
        of metadata attributes. The store will then return extra metadata
        for each returned data resource identifier according to the
        names of the metadata attributes as tuples (*data_id*, *attrs*).

        Hence, the type of the returned iterator items depends on the
        value of *include_attrs*:

        - If *include_attrs* is False (the default), the method returns
          an iterator of dataset identifiers *data_id* of type `str`.
        - If *include_attrs* is True, the method returns an iterator of tuples
          (*data_id*, *attrs*) of type `Tuple[str, Dict]`, where *attrs*
          is a dictionary filled with all the attributes available respectively
          for each *data_id*.
        - If *include_attrs* is a sequence of attribute names, even an
          empty one, the method returns an iterator of tuples
          (*data_id*, *attrs*) of type `Tuple[str, Dict]`, where *attrs*
          is a dictionary filled according to the names in *include_attrs*.
          If a store cannot provide a given attribute, it should simply
          ignore it. This may even yield to an empty dictionary for a given
          *data_id*.

        The individual attributes do not have to exist in the dataset's
        metadata, they may also be generated on-the-fly.
        An example for a generic attribute name is "title".
        A store should try to resolve ``include_attrs=["title"]``
        by returning items such as
        ``("ESACCI-L4_GHRSST-SSTdepth-OSTIA-GLOB_CDR2.1-v02.0-fv01.0.zarr",
        {"title": "Level-4 GHRSST Analysed Sea Surface Temperature"})``.

        Args:
            data_type: If given, only data identifiers that are
                available as this type are returned. If this is omitted,
                all available data identifiers are returned.
            include_attrs: A sequence of names of attributes to be
                returned for each dataset identifier. If given, the
                store will attempt to provide the set of requested
                dataset attributes in addition to the data ids. (added
                in xcube 0.8.0)

        Returns:
            An iterator over the identifiers and titles of data
            resources provided by this data store.

        Raises:
            DataStoreError: If an error occurs.
        """

    def list_data_ids(
        self,
        data_type: DataTypeLike = None,
        include_attrs: Container[str] | bool = False,
    ) -> Union[list[str], list[tuple[str, dict[str, Any]]]]:
        """Convenience version of `get_data_ids()` that returns a list rather
        than an iterator.

        Args:
            data_type: If given, only data identifiers that are
                available as this type are returned. If this is omitted,
                all available data identifiers are returned.
            include_attrs: A boolean or sequence of names of attributes to be
                returned for each dataset identifier. If a sequence of names of
                attributes given, the store will attempt to provide the set of requested
                dataset attributes in addition to the data ids. (added
                in xcube 0.8.0).
                If True, all the attributes for each dataset identifier will be
                returned.
                If False (default), only the data_ids are returned.

        Returns:
            A list comprising the identifiers and titles of data
            resources provided by this data store.

        Raises:
            DataStoreError: If an error occurs.
        """
        return list(self.get_data_ids(data_type=data_type, include_attrs=include_attrs))

    @abstractmethod
    def has_data(self, data_id: str, data_type: DataTypeLike = None) -> bool:
        """Check if the data resource given by *data_id* is
        available in this store.

        Args:
            data_id: A data identifier
            data_type: An optional data type. If given, it will also be
                checked whether the data is available as the specified
                type. May be given as type alias name, as a type, or as
                a :class:`DataType` instance.

        Returns:
            True, if the data resource is available in this store, False
            otherwise.
        """

    @abstractmethod
    def describe_data(
        self, data_id: str, data_type: DataTypeLike = None
    ) -> DataDescriptor:
        """Get the descriptor for the data resource given by *data_id*.

        Raises a :class:`DataStoreError` if *data_id* does not
        exist in this store or the data is not available as the
        specified *data_type*.

        Args:
            data_id: An identifier of data provided by this store
            data_type: If given, the descriptor of the data will
                describe the data as specified by the data type. May be
                given as type alias name, as a type, or as a
                :class:`DataType` instance.

        Returns: a data-type specific data descriptor

        Raises:
            DataStoreError: If an error occurs.
        """

    @abstractmethod
    def get_data_opener_ids(
        self, data_id: str = None, data_type: DataTypeLike = None
    ) -> tuple[str, ...]:
        """Get identifiers of data openers that can be used to open data
        resources from this store.

        If *data_id* is given, data accessors are restricted to the ones
        that can open the identified data resource.
        Raises if *data_id* does not exist in this store.

        If *data_type* is given, only openers that are compatible with
        this data type are returned.

        If a store implementation supports only a single data type,
        it should verify that *data_type* is either None or equal to
        that single data type.

        Args:
            data_id: An optional data resource identifier that is known
                to exist in this data store.
            data_type: An optional data type that is known to be
                supported by this data store. May be given as type alias
                name, as a type, or as a :class:`DataType` instance.

        Returns:
            A tuple of identifiers of data openers that can be used to
            open data resources.

        Raises:
            DataStoreError: If an error occurs.
        """

    @abstractmethod
    def get_open_data_params_schema(
        self, data_id: str = None, opener_id: str = None
    ) -> JsonObjectSchema:
        """Get the schema for the parameters passed as *open_params* to
        :meth:`open_data`.

        If *data_id* is given, the returned schema will be tailored
        to the constraints implied by the identified data resource.
        Some openers might not support this, therefore *data_id* is optional,
        and if it is omitted, the returned schema will be less restrictive.
        If given, the method raises if *data_id* does not exist in this store.

        If *opener_id* is given, the returned schema will be tailored to
        the constraints implied by the identified opener. Some openers
        might not support this, therefore *opener_id* is optional, and if
        it is omitted, the returned schema will be less restrictive.

        For maximum compatibility of stores, it is strongly encouraged to
        apply the following conventions on parameter names, types,
        and their interpretation.

        Let P be the value of an optional, data constraining open parameter,
        then it should be interpreted as follows:

          * _if P is None_ means, parameter not given,
            hence no constraint applies, hence no additional restrictions
            on requested data.
          * _if not P_ means, we exclude data that would be
            included by default.
          * _else_, the given constraint applies.

        Given here are names, types, and descriptions of common,
        constraining open parameters for gridded datasets.
        Note, whether any of these is optional or mandatory depends
        on the individual data store. A store may also
        define other open parameters or support only a subset of the
        following. Note all parameters may be optional,
        the Python-types given here refer to _given_, non-Null parameters:

          * ``variable_names: List[str]``: Included data variables.
            Available coordinate variables will be auto-included for
            any dimension of the data variables.
          * ``bbox: Tuple[float, float, float, float]``: Spatial coverage
            as xmin, ymin, xmax, ymax.
          * ``crs: str``: Spatial CRS, e.g. "EPSG:4326" or OGC CRS URI.
          * ``spatial_res: float``: Spatial resolution in
            coordinates of the spatial CRS.
          * ``time_range: Tuple[Optional[str], Optional[str]]``:
            Time range interval in UTC date/time units using ISO format.
            Start or end time may be missing which means everything until
            available start or end time.
          * ``time_period: str`: Pandas-compatible period/frequency
            string, e.g. "8D", "2W".

        E.g. applied to an optional `variable_names` parameter, this means

          * `variable_names is None` - include all data variables
          * `variable_names == []` - do not include data variables
            (schema only)
          * `variable_names == ["<var_1>", "<var_2>", ...]` only
            include data variables named "<var_1>", "<var_2>", ...

        Args:
            data_id: An optional data identifier that is known to exist
                in this data store.
            opener_id: An optional data opener identifier.

        Returns:
            The schema for the parameters in *open_params*.

        Raises:
            DataStoreError: If an error occurs.
        """

    @abstractmethod
    def open_data(
        self,
        data_id: str,
        opener_id: str = None,
        **open_params,
    ) -> Any:
        """Open the data given by the data resource identifier *data_id*
        using the supplied *open_params*.

        If *opener_id* is given, the identified data opener will be used
        to open the data resource and *open_params* must comply with the
        schema of the opener's parameters. Note that some store
        implementations may not support using different openers or just
        support a single one.

        Implementations are advised to support an additional optional keyword
        argument `data_type: DataTypeLike = None`.
        If *data_type* is provided, the return value will be in the specified
        data type. If no data opener exists for the given *data_type* and format
        extracted from the *data_id*, the default data type alias 'dataset' will
        be used. Note that *opener_id* includes the *data_type* at its first
        position and will override the *date_type* argument.

        Raises if *data_id* does not exist in this store.

        Args:
            data_id: The data identifier that is known to exist in this
                data store.
            opener_id: An optional data opener identifier.
            **open_params: Opener-specific parameters. Note that
                `data_type: DataTypeLike = None` may be assigned here.

        Returns:
            An in-memory representation of the data resources identified
            by *data_id* and *open_params*.

        Raises:
            DataStoreError: If an error occurs.
        """

    def get_preload_data_params_schema(self) -> JsonObjectSchema:
        """Get the JSON schema that describes the keyword
        arguments that can be passed to ``preload_data()``.

        Returns:
            A ``JsonObjectSchema`` object whose properties describe
            the parameters of ``preload_data()``.
        """
        return JsonObjectSchema(additional_properties=False)

    # noinspection PyMethodMayBeStatic
    def preload_data(
        self,
        *data_ids: str,
        **preload_params: Any,
    ) -> "PreloadedDataStore":
        """Preload the given data items for faster access.

        Warning: This is an experimental and potentially unstable API
        introduced in xcube 1.8.

        The method may be blocking or non-blocking.
        Implementations may offer the following keyword arguments
        in *preload_params*:

        - ``blocking``: whether the preload process is blocking.
          Should be `True` by default if supported.
        - ``monitor``: a callback function that serves as a progress monitor.
          It receives the preload handle and the recent partial state update.

        Args:
            data_ids: Data identifiers to be preloaded.
            preload_params: data store specific preload parameters.
              See method ``get_preload_data_params_schema()`` for information
              on the possible options.

        Returns:
            A mutable data store containing the preload handle.
            The default implementation contains an empty preload handle.
        """
        self.preload_handle = NullPreloadHandle()
        return self

get_data_ids(data_type=None, include_attrs=False) abstractmethod

Get an iterator over the data resource identifiers for the given type data_type. If data_type is omitted, all data resource identifiers are returned.

If a store implementation supports only a single data type, it should verify that data_type is either None or compatible with the supported data type.

If include_attrs is provided, it must be a sequence of names of metadata attributes. The store will then return extra metadata for each returned data resource identifier according to the names of the metadata attributes as tuples (data_id, attrs).

Hence, the type of the returned iterator items depends on the value of include_attrs:

• If include_attrs is False (the default), the method returns an iterator of dataset identifiers data_id of type str.
• If include_attrs is True, the method returns an iterator of tuples (data_id, attrs) of type Tuple[str, Dict], where attrs is a dictionary filled with all the attributes available respectively for each data_id.
• If include_attrs is a sequence of attribute names, even an empty one, the method returns an iterator of tuples (data_id, attrs) of type Tuple[str, Dict], where attrs is a dictionary filled according to the names in include_attrs. If a store cannot provide a given attribute, it should simply ignore it. This may even yield to an empty dictionary for a given data_id.

The individual attributes do not have to exist in the dataset's metadata, they may also be generated on-the-fly. An example for a generic attribute name is "title". A store should try to resolve include_attrs=["title"] by returning items such as ("ESACCI-L4_GHRSST-SSTdepth-OSTIA-GLOB_CDR2.1-v02.0-fv01.0.zarr", {"title": "Level-4 GHRSST Analysed Sea Surface Temperature"}).

Parameters:

Name	Type	Description	Default
data_type	DataTypeLike	If given, only data identifiers that are available as this type are returned. If this is omitted, all available data identifiers are returned.	None
include_attrs	Container[str] | bool	A sequence of names of attributes to be returned for each dataset identifier. If given, the store will attempt to provide the set of requested dataset attributes in addition to the data ids. (added in xcube 0.8.0)	False

Returns:

Type	Description
Union[Iterator[str], Iterator[tuple[str, dict[str, Any]]]]	An iterator over the identifiers and titles of data
Union[Iterator[str], Iterator[tuple[str, dict[str, Any]]]]	resources provided by this data store.

Raises:

Type	Description
DataStoreError	If an error occurs.

Source code in xcube/core/store/store.py

@abstractmethod
def get_data_ids(
    self,
    data_type: DataTypeLike = None,
    include_attrs: Container[str] | bool = False,
) -> Union[Iterator[str], Iterator[tuple[str, dict[str, Any]]]]:
    """Get an iterator over the data resource identifiers for the
    given type *data_type*. If *data_type* is omitted, all data
    resource identifiers are returned.

    If a store implementation supports only a single data type,
    it should verify that *data_type* is either None or
    compatible with the supported data type.

    If *include_attrs* is provided, it must be a sequence of names
    of metadata attributes. The store will then return extra metadata
    for each returned data resource identifier according to the
    names of the metadata attributes as tuples (*data_id*, *attrs*).

    Hence, the type of the returned iterator items depends on the
    value of *include_attrs*:

    - If *include_attrs* is False (the default), the method returns
      an iterator of dataset identifiers *data_id* of type `str`.
    - If *include_attrs* is True, the method returns an iterator of tuples
      (*data_id*, *attrs*) of type `Tuple[str, Dict]`, where *attrs*
      is a dictionary filled with all the attributes available respectively
      for each *data_id*.
    - If *include_attrs* is a sequence of attribute names, even an
      empty one, the method returns an iterator of tuples
      (*data_id*, *attrs*) of type `Tuple[str, Dict]`, where *attrs*
      is a dictionary filled according to the names in *include_attrs*.
      If a store cannot provide a given attribute, it should simply
      ignore it. This may even yield to an empty dictionary for a given
      *data_id*.

    The individual attributes do not have to exist in the dataset's
    metadata, they may also be generated on-the-fly.
    An example for a generic attribute name is "title".
    A store should try to resolve ``include_attrs=["title"]``
    by returning items such as
    ``("ESACCI-L4_GHRSST-SSTdepth-OSTIA-GLOB_CDR2.1-v02.0-fv01.0.zarr",
    {"title": "Level-4 GHRSST Analysed Sea Surface Temperature"})``.

    Args:
        data_type: If given, only data identifiers that are
            available as this type are returned. If this is omitted,
            all available data identifiers are returned.
        include_attrs: A sequence of names of attributes to be
            returned for each dataset identifier. If given, the
            store will attempt to provide the set of requested
            dataset attributes in addition to the data ids. (added
            in xcube 0.8.0)

    Returns:
        An iterator over the identifiers and titles of data
        resources provided by this data store.

    Raises:
        DataStoreError: If an error occurs.
    """

list_data_ids(data_type=None, include_attrs=False)

Convenience version of get_data_ids() that returns a list rather than an iterator.

Parameters:

Name	Type	Description	Default
data_type	DataTypeLike	If given, only data identifiers that are available as this type are returned. If this is omitted, all available data identifiers are returned.	None
include_attrs	Container[str] | bool	A boolean or sequence of names of attributes to be returned for each dataset identifier. If a sequence of names of attributes given, the store will attempt to provide the set of requested dataset attributes in addition to the data ids. (added in xcube 0.8.0). If True, all the attributes for each dataset identifier will be returned. If False (default), only the data_ids are returned.	False

Returns:

Type	Description
Union[list[str], list[tuple[str, dict[str, Any]]]]	A list comprising the identifiers and titles of data
Union[list[str], list[tuple[str, dict[str, Any]]]]	resources provided by this data store.

Raises:

Type	Description
DataStoreError	If an error occurs.

Source code in xcube/core/store/store.py

def list_data_ids(
    self,
    data_type: DataTypeLike = None,
    include_attrs: Container[str] | bool = False,
) -> Union[list[str], list[tuple[str, dict[str, Any]]]]:
    """Convenience version of `get_data_ids()` that returns a list rather
    than an iterator.

    Args:
        data_type: If given, only data identifiers that are
            available as this type are returned. If this is omitted,
            all available data identifiers are returned.
        include_attrs: A boolean or sequence of names of attributes to be
            returned for each dataset identifier. If a sequence of names of
            attributes given, the store will attempt to provide the set of requested
            dataset attributes in addition to the data ids. (added
            in xcube 0.8.0).
            If True, all the attributes for each dataset identifier will be
            returned.
            If False (default), only the data_ids are returned.

    Returns:
        A list comprising the identifiers and titles of data
        resources provided by this data store.

    Raises:
        DataStoreError: If an error occurs.
    """
    return list(self.get_data_ids(data_type=data_type, include_attrs=include_attrs))

has_data(data_id, data_type=None) abstractmethod

Check if the data resource given by data_id is available in this store.

Parameters:

Name	Type	Description	Default
data_id	str	A data identifier	required
data_type	DataTypeLike	An optional data type. If given, it will also be checked whether the data is available as the specified type. May be given as type alias name, as a type, or as a :class:DataType instance.	None

Returns:

Type	Description
bool	True, if the data resource is available in this store, False
bool	otherwise.

Source code in xcube/core/store/store.py

@abstractmethod
def has_data(self, data_id: str, data_type: DataTypeLike = None) -> bool:
    """Check if the data resource given by *data_id* is
    available in this store.

    Args:
        data_id: A data identifier
        data_type: An optional data type. If given, it will also be
            checked whether the data is available as the specified
            type. May be given as type alias name, as a type, or as
            a :class:`DataType` instance.

    Returns:
        True, if the data resource is available in this store, False
        otherwise.
    """

get_open_data_params_schema(data_id=None, opener_id=None) abstractmethod

Get the schema for the parameters passed as open_params to :meth:open_data.

If data_id is given, the returned schema will be tailored to the constraints implied by the identified data resource. Some openers might not support this, therefore data_id is optional, and if it is omitted, the returned schema will be less restrictive. If given, the method raises if data_id does not exist in this store.

If opener_id is given, the returned schema will be tailored to the constraints implied by the identified opener. Some openers might not support this, therefore opener_id is optional, and if it is omitted, the returned schema will be less restrictive.

For maximum compatibility of stores, it is strongly encouraged to apply the following conventions on parameter names, types, and their interpretation.

Let P be the value of an optional, data constraining open parameter, then it should be interpreted as follows:

• if P is None means, parameter not given, hence no constraint applies, hence no additional restrictions on requested data.
• if not P means, we exclude data that would be included by default.
• else, the given constraint applies.

Given here are names, types, and descriptions of common, constraining open parameters for gridded datasets. Note, whether any of these is optional or mandatory depends on the individual data store. A store may also define other open parameters or support only a subset of the following. Note all parameters may be optional, the Python-types given here refer to given, non-Null parameters:

• variable_names: List[str]: Included data variables. Available coordinate variables will be auto-included for any dimension of the data variables.
• bbox: Tuple[float, float, float, float]: Spatial coverage as xmin, ymin, xmax, ymax.
• crs: str: Spatial CRS, e.g. "EPSG:4326" or OGC CRS URI.
• spatial_res: float: Spatial resolution in coordinates of the spatial CRS.
• time_range: Tuple[Optional[str], Optional[str]]: Time range interval in UTC date/time units using ISO format. Start or end time may be missing which means everything until available start or end time.
• `time_period: str: Pandas-compatible period/frequency string, e.g. "8D", "2W".

E.g. applied to an optional variable_names parameter, this means

• variable_names is None - include all data variables
• variable_names == [] - do not include data variables (schema only)
• variable_names == ["<var_1>", "<var_2>", ...] only include data variables named "", "", ...

Parameters:

Name	Type	Description	Default
data_id	str	An optional data identifier that is known to exist in this data store.	None
opener_id	str	An optional data opener identifier.	None

Returns:

Type	Description
JsonObjectSchema	The schema for the parameters in open_params.

Raises:

Type	Description
DataStoreError	If an error occurs.

Source code in xcube/core/store/store.py

@abstractmethod
def get_open_data_params_schema(
    self, data_id: str = None, opener_id: str = None
) -> JsonObjectSchema:
    """Get the schema for the parameters passed as *open_params* to
    :meth:`open_data`.

    If *data_id* is given, the returned schema will be tailored
    to the constraints implied by the identified data resource.
    Some openers might not support this, therefore *data_id* is optional,
    and if it is omitted, the returned schema will be less restrictive.
    If given, the method raises if *data_id* does not exist in this store.

    If *opener_id* is given, the returned schema will be tailored to
    the constraints implied by the identified opener. Some openers
    might not support this, therefore *opener_id* is optional, and if
    it is omitted, the returned schema will be less restrictive.

    For maximum compatibility of stores, it is strongly encouraged to
    apply the following conventions on parameter names, types,
    and their interpretation.

    Let P be the value of an optional, data constraining open parameter,
    then it should be interpreted as follows:

      * _if P is None_ means, parameter not given,
        hence no constraint applies, hence no additional restrictions
        on requested data.
      * _if not P_ means, we exclude data that would be
        included by default.
      * _else_, the given constraint applies.

    Given here are names, types, and descriptions of common,
    constraining open parameters for gridded datasets.
    Note, whether any of these is optional or mandatory depends
    on the individual data store. A store may also
    define other open parameters or support only a subset of the
    following. Note all parameters may be optional,
    the Python-types given here refer to _given_, non-Null parameters:

      * ``variable_names: List[str]``: Included data variables.
        Available coordinate variables will be auto-included for
        any dimension of the data variables.
      * ``bbox: Tuple[float, float, float, float]``: Spatial coverage
        as xmin, ymin, xmax, ymax.
      * ``crs: str``: Spatial CRS, e.g. "EPSG:4326" or OGC CRS URI.
      * ``spatial_res: float``: Spatial resolution in
        coordinates of the spatial CRS.
      * ``time_range: Tuple[Optional[str], Optional[str]]``:
        Time range interval in UTC date/time units using ISO format.
        Start or end time may be missing which means everything until
        available start or end time.
      * ``time_period: str`: Pandas-compatible period/frequency
        string, e.g. "8D", "2W".

    E.g. applied to an optional `variable_names` parameter, this means

      * `variable_names is None` - include all data variables
      * `variable_names == []` - do not include data variables
        (schema only)
      * `variable_names == ["<var_1>", "<var_2>", ...]` only
        include data variables named "<var_1>", "<var_2>", ...

    Args:
        data_id: An optional data identifier that is known to exist
            in this data store.
        opener_id: An optional data opener identifier.

    Returns:
        The schema for the parameters in *open_params*.

    Raises:
        DataStoreError: If an error occurs.
    """

open_data(data_id, opener_id=None, **open_params) abstractmethod

Open the data given by the data resource identifier data_id using the supplied open_params.

If opener_id is given, the identified data opener will be used to open the data resource and open_params must comply with the schema of the opener's parameters. Note that some store implementations may not support using different openers or just support a single one.

Implementations are advised to support an additional optional keyword argument data_type: DataTypeLike = None. If data_type is provided, the return value will be in the specified data type. If no data opener exists for the given data_type and format extracted from the data_id, the default data type alias 'dataset' will be used. Note that opener_id includes the data_type at its first position and will override the date_type argument.

Raises if data_id does not exist in this store.

Parameters:

Name	Type	Description	Default
data_id	str	The data identifier that is known to exist in this data store.	required
opener_id	str	An optional data opener identifier.	None
**open_params		Opener-specific parameters. Note that data_type: DataTypeLike = None may be assigned here.	{}

Returns:

Type	Description
Any	An in-memory representation of the data resources identified
Any	by data_id and open_params.

Raises:

Type	Description
DataStoreError	If an error occurs.

Source code in xcube/core/store/store.py

@abstractmethod
def open_data(
    self,
    data_id: str,
    opener_id: str = None,
    **open_params,
) -> Any:
    """Open the data given by the data resource identifier *data_id*
    using the supplied *open_params*.

    If *opener_id* is given, the identified data opener will be used
    to open the data resource and *open_params* must comply with the
    schema of the opener's parameters. Note that some store
    implementations may not support using different openers or just
    support a single one.

    Implementations are advised to support an additional optional keyword
    argument `data_type: DataTypeLike = None`.
    If *data_type* is provided, the return value will be in the specified
    data type. If no data opener exists for the given *data_type* and format
    extracted from the *data_id*, the default data type alias 'dataset' will
    be used. Note that *opener_id* includes the *data_type* at its first
    position and will override the *date_type* argument.

    Raises if *data_id* does not exist in this store.

    Args:
        data_id: The data identifier that is known to exist in this
            data store.
        opener_id: An optional data opener identifier.
        **open_params: Opener-specific parameters. Note that
            `data_type: DataTypeLike = None` may be assigned here.

    Returns:
        An in-memory representation of the data resources identified
        by *data_id* and *open_params*.

    Raises:
        DataStoreError: If an error occurs.
    """