sticky_pi_api package¶

Subpackages¶

sticky_pi_api.database package

Submodules¶

sticky_pi_api.client module¶

Main module of the client. Implements classes to interact with the API.

class sticky_pi_api.client.BaseClient(local_dir, n_threads=8)[source]¶

Bases: sticky_pi_api.specifications.BaseAPISpec, abc.ABC

Abstract class that defines the methods of the client (common between remote and client).

Parameters

local_dir (str) – The path to a client directory that acts as a client storage
n_threads (int) – The number of parallel threads to use to compute statistics on the image (md5 and such)

delete_cache()[source]¶

get_images_with_uid_annotations_series(info, what_image='metadata', what_annotation='metadata')[source]¶

Retrieves images alongside their annotations (if available) for images from a given device and within a given datetime range.

Parameters

info (List[Dict[str, str]]) – A list of dicts. each dicts has, at least, the keys: 'device', 'start_datetime' and 'end_datetime'
what_image (str) – The nature of the image objects to retrieve. One of {'metadata', 'image', 'thumbnail', 'thumbnail_mini'}
what_annotation (str) – The nature of the object to retrieve. One of {'metadata', 'data'}.

Return type

List[Dict[str, Union[float, int, str]]]

Returns

A list of dictionaries with one element for each queried value. Each dictionary contains the fields present in the underlying database tables (see UIDAnnotations and Images).

get_ml_bundle_dir(bundle_name, bundle_dir, what)[source]¶

Return type: List[Dict[str, Union[float, str]]]

get_tiled_tuboid_series_itc_labels(info, what='metadata')[source]¶

Return type: List[Dict[str, Union[float, int, str]]]

property local_dir¶

put_images(files)[source]¶

Incrementally upload a list of client files

Parameters: files (List[str]) – the paths to the client files
Return type: List[Dict[str, Union[float, int, str]]]
Returns: the data of the uploaded files, as represented in by API

put_ml_bundle_dir(bundle_name, bundle_dir, what='all')[source]¶

Return type: List[Dict[str, Union[float, str]]]

put_tiled_tuboids(tuboid_directories, series_info)[source]¶

class sticky_pi_api.client.Cache(path)[source]¶

Bases: dict

add(function, results)[source]¶

delete()[source]¶

get_cached(function, hash)[source]¶

class sticky_pi_api.client.LocalClient(local_dir, n_threads=8, *args, **kwargs)[source]¶

Bases: sticky_pi_api.specifications.LocalAPI, sticky_pi_api.client.BaseClient

Abstract class that defines the methods of the client (common between remote and client).

Parameters

local_dir (str) – The path to a client directory that acts as a client storage
n_threads (int) – The number of parallel threads to use to compute statistics on the image (md5 and such)

class sticky_pi_api.client.RemoteAPIConnector(host, username, password, protocol='https', port=443)[source]¶

Bases: sticky_pi_api.specifications.BaseAPISpec

delete_images(info, client_info=None)[source]¶

#fixme. this is false. it now takes a set of images as returned by get_images Delete a set of images, defined by their parent device and the datetime of the picture.

Parameters

client_info (Optional[Dict[str, Any]]) – optional information about the client/user contains key 'username'
info (List[Dict[str, str]]) – A list of dicts. each dicts has, at least, keys: 'device' and 'datetime'

Return type

List[Dict[str, Union[float, int, str]]]

Returns

A list of dictionaries with one element for each deleted image.

delete_tiled_tuboids(info, client_info=None)[source]¶

Delete a set of tiled tuboids series, defined by their parent device, start a datetime.

Parameters

client_info (Optional[Dict[str, Any]]) – optional information about the client/user contains key 'username'
info (List[Dict[str, str]]) – A list of dicts. each dicts has, at least, keys: 'device', 'start_datetime' and 'end_datetime'

Return type

List[Dict[str, Union[float, int, str]]]

Returns

A list of dictionaries with one element for each deleted image.

get_image_series(info, what='metadata', client_info=None)[source]¶

Retrieves image sequences (i.e. series). A series contains all images from a given device within a datetime range.

Parameters

client_info (Optional[Dict[str, Any]]) – optional information about the client/user contains key 'username'
info – A list of dicts. each dicts has, at least, the keys: 'device', 'start_datetime' and 'end_datetime'. device is interpreted to the MySQL like operator. For instance,one can match all devices with device="%".
what (str) – The nature of the objects to retrieve. One of {'metadata', 'image', 'thumbnail', 'thumbnail-mini'}

Return type

List[Dict[str, Union[float, int, str]]]

Returns

A list of dictionaries with one element for each queried value. Each dictionary contains the fields present in the underlying database plus a 'url' fields to retrieve the actual object requested (i.e. the what) argument. In the case of what='metadata', url='' (i.e. no url is generated).

