API¶
High-level¶
- 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
- metadata_search(namespace, key, conjunctive=True)¶
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 withTimeSeriesId
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
Authentication¶
- datareservoirio.Authenticator¶
- class datareservoirio.authenticate.UserAuthenticator(auth_force=False, session_key=None)¶
Authorized session where credentials are given in the DataReservoir.io web application. When a valid code is presented, the session is authenticated and persisted. A previous session will be reused as long as it is not expired. When required, a new authentication code is prompted for.
Extends
BaseAuthSession
.- Parameters
auth_force (bool, optional) – Force re-authenticating the session (default is False)
session_key (str, optional) – Unique identifier for an auth session. Can be used so that multiple instances can have independent auth/refresh cycles with the identity authority. Prevents local cache from being accidently overwritten.
- class datareservoirio.authenticate.ClientAuthenticator(client_id, client_secret)¶
Authorized session where credentials are given as client_id and client_secret. When valid credentials are presented, the session is authenticated and persisted.
Extends
BaseAuthSession
.- Parameters
client_id (str) – Unique identifier for the client (i.e. app/service etc.).
client_secret (str) – Secret/password for the client.
- refresh_token(*args, **kwargs)¶
Refresh (expired) access token