Client

class datareservoirio.Client(auth, cache=True, cache_opt={'cache_root': None, 'format': 'parquet', 'max_size': 1024})

DataReservoir.io client for user-friendly interaction.

Parameters

  • auth (cls) – An authenticated session that is used in all API calls. Must supply a valid bearer token to all API calls.

  • cache (bool) – Enable caching (default).

  • cache_opt (dict, optional) – Configuration object for controlling the series cache. ‘format’: ‘parquet’ or ‘csv’. Default is ‘parquet’. ‘max_size’: max size of cache in megabytes. Default is 1024 MB. ‘cache_root’: cache storage location. See documentation for platform specific defaults.

CACHE_DEFAULT = {'cache_root': None, 'format': 'parquet', 'max_size': 1024}
append(series, series_id, wait_on_verification=True)

Append data to an already existing series.

Parameters

  • series (pandas.Series) – Series with index (as DatetimeIndex-like or integer array).

  • series_id (string) – The identifier of the existing series.

  • wait_on_verification (bool (optional)) – All series are subjected to a server-side data validation before they are made available for consumption; failing validation will result in the series being ignored. If True, the method will wait for the data validation process to be completed and return the outcome, which may be time consuming. If False, the method will NOT wait for the outcome and the data will be available when/if the validation is successful. The latter is significantly faster, but is recommended when the data is “validated” in advance. Default is True.

Returns

The response from DataReservoir.io.

Return type

dict

create(series=None, wait_on_verification=True)

Create a new series in DataReservoir.io from a pandas.Series. If no data is provided, an empty series is created.

Parameters

  • series (pandas.Series, optional) – Series with index (as DatetimeIndex-like or integer array). Default is None.

  • wait_on_verification (bool (optional)) – All series are subjected to a server-side data validation before they are made available for consumption; failing validation will result in the series being ignored. If True, the method will wait for the data validation process to be completed and return the outcome, which may be time consuming. If False, the method will NOT wait for the outcome and the data will be available when/if the validation is successful. The latter is significantly faster, but is recommended when the data is “validated” in advance. Default is True.

Returns

The response from DataReservoir.io containing the unique id of the newly created series.

Return type

dict

delete(series_id)

Delete a series from DataReservoir.io.

Parameters

series_id (string) – The id of the series to delete.

get(series_id, start=None, end=None, convert_date=True, raise_empty=False)

Retrieve a series from DataReservoir.io.

Parameters

  • series_id (str) – Identifier of the series to download

  • start (optional) – start time (inclusive) of the series given as anything pandas.to_datetime is able to parse.

  • end (optional) – stop time (inclusive) of the series given as anything pandas.to_datetime is able to parse.

  • convert_date (bool) – If True (default), the index is converted to DatetimeIndex. If False, index is returned as ascending integers.

  • raise_empty (bool) – If True, raise ValueError if no data exist in the provided interval. Otherwise, return an empty pandas.Series (default).

Returns

Series data

Return type

pandas.Series

info(series_id)

Retrieve basic information about a series.

Returns

Available information about the series. None if series not found.

Return type

dict

metadata_browse(namespace=None, key=None)

Browse available metadata namespace/key/names combinations.

Parameters

  • namespace (string) – The namespace to search in

  • key (string) – the namespace key to narrow search

Returns

The namespaces or keys found. Or if both namespace and key is present, the specific metadata for the namespace/key combination.

Return type

list or dict

metadata_delete(metadata_id)

Delete an existing metadata entry.

Parameters

metadata_id (str) – id of metadata

metadata_get(metadata_id=None, namespace=None, key=None)

Retrieve a metedata entry.

Parameters

  • metadata_id (str) – The identifier of existing metadata

  • namespace (str) – Metadata namespace. Ignored if metadata_id is set.

  • key (str) – Metadata key. Ignored if metadata_id is set.

Returns

Metadata entry.

Return type

dict

Find metadata entries given namespace/key combination.

namespacestring

The namespace to search in

keystring

The key to narrow search

conjuctivebool
Returns

Metadata entries that matches the search.

Return type

dict

metadata_set(namespace, key, **namevalues)

Create or update a metadata entry. If the namespace/key combination does not already exist, a new entry will be created. If the combination already exist, the entry will be updated with the specified namevalues.

Parameters

  • namespace (str) – Metadata namespace

  • key (str) – Metadata key

  • namevalues (keyword arguments) – Metadata name-value pairs

Returns

The response from DataReservoir.io containing the unique id of the new or updated metadata.

Return type

dict

ping()

Test that you have a working connection to DataReservoir.io.

remove_metadata(series_id, metadata_id)

Remove a metadata entry from a series. Note that metadata entries are not deleted, but the link between series and metadata is broken.

Parameters

  • series_id (str) – The identifier of the existing series

  • metadata_id (str) – The identifier of the existing metadata entry.

Returns

response.json()

Return type

dict

search(namespace, key, name, value=None)

Find available series having metadata with given namespace + key* + name + value (optional) combination.

Parameters

  • namespace (str) – The namespace to search in

  • key (str) – The key to narrow search. Search is made with wildcard postfix.

  • name (str) – name to narrow search further

  • value (str, optional) – Value to narrow search further. Default (None) will include all.

Returns

Available information about the series. If value is passed, a dict is returned -> {TimeSeriesId: metadata}. Otherwise, a plain list with TimeSeriesId is returned.

Return type

dict or list

set_metadata(series_id, metadata_id=None, namespace=None, key=None, overwrite=False, **namevalues)

Set metadata entries on a series. Metadata can be set from existing values or new metadata can be created.

Parameters

  • series_id (str) – The identifier of the existing series

  • metadata_id (str, optional) – The identifier of the existing metadata entries. If passed, other metadata related arguments are ignored.

  • namespace (str, optional) – Metadata namespace.

  • key (str, mandatory if namespace is passed.) – Metadata key.

  • overwrite (bool, optional) – If true, and namespace+key corresponds to existing metadata, the value of the metadata will be overwritten. If false, a ValueError will be raised if the metadata already exist.

  • namevalues (keyword arguments) – Metadata name-value pairs

Returns

response.json()

Return type

dict

previous

API reference

next

Authentication