API Documentation

Base API

Base class for the library. Describes the API that should be consumed for optimal TopChefiness.

class topchef_client.api.Client(url, http_library=<module 'requests' from '/home/docs/checkouts/readthedocs.org/user_builds/topchef-client/envs/latest/local/lib/python2.7/site-packages/requests/__init__.pyc'>)

The main entry point for the TopChef API. This is the base object which will be used to communicate with the API.

class AbstractServicesGetter

Describes the interface for getting services from the TopChef API. This type should behave in a similar way to that of the dict type.

One MUST be allowed to get services using the __getitem__ method. Iteration should also be allowed over all services on the API.

__getitem__(service_uuid)

Parameters:or UUID service_uuid (str) – The UUID matching that of the service. Returns:The service with service_id matching that of the UUID Return type:Service Raises:ServiceNotFoundError if the service cannot be found

__iter__()

Returns:An iterator over all the services registered on the API

__len__()

Returns:The number of services registered on this API Return type:int

__next__()

Returns:The next service to be iterated over

__weakref__

list of weak references to the object (if defined)

class Client._TopChefServicesGetter(client)

Provides a means of getting services, implementing AbstractServicesGetter

__getitem__(service_uuid)

Parameters:service_uuid – Return a service by a given UUID Returns:The service with the given UUID, if it exists Return type:Service Raises:ServiceNotFoundError

__init__(client)

Parameters:client (Client) – The TopChef API client to which this instance is attached

__iter__()

Returns:Since this type is iterable, return itself

__len__()

Returns:The number of services on the API

__next__()

Returns:The next service in the mapping of iterables

_data_from_services_request

Returns:The parsed JSON from the request to the services endpoint, containing just the data Return type:dict

_handle_iterator_stop()

Clear the last iterated index and throw StopIteration

_handle_nonexistent_service(service)

Parameters:service – The non-existent service Raises:ServiceNotFoundError

_http_library

Returns:The library to use for HTTP requests

_services_url

Returns:The URL to which requests for services are to be made

content_type_header

Returns:The header indicating that the HTTP request to the

services endpoint is to be made in JSON

Client.__init__(url, http_library=<module 'requests' from '/home/docs/checkouts/readthedocs.org/user_builds/topchef-client/envs/latest/local/lib/python2.7/site-packages/requests/__init__.pyc'>)

Parameters:

• url (str) – The base URL to the TopChef API
• http_library (mod) – The library to use for making HTTP requests. By default, this is requests, but it can be overwritten for testing

Client.__weakref__

list of weak references to the object (if defined)

Client.http_library

Provides read-only access to the library used to make HTTP calls

Returns:The current HTTP library

Client.services

Returns:The services available on the API. Return type:Client.AbstractServicesGetter

Client.services_url

Returns:The URL where broad information is kept on the services registered with the API

Models

TopChef Job

Describes a TopChef Job

class topchef_client.models.job.Job(topchef_url, job_id, http_library=<module 'requests' from '/home/docs/checkouts/readthedocs.org/user_builds/topchef-client/envs/latest/local/lib/python2.7/site-packages/requests/__init__.pyc'>)

Base class for a job

__init__(topchef_url, job_id, http_library=<module 'requests' from '/home/docs/checkouts/readthedocs.org/user_builds/topchef-client/envs/latest/local/lib/python2.7/site-packages/requests/__init__.pyc'>)

Parameters:

• topchef_url (str) – The base URL to the TopChef API
• job_id (UUID) – The Job ID
• http_library (mod) – The library to use for making HTTP requests

__weakref__

list of weak references to the object (if defined)

job_details

Returns:The details for the job

job_details_endpoint

Returns:The URL to the job details Return type:str

result

Returns:The result for the job Return type:object

TopChef Service

Describes a TopChef service

class topchef_client.models.service.Service(service_id, topchef_url, http_library=<module 'requests' from '/home/docs/checkouts/readthedocs.org/user_builds/topchef-client/envs/latest/local/lib/python2.7/site-packages/requests/__init__.pyc'>)

Represents a TopChef service

__init__(service_id, topchef_url, http_library=<module 'requests' from '/home/docs/checkouts/readthedocs.org/user_builds/topchef-client/envs/latest/local/lib/python2.7/site-packages/requests/__init__.pyc'>)

Parameters:

• service_id – The ID for the service
• topchef_url – The base URL for the TopChef API
• http_library – The library to use for HTTP requests

__weakref__

