voxel51 package

Submodules

voxel51.api module

Main interface for the Voxel51 Vision Services API.

Copyright 2017-2018, Voxel51, LLC
class voxel51.api.API(token_path=None)[source]

Bases: object

Main class for managing a session with the Voxel51 Vision Services API.

url

the base URL of the API

Type:string
token

the authentication token for this session

Type:voxel51.auth.Token
delete_data(data_id)[source]

Deletes the data with the given ID from the cloud.

Parameters:data_id (str) – the data ID
Raises:APIError if the request was unsuccessful
download_data(data_id, output_path=None)[source]

Downloads the data with the given ID.

Parameters:
  • data_id (str) – the data ID
  • output_path (str, optional) – the output path to write to. By default, the data is written to the current working directory with the same filename as the data in cloud storage
Raises:

APIError if the request was unsuccessful

download_job_output(job_id, output_path='output.zip')[source]

Downloads the output of the job with the given ID.

Parameters:
  • job_id (str) – the job ID
  • output_path (str, optional) – the output path to write to. The default is ‘output.zip’
Raises:

APIError if the request was unsuccessful

get_analytic_doc(analytic_id)[source]

Gets documentation about the analytic with the given ID.

Parameters:analytic_id (str) – the analytic ID
Returns:a dictionary containing the analytic documentation
Raises:APIError if the request was unsuccessful
get_data_details(data_id)[source]

Gets details about the data with the given ID.

Parameters:data_id (str) – the data ID
Returns:a dictionary containing metadata about the data
Raises:APIError if the request was unsuccessful
get_job_details(job_id)[source]

Gets details about the job with the given ID.

Parameters:job_id (str) – the job ID
Returns:a dictionary containing metadata about the job
Raises:APIError if the request was unsuccessful
get_job_request(job_id)[source]

Gets the job request for the job with the given ID.

Parameters:job_id (str) – the job ID
Returns:a voxel51.jobs.JobRequest instance describing the job
Raises:APIError if the request was unsuccessful
get_job_state(job_id)[source]

Gets the state of the job with the given ID.

Parameters:job_id (str) – the job ID
Returns:the state of the job, which is a value in the JobState enum
Raises:APIError if the request was unsuccessful
get_job_status(job_id)[source]

Gets the status of the job with the given ID.

Parameters:job_id (str) – the job ID
Returns:a dictionary describing the status of the job
Raises:APIError if the request was unsuccessful
is_job_complete(job_id)[source]

Determines whether the job with the given ID is complete.

Parameters:

job_id (str) – the job ID

Returns:

True if the job is complete, and False otherwise

Raises:
  • JobExecutionError if the job failed
  • APIError if the underlying API request was unsuccessful
list_analytics()[source]

Returns a list of all available analytics.

Returns:a list of dicts describing the available analytics
Raises:APIError if the request was unsuccessful
list_data()[source]

Returns a list of all data uploaded to cloud storage.

Returns:a list of data IDs
Raises:APIError if the request was unsuccessful
list_jobs()[source]

Returns a list of all jobs in the cloud.

Returns:a list of job IDs
Raises:APIError if the request was unsuccessful
start_job(job_id)[source]

Starts the job with the given ID.

Parameters:job_id (str) – the job ID
Raises:APIError if the request was unsuccessful
upload_data(path)[source]

Uploads data to cloud storage.

Parameters:path (str) – the path to the data file
Returns:a dictionary containing metadata about the uploaded data
Raises:APIError if the request was unsuccessful
upload_job_request(job_request, job_name, auto_start=False)[source]

Uploads a job request to the cloud.

Parameters:
  • job_request (voxel51.jobs.JobRequest) – a JobRequest instance describing the job
  • job_name (str) – a name for the job
  • auto_start (bool) – whether to automatically start the job upon creation. By default, this is False
Returns:

a dictionary containing metadata about the job

Raises:

APIError if the request was unsuccessful

wait_until_job_completes(job_id, sleep_time=5, max_wait_time=600)[source]

Block execution until the job with the given ID is complete.

Parameters:
  • job_id (str) – the job ID
  • sleep_time (float, optional) – the number of seconds to wait between job state checks. The default is 5
  • max_wait_time (float, optional) – the maximum number of seconds to wait for the job to complete. The default is 600
Raises:
  • JobExecutionError if the job failed or the maximum wait time was – exceeded
  • APIError if an underlying API request was unsuccessful
exception voxel51.api.APIError(message, code)[source]

Bases: exceptions.Exception

Exception raised when an API request fails.

args
classmethod from_response(res)[source]

Constructs an APIError from a requests reponse.

