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
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’.
-