get_images(info, what='metadata', client_info=None)[source]¶

Retrieves information about a given set of images, defined by their parent device and the datetime of the picture. If an image is not available, no data is returned for this image.

Parameters

client_info (Optional[Dict[str, Any]]) – optional information about the client/user contains key 'username'
info (List[Dict[str, str]]) – A list of dicts. each dicts has, at least, keys: 'device' and 'datetime'
what (str) – The nature of the objects to retrieve. One of {'metadata', 'image', 'thumbnail', 'thumbnail-mini'}

Return type

List[Dict[str, Union[float, int, str]]]

Returns

A list of dictionaries with one element for each queried value. Each dictionary contains the fields present in the underlying database plus a 'url' fields to retrieve the actual object requested (i.e. the what) argument. In the case of what='metadata', url='' (i.e. no url is generated).

get_tiled_tuboid_series(info, what='metadata', client_info=None)[source]¶

Retrieves tiled tuboids – i.e. stitched annotations into a tile, where the assumption is one tuboid per instance. A series contains all tuboids fully contained within a range

Parameters

info (List[Dict[str, str]]) – A list of dicts. each dicts has, at least, the keys: 'device', 'start_datetime' and 'end_datetime'. device is interpreted to the MySQL like operator. For instance,one can match all devices with device="%".
what (str) – The nature of the objects to retrieve, either 'data' or 'metadata'. 'metadata' will not add the extra three fields mapping the files to the results
client_info (Optional[Dict[str, Any]]) – optional information about the client/user contains key 'username'

Return type

List[Dict[str, Union[float, int, str]]]

Returns

A list of dictionaries with one element for each queried value. Each dictionary contains the fields present in the underlying database plus the fields 'metadata', 'tuboid' and 'context' fields, which have a url to fetch the relevant file.

get_token(client_info=None)[source]¶

A authentication token for a user. injection in this function.

Parameters: client_info (Optional[Dict[str, Any]]) – optional information about the client/user contains key 'username'
Return type: str
Returns: a dictionary with the keys 'token' and 'expiration', an ascii formatted token, and expiration timestamp, respectively

get_uid_annotations(info, what='metadata', client_info=None)[source]¶

Retrieves annotations for a given set of images.

Parameters

info (List[Dict[str, str]]) – A list of dict with keys: 'device' and 'datetime'
what (str) – The nature of the object to retrieve. One of {'metadata', 'json'}.
client_info (Optional[Dict[str, Any]]) – optional information about the client/user contains key 'username'

Return type

List[Dict[str, Union[float, int, str]]]

Returns

A list of dictionaries with one element for each queried value. Each dictionary contains the fields present in the underlying database table (see UIDAnnotations). In the case of what='metadata', the field json=''. Otherwise, it contains a json string with the actual annotation data.

get_uid_annotations_series(info, what='metadata', client_info=None)[source]¶

Retrieves annotations for a given set of images.

Parameters

info (List[Dict[str, str]]) – A list of dicts. each dicts has, at least, the keys: 'device', 'start_datetime' and 'end_datetime'. device is interpreted to the MySQL like operator.
what (str) – The nature of the object to retrieve. One of {'metadata', 'json'}.
client_info (Optional[Dict[str, Any]]) – optional information about the client/user contains key 'username'

Return type

List[Dict[str, Union[float, int, str]]]

Returns

A list of dictionaries with one element for each queried value. Each dictionary contains the fields present in the underlying database table (see UIDAnnotations). In the case of what='metadata', the field json=''. Otherwise, it contains a json string with the actual annotation data.

get_users(info=None, client_info=None)[source]¶

Get a list of API users. Either all users (Default), or filter users by field if info is specified. In the latter case, the union of all matched users is returned.

Parameters

info (Optional[List[Dict[str, str]]]) – A dictionary acting as a filter, using an SQL like-type match. For instance {'username': '%'} return all users.
client_info (Optional[Dict[str, Any]]) – optional information about the client/user contains key 'username'

Return type

List[Dict[str, Any]]

Returns