Parameters:

res (requests.Response) – a requests response

Returns:

an instance of APIError

Raises:
  • ValueError – if the given response is not an error response
  • HTTPError – if the error was caused by the HTTP connection, not the API itself
message

voxel51.auth module

Authentication module for the Voxel51 Vision Services API.

Copyright 2017-2018, Voxel51, LLC
class voxel51.auth.Token(token_dict)[source]

Bases: object

A class encapsulating an API authentication token.

classmethod from_disk(path)[source]

Loads a token from disk.

Parameters:path (str) – the path to a valid token JSON file
Returns:a Token instance
get_header()[source]

Returns a header dictionary for authenticating requests with this token.

Returns:a header dictionary
exception voxel51.auth.TokenLoadError[source]

Bases: exceptions.Exception

Exception raised when a Token fails to load.

args
message
voxel51.auth.activate_token(path)[source]

Activates the given token by copying it to ~/.voxel51/api-token.json.

Subsequent voxel51.api.API() instances created will now use this token for authentication.

Parameters:path (str) – the path to an API token JSON file
voxel51.auth.deactivate_token()[source]

Deactivates (deletes) the currently active token, if any.

The active token is the token at ~/.voxel51/api-token.json.

voxel51.auth.load_token(token_path=None)[source]

Loads the active API token.

Parameters:token_path – an optional path to a valid Token JSON file. If no path is provided as an argument, the VOXEL51_API_TOKEN environment variable is checked and, if set, the token is loaded from that path. Otherwise, the token is loaded from ~/.voxel51/api-token.json
Returns:a Token instance
Raises:TokenLoadError if no valid token was found

voxel51.jobs module

Job request creation and manipulation library for the Voxel51 Vision Services API.

Copyright 2017-2018, Voxel51, LLC
exception voxel51.jobs.JobExecutionError[source]

Bases: exceptions.Exception

Error raised when there is a problem with the execution of a job.

args
message
class voxel51.jobs.JobRequest(analytic)[source]

Bases: voxel51.utils.Serializable

Class encapsulating a job request for the API.

analytic

the name of the analytic to run

Type:str
inputs

a dictionary mapping input names to RemoteDataPath instances

Type:dict
parameters

a dictionary mapping parameter names to values

Type:dict
classmethod from_dict(d)[source]

Constructs a JobRequest instance from a JSON dictionary.

Parameters:d (dict) – a JSON dictionary defining a JobRequest instance
Returns:a JobRequest instance
classmethod from_json(path)

Constructs a Serializable object from a JSON file.

Parameters:path (str) – the path to a JSON file
Returns:an instance of the Serializable subclass
classmethod from_string(s)

Constructs a Serializable object from a string representation of it.

Parameters:s (str) – a string representation of a Serializable subclass
Returns:an instance of the Serializable subclass
set_data_parameter(name, path=None, **kwargs)[source]

Sets the data parameter of the given name.

Data parameters are parameters that are defined by a RemoteDataPath instance and are read from cloud storage at runtime by the Vision Engine. The parameter can be specified either as a RemoteDataPath instance or as valid keyword arguments to construct one.

Parameters:
  • name (str) – the input name to set
  • path (RemoteDataPath, optional) – a RemoteDataPath instance. If not specified, valid kwargs must be provided
  • **kwargs – valid argument(s) for RemoteDataPath()
set_input(name, path=None, **kwargs)[source]

Sets the input of the given name.

The input value can be specified either as a RemoteDataPath instance or as valid keyword arguments to construct one.

Parameters:
  • name (str) – the input name to set
  • path (RemoteDataPath, optional) – a RemoteDataPath instance. If not specified, valid kwargs must be provided
  • **kwargs – valid argument(s) for RemoteDataPath()
set_parameter(name, val)[source]

Sets the (non-data) parameter of the given name.

Non-data parameters are parameters whose values are defined directly by a value that is JSON serializable.

Parameters:
  • name (str) – the input name to set
  • val – the parameter value, which must be JSON serializable
to_dict()

Generates a JSON dictionary representation of the object.

Returns:a JSON dictionary representation of the object
to_json(path)

Write the object to disk in JSON format.

Parameters:path (str) – the output JSON file path. The base output directory is created, if necessary
to_string()

Generates a string representation of the object.

Returns:a string representation of the object
class voxel51.jobs.JobState[source]

Bases: object

Enum describing the possible states of a job.

COMPLETE = 'COMPLETE'
FAILED = 'FAILED'
QUEUED = 'QUEUED'
READY = 'READY'
RUNNING = 'RUNNING'
class voxel51.jobs.RemoteDataPath(data_id=None, signed_url=None)[source]