list of weak references to the object (if defined)

_get_data()

Returns:A dictionary representing the details for a service

static _handle_http_error(response_code)

Parameters:response_code – The offending status code Raises:NetworkError

static _handle_job_not_created_error(status_code)

Parameters:status_code – The offending status code Raises:NetworkError

_service_endpoint

Returns:A URL for getting details for a particular service Return type:str

does_service_exist

Returns:A boolean that is true if the service exists. A sufficient

condition for existence of the service is if the GET request to the service endpoint returns the OK status code

job_registration_schema

Returns:The schema that must be satisfied in order to post jobs to this service Return type:dict

new_job(parameters, validator_factory=<class 'topchef_client.models.validator.Validator'>)

Parameters:

• parameters (dict) – The parameters to use for the job
• validator_factory (type) – The JSON Schema validator to use for checking the parameters

Returns:

The newly-created job

Return type:

Job

Remote JSON Schema Validator

Describes a JSON schema validator

class topchef_client.models.validator.Validator(topchef_url, http_library=<module 'requests' from '/home/docs/checkouts/readthedocs.org/user_builds/topchef-client/envs/latest/local/lib/python2.7/site-packages/requests/__init__.pyc'>)

Validates schemas

class AbstractValidator

Describes the interface for an object capable of validating JSON schemas. This object does the heavy lifting for validating JSON. It also helps with testing as the validation procedure can be stubbed out more efficiently.

__weakref__

list of weak references to the object (if defined)

does_instance_match_schema(instance, schema)

Parameters:

• instance (dict) – The instance to validate
• schema (dict) – The schema against which the instance is to be validated

class Validator.RemoteSchemaValidator(topchef_url, http_library=<module 'requests' from '/home/docs/checkouts/readthedocs.org/user_builds/topchef-client/envs/latest/local/lib/python2.7/site-packages/requests/__init__.pyc'>)

Perfoms validation remotely using the TopChef API

__init__(topchef_url, http_library=<module 'requests' from '/home/docs/checkouts/readthedocs.org/user_builds/topchef-client/envs/latest/local/lib/python2.7/site-packages/requests/__init__.pyc'>)

Parameters:

• topchef_url (str) – The URL for the TopChef API
• http_library (mod) – The library to use for HTTP requests

_analyze_validation_response(response)

Analyze whether the validation request was successful or not based on the status code of the response

Parameters:response (requests.Response) – The response to analyze Returns:True if the status code is correct, and False if otherwise Raises:NetworkError if an unexpected status code is received

static _get_request_body(instance, schema)

Format a request for the body of the POST request for the TopChef JSON Schema validator

Parameters:

• instance (dict) – The instance to validate
• schema (dict) – The schema against which the instance is to be validated

_validator_endpoint

Returns:The URL for the JSON schema validator

does_instance_match_schema(instance, schema)

Parameters:

• instance (dict) – The instance to validate
• schema (dict) – The schema against which the instance is to be validated

Returns:

True if the instance matches the schema

Raises:

NetworkError if an unexpected status code is received

Validator.__init__(topchef_url, http_library=<module 'requests' from '/home/docs/checkouts/readthedocs.org/user_builds/topchef-client/envs/latest/local/lib/python2.7/site-packages/requests/__init__.pyc'>)

Parameters:

• topchef_url – The URL for the TopChef API
• http_library – The library to use for HTTP calls

Validator.__weakref__

list of weak references to the object (if defined)

Validator.assert_instance_matches_schema(instance, schema, validator=None)

Parameters:

• instance (dict) – The instance to validate
• schema (dict) – The schema against which the instance is to be validated
• validator (AbstractValidator) – The validator to use. If this is None, a RemoteSchemaValidator will be constructed

Returns:

True if the instance matches the schema

Raises:

NetworkError if an unexpected status code is received

Service Listener

Contains a class that provides a method for working

In the context of the API, a service is a resource capable of polling the API, taking in a single JSON object corresponding to a schema, and returning a result which is a valid instance of a result schema. A job is a resource which contains a parameter dictionary satisfying the service schema.

In order to use this client, Client needs to be subclassed, and its run() method needs to be implemented. The argument of run() is guaranteed to satisfy the service’s job registration schema. However, the onus is on the user to ensure that the return value satisfies the job result schema of the job’s service.

In accordance with the Python convention, properties and methods beginning with _ are private.

class topchef_client.service_listener.ServiceListener(address, service_id, timeout=30)

