.. _api_narrative:
|
|
Using the :mod:`repoze.who` Application Programming Interface (API)
|
===================================================================
|
|
.. _without_middleware:
|
|
Using :mod:`repoze.who` without Middleware
|
------------------------------------------
|
|
An application which does not use the :mod:`repoze.who` middleware needs
|
to perform two separate tasks to use :mod:`repoze.who` machinery:
|
|
- At application startup, it must create an :class:`repoze.who.api:APIFactory`
|
instance, populating it with a request classifier, a challenge decider,
|
and a set of plugins. It can do this process imperatively
|
(see :ref:`imperative_configuration`), or using a declarative
|
configuration file (see :ref:`declarative_configuration`). For the latter
|
case, there is a convenience function,
|
:func:`repoze.who.config.make_api_factory_with_config`:
|
|
.. code-block:: python
|
|
# myapp/run.py
|
from repoze.who.config import make_api_factory_with_config
|
who_api_factory = None
|
def startup(global_conf):
|
global who_api_factory
|
who_api_factory = make_api_factory_with_config(global_conf,
|
'/path/to/who.config')
|
|
- When it needs to use the API, it must call the ``APIFactory``, passing
|
the WSGI environment to it. The ``APIFactory`` returns an object
|
implementing the :class:`repoze.who.interfaces:IRepozeWhoAPI` interface.
|
|
.. code-block:: python
|
|
# myapp/views.py
|
from myapp.run import who_api_factory
|
def my_view(context, request):
|
who_api = who_api_factory(request.environ)
|
|
- Calling the ``APIFactory`` multiple times within the same request is
|
allowed, and should be very cheap (the API object is cached in the
|
request environment).
|
|
|
.. _middleware_api_hybrid:
|
|
Mixed Use of :mod:`repoze.who` Middleware and API
|
-------------------------------------------------
|
|
An application which uses the :mod:`repoze.who` middleware may still need
|
to interact directly with the ``IRepozeWhoAPI`` object for some purposes.
|
In such cases, it should call :func:`repoze.who.api:get_api`, passing
|
the WSGI environment.
|
|
.. code-block:: python
|
|
from repoze.who.api import get_api
|
def my_view(context, request):
|
who_api = get_api(request.environ)
|
|
Alternately, the application might configure the ``APIFactory`` at startup,
|
as above, and then use it to find the API object, or create it if it was
|
not already created for the current request (e.g. perhaps by the middleware):
|
|
.. code-block:: python
|
|
def my_view(context, request):
|
who_api = context.who_api_factory(request.environ)
|
|
|
.. _writing_custom_login_view:
|
|
Writing a Custom Login View
|
---------------------------
|
|
:class:`repoze.who.api.API` provides a helper method to assist developers
|
who want to control the details of the login view. The following
|
BFG example illustrates how this API might be used:
|
|
.. code-block:: python
|
:linenos:
|
|
def login_view(context, request):
|
message = ''
|
|
who_api = get_api(request.environ)
|
if 'form.login' in request.POST:
|
creds = {}
|
creds['login'] = request.POST['login']
|
creds['password'] = request.POST['password']
|
authenticated, headers = who_api.login(creds)
|
if authenticated:
|
return HTTPFound(location='/', headers=headers)
|
|
message = 'Invalid login.'
|
else:
|
# Forcefully forget any existing credentials.
|
_, headers = who_api.login({})
|
|
request.response_headerlist = headers
|
if 'REMOTE_USER' in request.environ:
|
del request.environ['REMOTE_USER']
|
|
return {'message': message}
|
|
This application is written as a "hybrid": the :mod:`repoze.who` middleware
|
injects the API object into the WSGI enviornment on each request.
|
|
- In line 4, this application extracts the API object from the environ
|
using :func:`repoze.who.api:get_api`.
|
|
- Lines 6 - 8 fabricate a set of credentials, based on the values the
|
user entered in the form.
|
|
- In line 9, the application asks the API to authenticate those credentials,
|
returning an identity and a set of respones headers.
|
|
- Lines 10 and 11 handle the case of successful authentication: in this
|
case, the application redirects to the site root, setting the headers
|
returned by the API object, which will "remember" the user across requests.
|
|
- Line 13 is reached on failed login. In this case, the headers returned
|
in line 9 will be "forget" headers, clearing any existing cookies or other
|
tokens.
|
|
- Lines 14 - 16 perform a "fake" login, in order to get the "forget" headers.
|
|
- Line 18 sets the "forget" headers to clear any authenticated user for
|
subsequent requests.
|
|
- Lines 19 - 20 clear any authenticated user for the current request.
|
|
- Line 22 returns any message about a failed login to the rendering template.
|
|
|
.. _interfaces:
|
|
Interfaces
|
----------
|
|
.. automodule:: repoze.who.interfaces
|
|
.. autointerface:: IAPIFactory
|
:members:
|
|
.. autointerface:: IAPI
|
:members:
|
|
.. autointerface:: IPlugin
|
:members:
|
|
.. autointerface:: IRequestClassifier
|
:members:
|
|
.. autointerface:: IChallengeDecider
|
:members:
|
|
.. autointerface:: IIdentifier
|
:members:
|
|
.. autointerface:: IAuthenticator
|
:members:
|
|
.. autointerface:: IChallenger
|
:members:
|
|
.. autointerface:: IMetadataProvider
|
:members:
|
