Bucket

Thing

class dcd.bucket.thing.Thing(thing_id: str = None, private_key_path: str = None, private_key: str = None, json_thing: dict = None, connect=True)

This is a conceptual class representation of a physical or virtual entity collecting data.

Attributes:

thing_id : str

The id of the Thing, starting with “dcd:things:”.

name : str

Name of the Thing

description : str

Description of the Thing

thing_type : str

Type of the Thing

properties : Property[]

Properties of the Thing

private_key_path : str

Path to the private key to use for the generation of authentication tokens.

created_at : int

Creation time of the Thing on Bucket (UNIX timestamp)

updated_at : int

Last update time of the Thing on Bucket (UNIX timestamp)

describe()

Prints formatted JSON with the details of the Thing

find_or_create_property(property_name: str, type_id: str) → dcd.bucket.properties.property.Property

Search for a property in thing by name, create it if not found & return it.

Args:

property_name : str

The name of the property to look for.

type_id : str

The type of the property, so that we can create it if it is not found.

Returns:

Property: The found or newly created Property.

find_property_by_name(property_name_to_find: str) → dcd.bucket.properties.property.Property

Search for a property in thing by name

Args:

property_name_to_find : str

The name of the property to look for.

Returns:

Property: The found property, None if not found

find_shared_properties(group='*') → List[dcd.bucket.properties.property.Property]

Search for properties that are accessible by the Thing.

Args:

group (str, optional): [description]. Defaults to “*”, fetching for all groups.

Returns:

[Property]: Shared properties accessible by the Thing.

read_property(property_id: str, from_ts: int = None, to_ts: int = None, time_interval=None, time_fct=None, fill=None, shared_with=None) → dcd.bucket.properties.property.Property

Read the details of a property from Bucket

Args:

property_id : str

The id of the property to read

from_ts : int, optional

The start time of the values to fetch. Defaults to None.

to_ts : int, optional

The end time of the values to fetch. Defaults to None.

Raises:

ValueError: The requested property is not part of the Thing ValueError: Could not parse the reponse

Returns:

Property: The property with its details and values.

update_property(prop: dcd.bucket.properties.property.Property, file_name: str = None)

Send new property values to Bucket

Args:

prop : Property

The property containing values to send

file_name : str, optional

If media type property, the path to the file to upload. Defaults to None.

Authentication

class dcd.bucket.thing.ThingToken(private_key_path: str, subject: str, issuer: str, audience: str, algorithm='RS256')

Handle JSON web token for the Thing authentication

decode(public_key_path: str = None, jwt_token: str = None) → dict

Decode a JWT, revealing the dictionary of its values

Args:

public_key_path : str, optional

The path to the public key. If none provided, looking at PUBLIC_KEY_PATH environment variable, or use ‘./public.pem’ as default. Defaults to None.

jwt_token : str, optional

String representing the JSON web token. If none provided, taking the one from the class Defaults to None.

Returns:

dict: Decoded JSON Web Token including the issuer (iss), audience (aud), subject (sub), the creation date (iat) and the expiration date (exp)

get_token() → str

Check if the current JWT is still valid, refresh it if necessary and returns it.

Returns:

str: The existing (and still valid) JWT or a newly generated JWT

refresh(duration_sec: int = 3600) → str

Use the private key to generate a new JWT.

Args:

duration_sec (int, optional): The life time of the token in seconds

Returns:

str: the resulting JSON web token

Network

class dcd.bucket.thing.ThingHTTP(thing, http_uri: str)

Handle Bucket interaction for a Thing via HTTP

create_property(name: str, type_id: str)

Create a new property on Bucket.

Args:

name : str

Name of the property to create

type_id : str

Type id of the property to create

Returns:

Property: The newly created property

is_connected() → bool

Check whether the HTTP connection was established.

Returns:

bool: Whether the initial HTTP request read() succeeded.

read() → bool

Read details of the Thing from Bucket.

Returns:

bool: True if succeeded in reading the Thing details from Bucket

read_property(property_id: str, from_ts: int = None, to_ts: int = None, time_interval=None, time_fct=None, fill=None, shared_with=None) → dcd.bucket.properties.property.Property

Read the details of a property from Bucket

Args:

property_id : str

The id of the property to read

from_ts : int, optional

The start time of the values to fetch. Defaults to None.

to_ts : int, optional

The end time of the values to fetch. Defaults to None.

Raises:

ValueError: The requested property is not part of the Thing ValueError: Could not parse the reponse

Returns:

Property: The property with its details and values.

update_property(prop: dcd.bucket.properties.property.Property, file_name: str = None) → int

Update the values of a property on Bucket

Args:

prop : Property

The property to update

file_name : str, optional

The media to upload. Defaults to None.

Returns:

int: Status response code

class dcd.bucket.thing.ThingMQTT(thing, DigiCertCA='DigicertCA', connect=True)

find_or_create_property(property_name: str, type_id: str)

Search for a property in thing by name, create it if not found & return it.

Args:

property_name : str

The name of the property to look for.

type_id : str

The type of the property, so that we can create it if it is not found.

update_property(prop: dcd.bucket.properties.property.Property, file_name: str)

Send new property values to Bucket

Args:

prop : Property

The property containing values to send

file_name : str, optional

If media type property, the path to the file to upload. Defaults to None.

Properties

class dcd.bucket.properties.property.Property(property_id: str = None, name: str = None, description: str = None, type_id: str = None, property_type: dict = None, json_property: dict = None, values: dict = (), thing=None)

” A DCD “Property” represents a numerical property of a Thing.

align_values_to(prop2)

Create if missing, an intermediary row of values for each timestamp in prop2

merge(prop2)

Create a new Property with id and name of form “prop1+prop2”, concat dimension and values (MUST have same number of rows) and return this new property

read(from_ts=None, to_ts=None, time_interval=None, time_fct=None, shared_with: str = None)

Read the details of a property from Bucket

Args:

from_ts : int|str, optional

The start time of the values to fetch. Can be a UNIX timestamp in milliseconds or a string date ‘%Y-%m-%d %H:%M:%S’. Defaults to None.

to_ts : int|str, optional

The end time of the values to fetch. Can be a UNIX timestamp in milliseconds or a string date ‘%Y-%m-%d %H:%M:%S’. Defaults to None.

Returns:

Property: The property with its details and values.

sync()

Upload values to the server and clean up the loacl values

update_values(values: dict, time_ms: int = None, file_name: str = None, mode: str = 'w')

Update the values of a property.

Args:

values: dict

List containing values [val-dim1, val-dim2,…]

time_ms : int, optional

Collection time in milliseconds to add to the values. Default to None

file_name: path to a file to upload (e.g. for video, image or audio properties) mode : str, optional

Control how to manage existing values. - ‘w’ overwrite existing (local) values, replace with new values, and send to the server - ‘a’ append new values after existing values. In this mode, you must call sync() to upload the data on the server. TODO: does not work with files yet. Defaults to ‘overwrite’.