Bases: pluggdapps.plugin.Interface
Interface specification for resolving application request to view callable. A plugin implementing this interfaces, typically, compares request’s url, method and few other header fields with pre-configured router mapping, added via add_view() method, and resolve the request to view callable.
The router plugin will be instantiated by the web-application during boot time and re-used till the platform is shutdown.
Chained call from IWebApp.startapp(). Implementation can chain this onboot() call further down to other framwork / application plugins.
While building a web application, this method can be used to configure url route-mapping by calling add_view() or by parsing a mapper file. In any case, when this method returns, route-mapping must be compiled and cached for resolving request’s view-callables.
A view is the representation of a resource. During boot-time applications can add resource representation as callables using this API. Since there can be more than one representation of a resource, there can be more than one view-callable for the same request-URL. In which case the view callable had to be resolved based on request predicates.
args and kwargs specific to router plugins, for more details refer to the corresponding router plugin.
Resolve request to view-callable. For a successful match, populate relevant attributes, like matchdict and view, in request plugin. A view-callable can be a plain python callable that accepts request and context arguments or a plugin implementing IHTTPView interface.
Generate path, including query and fragment (aka anchor), for request using positional arguments args and keyword arguments kwargs. Refer to corresponding router plugin for specific signature for positional and key-word arguments. Returns urlpath string. This does not include SCRIPT_NAME, netlocation and scheme.
Callback for asyncrhonous finish(). Means the response is sent and the request is forgotten. Chained call originating from IHTTPResponse.onfinish().
Bases: pluggdapps.plugin.Interface
Interface specification to handle server side negotiation for resource variant.
When the router finds that a resource (typically indicated by the request-URL) has multiple representations, where each representation is called a variant, it has to pick the best representation negotiated by the client. Negotiation is handled through attributes like media-type, language, charset and content-encoding.
Returns the best matching variant from variants.
Bases: pluggdapps.plugin.Interface
Interface specification for resource or model plugins. Resource plugins can be configured for view-callables. In which case they are expected to be called before calling view-callable. They can lookup backend database and populate context that can be consumed by view-callable and view-template.
Resource object to gather necessary data before a request is handled by the view (and templates). Return updated pluggdapps.utils.lib.Context. The context dictionary is also preserved in the pluggdapps.web.interfaces.IHTTPResponse plugin for chunked transfer-encoding.
Bases: pluggdapps.plugin.Interface
Handle HTTP cookies. This specification is compatible with IHTTPRequest and python’s Cookie standard library.
Use HTTP headers dictionary, to parse cookie name/value pairs, along with its meta-information, into Cookie Morsels. Get the cookie string from headers like,
1 | headers.get( 'cookie', '' )
|
Return a SimpleCookie object from python’s standard-library.
Update cookies dictionary with cookie name and its morsel. Optional Key-word arguments, typically, contain domain, expires_days, expires, path, which are set on the Cookie.Morsel directly.
See http://docs.python.org/library/cookie.html#morsel-objects for available attributes.
Encode name and value string into byte-string using ‘utf-8’ encoding settings, convert value into base64. Return signed value as string,:
<base64-encoded-value>|<timestamp>|<signature>
<signature> is generated using a secret, name, base64 encoded value and timestamp-in-seconds.
Bases: pluggdapps.plugin.Interface
Interface specification to encapulate HTTP request.
IHTTPConnection plugin instance. Initialized during plugin instantiation.
HTTP request method, e.g. b’GET’ or b’POST’. Initialized during plugin instantiation.
HTTP Request URI in byte-string as found in request start-line. Initialized during plugin instantiation.
HTTP protocol version found in request start-line, e.g. b’HTTP/1.1’. Initialized during plugin instantiation.
Dictionary-like object for HTTP headers. Key name are in string, while values are in byte-string. Initialized during plugin instantiation.
Request body, if present, as a byte string.
List of request chunks. Matching view-callable will be called for every request chunk, stored as the last element in this list, that are received. It is upto the application logic to clear previous chunks or to preserve them, until the request is finished.
Similar to headers attribute. But received after the last chunk of request in chunked transfer-coding.
UserDict object of uri parts in decoded, parsed and unquoted form. scheme, netloc, path, query, fragment, username, password, hostname, port, script, keys are available. Except query, which is a dictionary of query arguments, all other values are in string.
A dictionary of http.cookies.Morsel objects representing request ” cookies from client.
GET arguments are available in the params property, which maps parameter names to lists of values (to support multiple values for individual names). Names and values are are of type str, where, response.charset will be used to decode the byte values.
POST arguments are available in the params property, which maps parameter names to lists of values (to support multiple values for individual names). Names and values are are of type str, where, response.charset will be used to decode the byte values.
POST arguments in multipart format (like uploaded file content) are available as a dictionary of name,value pairs.
Combined arguments of GET/POST, which maps parameter names to lists of values (to support multiple values for individual names). Names and values are are of type str, where, response.charset will be used to decode the byte values.
File uploads are available in this attribute as a dictionary of name and a list of files submited under name. File is a dictionary of,:
{ 'filename' : ...,
'value' : ...,
'content-type' : ... }
If a session factory has been configured, this attribute will represent the current user’s session object.
IHTTPCookie plugin instance to handle request and response cookies.
Response object corresponding to this request. The object is an instance of plugin implementing IHTTPResponse interface.
IHTTPRouter plugin resolving this request.
Optinal dictionary attribute that contains maps a variable portion of url with matched value.
A view-callable resolved for this request.
When a view is resolved, along with that an optional resource callable might be available. If so this attribute can be one of the following,
- plugin implementing IHTTPResource interface.
- An importable string which points to a callable object.
- Or any python callable object.
Timestamp when request was recieved
Timestamp when request was finished.
Instance of plugin implementing this interface corresponds to a single HTTP request. Note that instantiating this class does not essentially mean the entire request is received. Only when IHTTPRequest.handle() is called complete request is available and partially parsed.
When a request object is instantiated no assumption should be made about the web application framework. Only processing of request init parameters are allowed.
Returns the client’s SSL certificate, if any. To use client certificates, cert_reqs configuration value must be set to ssl.CERT_REQUIRED. The return value is a dictionary, see SSLSocket.getpeercert() in the standard library for more details. http://docs.python.org/library/ssl.html#sslsocket-objects.
Gets the value of the cookie with the given name, else return default. Call to this method is valid only after handle() is called.
Returns a signed cookie if it validates, or None. Call to this method is valid only after handle() is called. Refer to IHTTPCookie interface specification to learn more about secure-signing cookies.
Return True if this request is considered finished, which is, when the flush( finishing=True ) method is called on IHTTPResponse.
Typically called by IWebApp plugin, after the request is resolved for a web-application. Along with applying in-bound request transformers, the method will initialize most of the attributes under this specification.
Bases: pluggdapps.plugin.Interface
Interface specification to encapulate HTTP response.
Response status code in byte-string.
Reason byte-string for response status.
HTTP protocol version, in byte-string, supported by this server.
HTTP header dictionary to sent in the response message.
Response body, if present, as a byte string.
List of response chunks. It is the responsibility of the implementing plugin to remove or keep the previous chunks in this list. For chunked response atleast one chunk must be present.
In chunked transfer-coding, HTTP header dictionary to be sent after the last chunk is transfered.
A dictionary of Cookie.Morsel objects representing a new set of cookies to be set on the client side.
Plugin instance implementing IHTTPRequest interface.
A dictionary like object that will be passed to resource objects and view callables, and eventually to template code.
If route configuration or content-negotiation supplies media_type specification, this attribute will be set with supplied value before calling view-callable. View-callable can also override this attribute, the media-type header field is normally set in out-bound-transformer plugin ResponseHeaders.
If route configuration or content-negotiation supplies charset specification, this attribute will be set with supplied value before calling view-callable. View-callable can also override this attribute, the charset header field is normally set in out-bound-transformer plugin ResponseHeaders.
If route configuration or content-negotiation supplies language specification, this attribute will be set with supplied value before calling view-callable. View-callable can also override this attribute, the language header field is normally set in out-bound-transformer plugin ResponseHeaders.
If route configuration or content-negotiation supplies content-encoding specification, this attribute will be set with supplied value before calling view-callable. View-callable can also override this attribute, the content-encoding header field is normally set in out-bound-transformer plugin ResponseHeaders.
Instantiate a response plugin for a corresponding request plugin.
Sets the given response header name and value. If there is already a response header by name present, it will be overwritten. Returns the new value for header name as byte-string.
Similar to set_header() except that, if there is already a response header by name present, value will be appended to existing value using ‘,’ seperator. Returns the new value for header name as byte-string.
Sets the given chunk trailing header, name and value. If there is already a trailing header by name present, it will be overwritten. Returns the new value for header name as byte-string.
Similar to set_trailer() except that, if there is already a trailing header by name present, value will be appended to existing value using ‘,’ seperator. Returns the new value for header name as byte-string.
Set cookie name/value with optional kwargs. Key-word arguments typically contains, domain, expires_days, expires, path. Additional keyword arguments are set on the Cookie.Morsel directly. By calling this method cookies attribute will be updated inplace. See http://docs.python.org/library/cookie.html#morsel-objects for available attributes.
Similar to set_cookie() method, additionally signs and timestamps a cookie value so it cannot be forged. Uses IHTTPCookie.create_signed_value() method to sign the cookie. To read a cookie set with this method, use get_secure_cookie().
Deletes the cookie with the given name. Note that setcookies will still contain cookie-name name, only that it is set to expire in the client side. Return the original value of the cookie.
Deletes all the cookies the user sent with this request.
Subscribe a callback function, to be called when this response is finished.
Return True if finish() method is called on IHTTPResponse.
For chunked-encoding, returns a boolean, if True means the response has started and response headers are written.
Writes the given chunk to the output buffer. To actually write the output to the network, use the flush() method below.
Flushes the response-header (if not written already) to the socket connection. Then flushes the write-buffer to the socket connection.
Sends the given HTTP error code to the browser.
If flush() has already been called, it is not possible to send an error, so this method will simply terminate the response. If output has been written but not yet flushed, it will be discarded and replaced with the error page.
It is the caller’s responsibility to finish the request, by calling finish().
Use the view configuration parameter ‘IHTTPRenderer’ to invoke the view plugin and apply IHTTPRenderer.render() method with request, c, args and kwargs.
A python generate which returns a response chunk for every iteration.
A python generate which returns a response chunk for every iteration.
Bases: pluggdapps.plugin.Interface
String name that maps into IHTTPRouter.views dictionary.
Dictionary of view predicates for which this view-callbale was resolved.
In the absence of method specific attributes or if the resolver cannot find an instance attribute to apply the handler call back, the object will simply be called.
Optional callable attribute, if present will be called at the end of a request, after the response has been sent to the client. Note that this is not the same as close callback, which is called when the connection get closed. In this case the connection may or may not remain open. Refer to HTTP/1.1 spec.
Bases: pluggdapps.plugin.Interface
Specification to transform response headers and body. A chain of transforms can be configured on IWebApp plugin.
Transform in-coming message entity. request will be updated in place. Returns the transformed request data.
Bases: pluggdapps.plugin.Interface
Specification to transform response headers and message-body. A chain of transforms can be configured on IWebApp plugin.
Transform out-going message entity. request.response will be updated inplace.
Bases: pluggdapps.plugin.Interface
Catch exceptions in application code and handle them. Typically the exceptions can be formated and logged and/or sent as email and/or rendered as html page in debug mode and optionally provide interactive debugging via browser.