#!/usr/bin/env python
# -*- coding: utf-8 -*-
""" :py:mod:`weblayer.interfaces` provides `Interface`_ definitions that show
the contracts that :ref:`weblayer`'s :ref:`components` implement and are
registered against and looked up by through the :py:mod:`weblayer.component`
:py:obj:`registry`.
.. _`Interface`: http://pypi.python.org/pypi/zope.interface
"""
__all__ = [
'IAuthenticationManager',
'IMethodSelector',
'IPathRouter',
'IRequest',
'IRequestHandler',
'IResponse',
'IResponseNormaliser',
'ISecureCookieWrapper',
'ISettings',
'IStaticURLGenerator',
'ITemplateRenderer',
'IWSGIApplication'
]
from zope.interface import Attribute, Interface
[docs]class IAuthenticationManager(Interface):
""" Authentication manager. Default implementation is
:py:class:`~weblayer.auth.TrivialAuthenticationManager`.
"""
is_authenticated = Attribute(u'Boolean -- is there an authenticated user?')
current_user = Attribute(u'The authenticated user, or `None`')
[docs]class IMethodSelector(Interface):
""" Selects request handler methods by name. Default implementation is
:py:class:`~weblayer.method.ExposedMethodSelector`.
"""
[docs] def select_method(method_name):
""" Return a method using :py:obj:`method_name`.
"""
[docs]class IPathRouter(Interface):
""" Maps incoming requests to request handlers using the request path.
Default implementation is :py:class:`~weblayer.route.RegExpPathRouter`.
"""
[docs] def match(path):
""" Return ``handler, args, kwargs`` from ``path``.
"""
[docs]class IRequest(Interface):
""" A Request object, based on `webob.Request`_. Default implementation
is :py:class:`~weblayer.base.Request`.
This interface details only the attributes of `webob.Request`_ that
:ref:`weblayer` uses by default, not the full interface `webob.Request`_
actually provides.
.. _`webob.Request`: http://pythonpaste.org/webob/reference.html#id1
"""
url = Attribute(u'Full request URL, including QUERY_STRING')
host = Attribute(u'HOST provided in HTTP_HOST w. fall-back to SERVER_NAME')
host_url = Attribute(u'The URL through the HOST (no path)')
application_url = Attribute(u'URL w. SCRIPT_NAME no PATH_INFO or QUERY_STRING')
path_url = Attribute(u'URL w. SCRIPT_NAME & PATH_INFO no QUERY_STRING')
path = Attribute(u'Path of the request, without HOST or QUERY_STRING')
path_qs = Attribute(u'Path without HOST but with QUERY_STRING')
headers = Attribute(u'Headers as case-insensitive dictionary-like object')
params = Attribute(u'Dictionary-like obj of params from POST and QUERY_STRING')
body = Attribute(u'Content of the request body.')
cookies = Attribute(u'Dictionary of cookies found in the request')
[docs]class IRequestHandler(Interface):
""" A request handler. Default implementation is
:py:class:`~weblayer.request.RequestHandler`.
"""
request = Attribute(u'Request instance')
response = Attribute(u'Response instance')
settings = Attribute(u'Settings instance')
auth = Attribute(u'Authentication manager')
cookies = Attribute(u'Cookie wrapper')
static = Attribute(u'Static url generator')
xsrf_token = Attribute(u'XSRF prevention token')
xsrf_input = Attribute(u'``<input/>`` element to be included in forms.')
[docs] def xsrf_validate():
""" Validate against XSRF.
"""
[docs] def render(tmpl_name, **kwargs):
""" Render the template called ``tmpl_name``.
"""
[docs] def redirect(url, status=302, content_type=None):
""" Redirect to ``url``.
"""
[docs] def error(status=500, body=u'System Error'):
""" Clear response and return an error.
"""
[docs] def __call__(method_name, *args, **kwargs):
""" Call the appropriate method to return a response.
"""
[docs]class IResponse(Interface):
""" A Response object, based on `webob.Response`_. Default implementation
is :py:class:`~weblayer.base.Response`.
This interface details only the attributes of `webob.Response`_ that
:ref:`weblayer` uses by default, not the full interface `webob.Response`_
actually provides.
.. _`webob.Response`: http://pythonpaste.org/webob/reference.html#id2
"""
headers = Attribute(u'The headers in a dictionary-like object')
headerlist = Attribute(u'The list of response headers')
body = Attribute(u'The body of the response, as a ``str``.')
unicode_body = Attribute(u'The body of the response, as a ``unicode``.')
content_type = Attribute(u'The `Content-Type` header')
status = Attribute(u'The `status` string')
[docs] def set_cookie(key, value='', **kwargs):
""" Set ``value`` for cookie called ``key``.
"""
[docs]class IResponseNormaliser(Interface):
""" Normalise the response provided by a request handler method. Default
implementation is
:py:class:`~weblayer.normalise.DefaultToJSONResponseNormaliser`.
"""
[docs] def normalise(handler_response):
""" Normalise ``handler_response``.
"""
[docs]class ISecureCookieWrapper(Interface):
""" Get and set cookies that can't be forged. Default implementation is
:py:class:`~weblayer.cookie.SignedSecureCookieWrapper`.
"""
[docs] def set(name, value, expires_days=30, **kwargs):
""" Set cookie.
"""
[docs] def get(name, include_name=True, value=None):
""" Get cookie.
"""
[docs] def delete(self, name, path="/", domain=None):
""" Clear cookie.
"""
[docs]class ISettings(Interface):
""" Provides dictionary-like access to global application settings.
Default implementation is
:py:class:`~weblayer.settings.RequirableSettings`.
"""
[docs] def __call__(items):
""" Update with items.
"""
[docs] def __getitem__(key):
""" Get item.
"""
[docs] def __setitem__(key, value):
""" Set item.
"""
[docs] def __delitem__(key):
""" Delete item.
"""
[docs] def __contains__(key):
""" Return whether contains item.
"""
[docs] def __iter__():
""" Iterate through items.
"""
[docs] def __repr__():
""" Represent as a string.
"""
[docs] def __cmp__(self, other):
""" Compare against other.
"""
[docs] def __len__(self):
""" Return number of items.
"""
[docs] def has_key(key):
""" Has key.
"""
[docs] def iteritems():
""" Iter items.
"""
[docs] def iterkeys():
""" Iter keys.
"""
[docs] def itervalues():
""" Iter values.
"""
[docs] def items():
""" Items.
"""
[docs] def keys():
""" Keys.
"""
[docs] def values():
""" Values.
"""
[docs] def clear():
""" Clear items.
"""
[docs] def setdefault(key, default=None):
""" Set default.
"""
[docs] def pop(key, *args):
""" Pop.
"""
[docs] def popitem():
""" Pop item.
"""
[docs] def update(other=None, **kwargs):
""" Update.
"""
[docs] def get(key, default=None):
""" Get item if exists, or return ``default``.
"""
[docs]class IStaticURLGenerator(Interface):
""" Static url generator. Default implementation is
:py:class:`~weblayer.static.MemoryCachedStaticURLGenerator`.
"""
[docs] def get_url(path):
""" Get a fully expanded url for the given static resource ``path``.
"""
[docs]class ITemplateRenderer(Interface):
""" A template renderer. Default implementation is
:py:class:`~weblayer.template.MakoTemplateRenderer`.
"""
[docs] def render(tmpl_name, **kwargs):
""" Render the template called ``tmpl_name``.
"""
[docs]class IWSGIApplication(Interface):
""" A callable WSGI application. Default implementation is
:py:class:`~weblayer.wsgi.WSGIApplication`.
"""
[docs] def __call__(environ, start_response):
""" Handle a new request.
"""