A list of users as represented in the underlying database, as one dictionary [per user, with the keys being database column names. Note that the crypo/sensitive fields are not returned (e.g. password_hash)

put_itc_labels(info, client_info=None)[source]¶

Stores labels for a given set of tiled tuboid

Parameters

info (List[Dict[str, Union[str, int]]]) – A list of dict with keys: 'tuboid_id', 'label', 'pattern', 'algo_version'``and ``'algo_name' (see ITCLabels).
client_info (Optional[Dict[str, Any]]) – optional information about the client/user contains key 'username'

Return type

List[Dict[str, Union[float, int, str]]]

Returns

the field corresponding to the labels that were submitted

put_uid_annotations(info, client_info=None)[source]¶

Parameters

info (List[Dict[str, Union[List, Dict[str, Any]]]]) –
A list of dictionaries corresponding to annotations (one list element per image). The annotations are formatted as a dictionaries with two keys: 'annotations' and 'metadata'.
- 'metadata' must have the fields:
  - 'algo_name': the name of the algorithm used to find the object (e.g. 'sticky-pi-universal-insect-detector')
  - 'algo_version': The version of the algorithm as timestamp-md5 (e.g. '1598113346-ad2cd78dfaca12821046dfb8994724d5')
  - 'device': The device that took the annotated image (e.g. '5c173ff2')
  - 'datetime': The datetime at which the image was taken (e.g. '2020-06-20_21-33-24')
  - 'md5': The md5 of the image that was analysed (e.g. '9e6e908d9c29d332b511f8d5121857f8')
- 'annotations' is a list where each element represent an object. It has the fields:
  - 'contour': a 3d array encoding the position of the vertices (as convention in OpenCV)
  - 'name': the name/type of the object (e.g. 'insect')
  - 'fill_colour' and 'stroke_colour': the colours of the contour (if it is to be drawn – e.g. '#0000ff')
  - 'value': an optional integer further describing the contour (e.g. 1)
client_info (Optional[Dict[str, Any]]) – optional information about the client/user contains key 'username'

Return type

List[Dict[str, Union[float, int, str]]]

Returns

The metadata of the uploaded annotations (i.e. a list od dicts. each field of the dict naming a column in the database). This corresponds to the annotation data as represented in UIDAnnotations

put_users(info, client_info=None)[source]¶

Add a list of users defined by a dict of proprieties.

Parameters

info (List[Dict[str, Any]]) – A list of dictionary each dictionary has the fields {'username', 'password'}, and optionally: {'email', 'is_admin'},
client_info (Optional[Dict[str, Any]]) – optional information about the client/user contains key 'username'

Return type

List[Dict[str, Any]]

Returns

A list of dictionaries describing the users that were created

exception sticky_pi_api.client.RemoteAPIException[source]¶: Bases: Exception

class sticky_pi_api.client.RemoteClient(local_dir, host, username, password, protocol='https', port=443, n_threads=8)[source]¶

Bases: sticky_pi_api.client.RemoteAPIConnector, sticky_pi_api.client.BaseClient

Abstract class that defines the methods of the client (common between remote and client).

Parameters

local_dir (str) – The path to a client directory that acts as a client storage
n_threads (int) – The number of parallel threads to use to compute statistics on the image (md5 and such)

sticky_pi_api.configuration module¶

class sticky_pi_api.configuration.BaseAPIConf(env_file=None, **kwargs)[source]¶: Bases: dict

class sticky_pi_api.configuration.LocalAPIConf(env_file=None, **kwargs)[source]¶: Bases: sticky_pi_api.configuration.BaseAPIConf

class sticky_pi_api.configuration.RemoteAPIConf(env_file=None, **kwargs)[source]¶: Bases: sticky_pi_api.configuration.BaseAPIConf

class sticky_pi_api.configuration.RequiredConfVar[source]¶: Bases: object

sticky_pi_api.image_parser module¶

class sticky_pi_api.image_parser.ImageParser(file)[source]¶

Bases: dict

A class derived from dict that contains image metadata in its fields. It parses data from an input JPEG image file taken by a Sticky Pi and retrieves its metadata from filename an exif fields. In addition, it computes md5 sum and generate thumbnails for the input image. :param file: path to file or file like object

property file_blob¶

property filename¶

property thumbnail¶

property thumbnail_mini¶

sticky_pi_api.specifications module¶

class sticky_pi_api.specifications.BaseAPI(api_conf, *args, **kwargs)[source]¶

Bases: sticky_pi_api.specifications.BaseAPISpec, abc.ABC

delete_images(info, client_info=None)[source]¶

#fixme. this is false. it now takes a set of images as returned by get_images Delete a set of images, defined by their parent device and the datetime of the picture.

Parameters

client_info (Optional[Dict[str, Any]]) – optional information about the client/user contains key 'username'
info (List[Dict[str, Union[float, int, str]]]) – A list of dicts. each dicts has, at least, keys: 'device' and 'datetime'

Return type

List[Dict[str, Union[float, int, str]]]

Returns

A list of dictionaries with one element for each deleted image.

delete_tiled_tuboids(info, client_info=None)[source]¶

Delete a set of tiled tuboids series, defined by their parent device, start a datetime.

Parameters

client_info (Optional[Dict[str, Any]]) – optional information about the client/user contains key 'username'
info (List[Dict[str, str]]) – A list of dicts. each dicts has, at least, keys: 'device', 'start_datetime' and 'end_datetime'

Return type

List[Dict[str, Union[float, int, str]]]

Returns

A list of dictionaries with one element for each deleted image.

get_image_series(info, what='metadata', client_info=None)[source]¶

Retrieves image sequences (i.e. series). A series contains all images from a given device within a datetime range.

Parameters

client_info (Optional[Dict[str, Any]]) – optional information about the client/user contains key 'username'
info (List[Dict[str, Union[float, int, str]]]) – A list of dicts. each dicts has, at least, the keys: 'device', 'start_datetime' and 'end_datetime'. device is interpreted to the MySQL like operator. For instance,one can match all devices with device="%".
what (str) – The nature of the objects to retrieve. One of {'metadata', 'image', 'thumbnail', 'thumbnail-mini'}

Returns

A list of dictionaries with one element for each queried value. Each dictionary contains the fields present in the underlying database plus a 'url' fields to retrieve the actual object requested (i.e. the what) argument. In the case of what='metadata', url='' (i.e. no url is generated).

get_images(info, what='metadata', client_info=None)[source]¶

Retrieves information about a given set of images, defined by their parent device and the datetime of the picture. If an image is not available, no data is returned for this image.

Parameters

client_info (Optional[Dict[str, Any]]) – optional information about the client/user contains key 'username'
info (List[Dict[str, Union[float, int, str]]]) – A list of dicts. each dicts has, at least, keys: 'device' and 'datetime'
what (str) – The nature of the objects to retrieve. One of {'metadata', 'image', 'thumbnail', 'thumbnail-mini'}

Returns

A list of dictionaries with one element for each queried value. Each dictionary contains the fields present in the underlying database plus a 'url' fields to retrieve the actual object requested (i.e. the what) argument. In the case of what='metadata', url='' (i.e. no url is generated).

get_tiled_tuboid_series(info, what='metadata', client_info=None)[source]¶

Retrieves tiled tuboids – i.e. stitched annotations into a tile, where the assumption is one tuboid per instance. A series contains all tuboids fully contained within a range

Parameters

info (List[Dict[str, str]]) – A list of dicts. each dicts has, at least, the keys: 'device', 'start_datetime' and 'end_datetime'. device is interpreted to the MySQL like operator. For instance,one can match all devices with device="%".
what (str) – The nature of the objects to retrieve, either 'data' or 'metadata'. 'metadata' will not add the extra three fields mapping the files to the results
client_info (Optional[Dict[str, Any]]) – optional information about the client/user contains key 'username'

Return type

List[Dict[str, Union[float, int, str]]]

Returns

A list of dictionaries with one element for each queried value. Each dictionary contains the fields present in the underlying database plus the fields 'metadata', 'tuboid' and 'context' fields, which have a url to fetch the relevant file.

get_uid_annotations(info, what='metadata', client_info=None)[source]¶

Retrieves annotations for a given set of images.

Parameters

info (List[Dict[str, Union[float, int, str]]]) – A list of dict with keys: 'device' and 'datetime'
what (str) – The nature of the object to retrieve. One of {'metadata', 'json'}.
client_info (Optional[Dict[str, Any]]) – optional information about the client/user contains key 'username'

Returns

A list of dictionaries with one element for each queried value. Each dictionary contains the fields present in the underlying database table (see UIDAnnotations). In the case of what='metadata', the field json=''. Otherwise, it contains a json string with the actual annotation data.

get_uid_annotations_series(info, what='metadata', client_info=None)[source]¶

Retrieves annotations for a given set of images.

Parameters

info (List[Dict[str, Union[float, int, str]]]) – A list of dicts. each dicts has, at least, the keys: 'device', 'start_datetime' and 'end_datetime'. device is interpreted to the MySQL like operator.
what (str) – The nature of the object to retrieve. One of {'metadata', 'json'}.
client_info (Optional[Dict[str, Any]]) – optional information about the client/user contains key 'username'

Returns

A list of dictionaries with one element for each queried value. Each dictionary contains the fields present in the underlying database table (see UIDAnnotations). In the case of what='metadata', the field json=''. Otherwise, it contains a json string with the actual annotation data.

get_users(info=None, client_info=None)[source]¶

Get a list of API users. Either all users (Default), or filter users by field if info is specified. In the latter case, the union of all matched users is returned.

Parameters

info (Optional[List[Dict[str, str]]]) – A dictionary acting as a filter, using an SQL like-type match. For instance {'username': '%'} return all users.
client_info (Optional[Dict[str, Any]]) – optional information about the client/user contains key 'username'

Return type

List[Dict[str, Any]]

Returns

A list of users as represented in the underlying database, as one dictionary [per user, with the keys being database column names. Note that the crypo/sensitive fields are not returned (e.g. password_hash)

put_itc_labels(info, client_info=None)[source]¶

Stores labels for a given set of tiled tuboid

Parameters

info (List[Dict[str, Union[str, int]]]) – A list of dict with keys: 'tuboid_id', 'label', 'pattern', 'algo_version'``and ``'algo_name' (see ITCLabels).
client_info (Optional[Dict[str, Any]]) – optional information about the client/user contains key 'username'

Return type

List[Dict[str, Union[float, int, str]]]

Returns

the field corresponding to the labels that were submitted

put_uid_annotations(info, client_info=None)[source]¶

Parameters

info (List[Dict[str, Union[List, Dict[str, Any]]]]) –
A list of dictionaries corresponding to annotations (one list element per image). The annotations are formatted as a dictionaries with two keys: 'annotations' and 'metadata'.
- 'metadata' must have the fields:
  - 'algo_name': the name of the algorithm used to find the object (e.g. 'sticky-pi-universal-insect-detector')
  - 'algo_version': The version of the algorithm as timestamp-md5 (e.g. '1598113346-ad2cd78dfaca12821046dfb8994724d5')
  - 'device': The device that took the annotated image (e.g. '5c173ff2')
  - 'datetime': The datetime at which the image was taken (e.g. '2020-06-20_21-33-24')
  - 'md5': The md5 of the image that was analysed (e.g. '9e6e908d9c29d332b511f8d5121857f8')
- 'annotations' is a list where each element represent an object. It has the fields:
  - 'contour': a 3d array encoding the position of the vertices (as convention in OpenCV)
  - 'name': the name/type of the object (e.g. 'insect')
  - 'fill_colour' and 'stroke_colour': the colours of the contour (if it is to be drawn – e.g. '#0000ff')
  - 'value': an optional integer further describing the contour (e.g. 1)
client_info (Optional[Dict[str, Any]]) – optional information about the client/user contains key 'username'

Returns

The metadata of the uploaded annotations (i.e. a list od dicts. each field of the dict naming a column in the database). This corresponds to the annotation data as represented in UIDAnnotations

put_users(info, client_info=None)[source]¶

Add a list of users defined by a dict of proprieties.

Parameters

info (List[Dict[str, Any]]) – A list of dictionary each dictionary has the fields {'username', 'password'}, and optionally: {'email', 'is_admin'},
client_info (Optional[Dict[str, Any]]) – optional information about the client/user contains key 'username'

Return type

List[Dict[str, Any]]

Returns

A list of dictionaries describing the users that were created

verify_password(username_or_token, password)[source]¶

class sticky_pi_api.specifications.BaseAPISpec[source]¶

Bases: abc.ABC

abstract delete_images(info, client_info=None)[source]¶

#fixme. this is false. it now takes a set of images as returned by get_images Delete a set of images, defined by their parent device and the datetime of the picture.

Parameters

client_info (Optional[Dict[str, Any]]) – optional information about the client/user contains key 'username'
info (List[Dict[str, Union[float, int, str]]]) – A list of dicts. each dicts has, at least, keys: 'device' and 'datetime'

Returns

A list of dictionaries with one element for each deleted image.

abstract delete_tiled_tuboids(info, client_info=None)[source]¶

Delete a set of tiled tuboids series, defined by their parent device, start a datetime.

Parameters

client_info (Optional[Dict[str, Any]]) – optional information about the client/user contains key 'username'
info (List[Dict[str, str]]) – A list of dicts. each dicts has, at least, keys: 'device', 'start_datetime' and 'end_datetime'

Return type

List[Dict[str, Union[float, int, str]]]

Returns

A list of dictionaries with one element for each deleted image.

abstract get_image_series(info, what='metadata', client_info=None)[source]¶

Retrieves image sequences (i.e. series). A series contains all images from a given device within a datetime range.

Parameters

client_info (Optional[Dict[str, Any]]) – optional information about the client/user contains key 'username'
info – A list of dicts. each dicts has, at least, the keys: 'device', 'start_datetime' and 'end_datetime'. device is interpreted to the MySQL like operator. For instance,one can match all devices with device="%".
what (str) – The nature of the objects to retrieve. One of {'metadata', 'image', 'thumbnail', 'thumbnail-mini'}

Return type

List[Dict[str, Union[float, int, str]]]

Returns

A list of dictionaries with one element for each queried value. Each dictionary contains the fields present in the underlying database plus a 'url' fields to retrieve the actual object requested (i.e. the what) argument. In the case of what='metadata', url='' (i.e. no url is generated).

abstract get_images(info, what='metadata', client_info=None)[source]¶

Retrieves information about a given set of images, defined by their parent device and the datetime of the picture. If an image is not available, no data is returned for this image.

Parameters

client_info (Optional[Dict[str, Any]]) – optional information about the client/user contains key 'username'
info (List[Dict[str, str]]) – A list of dicts. each dicts has, at least, keys: 'device' and 'datetime'
what (str) – The nature of the objects to retrieve. One of {'metadata', 'image', 'thumbnail', 'thumbnail-mini'}

Return type

List[Dict[str, Union[float, int, str]]]

Returns

A list of dictionaries with one element for each queried value. Each dictionary contains the fields present in the underlying database plus a 'url' fields to retrieve the actual object requested (i.e. the what) argument. In the case of what='metadata', url='' (i.e. no url is generated).

abstract get_tiled_tuboid_series(info, what='metadata', client_info=None)[source]¶

Retrieves tiled tuboids – i.e. stitched annotations into a tile, where the assumption is one tuboid per instance. A series contains all tuboids fully contained within a range

Parameters

info (List[Dict[str, str]]) – A list of dicts. each dicts has, at least, the keys: 'device', 'start_datetime' and 'end_datetime'. device is interpreted to the MySQL like operator. For instance,one can match all devices with device="%".
what (str) – The nature of the objects to retrieve, either 'data' or 'metadata'. 'metadata' will not add the extra three fields mapping the files to the results
client_info (Optional[Dict[str, Any]]) – optional information about the client/user contains key 'username'

Return type

List[Dict[str, Union[float, int, str]]]

Returns

A list of dictionaries with one element for each queried value. Each dictionary contains the fields present in the underlying database plus the fields 'metadata', 'tuboid' and 'context' fields, which have a url to fetch the relevant file.

abstract get_token(client_info=None)[source]¶

A authentication token for a user. injection in this function.

Parameters: client_info (Optional[Dict[str, Any]]) – optional information about the client/user contains key 'username'
Return type: Dict[str, Union[str, int]]
Returns: a dictionary with the keys 'token' and 'expiration', an ascii formatted token, and expiration timestamp, respectively

abstract get_uid_annotations(info, what='metadata', client_info=None)[source]¶

Retrieves annotations for a given set of images.

Parameters

info (List[Dict[str, str]]) – A list of dict with keys: 'device' and 'datetime'
what (str) – The nature of the object to retrieve. One of {'metadata', 'json'}.
client_info (Optional[Dict[str, Any]]) – optional information about the client/user contains key 'username'

Return type

List[Dict[str, Union[float, int, str]]]

Returns

A list of dictionaries with one element for each queried value. Each dictionary contains the fields present in the underlying database table (see UIDAnnotations). In the case of what='metadata', the field json=''. Otherwise, it contains a json string with the actual annotation data.

abstract get_uid_annotations_series(info, what='metadata', client_info=None)[source]¶

Retrieves annotations for a given set of images.

Parameters

info (List[Dict[str, str]]) – A list of dicts. each dicts has, at least, the keys: 'device', 'start_datetime' and 'end_datetime'. device is interpreted to the MySQL like operator.
what (str) – The nature of the object to retrieve. One of {'metadata', 'json'}.
client_info (Optional[Dict[str, Any]]) – optional information about the client/user contains key 'username'

Return type

List[Dict[str, Union[float, int, str]]]

Returns

A list of dictionaries with one element for each queried value. Each dictionary contains the fields present in the underlying database table (see UIDAnnotations). In the case of what='metadata', the field json=''. Otherwise, it contains a json string with the actual annotation data.

abstract get_users(info=None, client_info=None)[source]¶

Get a list of API users. Either all users (Default), or filter users by field if info is specified. In the latter case, the union of all matched users is returned.

Parameters

info (Optional[List[Dict[str, str]]]) – A dictionary acting as a filter, using an SQL like-type match. For instance {'username': '%'} return all users.
client_info (Optional[Dict[str, Any]]) – optional information about the client/user contains key 'username'

Return type

List[Dict[str, Any]]

Returns

A list of users as represented in the underlying database, as one dictionary [per user, with the keys being database column names. Note that the crypo/sensitive fields are not returned (e.g. password_hash)

abstract put_itc_labels(info, client_info=None)[source]¶

Stores labels for a given set of tiled tuboid

Parameters

info (List[Dict[str, Union[str, int]]]) – A list of dict with keys: 'tuboid_id', 'label', 'pattern', 'algo_version'``and ``'algo_name' (see ITCLabels).
client_info (Optional[Dict[str, Any]]) – optional information about the client/user contains key 'username'

Return type

List[Dict[str, Union[float, int, str]]]

Returns

the field corresponding to the labels that were submitted

abstract put_uid_annotations(info, client_info=None)[source]¶

Parameters

info (List[Dict[str, Union[List, Dict[str, Any]]]]) –
A list of dictionaries corresponding to annotations (one list element per image). The annotations are formatted as a dictionaries with two keys: 'annotations' and 'metadata'.
- 'metadata' must have the fields:
  - 'algo_name': the name of the algorithm used to find the object (e.g. 'sticky-pi-universal-insect-detector')
  - 'algo_version': The version of the algorithm as timestamp-md5 (e.g. '1598113346-ad2cd78dfaca12821046dfb8994724d5')
  - 'device': The device that took the annotated image (e.g. '5c173ff2')
  - 'datetime': The datetime at which the image was taken (e.g. '2020-06-20_21-33-24')
  - 'md5': The md5 of the image that was analysed (e.g. '9e6e908d9c29d332b511f8d5121857f8')
- 'annotations' is a list where each element represent an object. It has the fields:
  - 'contour': a 3d array encoding the position of the vertices (as convention in OpenCV)
  - 'name': the name/type of the object (e.g. 'insect')
  - 'fill_colour' and 'stroke_colour': the colours of the contour (if it is to be drawn – e.g. '#0000ff')
  - 'value': an optional integer further describing the contour (e.g. 1)
client_info (Optional[Dict[str, Any]]) – optional information about the client/user contains key 'username'

Return type

List[Dict[str, Union[float, int, str]]]

Returns

The metadata of the uploaded annotations (i.e. a list od dicts. each field of the dict naming a column in the database). This corresponds to the annotation data as represented in UIDAnnotations

abstract put_users(info, client_info=None)[source]¶

Add a list of users defined by a dict of proprieties.

Parameters

info (List[Dict[str, Any]]) – A list of dictionary each dictionary has the fields {'username', 'password'}, and optionally: {'email', 'is_admin'},
client_info (Optional[Dict[str, Any]]) – optional information about the client/user contains key 'username'

Return type

List[Dict[str, Any]]

Returns

A list of dictionaries describing the users that were created

class sticky_pi_api.specifications.LocalAPI(api_conf, *args, **kwargs)[source]¶

Bases: sticky_pi_api.specifications.BaseAPI

get_token(client_info=None)[source]¶

A authentication token for a user. injection in this function.

Parameters: client_info (Optional[Dict[str, Any]]) – optional information about the client/user contains key 'username'
Returns: a dictionary with the keys 'token' and 'expiration', an ascii formatted token, and expiration timestamp, respectively

class sticky_pi_api.specifications.RemoteAPI(api_conf, *args, **kwargs)[source]¶

Bases: sticky_pi_api.specifications.BaseAPI

get_token(client_info=None)[source]¶

A authentication token for a user. injection in this function.

Parameters: client_info (Optional[Dict[str, Any]]) – optional information about the client/user contains key 'username'
Return type: Dict[str, Union[str, int]]
Returns: a dictionary with the keys 'token' and 'expiration', an ascii formatted token, and expiration timestamp, respectively

put_images(files, client_info=None)[source]¶

sticky_pi_api.specifications.set_sqlite_pragma(dbapi_connection, connection_record)[source]¶

sticky_pi_api.storage module¶

class sticky_pi_api.storage.BaseStorage(api_conf, *args, **kwargs)[source]¶

Bases: abc.ABC

abstract delete_image_files(image)[source]¶

Delete the files corresponding to an image. :type image: Images :param image: an image object

Return type: None

abstract delete_tiled_tuboid_files(tuboid)[source]¶

Delete the files corresponding to a tiled tuboid :param image: an image object

Return type: None

abstract get_ml_bundle_file_list(bundle_name, what='all')[source]¶

List and describes the files present in a ML bundle.

Parameters

bundle_name (str) – the name of the machine learning bundle to fetch the files from
what (str) – One of {'all', 'data',``’model’`` }, to return all files, only the training data(training), or only the model (inference), respectively.

Return type

List[Dict[str, Union[float, str]]]

Returns

A list of dict containing the fields key and url of the files to be downloaded, which can be used to download the files

get_ml_bundle_upload_links(bundle_name, info)[source]¶

Request a list of upload links to put files in a given ML bundle

Parameters

bundle_name (str) –
info (List[Dict[str, Union[float, str]]]) – A list of dict containing the fields key, md5 mtime describing the upload candidates.

Return type

List[Dict[str, Union[float, str]]]

Returns

A list like info with the extra key url pointing to a destination where the file can be copied/posted. The list contains only files that did not exist on remote – hence can be empty.

abstract get_url_for_image(image, what='metadata')[source]¶

Retrieves the URL to the file corresponding to an image in the database.

Parameters

image (Images) – an image object
what (str) – One of {'metadata', 'image', 'thumbnail', 'thumbnail-mini'}

Return type

str

Returns

a url/path as a string. For what='metadata', an empty string is returned. for consistency

abstract get_urls_for_tiled_tuboids(data)[source]¶

Return type: Dict[str, str]

classmethod local_bundle_files_info(bundle_dir, what='all', ignored_dir_names=('.cache'))[source]¶

abstract store_image_files(image)[source]¶

Saves the files corresponding to a an image. Those are generally the original JPEG plus thumbnail and thumbnail-mini

Parameters: image (Images) – an image object
Return type: None

abstract store_tiled_tuboid(data)[source]¶

Return type: None

class sticky_pi_api.storage.DiskStorage(api_conf, *args, **kwargs)[source]¶

Bases: sticky_pi_api.storage.BaseStorage

delete_image_files(image)[source]¶

Delete the files corresponding to an image. :type image: Images :param image: an image object

Return type: None

delete_tiled_tuboid_files(tuboid)[source]¶

Delete the files corresponding to a tiled tuboid :param image: an image object

Return type: None

get_ml_bundle_file_list(bundle_name, what='all')[source]¶

List and describes the files present in a ML bundle.

Parameters

bundle_name (str) – the name of the machine learning bundle to fetch the files from
what (str) – One of {'all', 'data',``’model’`` }, to return all files, only the training data(training), or only the model (inference), respectively.

Return type

List[Dict[str, Union[float, str]]]

Returns

A list of dict containing the fields key and url of the files to be downloaded, which can be used to download the files

get_url_for_image(image, what='metadata')[source]¶

Retrieves the URL to the file corresponding to an image in the database.

Parameters

image (Images) – an image object
what (str) – One of {'metadata', 'image', 'thumbnail', 'thumbnail-mini'}

Return type

str

Returns

a url/path as a string. For what='metadata', an empty string is returned. for consistency

get_urls_for_tiled_tuboids(data)[source]¶

Return type: Dict[str, str]

store_image_files(image)[source]¶

Saves the files corresponding to a an image. Those are generally the original JPEG plus thumbnail and thumbnail-mini

Parameters: image (Images) – an image object
Return type: None

store_tiled_tuboid(data)[source]¶

Return type: None

class sticky_pi_api.storage.S3Storage(api_conf, *args, **kwargs)[source]¶

Bases: sticky_pi_api.storage.BaseStorage

delete_image_files(image)[source]¶

Delete the files corresponding to an image. :type image: Images :param image: an image object

Return type: None

delete_tiled_tuboid_files(tuboid)[source]¶

Delete the files corresponding to a tiled tuboid :param image: an image object

Return type: None

get_ml_bundle_file_list(bundle_name, what='all')[source]¶

List and describes the files present in a ML bundle.

Parameters

bundle_name (str) – the name of the machine learning bundle to fetch the files from
what (str) – One of {'all', 'data',``’model’`` }, to return all files, only the training data(training), or only the model (inference), respectively.

Return type

List[Dict[str, Union[float, str]]]

Returns

A list of dict containing the fields key and url of the files to be downloaded, which can be used to download the files

get_url_for_image(image, what='metadata')[source]¶

Retrieves the URL to the file corresponding to an image in the database.

Parameters

image (Images) – an image object
what (str) – One of {'metadata', 'image', 'thumbnail', 'thumbnail-mini'}

Return type

str

Returns

a url/path as a string. For what='metadata', an empty string is returned. for consistency

get_urls_for_tiled_tuboids(data)[source]¶

Return type: Dict[str, str]

store_image_files(image)[source]¶

Saves the files corresponding to a an image. Those are generally the original JPEG plus thumbnail and thumbnail-mini

Parameters: image (Images) – an image object
Return type: None

store_tiled_tuboid(data)[source]¶

Return type: None

sticky_pi_api.types module¶

sticky_pi_api.utils module¶

class sticky_pi_api.utils.URLOrFileOpen(file_or_url, mode)[source]¶: Bases: object

sticky_pi_api.utils.chunker(seq, size)[source]¶

Breaks an interable into a list of smaller chunks of size size (or less for the last chunk)

Parameters

seq – an iterable
size (int) – the size of the chunk

Returns

sticky_pi_api.utils.datetime_to_string(dt)[source]¶

sticky_pi_api.utils.json_inputs_to_python(func)[source]¶

sticky_pi_api.utils.json_io_converter(o)[source]¶

sticky_pi_api.utils.json_out_parser(o)[source]¶

sticky_pi_api.utils.md5(file, chunk_size=32768)[source]¶

sticky_pi_api.utils.multipart_etag(file, chunk_size)[source]¶

sticky_pi_api.utils.python_inputs_to_json(func)[source]¶

sticky_pi_api.utils.string_to_datetime(string)[source]¶

Module contents¶

this is the __init__ of sticky_pi_api