Core API¶

DeviceCloud Core API¶

The devicecloud.DeviceCloud class contains the core interface which will be used by all clients using the devicecloud library.

class devicecloud.DeviceCloud(username, password, base_url=None, throttle_retries=5, throttle_delay_init=1.0, throttle_delay_max=10.0, throttle_delay_backoff_coefficient=1.5)¶

Provide access to core device cloud features

This class is the primary interface to Device Cloud through which access to individual device cloud services is provided. Creating a DeviceCloud object is as easy as doing the following:

from devicecloud import DeviceCloud

dc = DeviceCloud('user', 'pass')
if dc.has_valid_credentials():
    print list(dc.devicecore.get_devices())

From there, access to all of Device Clouds features are possible. In some cases, methods for quickly performing selected actions may be provided directly via the DeviceCloud object while advanced usage requires using functionality exposed through other interfaces.

has_valid_credentials()¶

Verify that Device Cloud url, username, and password are valid

This method will attempt to “ping” Device Cloud in order to ensure that all of the provided information is correct.

Returns: True if the credentials are valid and false if not
Return type: bool

property streams¶: Property providing access to the StreamsAPI

property filedata¶: Property providing access to the FileDataAPI

property devicecore¶: Property providing access to the DeviceCoreAPI

property sci¶: Property providing access to the ServerCommandInterfaceAPI

property file_system_service¶: Property providing access to the FileSystemServiceAPI

property monitor¶: Property providing access to the MonitorAPI

property ws¶: Property providing access to the WebServiceStub with a base of /ws

get_connection()¶

Get the low-level DeviceCloudConnection for this device cloud instance

This object provides a low-level interface for making authenticated requests to Device Cloud.

get_streams_api()¶

Returns a StreamsAPI bound to this device cloud instance

This provides access to the same API as DeviceCloud.streams but will create a new object (with a new cache) each time called.

Returns: Stream API object bound to this device cloud account
Return type: StreamsAPI

get_filedata_api()¶

Returns a FileDataAPI bound to this device cloud instance

This provides access to the same API as DeviceCloud.filedata but will create a new object (with a new cache) each time called.

Returns: FileData API object bound to this device cloud account
Return type: FileDataAPI

get_devicecore_api()¶

Returns a DeviceCoreAPI bound to this device cloud instance

This provides access to the same API as DeviceCloud.devicecore but will create a new object (with a new cache) each time called.

Returns: devicecore API object bound to this device cloud account
Return type: DeviceCoreAPI

get_sci_api()¶

Returns a ServerCommandInterfaceAPI bound to this device cloud instance

This provides access to the same API as DeviceCloud.sci but will create a new object (with a new cache) each time called.

Returns: SCI API object bound to this device cloud account
Return type: ServerCommandInterfaceAPI

get_fss_api()¶

Returns a FileSystemServiceAPI bound to this device cloud instance

This provides access to the same API as DeviceCloud.file_system_service but will create a new object (with a new cache) each time called.

Returns: FSS API object bound to this device cloud account
Return type: FileSystemServiceAPI

get_monitor_api()¶

Returns a MonitorAPI bound to this device cloud instance

This provides access to the same API as DeviceCloud.monitor but will create a new object (with a new cache) each time called.

Returns: Monitor API object bound to this device cloud account
Return type: MonitorAPI

get_web_service_stub()¶

Returns a WebServiceStub bound to this device cloud instance

This provides access to the same API as DeviceCloud.legacy but will create a new object (with a new cache) each time called.

Returns: WebServiceStub object bound to this device cloud account with a base of /ws
Return type: WebServiceStub

exception devicecloud.DeviceCloudException¶: Base class for Device Cloud Exceptions

exception devicecloud.DeviceCloudHttpException(response, *args, **kwargs)¶

Exception raised when we failed a request to the DC over HTTP

This exception will be raised whenever a non-success HTTP status code is received from Device Cloud and there is no other logic in place for gracefully handling the error case.

Often, if there is an error with a request to Device Cloud, the device cloud will respond with an error status and include additional information about the nature of the error in the response body. This information can be accessed via the response property.

property response¶

Get the requests response object for the failing HTTP request

This object will be an instance of requests.Response which in turn provides information including the content (body) of the response and the HTTP status code:

try:
    dc.sci.send_request(...)
except DeviceCloudHttpException as e:
    print "HTTP Error: %s" % e.response.status_code
    print e.response.content

class devicecloud.DeviceCloudConnection(auth, base_url, throttle_retries=5, throttle_delay_init=1.0, throttle_delay_max=10.0, throttle_delay_backoff_coefficient=1.5)¶

Provide low-level access to Device Cloud web services