Abstract base class that consumes the TopChef API, passes the parameters to run(), and returns the result to the server. The work is done in a background thread.

The main thread of the application checks if there are any jobs available in a service’s queue. If there are jobs available, it executes run() with the job’s parameters.

__init__(address, service_id, timeout=30)

Initialize a client to listen on a server and look for jobs for the next service id

Parameters:

• address (str) – The hostname of the topchef API on which the client is to listen
• service_id (str) – The ID of the service that this client represents
• timeout (int) – The number of seconds that the polling thread should wait before sending a PATCH request to the server. The client contains a thread for polling the API periodically, so that the API knows that a particular service has an instance of a client bound to it, ready to accept jobs.

__weakref__

list of weak references to the object (if defined)

_first_job_id_in_queue

Returns the first ID of a job in the queue

Returns:The ID of the first job in the queue Return type:str

static _json_get(endpoint)

Obtain data from an endpoint and return the body of the request as a dictionary. This dictionary is built from the request body’s JSON.

Parameters:endpoint (str) – The URL from which data needs to be obtained Returns:The JSON from the endpoint Return type:dict Raises:NetworkError if the response status code from the request is not 200.

_polling_loop()

Starts an unescaped loop to poll the server.

Note

Should only be run in the polling thread. This will block your program if it’s run in the main thread.

_processing_loop()

Responsible for fetching the job parameters, running the run method, and validating the runner results against the result schema

_service_details

Returns the dictionary containing the details for the current service to which this client is bound.

Returns:The details for a service Return type:dict

classmethod check_in_to_server(address, service_id)

Send a PATCH request to the server to let the server know that this class still exists and is accepting jobs

Parameters:

• address (str) – The address that must be patched
• service_id (str) – The ID of the service that must be ``PATCH``ed

Raises:

NetworkError if the site cannot be ``PATCH``ed

current_job

Returns the current job that is to be worked on

Returns:A job that must be processed Return type:_Job

is_queue_empty

Returns True if the service’s queue is empty and False if not.

is_server_alive

Getter that returns True if the target server is up and running

Returns:True if a GET request to the API is successful and False if not Return type:bool

job_registration_schema

Returns the job registration schema

Returns:The schema that must be satisfied for a job to be registered Return type:dict

job_result_schema

Returns the schema that must be satisfied for a result to be posted

Returns:The job result schema Return type:dict

classmethod new_service(address, name, description, job_registration_schema, job_result_schema={'type': 'object'})

Create a new service and bind the client to accept jobs using this service

Parameters:

• address (str) – The hostname of the topchef API on which the client is to listen
• description (str) – The description that will accompany the newly-created service
• description – The service description
• job_registration_schema (dict) – The JSON schema that must be satisfied in order to submit a job
• job_result_schema (dict) – The schema that must be satisfied in order to produce a valid job result. By default, this schema is {"type": "object"}, meaning it matches all possible objects.

run(parameters)

Abstract method that should take in a dictionary of parameters and return a valid dictionary.

Raises:NotImplementedError if the method is not subclassed

run_iteration()

Run a single iteration of the processing loop. This is exposed to enable packaging of the Client’s main loop in a more elaborate multitasking system.

start(should_poll=True)

Start the client’s main processing loop. Start a polling loop in a separate thread

Parameters:should_poll (bool) – If true, then the polling thread will be started along with the processing thread

validate_schema(instance, schema)

POST to the API to check if a dictionary instance is a valid instance of the provided schema

Parameters:

• instance (dict) – The object that must be validated
• schema (dict) – The schema against which the instance is to be validated

Raises:

ValidationError if instance does not validate against schema

Raises:

NetworkError if a connection cannot be made to the validator endpoint

class topchef_client.service_listener._Job(address, job_dict)

A private representation of a TopChef job. This class is used as an adapter to make business logic clearer in client definitions.

__getitem__(item)

Returns the corresponding entry from this job’s job_dict

Parameters:item (str) – The key from the job dict that must be obtained Returns:the entry from the dictionary

__init__(address, job_dict)

Instantiates the variables listed in the class description

Parameters:

• address (str) – The base address of the TopChef server.
• job_dict (dict) – A dictionary representing the details of the job

__weakref__

list of weak references to the object (if defined)

_update()

Send a PUT request to the server with the updated job data

Raises:NetworkError if the update was not successful

id

Returns the job id

Returns:the Job ID Return type:str

result

Returns the job result

status

Returns the job status

Returns:The job status Return type:str