Core API¶

DeviceCloud Core API¶

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

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

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 the 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().

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 the device cloud.
params – These are additional query parameters that should be sent with each request to the device cloud.

ping()¶

Ping the 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 the device cloud

Make an HTTP GET request against the 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.

Raises DeviceCloudHttpException:
Parameters:	path (str) – The 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.
	if a non-success response to the request is received from the device cloud
Returns:	A requests `Response` object

get_json(path, **kwargs)¶

Perform an HTTP GET request with JSON headers of the specified path against the device cloud

Make an HTTP GET request against the 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 the device cloud.

Raises DeviceCloudHttpException:
Parameters:	path (str) – The 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.
	if a non-success response to the request is received from the device cloud
Returns:	A python data structure containing the results of calling `json.loads` on the body of the response from the device cloud.

post(path, data, **kwargs)¶

Perform an HTTP POST request of the specified path in the device cloud

Make an HTTP POST request against the 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.

Raises DeviceCloudHttpException:
Parameters:	path (str) – The 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`
	if a non-success response to the request is received from the device cloud
Returns:	A requests `Response` object

put(path, data, **kwargs)¶

Perform an HTTP PUT request of the specified path in the device cloud

Make an HTTP PUT request against the 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.

Raises DeviceCloudHttpException:
Parameters:	path (str) – The 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`
	if a non-success response to the request is received from the device cloud
Returns:	A requests `Response` object

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

Perform an HTTP DELETE request of the specified path in the device cloud

Make an HTTP DELETE request against the 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.

Raises DeviceCloudHttpException:
Parameters:	path (str) – The 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.
	if a non-success response to the request is received from the device cloud
Returns:	A requests `Response` object

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 the 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 the 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 the device cloud url, username, and password are valid

This method will attempt to “ping” the 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

streams¶: Property providing access to the StreamsAPI

filedata¶: Property providing access to the FileDataAPI

devicecore¶: Property providing access to the DeviceCoreAPI

sci¶: Property providing access to the ServerCommandInterfaceAPI

monitor¶: Property providing access to the MonitorAPI

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 the 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_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`

Conditions API¶

Module with functionality for building queries against cloud resources

This functionality is somewhat poorly documented in the 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.