This is a convenience object that provides methods that make sending requests to the device cloud easier. This object is used extensively within the library but can also be used externally (for instance, to support an API exposed by the device cloud that is not currently supported in the library).

This object is accessible via get_connection().

property hostname¶: Get the hostname that this connection is associated with

iter_json_pages(path, page_size=1000, **params)¶

Return an iterator over JSON items from a paginated resource

Legacy resources (prior to V1) implemented a common paging interfaces for several different resources. This method handles the details of iterating over the paged result set, yielding only the JSON data for each item within the aggregate resource.

Parameters

path (str) – The base path to the resource being requested (e.g. /ws/Group)
page_size (int) – The number of items that should be requested for each page. A larger page_size may mean fewer HTTP requests but could also increase the time to get a first result back from Device Cloud.
params – These are additional query parameters that should be sent with each request to Device Cloud.

ping()¶

Ping Device Cloud using the authorization provided

Returns: The response of getting a single device from DeviceCore on success
Raises: DeviceCloudHttpException if there is a problem

get(path, **kwargs)¶

Perform an HTTP GET request of the specified path in Device Cloud

Make an HTTP GET request against Device Cloud with this accounts credentials and base url. This method uses the requests library request method and all keyword arguments will be passed on to that method.

Parameters

path (str) – Device Cloud path to GET
retries (int) – The number of times the request should be retried if an unsuccessful response is received. Most likely, you should leave this at 0.

Raises

DeviceCloudHttpException – if a non-success response to the request is received from Device Cloud

Returns

A requests Response object

get_json(path, **kwargs)¶

Perform an HTTP GET request with JSON headers of the specified path against Device Cloud

Make an HTTP GET request against Device Cloud with this accounts credentials and base url. This method uses the requests library request method and all keyword arguments will be passed on to that method.

This method will automatically add the Accept: application/json and parse the JSON response from Device Cloud.

Parameters

path (str) – Device Cloud path to GET
retries (int) – The number of times the request should be retried if an unsuccessful response is received. Most likely, you should leave this at 0.

Raises

DeviceCloudHttpException – if a non-success response to the request is received from Device Cloud

Returns

A python data structure containing the results of calling json.loads on the body of the response from Device Cloud.

post(path, data, **kwargs)¶

Perform an HTTP POST request of the specified path in Device Cloud

Make an HTTP POST request against Device Cloud with this accounts credentials and base url. This method uses the requests library request method and all keyword arguments will be passed on to that method.

Parameters

path (str) – Device Cloud path to POST
retries (int) – The number of times the request should be retried if an unsuccessful response is received. Most likely, you should leave this at 0.
data – The data to be posted in the body of the POST request (see docs for requests.post

Raises

DeviceCloudHttpException – if a non-success response to the request is received from Device Cloud

Returns

A requests Response object

put(path, data, **kwargs)¶

Perform an HTTP PUT request of the specified path in Device Cloud

Make an HTTP PUT request against Device Cloud with this accounts credentials and base url. This method uses the requests library request method and all keyword arguments will be passed on to that method.

Parameters

path (str) – Device Cloud path to PUT
retries (int) – The number of times the request should be retried if an unsuccessful response is received. Most likely, you should leave this at 0.
data – The data to be posted in the body of the POST request (see docs for requests.post

Raises

DeviceCloudHttpException – if a non-success response to the request is received from Device Cloud

Returns

A requests Response object

delete(path, retries=5, **kwargs)¶

Perform an HTTP DELETE request of the specified path in Device Cloud

Make an HTTP DELETE request against Device Cloud with this accounts credentials and base url. This method uses the requests library request method and all keyword arguments will be passed on to that method.

Parameters

path (str) – Device Cloud path to DELETE
retries (int) – The number of times the request should be retried if an unsuccessful response is received. Most likely, you should leave this at 0.

Raises

DeviceCloudHttpException – if a non-success response to the request is received from Device Cloud

Returns

A requests Response object

Conditions API¶

Module with functionality for building queries against cloud resources

This functionality is somewhat poorly documented in Device Cloud documentation in the Compound Queries section.

class devicecloud.conditions.Expression¶

A condition is an evaluable filter

Examples of conditions would include the following: * fdType=’file’ * fdName like ‘sample%gas’

Conditions may also be compound. E.g. * (fdType=’file’ and fdName like ‘sample%gas’)

class devicecloud.conditions.Combination(lhs, sep, rhs)¶

A combination combines two expressions

compile()¶: Compile this expression into a query string

class devicecloud.conditions.Comparison(attribute, sep, value)¶

A comparison is an expression comparing an attribute with a value using some operator

compile()¶: Compile this expression into a query string

class devicecloud.conditions.Attribute(name)¶

An attribute is a piece of data on which we may perform comparisons

Comparisons performed to attributes will in turn generate new Comparison instances.