Bases: voxel51.utils.Serializable

Class enapsulating a remote data path.

data_id

the ID of the data in cloud storage

Type:str
signed_url

a signed URL with access to the data of interest in third-party cloud storage

Type:str
classmethod from_data_id(data_id)[source]

Creates a RemoteDataPath instance defined by the given data ID.

Parameters:data_id (str) – the ID of the data in cloud storage
Returns:a RemoteDataPath instance with the given data ID
classmethod from_dict(d)[source]

Constructs a RemoteDataPath instance from a JSON dictionary.

Parameters:d (dict) – a JSON dictionary defining a RemoteDataPath instance
Returns:a RemoteDataPath instance
classmethod from_json(path)

Constructs a Serializable object from a JSON file.

Parameters:path (str) – the path to a JSON file
Returns:an instance of the Serializable subclass
classmethod from_signed_url(signed_url)[source]

Creates a RemoteDataPath instance defined by the given signed URL.

Parameters:signed_url (str) – a signed URL with access to the data of interest in third-party cloud storage
Returns:a RemoteDataPath instance with the given signed URL
classmethod from_string(s)

Constructs a Serializable object from a string representation of it.

Parameters:s (str) – a string representation of a Serializable subclass
Returns:an instance of the Serializable subclass
has_data_id

Determines whether this RemoteDataPath instance has a data ID.

Returns:True if this instance has a data ID, and False otherwise
has_signed_url

Determines whether this RemoteDataPath instance has a signed URL.

Returns:True if this instance has a signed URL, and False otherwise
static is_remote_path_dict(val)[source]

Determines whether the given value defines a valid RemoteDataPath dictionary.

Parameters:val – either a JSON dictionary representation of a RemoteDataPath instance or another arbitrary value
Returns:
True if val is a valid RemoteDataPath JSON dictionary, and False
otherwise
is_valid

Determines whether this RemoteDataPath instance is valid.

Returns:True if this instance is valid, and False otherwise
to_dict()

Generates a JSON dictionary representation of the object.

Returns:a JSON dictionary representation of the object
to_json(path)

Write the object to disk in JSON format.

Parameters:path (str) – the output JSON file path. The base output directory is created, if necessary
to_string()

Generates a string representation of the object.

Returns:a string representation of the object
exception voxel51.jobs.RemoteDataPathError[source]

Bases: exceptions.Exception

Error raised when an invalid RemoteDataPath instance is found.

args
message

voxel51.utils module

Utility functions for the Voxel51 Vision Services API.

Copyright 2017-2018, Voxel51, LLC
class voxel51.utils.Serializable[source]

Bases: object

Base class for objects that can be represented in JSON format.

classmethod from_dict(d)[source]

Constructs a Serializable object from a JSON representation of it. Subclasses must implement this method.

Parameters:d (dict) – a JSON dictionary representation of a Serializable subclass
Returns:an instance of the Serializable subclass
classmethod from_json(path)[source]

Constructs a Serializable object from a JSON file.

Parameters:path (str) – the path to a JSON file
Returns:an instance of the Serializable subclass
classmethod from_string(s)[source]

Constructs a Serializable object from a string representation of it.

Parameters:s (str) – a string representation of a Serializable subclass
Returns:an instance of the Serializable subclass
to_dict()[source]

Generates a JSON dictionary representation of the object.

Returns:a JSON dictionary representation of the object
to_json(path)[source]

Write the object to disk in JSON format.

Parameters:path (str) – the output JSON file path. The base output directory is created, if necessary
to_string()[source]

Generates a string representation of the object.

Returns:a string representation of the object
voxel51.utils.copy_file(inpath, outpath)[source]

Copies the input file to the output location.

The base output directory is created, if necessary.

Parameters:
  • inpath (str) – the input file
  • output (str) – the output file location
voxel51.utils.ensure_basedir(path)[source]

Makes the base directory of the given path, if necessary.

Parameters:path (str) – a file path
voxel51.utils.json_to_str(obj)[source]

Generates a string representation of the JSON object.

Parameters:obj – an object that can be directly dumped to a JSON file
Returns:a string representation of the JSON object
voxel51.utils.read_json(path)[source]

Reads JSON from file.

Parameters:path (str) – the input path
Returns:a JSON list/dictionary
voxel51.utils.write_json(obj, path)[source]

Writes JSON object to file, creating the output directory if necessary.

Parameters:
  • obj – an object that can be directly dumped to a JSON file
  • path (str) – the output path

Module contents

Copyright 2017-2018, Voxel51, LLC