diff options
| -rw-r--r-- | CHANGES.txt | 2 | ||||
| -rw-r--r-- | docs/glossary.rst | 118 | ||||
| -rw-r--r-- | docs/narr/configuration.rst | 22 | ||||
| -rw-r--r-- | docs/narr/environment.rst | 20 | ||||
| -rw-r--r-- | docs/narr/events.rst | 8 | ||||
| -rw-r--r-- | docs/narr/extending.rst | 21 | ||||
| -rw-r--r-- | docs/narr/hooks.rst | 12 | ||||
| -rw-r--r-- | docs/narr/hybrid.rst | 13 | ||||
| -rw-r--r-- | docs/narr/install.rst | 18 | ||||
| -rw-r--r-- | docs/narr/introduction.rst | 6 | ||||
| -rw-r--r-- | docs/narr/models.rst | 18 | ||||
| -rw-r--r-- | docs/narr/project.rst | 41 | ||||
| -rw-r--r-- | docs/narr/resources.rst | 13 | ||||
| -rw-r--r-- | docs/narr/router.rst | 4 | ||||
| -rw-r--r-- | docs/narr/scanning.rst | 10 | ||||
| -rw-r--r-- | docs/narr/security.rst | 50 | ||||
| -rw-r--r-- | docs/narr/startup.rst | 3 | ||||
| -rw-r--r-- | docs/narr/templates.rst | 33 | ||||
| -rw-r--r-- | docs/narr/threadlocals.rst | 5 | ||||
| -rw-r--r-- | docs/narr/traversal.rst | 20 | ||||
| -rw-r--r-- | docs/narr/unittesting.rst | 16 | ||||
| -rw-r--r-- | docs/narr/urldispatch.rst | 30 | ||||
| -rw-r--r-- | docs/narr/urlmapping.rst | 3 | ||||
| -rw-r--r-- | docs/narr/vhosting.rst | 6 | ||||
| -rw-r--r-- | docs/narr/views.rst | 81 | ||||
| -rw-r--r-- | docs/narr/webob.rst | 17 |
26 files changed, 530 insertions, 60 deletions
diff --git a/CHANGES.txt b/CHANGES.txt index a221ba8dc..36a15b545 100644 --- a/CHANGES.txt +++ b/CHANGES.txt @@ -16,6 +16,8 @@ Documentation Licensing Documentation ------------- +- Added manual index entries to generated index. + - Document the previously existing (but non-API) ``repoze.bfg.configuration.Configurator.setup_registry`` method as an official API of a ``Configurator``. diff --git a/docs/glossary.rst b/docs/glossary.rst index a0d999c84..96490c23b 100644 --- a/docs/glossary.rst +++ b/docs/glossary.rst @@ -6,11 +6,11 @@ Glossary .. glossary:: :sorted: - Request + request A ``WebOb`` request object. See :ref:`webob_chapter` for information about request objects. - Response + response An object that has three attributes: ``app_iter`` (representing an iterable body), ``headerlist`` (representing the http headers sent to the user agent), and ``status`` (representing the http status @@ -26,7 +26,7 @@ Glossary The software developed "under the brand" is available in a `Subversion repository <http://svn.repoze.org>`_. - Setuptools + setuptools `Setuptools <http://peak.telecommunity.com/DevCenter/setuptools>`_ builds on Python's ``distutils`` to provide easier building, distribution, and installation of libraries and applications. @@ -39,11 +39,11 @@ Glossary a resource file. See also `PkgResources <http://peak.telecommunity.com/DevCenter/PkgResources>`_ - Resource + resource Any file contained within a Python :term:`package` which is *not* a Python source code file. - Resource Specification + resource specification A colon-delimited identifier for a :term:`resource`. The colon separates a Python :term:`package` name from a package subpath. For example, the resource specification @@ -51,30 +51,30 @@ Glossary ``baz.css`` in the ``static`` subdirectory of the ``my.package`` Python :term:`package`. - Package + package A directory on disk which contains an ``__init__.py`` file, making it recognizable to Python as a location which can be ``import`` -ed. - Project + project (Setuptools/distutils terminology). A directory on disk which contains a ``setup.py`` file and one or more Python packages. The ``setup.py`` file contains code that allows the package(s) to be installed, distributed, and tested. - Distribution + distribution (Setuptools/distutils terminology). A file representing an installable library or application. Distributions are usually files that have the suffix of ``.egg``, ``.tar.gz``, or ``.zip``. Distributions are the target of Setuptools commands such as ``easy_install``. - Entry Point + entry point A :term:`setuptools` indirection, defined within a setuptools :term:`distribution` setup.py. It is usually a name which refers to a function somewhere in a package which is held by the distribution. - Dotted Python name + dotted Python name A reference to a Python object by name using a string, in the form ``path.to.modulename:attributename``. Often used in Paste and setuptools configurations. A variant is used in dotted names @@ -82,10 +82,10 @@ Glossary "view" directive's "view" attribute): the colon (``:``) is not used; in its place is a dot. - View + view Common vernacular for a :term:`view callable`. - View Callable + view callable A "view callable" is a callable Python object which is associated with a :term:`view configuration`; it returns a :term:`response` object . A view callable accepts a single argument: ``request``, @@ -99,7 +99,7 @@ Glossary :ref:`views_chapter` for more information about :mod:`repoze.bfg` view callables. - View Configuration + view configuration View configuration is the act of associating a :term:`view callable` with configuration information. This configuration information helps map a given :term:`request` to a particular view @@ -109,7 +109,7 @@ Glossary decorator coupled with a :term:`scan`. See :ref:`views_chapter` for more information about view configuration. - View name + view name The "URL name" of a view, e.g ``index.html``. If a view is configured without a name, its name is considered to be the empty string (which implies the :term:`default view`). @@ -120,13 +120,13 @@ Glossary when :term:`traversal` exhausts the path elements in the PATH_INFO of a request before it returns a :term:`context`. - Virtualenv + virtualenv An isolated Python environment. Allows you to control which packages are used on a particular project by cloning your main Python. `virtualenv <http://pypi.python.org/pypi/virtualenv>`_ was created by Ian Bicking. - Model + model An object representing data in the system. If :mod:`traversal` is used, a model is a node in the object graph traversed by the system. When traversal is used, a model instance becomes the @@ -136,7 +136,7 @@ Glossary a "model" in :mod:`repoze.bfg` terms, although this terminology can be a bit confusing: see :ref:`model_traversal_confusion`. - Traversal + traversal The act of descending "down" a graph of model objects from a root model in order to find a :term:`context`. The :mod:`repoze.bfg` :term:`router` performs traversal of model objects when a @@ -146,7 +146,7 @@ Glossary combined *with* URL dispatch. See :ref:`hybrid_chapter` for more information about combining traversal and URL dispatch (advanced). - Router + router The :term:`WSGI` application created when you start a :mod:`repoze.bfg` application. The router intercepts requests, invokes traversal and/or URL dispatch, calls view functions, and @@ -160,7 +160,7 @@ Glossary configuration`, you are using URL dispatch. See the :ref:`urldispatch_chapter` for more information. - Context + context An object in the system that is found during :term:`traversal` or :term:`URL dispatch` based on URL data; if it's found via traversal, it's usually a :term:`model` object that is part of an @@ -171,7 +171,7 @@ Glossary chapter and the :ref:`urldispatch_chapter` chapter for more information about how a URL is resolved to a context. - Application registry + application registry A registry of configuration information consulted by :mod:`repoze.bfg` while servicing an appliation. An application registry maps model types to views, as well as housing other @@ -179,15 +179,15 @@ Glossary :mod:`repoze.bfg` application has one (and only one) application registry. - Template + template A file with replaceable parts that is capable of representing some text, XML, or HTML when rendered. - Location + location The path to an object in an object graph. See :ref:`location_aware` for more information about how to make a model object *location-aware*. - Permission + permission A string or unicode object that represents an action being taken against a context. A permission is associated with a view name and a model type by the developer. Models are decorated with @@ -218,7 +218,7 @@ Glossary policy to determine wither a particular request can be fulfilled given the :term:`authentication` information in the request. - Authentication + authentication The act of determining that the credentials a user presents during a particular request are "good". :mod:`repoze.bfg` uses the :term:`authentication` data supplied by the upstream component as @@ -226,7 +226,7 @@ Glossary :mod:`repoze.bfg` is performed via an :term:`authentication policy`. - Authorization + authorization The act of determining whether a user can perform a specific action. In bfg terms, this means determining whether, for a given context, any :term:`principal` (or principals) associated with the @@ -234,7 +234,7 @@ Glossary to continue. Authorization in :mod:`repoze.bfg` is performed via its :term:`authorization policy`. - Principal + principal A *principal* is a string or unicode object representing a userid or a group id. It is provided by an :term:`authentication policy`. For example, if a user had the user id "bob", and Bob @@ -243,14 +243,14 @@ Glossary indictate that Bob was represented by three principals: "bob", "group foo" and "group bar". - Authorization Policy + authorization policy An authorization policy in :mod:`repoze.bfg` terms is a bit of code which has an API which determines whether or not the principals associated with the request can perform an action associated with a permission, based on the information found on the :term:`context`. - Authentication Policy + authentication policy An authentication policy in :mod:`repoze.bfg` terms is a bit of code which has an API which determines the current :term:`principal` (or principals) associated with a request. @@ -261,7 +261,7 @@ Glossary similar to the concept of Java Servlets. ``repoze.bfg`` requires that your application be served as a WSGI application. - Middleware + middleware *Middleware* is a :term:`WSGI` concept. It is a WSGI component that acts both as a server and an application. Interesting uses for middleware exist, such as caching, content-transport @@ -269,7 +269,7 @@ Glossary or `PyPI <http://python.org/pypi>`_ to find middleware for your application. - Pipeline + pipeline The :term:`Paste` term for a single configuration of a WSGI server, a WSGI application, with a set of middleware in-between. @@ -344,12 +344,12 @@ Glossary inspired by the Routes syntax (which was inspired by Ruby On Rails pattern syntax). - Route + route A single pattern matched by the :term:`url dispatch` subsystem, which generally resolves to a :term:`root factory` (and then ultimately a :term:`view`). See also :term:`url dispatch`. - Route Configuration + route configuration Route configuration is the act of using :term:`imperative configuration` or a :term:`ZCML` ``<route>`` statement to associate request parameters with a particular :term:`route` using @@ -368,10 +368,10 @@ Glossary application. You can use ZCML as an alternative to :term:`imperative configuration`. - ZCML Directive + ZCML directive A ZCML "tag" such as ``<view>`` or ``<route>``. - ZCML Declaration + ZCML declaration The concrete use of a :term:`ZCML directive` within a ZCML file. Zope Component Architecture @@ -382,18 +382,18 @@ Glossary :mod:`repoze.bfg` uses the ZCA "under the hood" to perform view dispatching and other application configuration tasks. - ReStructuredText + reStructuredText A `plain text format <http://docutils.sourceforge.net/rst.html>`_ that is the defacto standard for descriptive text shipped in :term:`distribution` files, and Python docstrings. This documentation is authored in ReStructuredText format. - Root + root The object at which :term:`traversal` begins when :mod:`repoze.bfg` searches for a :term:`context` (for :term:`URL Dispatch`, the root is *always* the context). - Subpath + subpath A list of element "left over" after the :term:`router` has performed a successful traversal to a view. The subpath is a sequence of strings, e.g. ``['left', 'over', 'names']``. Within @@ -401,7 +401,7 @@ Glossary can use ``*subpath`` in the route pattern to influence the subpath. See :ref:`star_subpath` for more information. - Interface + interface A `Zope interface <http://pypi.python.org/pypi/zope.interface>`_ object. In :mod:`repoze.bfg`, an interface may be attached to a :term:`model` object or a :term:`request` object in order to @@ -420,20 +420,20 @@ Glossary to, :mod:`repoze.bfg` programmers do not need to understand or use this feature of interfaces. - Event + event An object broadcast to zero or more :term:`subscriber` callables during normal :mod:`repoze.bfg` system operations during the lifetime of an application. Application code can subscribe to these events by using the subscriber functionality described in :ref:`events_chapter`. - Subscriber + subscriber A callable which receives an :term:`event`. A callable becomes a subscriber via :term:`imperative configuration` or the ``<subscriber>`` ZCML directive. See :ref:`events_chapter` for more information. - Request type + request type An attribute of a :term:`request` that allows for specialization of view invocation based on arbitrary categorization. The every :term:`request` object that :mod:`repoze.bfg` generates and @@ -462,13 +462,13 @@ Glossary <http://docs.repoze.org/workflow>`_ . It can be used by :mod:`repoze.bfg` to form a workflow system. - Virtual root + virtual root A model object representing the "virtual" root of a request; this is typically the physical root object (the object returned by the application root factory) unless :ref:`vhosting_chapter` is in use. - Lineage + lineage An ordered sequence of objects based on a ":term:`location` -aware" context. The lineage of any given :term:`context` is composed of itself, its parent, its parent's parent, and so on. @@ -476,7 +476,7 @@ Glossary context, then its parent's parent, and so on. The parent of an object in a lineage is available as its ``__parent__`` attribute. - Root Factory + root factory The "root factory" of an :mod:`repoze.bfg` application is called on every request sent to the application. The root factory returns the traversal root of an application. It is @@ -495,7 +495,7 @@ Glossary `JavaScript Object Notation <http://www.json.org/>`_ is a data serialization format. - Renderer + renderer A registered serializer that can be configured via :term:`view configuration` which converts a non-:term:`Response` return values from a :term:`view` into a string (and ultimately a response). @@ -509,14 +509,14 @@ Glossary applications (such as applications developed using :mod:`repoze.bfg`) to be served using the Apache web server. - View Predicate + view predicate An argument to a :term:`view configuration` which evaluates to ``True`` or ``False`` for a given :term:`request`. All predicates attached to a view configuration must evaluate to true for the associated view to be considered as a possible callable for a given request. - Route Predicate + route predicate An argument to a :term:`route configuration` which implies a value that evaluates to ``True`` or ``False`` for a given :term:`request`. All predicates attached to a :term:`route @@ -525,21 +525,21 @@ Glossary current request, the next route (in definition order) is attempted. - Predicate + predicate A test which returns ``True`` or ``False``. Two different types of predicates exist in :mod:`repoze.bfg`: a :term:`view predicate` and a :term:`route predicate`. View predicates are attached to :term:`view configuration` and route predicates are attached to :term:`route configuration`. - Decorator + decorator A wrapper around a Python function or class which accepts the function or class as its first argument and which returns an arbitrary object. :mod:`repoze.bfg` provides several decorators, used for configuration and return value modification purposes. See also `PEP 318 <http://www.python.org/dev/peps/pep-0318/>`_. - Configuration Declaration + configuration declaration An individual method call made to an instance of a :mod:`repoze.bfg` :term:`Configurator` object which performs an arbitrary action, such as registering a :term:`view configuration` @@ -550,31 +550,31 @@ Glossary of configuration declarations might be performed by a :term:`scan` of code in a package. - Configuration Decoration + configuration decoration Metadata implying one or more :term:`configuration declaration` invocations. Often set by configuration Python :term:`decorator` attributes, such as ``repoze.bfg.view.bfg_view``, aka ``@bfg_view``. - Scan + scan The term used by :mod:`repoze.bfg` to define the process of importing and examining all code in a Python package or module for :term:`configuration decoration`. - Configurator + configurator An object used to do :term:`configuration declaration` within an application. The most common configurator is an instance of the ``repoze.bfg.configuration.Configurator`` class. - Imperative Configuration + imperative configuration The configuration mode in which you use Python to call methods on a :term:`Configurator` in order to add each :term:`configuration declaration` required by your application. - Declarative Configuration + declarative configuration The configuration mode in which you use :term:`ZCML` to make a set of :term:`configuration declaration` statements. - Not Found View + Not Found view The :term:`view callable` invoked by :mod:`repoze.bfg` when the developer explicitly raises a ``repoze.bfg.exceptions.NotFound`` exception from within @@ -584,7 +584,7 @@ Glossary found view; it can be overridden. See :ref:`changing_the_notfound_view`. - Forbidden View + Forbidden view The :term:`view callable` invoked by :mod:`repoze.bfg` when the developer explicitly raises a ``repoze.bfg.exceptions.Forbidden`` exception from within @@ -595,7 +595,7 @@ Glossary forbidden view; it can be overridden. See :ref:`changing_the_forbidden_view`. - Thread Local + thread local A thread-local variable is one which is essentially a global variable in terms of how it is accessed and treated, however, each `thread @@ -607,7 +607,7 @@ Glossary <http://docs.python.org/library/threading.html#threading.local>` for more information. - Multidict + multidict An ordered dictionary that can have multiple values for each key. Adds the methods ``getall``, ``getone``, ``mixed``, and ``add`` to the normal dictionary interface. See diff --git a/docs/narr/configuration.rst b/docs/narr/configuration.rst index 738295842..9a7379c3e 100644 --- a/docs/narr/configuration.rst +++ b/docs/narr/configuration.rst @@ -57,6 +57,9 @@ There are a number of different mechanisms you may use to configure and *declarative* configuration. We'll examine both modes in the sections which follow. +.. index:: + pair: imperative; helloworld + .. _helloworld_imperative: Hello World, Configured Imperatively @@ -175,6 +178,9 @@ but return a response with the body ``Hello world!``; the ``goodbye_world`` view callable returns a response with the body ``Goodbye world!``. +.. index:: + pair: traversal; introduction + .. _traversal_intro: An Introduction to Traversal @@ -259,6 +265,10 @@ sole possible URL that will resolve to the ``goodbye_world`` in this application the URL ``'/goodbye'`` because it is the only URL that will resolve to the :term:`view name` of ``goodbye``. +.. index:: + pair: imperative; configuration + single: Configurator + .. _helloworld_imperative_appconfig: Application Configuration @@ -458,6 +468,11 @@ registry, meaning that code which attempts to use the application registry :term:`thread local` will no longer obtain the registry associated with the configurator. +.. index:: + single: make_wsgi_app + pair: WSGI; application + triple: WSGI; application; creation + WSGI Application Creation ~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -515,6 +530,10 @@ a good deal of what's going on "under the hood" when we configure a :mod:`repoze.bfg` application imperatively. However, another mode of configuration exists named *declarative* configuration. +.. index:: + pair: helloworld; declarative + single: helloworld + .. _helloworld_declarative: Hello World, Configured Declaratively @@ -804,6 +823,9 @@ tag. Other such tags include ``<route>``, ``<scan>``, ``<notfound>``, "macro" which calls methods on the :class:`repoze.bfg.configuration.Configurator` object on your behalf. +.. index:: + pair: ZCML; conflict detection + ZCML Conflict Detection ~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/narr/environment.rst b/docs/narr/environment.rst index 5f3dc345c..e56c2602f 100644 --- a/docs/narr/environment.rst +++ b/docs/narr/environment.rst @@ -1,3 +1,20 @@ +.. index:: + single: environment variables + single: settings + single: reload + single: configure.zcml + single: configure_zcml + single: debug_authorization + single: reload_resources + single: debug_notfound + single: debug_all + single: reload_all + pair: debug; settings + pair: reload; settings + pair: environment; variables + pair: ini file; settings + pair: PasteDeploy; settings + .. _environment_chapter: Environment Variables and ``.ini`` File Settings @@ -107,6 +124,9 @@ with ``reload_``). on in one fell swoop, you can use effect settings that do not start with ``reload_*`` such as ``debug_notfound``. +.. index:: + pair: reload_templates; reload_resources + Understanding the Distinction Between ``reload_templates`` and ``reload_resources`` ----------------------------------------------------------------------------------- diff --git a/docs/narr/events.rst b/docs/narr/events.rst index b2d2f20b5..2cbbe572d 100644 --- a/docs/narr/events.rst +++ b/docs/narr/events.rst @@ -1,3 +1,11 @@ +.. index:: + single: event + single: events + single: subscriber + single: INewRequest + single: INewResponse + pair: subscriber; ZCML directive + .. _events_chapter: Using Events diff --git a/docs/narr/extending.rst b/docs/narr/extending.rst index c757dde99..0f9bc433d 100644 --- a/docs/narr/extending.rst +++ b/docs/narr/extending.rst @@ -10,6 +10,9 @@ source code that makes up the application. The behavior of a :mod:`repoze.bfg` application that obeys these constraints can be *overridden* or *extended* without modification. +.. index:: + triple: building; extensible; application + Rules for Building An Extensible Application -------------------------------------------- @@ -41,6 +44,9 @@ declarations made using the ZCML ``<view>`` directive (or the repoze bfg using the :term:`pkg_resources` API such as static files and templates. +.. index:: + pair: ZCML; granularity + ZCML Granularity ~~~~~~~~~~~~~~~~ @@ -70,6 +76,9 @@ disuse *all* your ZCML, choosing instead to copy and paste it into his own package, if necessary. However, doing so is considerate, and allows for the best reusability. +.. index:: + pair: extending existing; application + Extending an Existing Application --------------------------------- @@ -163,6 +172,9 @@ something like this: ``configure.zcml`` file. See :ref:`environment_chapter` for more information about this setting. +.. index:: + pair: overriding; views + .. _overriding_views: Overriding Views @@ -188,6 +200,9 @@ A similar pattern can be used to *extend* the application with existing model type and make sure the URLs it implies are available on some other page rendering. +.. index:: + pair: overriding; routes + .. _overriding_routes: Overriding Routes @@ -202,6 +217,9 @@ declarations when performing an override. Typically, this means and changing them as necessary. Then disinclude any ZCML from the original application which contains the original declarations. +.. index:: + pair: overriding; resources + .. _overriding_resources: Overriding Resources @@ -216,6 +234,9 @@ other resources by using :term:`ZCML` ``<resource>`` declarations. Add such ``<resource>`` declarations to your override package's ``configure.zcml`` to perform overrides. +.. index:: + pair: ZCML; inclusion + Dealing With ZCML Inclusions ---------------------------- diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst index 6bfd99e52..990290744 100644 --- a/docs/narr/hooks.rst +++ b/docs/narr/hooks.rst @@ -6,6 +6,9 @@ Using Hooks "Hooks" can be used to influence the behavior of the :mod:`repoze.bfg` framework in various ways. +.. index:: + pair: not found view; changing + .. _changing_the_notfound_view: Changing the Not Found View @@ -70,6 +73,9 @@ Here's some sample code that implements a minimal NotFound view: ``debug_notfound`` environment setting is true than it is when it is false. +.. index:: + pair: forbidden view; changing + .. _changing_the_forbidden_view: Changing the Forbidden View @@ -148,6 +154,9 @@ Here's some sample code that implements a minimal forbidden view: an alternate forbidden view. For example, it would make sense to return a response with a ``403 Forbidden`` status code. +.. index:: + pair: traverser; changing + .. _changing_the_traverser: Changing the Traverser @@ -242,6 +251,9 @@ wild" within `repoze.bfg.traversalwrapper <http://pypi.python.org/pypi/repoze.bfg.traversalwrapper>`_ and `repoze.bfg.metatg <http://svn.repoze.org/repoze.bfg.metatg/trunk/>`_. +.. index:: + pair: url generator; changing + Changing How :mod:`repoze.bfg.url.model_url` Generates a URL ------------------------------------------------------------ diff --git a/docs/narr/hybrid.rst b/docs/narr/hybrid.rst index a08425a5a..14cb1d4ab 100644 --- a/docs/narr/hybrid.rst +++ b/docs/narr/hybrid.rst @@ -100,6 +100,9 @@ code just won't have any ``<route>`` declarations. Instead, its ZCML above will match the URL ``/a/b/c/foobar`` or ``/foobar``, etc, assuming that no view is named "a", "b", or "c" during traversal. +.. index:: + single: hybrid mode application + Hybrid Applications ------------------- @@ -199,6 +202,10 @@ It's :term:`view name` will be looked for during traversal. So if our URL is "http://example.com/one/two/a/another", the ``.views.another`` view will be called. +.. index:: + pair: route; factory + single: route factory + Route Factories --------------- @@ -218,6 +225,9 @@ In this way, each route can use a different factory, making it possible to traverse different graphs based on some routing parameter within the same application. +.. index:: + pair: subpath; route + .. _star_subpath: Using ``*subpath`` in a Route Path @@ -453,6 +463,9 @@ you must the special ``*traverse`` token to the route's "path"., e.g.: route_name="abc" /> +.. index:: + pair: route; ordering + Route Ordering ~~~~~~~~~~~~~~ diff --git a/docs/narr/install.rst b/docs/narr/install.rst index 4fa0ef1d8..667b08a7b 100644 --- a/docs/narr/install.rst +++ b/docs/narr/install.rst @@ -3,6 +3,9 @@ Installing :mod:`repoze.bfg` ============================ +.. index:: + pair: install; preparation + Before You Install ------------------ @@ -112,6 +115,9 @@ executable and accept the defaults during the installation process. You may also need to download and install the `Python for Windows extensions <http://sourceforge.net/projects/pywin32/files/>`_. +.. index:: + pair: installing; UNIX + Installing :mod:`repoze.bfg` on a UNIX System --------------------------------------------- @@ -165,6 +171,9 @@ the script. To remediate this, you may need to do: $ sudo python ez_setup.py +.. index:: + pair: installing; virtualenv + Installing the ``virtualenv`` Package ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -185,6 +194,9 @@ to install it as your system's administrative user. For example: $ sudo easy_install virtualenv +.. index:: + pair: creating; virtualenv + Creating the Virtual Python Environment ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -228,6 +240,9 @@ virtualenv (``bfgenv``) directory: This command will take longer than the previous ones to complete, as it downloads and installs a number of dependencies. +.. index:: + pair: installing; Windows + Installing :mod:`repoze.bfg` on a Windows System ------------------------------------------------- @@ -277,6 +292,9 @@ Installing :mod:`repoze.bfg` on a Windows System c:\bfgenv> Scripts\easy_install -i http://dist.repoze.org/bfg/1.1/simple repoze.bfg +.. index:: + pair: installing; Google App Engine + Installing :mod:`repoze.bfg` on Google App Engine ------------------------------------------------- diff --git a/docs/narr/introduction.rst b/docs/narr/introduction.rst index 6b5494d76..2331a50c0 100644 --- a/docs/narr/introduction.rst +++ b/docs/narr/introduction.rst @@ -61,6 +61,9 @@ A Sense of Fun Developing a :mod:`repoze.bfg` application should not feel foreign or "enterprisey". We like to keep things down-to-earth. +.. index:: + single: similarities to other frameworks + Similarities to Other Web Frameworks ------------------------------------ @@ -113,6 +116,9 @@ The skeleton code generator of :mod:`repoze.bfg` generates a directory layout very similar to the directory layout suggested by the `Django Book <http://www.djangobook.com/>`_ . +.. index:: + single: differences from other frameworks + Differences from Other Web Frameworks ------------------------------------- diff --git a/docs/narr/models.rst b/docs/narr/models.rst index fdd8af9bc..0369ab178 100644 --- a/docs/narr/models.rst +++ b/docs/narr/models.rst @@ -8,6 +8,9 @@ traverse when :term:`traversal` is used. A model instance is also generated as a result of :term:`url dispatch`. A model instance is exposed to :term:`view` code as the :term:`context` of a view. +.. index:: + pair: model; constructor + Defining a Model Constructor ---------------------------- @@ -30,6 +33,9 @@ A model constructor may be essentially any Python object which is callable, and which returns a model instance. In the above example, the ``BlogEntry`` class can be "called", returning a model instance. +.. index:: + pair: model; interfaces + Model Instances Which Implement Interfaces ------------------------------------------ @@ -132,6 +138,13 @@ See the :ref:`views_chapter` for more information about why providing models with an interface can be an interesting thing to do with regard to :term:`view` lookup. +.. index:: + single: model graph + single: traversal graph + single: object graph + single: container nodes + single: leaf nodes + Defining a Graph of Model Instances for Traversal ------------------------------------------------- @@ -156,6 +169,9 @@ policy on model instance nodes in the graph: See :ref:`traversal_chapter` for more information about how traversal works against model instances. +.. index:: + pair: location-aware; model + .. _location_aware: Location-Aware Model Instances @@ -229,6 +245,8 @@ and so on. to every path and URL generated (as opposed to a single leading slash or empty tuple element). +.. index:: + pair: model; API functions :mod:`repoze.bfg` API Functions That Act Against Models ------------------------------------------------------- diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 2fe5489e2..681fba7a6 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -20,6 +20,9 @@ extended with new code and an application that lives inside a package can be distributed more easily than one which does not live within a package. +.. index:: + pair: project; creating + .. _creating_a_project: Creating the Project @@ -99,6 +102,10 @@ application's Python code and templates. name during ``paster create`` by adding the project name to the command line, e.g. ``paster create -t bfg_starter MyProject``. +.. index:: + single: paster templates + single: project templates + .. _additional_paster_templates: Additional Paster Templates @@ -142,6 +149,9 @@ This will install your application's :term:`package` into the interpreter so it can be found and run as a :term:`WSGI` application inside a WSGI server. +.. index:: + pair: running; tests + Running The Tests For Your Application -------------------------------------- @@ -176,6 +186,9 @@ Here's sample output from a test run: The tests are found in the ``tests.py`` module in your ``paster create`` -generated project. One sample test exists. +.. index:: + single: interactive shell + The Interactive Shell --------------------- @@ -311,6 +324,9 @@ something in your browser like what is displayed below: That's the page shown by default when you visit an unmodified ``paster create``-generated application. +.. index:: + single: project structure + The Project Structure --------------------- @@ -362,6 +378,10 @@ describe, run, and test your application. We won't describe the ``CHANGES.txt`` or ``README.txt`` files. +.. index:: + single: PasteDeploy + single: ini file + .. _MyProject_ini: ``MyProject.ini`` @@ -466,6 +486,9 @@ See the :term:`PasteDeploy` documentation for more information about other types of things you can put into this ``.ini`` file, such as other applications, :term:`middleware` and alternate servers. +.. index:: + single: setup.py + ``setup.py`` ~~~~~~~~~~~~ @@ -541,6 +564,9 @@ tarball to other people who want to use your application. you rerun ``setup.py sdist``, all files checked into the version control system will be included in the tarball. +.. index:: + single: package + The ``myproject`` :term:`Package` --------------------------------- @@ -573,6 +599,9 @@ These are purely conventions established by the ``paster`` template: :mod:`repoze.bfg` doesn't insist that you name things in any particular way. +.. index:: + single: configure.zcml + ``configure.zcml`` ~~~~~~~~~~~~~~~~~~ @@ -626,6 +655,9 @@ the :term:`application registry`. It looks like so: #. Line 17 ends the ``configure`` root tag. +.. index:: + single: views.py + ``views.py`` ~~~~~~~~~~~~ @@ -667,6 +699,9 @@ views, renderers, and templates relate and cooperate. set your project's ``reload_templates`` to ``false`` to increase the speed at which templates may be rendered. +.. index:: + single: models.py + .. _modelspy_project_section: ``models.py`` @@ -695,6 +730,9 @@ make any assumption about which sort of datastore you'll want to use, so the sample application uses an instance of :class:`myproject.models.MyModel` to represent the root. +.. index:: + single: run.py + ``run.py`` ~~~~~~~~~~ @@ -739,6 +777,9 @@ renderers. This directory contains static resources which support the ``mytemplate.pt`` template. It includes CSS and images. +.. index:: + single: tests.py + ``tests.py`` ~~~~~~~~~~~~ diff --git a/docs/narr/resources.rst b/docs/narr/resources.rst index 53d01c920..ce3c746cd 100644 --- a/docs/narr/resources.rst +++ b/docs/narr/resources.rst @@ -1,3 +1,6 @@ +.. index:: + single: resources + .. _resources_chapter: Resources @@ -70,6 +73,10 @@ Package names often contain dots. For example, ``repoze.bfg`` is a package. Resource names usually look a lot like relative UNIX file paths. +.. index:: + single: overriding resources + pair: overriding; resources + .. _overriding_resources_section: Overriding Resources @@ -142,6 +149,9 @@ hammer" way to do the same thing is explained in replace a :term:`view` wholesale rather than resources that might be used by a view. +.. index:: + single: override_resource + .. _override_resource: The ``override_resource`` API @@ -227,6 +237,9 @@ templates and static files. Any software which uses the :func:`pkg_resources.get_resource_string` APIs will obtain an overridden file when an override is used. +.. index:: + pair: ZCML directive; resource + .. _resource_zcml_directive: The ``resource`` ZCML Directive diff --git a/docs/narr/router.rst b/docs/narr/router.rst index 48a068626..98752216a 100644 --- a/docs/narr/router.rst +++ b/docs/narr/router.rst @@ -1,3 +1,7 @@ +.. index:: + single: request processing + single: request + .. _router_chapter: Request Processing diff --git a/docs/narr/scanning.rst b/docs/narr/scanning.rst index 2226b557f..4aceb926b 100644 --- a/docs/narr/scanning.rst +++ b/docs/narr/scanning.rst @@ -23,6 +23,10 @@ For example: registry` if the package the code lives in is run through a :term:`scan`. +.. index:: + single: decorator + single: scan + Decorations and Code Scanning ----------------------------- @@ -84,6 +88,12 @@ Scanning for :term:`configuration decoration` is performed via the ``<scan>`` :term:`ZCML declaration`. See :ref:`config_mode_equivalence` for examples. +.. index:: + pair: configuration mode; equivalence + single: add_view + single: bfg_view + pair: ZCML directive; view + .. _config_mode_equivalence: Configuration Mode Equivalence diff --git a/docs/narr/security.rst b/docs/narr/security.rst index 0d1e3295d..36469def0 100644 --- a/docs/narr/security.rst +++ b/docs/narr/security.rst @@ -12,6 +12,9 @@ appropriate level of access with respect to a specific Authorization is enabled by modifying your application to include a :term:`authentication policy` and :term:`authorization policy`. +.. index:: + pair: enabling; authorization policy + Enabling an Authorization Policy Imperatively --------------------------------------------- @@ -62,6 +65,9 @@ It is also possible to construct your own custom authentication policy or authorization policy: see :ref:`creating_an_authentication_policy` and :ref:`creating_an_authorization_policy`. +.. index:: + triple: enabling; authorization policy; via ZCML + Enabling an Authorization Policy Via ZCML ----------------------------------------- @@ -103,6 +109,10 @@ authentication policy ZCML directives that should prove useful. See :ref:`authentication_policies_directives_section` and :ref:`authorization_policies_directives_section` for more information. +.. index:: + single: permissions + single: protecting views + Protecting Views with Permissions --------------------------------- @@ -146,6 +156,9 @@ Permission names are usually just strings. They hold no special significance to the system. You can name permissions whatever you like. +.. index:: + pair: assigning; ACL + .. _assigning_acls: Assigning ACLs to your Model Objects @@ -201,6 +214,9 @@ individual model instances with an ACL (as opposed to just decorating their class) in applications such as "CMS" systems where fine-grained access is required on an object-by-object basis. +.. index:: + single: ACE + Elements of an ACL ------------------ @@ -287,6 +303,10 @@ view permission. On the other hand, if you have an ACL like this: The authorization policy will deny Everyone the view permission, even though later in the ACL is an ACE that allows everyone. +.. index:: + single: prinicpal + pair: special; principal names + Special Principal Names ----------------------- @@ -308,6 +328,9 @@ ACLs, e.g. :data:`repoze.bfg.security.Everyone`. This object is actually a string "under the hood" (``system.Authenticated``). +.. index:: + pair: special; permission names + Special Permissions ------------------- @@ -325,6 +348,9 @@ module. These can be imported for use in ACLs. known authorization policies, has the effect of indicating that a given principal "has" any permission asked for by the system. +.. index:: + pair: special; ACE + Special ACEs ------------ @@ -352,6 +378,9 @@ authorization policy is in effect might look like so: __acl__ = [ (Allow, 'fred', 'view'), DENY_ALL ] +.. index:: + single: ACL inheritance + ACL Inheritance --------------- @@ -361,6 +390,9 @@ consulted for an ACL. If that object does not have an ACL, *its* parent is consulted for an ACL, ad infinitum, until we've reached the root and there are no more parents left. +.. index:: + pair: location-aware; security + Location-Awareness ------------------ @@ -384,6 +416,9 @@ root object's ``__parent__`` is ``None``. See :ref:`location_module` for documentations of functions which use location-awareness. See also :ref:`location_aware`. +.. index:: + pair: forbidden view; changing + Changing the Forbidden View --------------------------- @@ -394,6 +429,9 @@ of the box", this forbidden view is very plain. See instructions on how to create a custom forbidden view and arrange for it to be called when view authorization is denied. +.. index:: + pair: debugging; authorization failures + .. _debug_authorization_section: Debugging View Authorization Failures @@ -440,6 +478,9 @@ denied or allowed. Introspecting this information in the debugger or via print statements when a call to :func:`repoze.bfg.security.has_permission` fails is often useful. +.. index:: + pair: ZCML directive; authentication policy + .. _authentication_policies_directives_section: Built-In Authentication Policy ZCML Directives @@ -516,6 +557,9 @@ An example of its usage, with all attributes fully expanded: See :ref:`repozewho1authenticationpolicy_directive` for detailed information. +.. index:: + pair: ZCML directive; authorization policy + .. _authorization_policies_directives_section: Built-In Authorization Policy ZCML Directives @@ -538,6 +582,9 @@ In other words, it has no configuration attributes; its existence in a See :ref:`aclauthorizationpolicy_directive` for detailed information. +.. index:: + pair: creating; authentication policy + .. _creating_an_authentication_policy: Creating Your Own Authentication Policy @@ -578,6 +625,9 @@ After you do so, you can pass an instance of such a class into the :class:`repoze.bfg.configuration.Configurator` class at configuration time as ``authentication_policy`` to use it. +.. index:: + pair: creating; authorization policy + .. _creating_an_authorization_policy: Creating Your Own Authorization Policy diff --git a/docs/narr/startup.rst b/docs/narr/startup.rst index 4e806ec17..960e2aa1d 100644 --- a/docs/narr/startup.rst +++ b/docs/narr/startup.rst @@ -17,6 +17,9 @@ This chapter explains what happens between the time you press the myproject/MyProject.ini`` and the the time the line ``serving on 0.0.0.0:6543 ...`` is output to your console. +.. index:: + single: startup process + The Startup Process ------------------- diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst index 1ea8da369..ac44b64da 100644 --- a/docs/narr/templates.rst +++ b/docs/narr/templates.rst @@ -7,6 +7,9 @@ information that is static. :mod:`repoze.bfg` offers a number of ways to perform templating tasks "out of the box", and provides alternative templating language support via add-on "bindings" packages. +.. index:: + triple: Chameleon; ZPT; templates + .. _chameleon_zpt_templates: Templating With :term:`Chameleon` ZPT Page Templates @@ -90,6 +93,10 @@ changing the content-type and status: response.status_int = 204 return response +.. index:: + single: templates used as renderers + pair: renderers; template + Templates Used as Renderers --------------------------- @@ -141,6 +148,9 @@ renderer configuration can be done imperatively and via :term:`ZCML`. See :ref:`views_which_use_a_renderer`. See also :ref:`built_in_renderers`. +.. index:: + single: sample template + A Sample Template ----------------- @@ -175,6 +185,9 @@ of keywords passed in to it via attribute-based syntax (e.g. ``tal:content`` and ``tal:replace``) also works in these templates. +.. index:: + single: ZPT macros + Using ZPT Macros in :mod:`repoze.bfg` ------------------------------------- @@ -235,6 +248,9 @@ And ``templates/mytemplate.pt`` might look like so: </span> </html> +.. index:: + pair: Chameleon; text templates + .. _chameleon_text_templates: Templating with :term:`Chameleon` Text Templates @@ -269,6 +285,9 @@ place; see :ref:`chameleon_text_module` for the API description. A Chameleon text template can also be used as a :term:`renderer`. See :ref:`built_in_renderers` for more information. +.. index:: + pair: template renderer; side effects + Side Effects of Rendering a Chameleon Template ---------------------------------------------- @@ -295,6 +314,9 @@ should cause it to ignore these files. Here's the contents of my *.cache *.pt.py +.. index:: + pair: template; automatic reloading + .. _reload_templates_section: Automatically Reloading Templates @@ -327,6 +349,9 @@ application's configuration section, e.g.:: use = egg:MyProject#app reload_templates = true +.. index:: + pair: template; internationalization + :term:`Chameleon` Template Internationalization ----------------------------------------------- @@ -335,6 +360,9 @@ See `the internationalization chapter documentation for information about supporting internationalized units of text within :term:`Chameleon` templates. +.. index:: + single: other templating languages + Templating with other Templating Languages ------------------------------------------ @@ -374,6 +402,11 @@ template resource overriding capability explained in possible to use any template using that language as a :term:`renderer`. +.. index:: + single: template system bindings + single: Jinja2 + single: Genshi + .. _available_template_system_bindings: Available Add-On Template System Bindings diff --git a/docs/narr/threadlocals.rst b/docs/narr/threadlocals.rst index a799e2d03..4600b7a88 100644 --- a/docs/narr/threadlocals.rst +++ b/docs/narr/threadlocals.rst @@ -1,3 +1,8 @@ +.. index:: + single: thread local variables + single: get_current_request + single: get_current_registry + .. _threadlocals_chapter: Thread Locals diff --git a/docs/narr/traversal.rst b/docs/narr/traversal.rst index 3476622d5..e59212728 100644 --- a/docs/narr/traversal.rst +++ b/docs/narr/traversal.rst @@ -13,6 +13,11 @@ Python class or any :term:`interface` attached to it). If :mod:`repoze.bfg` finds a :term:`view` for the context, it calls it and returns a response to the user. +.. index:: + single: object graph + single: traversal graph + single: model graph + The Object Graph ---------------- @@ -55,6 +60,9 @@ concept of :term:`model` objects used by many other frameworks (and :mod:`repoze.bfg` APIs often refers to them as "models", as well). They are typically instances of Python classes. +.. index:: + single: traversal behavior + .. _traversal_behavior: :mod:`repoze.bfg` Traversal Behavior @@ -240,6 +248,9 @@ code to execute: In either case, the result is returned upstream via the :term:`WSGI` protocol. +.. index:: + pair: traversal; example + A Traversal Example ------------------- @@ -361,6 +372,9 @@ There are two special cases: views that may have the same names as model instance names in the graph unambiguously. +.. index:: + pair: traversal; side-effects + .. _traversal_related_side_effects: Traversal-Related Side Effects @@ -402,6 +416,9 @@ will be a sequence representing the ordered set of names that were used to traverse to the virtual root object. See :ref:`vhosting_chapter` for more information about virtual roots. +.. index:: + pair: debugging; not found errors + .. _debug_notfound_section: :exc:`NotFound` Errors @@ -416,6 +433,9 @@ be printed to ``stderr``, and the browser representation of the error will include the same information. See :ref:`environment_chapter` for more information about how and where to set these values. +.. index:: + pair: traversal; unicode + Traversal and Unicode --------------------- diff --git a/docs/narr/unittesting.rst b/docs/narr/unittesting.rst index 316142c08..d032e3a36 100644 --- a/docs/narr/unittesting.rst +++ b/docs/narr/unittesting.rst @@ -1,3 +1,7 @@ +.. index:: + single: unit testing + single: integration testing + .. _unittesting_chapter: Unit and Integration Testing @@ -51,6 +55,11 @@ integration tests easier to write. The facilities become particularly useful when your code calls into :mod:`repoze.bfg` -related framework functions. +.. index:: + pair: test; setup + pair: test; tear down + single: unittest + .. _test_setup_and_teardown: Test Set Up and Tear Down @@ -151,6 +160,10 @@ method within the ``setUp`` of a unit test, then subsequently call its anything if the application you're testing does not call any ``get_current*`` function. +.. index:: + single: repoze.bfg.testing + pair: Configurator; testing + Using the ``Configurator`` and ``repoze.bfg.testing`` APIs in Unit Tests ------------------------------------------------------------------------ @@ -282,6 +295,9 @@ representing "dummy" implementations of a request and a model. See also the various methods of the :term:`Configurator` documented in :ref:`configuration_module` that begin with the ``testing_`` prefix. +.. index:: + pair: creating; integration tests + .. _integration_tests: Creating Integration Tests diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst index 2d74bfbca..728795e7f 100644 --- a/docs/narr/urldispatch.rst +++ b/docs/narr/urldispatch.rst @@ -1,3 +1,6 @@ +.. index:: + single: url dispatch + .. _urldispatch_chapter: URL Dispatch @@ -53,6 +56,9 @@ error to the user's browser when no routes match. .. note:: See :ref:`modelspy_project_section` for an example of a simple root factory callable that will use traversal. +.. index:: + single: add_route + The ``add_route`` Configurator Method ------------------------------------- @@ -65,6 +71,9 @@ registry`. Here's an example: config.add_route('myroute', '/prefix/:one/:two') +.. index:: + single: ZCML directive; route + Configuring a Route via ZCML ---------------------------- @@ -85,6 +94,9 @@ documentation. .. note:: The documentation that follows in this chapter assumes that :term:`ZCML` will be used to perform route configuration. +.. index:: + pair: URL dispatch; matchdict + The Matchdict ------------- @@ -95,6 +107,9 @@ matched, a dictionary is placed on the request named ``matchdict`` with the values that match patterns in the ``path`` element. If the URL pattern does not match, no matchdict is generated. +.. index:: + pair: URL dispatch; path pattern syntax + .. _route_path_pattern_syntax: Path Pattern Syntax @@ -204,6 +219,9 @@ Will generate the following matchdict: {'traverse':(u'La Pe\xf1a', u'a', u'b', u'c')} +.. index:: + triple: ZCML directive; route; examples + ``<route>`` Statement Examples ------------------------------ @@ -419,6 +437,9 @@ In this case in particular, when a user visits Article class and it will have an ``article`` attribute with the value of ``something``. +.. index:: + pair: URL dispatch; catching root URL + Catching the Root URL --------------------- @@ -446,6 +467,9 @@ Or provide the literal string ``/`` as the path: view=".views.root_view" /> +.. index:: + pair: URL dispatch; generating route URLs + Generating Route URLs --------------------- @@ -467,6 +491,9 @@ hostname implied ``http:/example.com``). See the :func:`repoze.bfg.url.route_url` API documentation for more information. +.. index:: + pair: URL dispatch; slash-redirecting + Redirecting to Slash-Appended Routes ------------------------------------ @@ -574,6 +601,9 @@ Then in the ``configure.zcml`` of your package, inject the following: This will cause the DBSession to be removed whenever the WSGI environment is destroyed (usually at the end of every request). +.. index:: + pair: URL dispatch; security + .. _using_security_with_urldispatch: Using :mod:`repoze.bfg` Security With URL Dispatch diff --git a/docs/narr/urlmapping.rst b/docs/narr/urlmapping.rst index e5933ae1e..1f094d452 100644 --- a/docs/narr/urlmapping.rst +++ b/docs/narr/urlmapping.rst @@ -29,6 +29,9 @@ potentially heterogeneous items, or if you need to attach "instance-level" security (akin to "row-level" security in relational parlance) declarations to :term:`model` instances. +.. index:: + triple: differences; URL dispatch; traversal + Differences Between Traversal and URL Dispatch ---------------------------------------------- diff --git a/docs/narr/vhosting.rst b/docs/narr/vhosting.rst index 964741080..80336fe82 100644 --- a/docs/narr/vhosting.rst +++ b/docs/narr/vhosting.rst @@ -3,6 +3,9 @@ Virtual Hosting =============== +.. index:: + pair: virtual hosting; URL prefix + Hosting an Application Under a URL Prefix ----------------------------------------- @@ -63,6 +66,9 @@ setting in a :term:`mod_wsgi` configuration does the work for you: In the above configuration, we root a :mod:`repoze.bfg` application at ``/bfgapp`` within the Apache configuration. +.. index:: + pair: virtual hosting; virtual root + Virtual Root Support -------------------- diff --git a/docs/narr/views.rst b/docs/narr/views.rst index 1a507f432..b25756fd9 100644 --- a/docs/narr/views.rst +++ b/docs/narr/views.rst @@ -38,6 +38,11 @@ adding a ``<route>`` statement to :term:`ZCML` used by your application. See :ref:`urldispatch_chapter` for more information on mapping URLs to views using routes. +.. index:: + pair: view; calling convention + single: view function + pair: view; function + .. _function_as_view: Defining a View as a Function @@ -56,6 +61,11 @@ implemented as a function: def hello_world(request): return Response('Hello world!') +.. index:: + pair: view; calling convention + single: view class + pair: view; class + .. _class_as_view: Defining a View as a Class @@ -100,6 +110,9 @@ represent the method expected to return a response, you can use an ``attr`` value as part of view configuration. See :ref:`view_configuration`. +.. index:: + pair: view; calling convention + .. _request_and_context_view_definitions: Request-And-Context View Definitions @@ -167,6 +180,9 @@ view code itself. No matter which view calling convention is used, the view always has access to the context via ``request.context``. +.. index:: + pair: view; response + .. _the_response: View Responses @@ -203,6 +219,10 @@ to construct a response. The associated renderer can be varied for a view by changing the ``renderer`` attribute in the view's configuration. See :ref:`views_which_use_a_renderer`. +.. index:: + single: renderer + pair: view; renderer + .. _views_which_use_a_renderer: Writing Views Which Use a Renderer @@ -259,6 +279,10 @@ class as a response, no renderer will be employed. Additional renderers can be added to the system as necessary via a ZCML directive (see :ref:`adding_and_overriding_renderers`). +.. index:: + single: view configuration + pair: view; configuration + .. _view_configuration: View Configuration: Mapping Views to URLs @@ -270,6 +294,9 @@ method, by adding ``view`` declarations using :term:`ZCML` or by using the :class:`repoze.bfg.view.bfg_view` decorator. Each method is explained below. +.. index:: + triple: zcml; view; configuration + .. _mapping_views_to_urls_using_zcml_section: View Configuration Via ZCML @@ -342,6 +369,9 @@ apply for the class which is named. See :ref:`view_directive` for complete ZCML directive documentation. +.. index:: + triple: view; bfg_view; decorator + .. _mapping_views_to_urls_using_a_decorator_section: View Configuration Using the ``@bfg_view`` Decorator @@ -638,6 +668,10 @@ could be spelled equivalently as the below: version 1.1. Previously it could only be used as a class or function decorator. +.. index:: + single: add_view + triple: imperative; adding; view + View Configuration Using the ``add_view`` Method of a Configurator ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -645,6 +679,9 @@ See the :meth:`repoze.bfg.configuration.Configurator.add_view` method within :ref:`configuration_module` for the arguments to configure a view imperatively. +.. index:: + pair: view; lookup ordering + .. _view_lookup_ordering: View Lookup Ordering @@ -703,6 +740,9 @@ to convert non-response return values from a view. The value of the ``attr`` attribute represents the attribute name looked up on the view object to return a response. +.. index:: + pair: model; interfaces + .. _using_model_interfaces: Using Model Interfaces @@ -790,6 +830,9 @@ view registered for the context's class will "win". See :term:`Interface` in the glossary to find more information about interfaces. +.. index:: + pair: renderers; built-in + .. _built_in_renderers: Built-In Renderers @@ -799,6 +842,9 @@ Several built-in "renderers" exist in :mod:`repoze.bfg`. These renderers can be used in the ``renderer`` attribute of view configurations. +.. index:: + pair: renderer; string + ``string``: String Renderer ~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -832,6 +878,9 @@ representing the ``str()`` serialization of the return value: {'content': 'Hello!'} +.. index:: + pair: renderer; JSON + ``json``: JSON Renderer ~~~~~~~~~~~~~~~~~~~~~~~ @@ -883,6 +932,9 @@ Views which use the JSON renderer can vary non-body response attributes by attaching properties to the request. See :ref:`response_request_attrs`. +.. index:: + pair: renderer; chameleon + .. _chameleon_template_renderers: ``*.pt`` or ``*.txt``: Chameleon Template Renderers @@ -958,6 +1010,11 @@ Views with use a Chameleon renderer can vary response attributes by attaching properties to the request. See :ref:`response_request_attrs`. +.. index:: + pair: renderer; response attributes + pair: renderer; changing headers + triple: headers; changing; renderer + .. _response_request_attrs: Varying Attributes of Rendered Responses @@ -999,6 +1056,9 @@ callable to influence automatically constructed response attributes. achieved by returning various values in the ``response_headerlist``, this is purely a convenience. +.. index:: + pair: renderers; adding + .. _adding_and_overriding_renderers: Adding and Overriding Renderers @@ -1147,6 +1207,9 @@ tag): See also :ref:`renderer_directive`. +.. index:: + pair: view; security + .. _view_security_section: View Security @@ -1188,6 +1251,9 @@ user does not possess the ``add`` permission relative to the current authenticate. Use this kind of package to ask the user for authentication credentials. +.. index:: + pair: view; http redirect + Using a View to Do A HTTP Redirect ---------------------------------- @@ -1207,6 +1273,9 @@ Webob :term:`Response` interface; any can be returned as the response from a view. See :term:`WebOb` for the documentation for this module; it includes other response types for ``Unauthorized``, etc. +.. index:: + triple: view; zcml; static resource + .. _static_resources_section: Serving Static Resources Using a ZCML Directive @@ -1275,6 +1344,9 @@ See :ref:`static_directive` for detailed information. .. note:: The ``<static>`` ZCML directive is new in :mod:`repoze.bfg` 1.1. +.. index:: + pair: generating; static resource + .. _generating_static_resource_urls: Generating Static Resource URLs @@ -1342,6 +1414,9 @@ URLs will continue to resolve properly after the rename. .. note:: The :func:`repoze.bfg.url.static_url` API is new in :mod:`repoze.bfg` 1.1. +.. index:: + pair: view; static resource + Serving Static Resources Using a View ------------------------------------- @@ -1409,6 +1484,9 @@ In this case, ``.models.Root`` refers to the class of which your ``/static/foo.js``. See :ref:`traversal_chapter` for information about "goggles" (``@@``). +.. index:: + triple: exceptions; special; view + Special Exceptions ------------------ @@ -1434,6 +1512,9 @@ In all cases, the message provided to the exception constructor is made available to the view which :mod:`repoze.bfg` invokes as ``request.environ['repoze.bfg.message']``. +.. index:: + triple: view; forms; unicode + Using Views to Handle Form Submissions (Unicode and Character Set Issues) ------------------------------------------------------------------------- diff --git a/docs/narr/webob.rst b/docs/narr/webob.rst index c4bd568c7..91413efd0 100644 --- a/docs/narr/webob.rst +++ b/docs/narr/webob.rst @@ -36,6 +36,9 @@ document. The `reference documentation <http://pythonpaste.org/webob/reference.html>`_ shows many examples of creating requests. +.. index:: + single: request object + Request ~~~~~~~ @@ -155,6 +158,9 @@ If it is set, then ``req.POST``, ``req.GET``, ``req.params``, and corresponding ``req.str_*`` (like ``req.str_POST``) that is always ``str`` and never unicode. +.. index:: + single: response object + Response ~~~~~~~~ @@ -222,6 +228,9 @@ Here's the highlights: ``conditional_response=True`` when instantiating (or set that attribute later). It can also do HEAD and Range requests. +.. index:: + pair: response; headers + Headers +++++++ @@ -249,7 +258,10 @@ The status defaults to ``'200 OK'``. The content_type does not default to anything, though if you subclass ``Response`` and set ``default_content_type`` you can override this behavior. -Exceptions +.. index:: + pair: WebOb; exceptions + +xceptions ++++++++++ To facilitate error responses like 404 Not Found, the module @@ -290,6 +302,9 @@ The exceptions are still WSGI applications, but you cannot set attributes like ``content_type``, ``charset``, etc. on these exception objects. +.. index:: + pair: WebOb; multidict + Multidict +++++++++ |