This class provides methods to make http requests slightly easier.
It’s a wrapper around httplib2 to allow for a bit of state to be stored (like the service root) so that you don’t need to repeat yourself as much.
It’s not intended to be used directly. Children classes should implement methods that actually call out to the api methods.
When you define your API’s methods you’ll want to just call out to the _get, _post, _put or _delete methods provided by this class.
Initialize a PistonAPI.
service_root is the url to the server’s service root. Children classes can provide a default_service_root class attribute that will be used if service_root is None.
timeout will be used as a socket timeout for all calls this instance makes. To explicitly set no timeout, set timeout=0. The default timeout=None will first check for an environment variable PISTON_MINI_CLIENT_DEFAULT_TIMEOUT and try to use that. If this environment variable is not found or it is an invalid float, the class’s default_timeout will be used. Finally, if the class’s default is also None, Python’s default timeout for sockets will be used. All these should be in seconds.
For all other arguments, see PistonRequester.
Perform an HTTP GET request.
The provided path is appended to this resource’s _service_root attribute to obtain the absolute URL that will be requested.
If provided, args should be a dict specifying additional GET arguments that will be encoded on to the end of the url.
scheme must be one of http or https, and will determine the scheme used for this particular request. If not provided the service_root’s scheme will be used.
extra_headers is an optional dictionary of header key/values that will be added to the http request.
Perform an HTTP POST request.
The provided path is appended to this api’s _service_root attribute to obtain the absolute URL that will be requested. data should be:
- A string, in which case it will be used directly as the request’s body, or
- A list, dict, int, bool or PistonSerializable (something with an as_serializable method) or even None, in which case it will be serialized into a string according to content_type.
If content_type is None, self.default_content_type will be used.
scheme must be one of http or https, and will determine the scheme used for this particular request. If not provided the service_root’s scheme will be used.
extra_headers is an optional dictionary of header key/values that will be added to the http request.
Perform an HTTP PUT request.
The provided path is appended to this api’s _service_root attribute to obtain the absolute URL that will be requested. data should be:
- A string, in which case it will be used directly as the request’s body, or
- A list, dict, int, bool or PistonSerializable (something with an as_serializable method) or even None, in which case it will be serialized into a string according to content_type.
If content_type is None, self.default_content_type will be used.
scheme must be one of http or https, and will determine the scheme used for this particular request. If not provided the service_root’s scheme will be used.
extra_headers is an optional dictionary of header key/values that will be added to the http request.
Perform an HTTP DELETE request.
The provided path is appended to this resource’s _service_root attribute to obtain the absolute URL that will be requested.
scheme must be one of http or https, and will determine the scheme used for this particular request. If not provided the service_root’s scheme will be used.
extra_headers is an optional dictionary of header key/values that will be added to the http request.
Base class for objects that are returned from api calls.
Base class for objects that want to be used as api call arguments.
Children classes should at least redefine _atts to state the list of attributes that will be serialized into each request.
Return a serializable representation of this object.
These decorators can be applied to your PistonAPI methods to control how the retrieved data is handled.
The response data will be deserialized using a simple JSON decoder
The response data will be deserialized into an instance of cls.
The provided class should be a descendant of PistonResponseObject, or some other class that provides a from_response method.
none_allowed, defaulting to False, specifies whether or not None is a valid response. If True then the api can return None instead of a PistonResponseObject.
The response data will be deserialized into a list of cls.
The provided class should be a descendant of PistonResponseObject, or some other class that provides a from_response method.
These decorators can be applied to your PistonAPI methods to control how your method arguments are validated.
Validate argument varname against regex pattern pattern.
The provided argument for varname will need to inherit from basestring.
If required is False then the argument can be omitted entirely. Your method signature will need to provide a default value in this case.
Check that argument varname is of class cls.
If required is False then the argument can be omitted entirely. Your method signature will need to provide a default value in this case.
Check that argument varname is between min and max.
The provided argument for varname will need to be of type int.
If required is False then the argument can be omitted entirely. Your method signature will need to provide a default value in this case.
Only allow a method to be called with an OAuthAuthorizer available.
To be able to call the method you’ve decorated you’ll need to instantiate the PistonAPI providing a valid OAuthAuthorizer.
Only allow a method to be called with an BasicAuthorizer available.
To be able to call the method you’ve decorated you’ll need to instantiate the PistonAPI providing a valid BasicAuthorizer.
A fail handler is passed the raw httplib2 response and body, and has a chance to raise an exception, modify the body or return it unaltered, or even return a completely different object. It’s up to the client (and possibly decorators) to know what to do with these returned objects.
A base class for fail handlers.
Child classes should at least define handle()
Returns True if ‘response’ is a failure
A fail handler that will raise APIErrors if anything goes wrong
Raise APIError if a strange status code is found
A fail handler that returns error information in a dict
Return a dict if a strange status code is found.
A fail handler that returns None if anything goes wrong.
You probably only want to use this if you really don’t care about what went wrong.
Return None if a strange status code is found
A fail handler that raises an exception according to what goes wrong
Return an exception according to what went wrong.
Classes that define ways for your API methods to serialize arguments into a request.
A serializer that renders JSON.
This is the default serializer for content type application/json.
Serialize obj into JSON.
As well as the usual basic JSON-encodable types, this serializer knows how to serialize PistonSerializable objects.
A serializer that renders form-urlencoded content.
This is the default serializer for content type application/x-www-form-urlencoded.
Note
this serializer doesn’t support nested structures.
It should be initialized with a dictionary, sequence of pairs, or PistonSerializable.
Classes for adding authentication headers to your API requests.
You usually want to pass in an instance of one of these classes when you instantiate a PistonAPI object.