wsgiservice
– Reference¶
resource
¶
Every resource to be served with WsgiService should inherit from the wsgiservice.resource.Resource
class.
Resource
class¶
-
class
wsgiservice.resource.
Resource
(request, response, path_params, application=None)¶ Base class for all WsgiService resources. A resource is a unique REST endpoint which accepts different methods for different actions.
For each HTTP call the corresponding method (equal to the HTTP method) will be called.
-
OPTIONS
()¶ Default implementation of the OPTIONS verb. Outputs a list of allowed methods on this resource in the
Allow
response header.
-
assert_condition_etag
()¶ If the resource has an ETag (see
get_etag()
) the request headersIf-Match
andIf-None-Match
are verified. May abort the request with 304 or 412 response codes.Raises: webob.exceptions.ResponseException
of status 304 if the ETag matches theIf-None-Match
request header (GET/HEAD requests only).webob.exceptions.ResponseException
of status 412 if the ETag matches theIf-None-Match
request header (for requests other than GET/HEAD) or the ETag does not match theIf-Match
header.
-
assert_condition_last_modified
()¶ If the resource has a last modified date (see
get_last_modified()
) the request headersIf-Modified-Since
andIf-Unmodified-Since
are verified. May abort the request with 304 or 412 response codes.Raises: webob.exceptions.ResponseException
of status 304 if theIf-Modified-Since
is later than the last modified date.webob.exceptions.ResponseException
of status 412 if the last modified date is later than theIf-Unmodified-Since
header.
-
assert_condition_md5
()¶ If the
Content-MD5
request header is present in the request it’s verified against the MD5 hash of the request body. If they don’t match, a 400 HTTP response is returned.Raises: webob.exceptions.ResponseException
of status 400 if the MD5 hash does not match the body.
-
assert_conditions
()¶ Handles various HTTP conditions and raises HTTP exceptions to abort the request.
- Content-MD5 request header must match the MD5 hash of the full
input (
assert_condition_md5()
). - If-Match and If-None-Match etags are checked against the ETag of
this resource (
assert_condition_etag()
). - If-Modified-Since and If-Unmodified-Since are checked against
the modification date of this resource
(
assert_condition_last_modified()
).
Todo
Return a 501 exception when any Content-* headers have been set in the request. (See RFC 2616, section 9.6)
- Content-MD5 request header must match the MD5 hash of the full
input (
-
call_method
(method_name)¶ Call an instance method filling in all the method parameters based on their names. The parameters are filled in from the following locations (in that order of precedence):
- Path parameters from routing
- GET parameters
- POST parameters
All values are validated using the method
validate_param()
. The return value of the method is returned unaltered.Parameters: method_name (str) – Name of the method on the current instance to call.
-
clean_etag
(etag)¶ Cleans the ETag as returned by
get_etag()
. Will wrap it in quotes and append the extension for the current MIME type.
-
convert_param
(method, param, value)¶ Converts the parameter using the function ‘convert’ function of the validation rules. Same parameters as the validate_param method, so it might have just been added there. But lumping together the two functionalities would make overwriting harder.
Parameters: - method (Python function) – A function to get the validation information from (done
using
_get_validation()
). - param (str) – Name of the parameter to validate the value for.
- value (Any valid Python value) – Value passed in for the given parameter.
Raises: wsgiservice.exceptions.ValidationException
if the value is invalid for the given method and parameter.- method (Python function) – A function to get the validation information from (done
using
-
convert_response
()¶ Finish filling the instance’s response object so it’s ready to be served to the client. This includes converting the body_raw property to the content type requested by the user if necessary.
-
data
¶ Returns the request data as a dictionary.
Merges the path parameters, GET parameters and POST parameters (form-encoded or JSON dictionary). If a key is present in multiple of these, the first one defined is used.
-
get_allowed_methods
()¶ Returns a coma-separated list of method names that are allowed on this instance. Useful to set the
Allowed
response header.
-
get_content_type
()¶ Returns the Content Type to serve from either the extension or the Accept headers. Uses the
EXTENSION_MAP
list for all the configured MIME types.
-
get_etag
()¶ Returns a string to be used as the ETag for this resource. Used to set the
ETag
response headers and for conditional requests using theIf-Match
andIf-None-Match
request headers.
-
get_last_modified
()¶ Return a
datetime.datetime
object of the when the resource was last modified. Used to set theLast-Modified
response header and for conditional requests using theIf-Modified-Since
andIf-Unmodified-Since
request headers.Return type: datetime.datetime
-
get_method
(method=None)¶ Returns the method to call on this instance as a string. Raises a HTTP exception if no method can be found. Aborts with a 405 status code for known methods (based on the
KNOWN_METHODS
list) and a 501 status code for all other methods.Parameters: method (str) – Name of the method to return. Must be all-uppercase. Raises: webob.exceptions.ResponseException
of status 405 or 501 if the method is not implemented on this resource.
-
get_request_data
()¶ Read the input values.
Returns a list of dictionaries. These will be used to automatically pass them into the method.
Additionally a combined dictionary is written to self.data.
In the case of JSON input, that element in this list will be the parsed JSON value. That may not be a dictionary.
-
get_resource
(resource, **kwargs)¶ Returns a new instance of the resource class passed in as resource. This is a helper to make future-compatibility easier when new arguments get added to the constructor.
Parameters: - resource (
Resource
) – Resource class to instantiate. Gets called with the named arguments as required for the constructor. - kwargs (dict) – Additional named arguments to pass to the constructor function.
- resource (
-
handle_exception
(e, status=500)¶ Handle the given exception. Log, sets the response code and output the exception message as an error message.
Parameters: - e (
Exception
) – Exception which is being handled. - status (int) – Status code to set.
- e (
-
handle_exception_404
(e)¶ Handle the given exception. Log, sets the response code to 404 and output the exception message as an error message.
Parameters: e ( Exception
) – Exception which is being handled.
-
handle_ignored_resources
()¶ Ignore robots.txt and favicon.ico GET requests based on a list of absolute paths in
IGNORED_PATHS
. Aborts the request with a 404 status code.This is mostly a usability issue to avoid extra log entries for resources we are not interested in.
Raises: webob.exceptions.ResponseException
of status 404 if the resource is ignored.
-
set_response_content_md5
()¶ Set the Content-MD5 response header. Calculated from the the response body by creating the MD5 hash from it.
-
set_response_content_type
()¶ Set the Content-Type in the response. Uses the
type
instance attribute which was set byget_content_type()
. Also declares a UTF-8 charset.
-
set_response_headers
()¶ Sets all the calculated response headers.
-
to_application_json
(raw)¶ Returns the JSON version of the given raw Python object.
Parameters: raw (Any valid Python value) – The return value of the resource method. Return type: string
-
to_text_xml
(raw)¶ Returns the XML string version of the given raw Python object. Uses
_get_xml_value()
which applies some heuristics for converting data to XML.The default root tag is ‘response’, but that can be overwritten by changing the
XML_ROOT_TAG
instance variable.Uses
wsgiservice.xmlserializer.dumps()
for the actual work.Parameters: raw (Any valid Python value) – The return value of the resource method. Return type: string
-
validate_param
(method, param, value)¶ Validates the parameter according to the configurations in the _validations dictionary of either the method or the instance. This dictionaries are written by the decorator
wsgiservice.decorators.validate()
.Todo
Allow validation by type (e.g. header, post, query, etc.)
Parameters: - method (Python function) – A function to get the validation information from (done
using
_get_validation()
). - param (str) – Name of the parameter to validate the value for.
- value (Any valid Python value) – Value passed in for the given parameter.
Raises: wsgiservice.exceptions.ValidationException
if the value is invalid for the given method and parameter.- method (Python function) – A function to get the validation information from (done
using
-
Help
class¶
-
class
wsgiservice.resource.
Help
(request, response, path_params, application=None)¶ Bases:
wsgiservice.resource.Resource
Provides documentation for all resources of the current application.
Todo
Allow documentation of output.
Todo
Use first sentence of docstring for summary, add bigger version at the bottom.
-
GET
()¶ Returns documentation for the application.
-
to_text_html
(raw)¶ Returns the HTML string version of the given raw Python object. Hard-coded to return a nicely-presented service information document.
Parameters: raw (Any valid Python object) – The return value of the resource method. Return type: string Todo
Treat paragraphs and/or newlines better in output.
-
to_text_html_methods
(retval, resource)¶ Add the methods of this resource to the HTML output.
Parameters: - retval (list) – The list of strings which is used to collect the HTML response.
- resource (Dictionary) – The documentation of one resource.
-
decorators
¶
-
wsgiservice.decorators.
expires
(duration, vary=None, currtime=<built-in function time>)¶ Decorator. Apply on a
wsgiservice.Resource
method to set the max-age cache control parameter to the given duration. Also calculates the correctExpires
response header.Parameters: - duration (
datetime.timedelta
) – Age which this resource may have before becoming stale. - vary (list of strings) – List of headers that should be added to the Vary response header.
- currtime (Function returning a
time.struct_time
) – Function used to find out the current UTC time. This is used for testing and not required in production code.
- duration (
-
wsgiservice.decorators.
mount
(path)¶ Decorator. Apply on a
wsgiservice.Resource
to mount it at the given path. The same can be achieved by setting the_path
attribute on the class directly.Parameters: path – A path to mount this resource on. See wsgiservice.routing.Router
for a description of how this path has to be formatted.
-
wsgiservice.decorators.
validate
(name, re=None, convert=None, doc=None)¶ Decorator. Apply on a
wsgiservice.Resource
or any of it’s methods to validates a parameter on input. When a parameter does not validate, awsgiservice.exceptions.ValidationException
exception will be thrown.Parameters: - name (string) – Name of the input parameter to validate.
- re (regular expression) – Regular expression to search for in the input parameter. If this is not set, just validates if the parameter has been set.
- convert (callable) – Callable to convert the validated parameter value to the final data type. Ideal candidates for this are the built-ins int or float functions. If the function raises a ValueError, this is reported to the client as a 400 error.
- doc (string) – Parameter description for the API documentation.
status
¶
Helper methods to raise responses for the various HTTP status codes.
The motivation for these methods is to be able to easily document the HTTP
response headers which are highly recommended or required. For example the
Location
header which should be set for 201 responses.
The following status codes don’t have a method here:
-
wsgiservice.status.
raise_200
(instance)¶ Abort the current request with a 200 (OK) response code.
Parameters: instance ( webob.resource.Resource
) – Resource instance (used to access the response)Raises: webob.exceptions.ResponseException
of status 200
-
wsgiservice.status.
raise_201
(instance, location)¶ Abort the current request with a 201 (Created) response code. Sets the Location header correctly. If the location does not start with a slash, the path of the current request is prepended.
Parameters: instance ( webob.resource.Resource
) – Resource instance (used to access the response)Raises: webob.exceptions.ResponseException
of status 201
-
wsgiservice.status.
raise_202
(instance)¶ Abort the current request with a 202 (Accepted) response code.
Parameters: instance ( webob.resource.Resource
) – Resource instance (used to access the response)Raises: webob.exceptions.ResponseException
of status 202
-
wsgiservice.status.
raise_204
(instance)¶ Abort the current request with a 204 (No Content) response code. Clears out the body of the response.
Parameters: instance ( webob.resource.Resource
) – Resource instance (used to access the response)Raises: webob.exceptions.ResponseException
of status 204
-
wsgiservice.status.
raise_205
(instance)¶ Abort the current request with a 205 (Reset Content) response code. Clears out the body of the response.
Parameters: instance ( webob.resource.Resource
) – Resource instance (used to access the response)Raises: webob.exceptions.ResponseException
of status 205
-
wsgiservice.status.
raise_300
(instance)¶ Abort the current request with a 300 (Multiple Choices) response code.
Parameters: instance ( webob.resource.Resource
) – Resource instance (used to access the response)Raises: webob.exceptions.ResponseException
of status 300
-
wsgiservice.status.
raise_301
(instance, location)¶ Abort the current request with a 301 (Moved Permanently) response code. Sets the Location header correctly. If the location does not start with a slash, the path of the current request is prepended.
Parameters: instance ( webob.resource.Resource
) – Resource instance (used to access the response)Raises: webob.exceptions.ResponseException
of status 301
-
wsgiservice.status.
raise_302
(instance, location)¶ Abort the current request with a 302 (Found) response code. Sets the Location header correctly. If the location does not start with a slash, the path of the current request is prepended.
Parameters: instance ( webob.resource.Resource
) – Resource instance (used to access the response)Raises: webob.exceptions.ResponseException
of status 302
-
wsgiservice.status.
raise_303
(instance, location)¶ Abort the current request with a 303 (See Other) response code. Sets the Location header correctly. If the location does not start with a slash, the path of the current request is prepended.
Parameters: instance ( webob.resource.Resource
) – Resource instance (used to access the response)Raises: webob.exceptions.ResponseException
of status 303
-
wsgiservice.status.
raise_304
(instance)¶ Abort the current request with a 304 (Not Modified) response code. Clears out the body of the response.
Parameters: instance ( webob.resource.Resource
) – Resource instance (used to access the response)Raises: webob.exceptions.ResponseException
of status 304
-
wsgiservice.status.
raise_305
(instance, location)¶ Abort the current request with a 305 (Use Proxy) response code. Sets the Location header correctly. If the location does not start with a slash, the path of the current request is prepended.
Parameters: instance ( webob.resource.Resource
) – Resource instance (used to access the response)Raises: webob.exceptions.ResponseException
of status 305
-
wsgiservice.status.
raise_307
(instance, location)¶ Abort the current request with a 307 (Temporary Redirect) response code. Sets the Location header correctly. If the location does not start with a slash, the path of the current request is prepended.
Parameters: instance ( webob.resource.Resource
) – Resource instance (used to access the response)Raises: webob.exceptions.ResponseException
of status 307
-
wsgiservice.status.
raise_400
(instance, msg=None)¶ Abort the current request with a 400 (Bad Request) response code. If the message is given it’s output as an error message in the response body (correctly converted to the requested MIME type).
Parameters: instance ( webob.resource.Resource
) – Resource instance (used to access the response)Raises: webob.exceptions.ResponseException
of status 400
-
wsgiservice.status.
raise_401
(instance, authenticate, msg=None)¶ Abort the current request with a 401 (Unauthorized) response code. If the message is given it’s output as an error message in the response body (correctly converted to the requested MIME type). Outputs the WWW-Authenticate header as given by the authenticate parameter.
Parameters: instance ( webob.resource.Resource
) – Resource instance (used to access the response)Raises: webob.exceptions.ResponseException
of status 401
-
wsgiservice.status.
raise_402
(instance, msg=None)¶ Abort the current request with a 402 (Payment Required) response code. If the message is given it’s output as an error message in the response body (correctly converted to the requested MIME type).
Parameters: instance ( webob.resource.Resource
) – Resource instance (used to access the response)Raises: webob.exceptions.ResponseException
of status 402
-
wsgiservice.status.
raise_403
(instance, msg=None)¶ Abort the current request with a 403 (Forbidden) response code. If the message is given it’s output as an error message in the response body (correctly converted to the requested MIME type).
Parameters: instance ( webob.resource.Resource
) – Resource instance (used to access the response)Raises: webob.exceptions.ResponseException
of status 403
-
wsgiservice.status.
raise_404
(instance)¶ Abort the current request with a 404 (Not Found) response code.
Parameters: instance ( webob.resource.Resource
) – Resource instance (used to access the response)Raises: webob.exceptions.ResponseException
of status 404
-
wsgiservice.status.
raise_405
(instance)¶ Abort the current request with a 405 (Method Not Allowed) response code. Sets the
Allow
response header to the return value of theResource.get_allowed_methods()
function.Parameters: instance ( webob.resource.Resource
) – Resource instance (used to access the response)Raises: webob.exceptions.ResponseException
of status 405
-
wsgiservice.status.
raise_406
(instance)¶ Abort the current request with a 406 (Not Acceptable) response code.
Parameters: instance ( webob.resource.Resource
) – Resource instance (used to access the response)Raises: webob.exceptions.ResponseException
of status 406
-
wsgiservice.status.
raise_409
(instance)¶ Abort the current request with a 409 (Conflict) response code.
Parameters: instance ( webob.resource.Resource
) – Resource instance (used to access the response)Raises: webob.exceptions.ResponseException
of status 409
-
wsgiservice.status.
raise_410
(instance)¶ Abort the current request with a 410 (Gone) response code.
Parameters: instance ( webob.resource.Resource
) – Resource instance (used to access the response)Raises: webob.exceptions.ResponseException
of status 410
-
wsgiservice.status.
raise_412
(instance, msg=None)¶ Abort the current request with a 412 (Precondition Failed) response code. If the message is given it’s output as an error message in the response body (correctly converted to the requested MIME type).
Parameters: instance ( webob.resource.Resource
) – Resource instance (used to access the response)Raises: webob.exceptions.ResponseException
of status 412
-
wsgiservice.status.
raise_415
(instance, msg=None)¶ Abort the current request with a 415 (Unsupported Media Type) response code. If the message is given it’s output as an error message in the response body (correctly converted to the requested MIME type).
Parameters: instance ( webob.resource.Resource
) – Resource instance (used to access the response)Raises: webob.exceptions.ResponseException
of status 415
-
wsgiservice.status.
raise_500
(instance, msg=None)¶ Abort the current request with a 500 (Internal Server Error) response code. If the message is given it’s output as an error message in the response body (correctly converted to the requested MIME type).
Parameters: instance ( webob.resource.Resource
) – Resource instance (used to access the response)Raises: webob.exceptions.ResponseException
of status 500
-
wsgiservice.status.
raise_501
(instance)¶ Abort the current request with a 501 (Not Implemented) response code. Sets the
Allow
response header to the return value of theResource.get_allowed_methods()
function.Parameters: instance ( webob.resource.Resource
) – Resource instance (used to access the response)Raises: webob.exceptions.ResponseException
of status 501
-
wsgiservice.status.
raise_503
(instance)¶ Abort the current request with a 503 (Service Unavailable) response code.
Parameters: instance ( webob.resource.Resource
) – Resource instance (used to access the response)Raises: webob.exceptions.ResponseException
of status 503
application
¶
Components responsible for building the WSGI application.
-
class
wsgiservice.application.
Application
(resources)¶ WSGI application wrapping a set of WsgiService resources. This class can be used as a WSGI application according to PEP 333.
Parameters: resources – A list of wsgiservice.Resource
classes to be served by this application.Todo
Easy deployment using good configuration file handling
-
NOT_FOUND_RESOURCE
¶ alias of
wsgiservice.resource.NotFoundResource
-
-
wsgiservice.application.
get_app
(defs, add_help=True)¶ Small wrapper function to returns an instance of
Application
which serves the objects in the defs. Usually this is called with return value globals() from the module where the resources are defined. The returned WSGI application will serve all subclasses ofwsgiservice.Resource
found in the dictionary.Parameters: - defs (dict) – Each
wsgiservice.Resource
object found in the values of this dictionary is used as application resource. The other values are discarded. - add_help (boolean) – Whether to add the Help resource which will expose the documentation of this service at /_internal/help
Return type: - defs (dict) – Each
exceptions
¶
Declares different exceptions as used throughout WsgiService.
-
exception
wsgiservice.exceptions.
ResponseException
(response)¶ Wraps a
webob.Response
object to be thrown as an exception.
-
exception
wsgiservice.exceptions.
ValidationException
(*args, **kwargs)¶ Exception thrown when a validation fails. See
wsgiservice.decorators.validate()
for it’s use.
routing
¶
Implements a simple routing class.
-
class
wsgiservice.routing.
Router
(resources)¶ Simple routing. Path parameters can be extracted with the syntax
{keyword}
where keyword is the path parameter. That parameter will then be passed on to the called request method.Parameters: resources – A list of wsgiservice.Resource
classes to be routed to.