Skip to content
Browse files

first cut (one test still fails)

  • Loading branch information...
1 parent cc95583 commit 5046ea4606addd74008422637be08c5b796af769 @mcdonc mcdonc committed Jan 16, 2011
Showing with 4,919 additions and 0 deletions.
  1. +6 −0 .gitignore
  2. +5 −0 CHANGES.txt
  3. +2 −0 docs/.gitignore
  4. BIN docs/.static/logo_hi.gif
  5. +25 −0 docs/.static/repoze.css
  6. +88 −0 docs/Makefile
  7. +7 −0 docs/api.rst
  8. +209 −0 docs/conf.py
  9. +306 −0 docs/glossary.rst
  10. +65 −0 docs/index.rst
  11. +32 −0 docs/zcml.rst
  12. +35 −0 docs/zcml/aclauthorizationpolicy.rst
  13. +47 −0 docs/zcml/adapter.rst
  14. +65 −0 docs/zcml/asset.rst
  15. +102 −0 docs/zcml/authtktauthenticationpolicy.rst
  16. +93 −0 docs/zcml/configure.rst
  17. +57 −0 docs/zcml/default_permission.rst
  18. +77 −0 docs/zcml/forbidden.rst
  19. +71 −0 docs/zcml/include.rst
  20. +39 −0 docs/zcml/localenegotiator.rst
  21. +77 −0 docs/zcml/notfound.rst
  22. +51 −0 docs/zcml/remoteuserauthenticationpolicy.rst
  23. +51 −0 docs/zcml/renderer.rst
  24. +53 −0 docs/zcml/repozewho1authenticationpolicy.rst
  25. +223 −0 docs/zcml/route.rst
  26. +34 −0 docs/zcml/scan.rst
  27. +89 −0 docs/zcml/static.rst
  28. +45 −0 docs/zcml/subscriber.rst
  29. +64 −0 docs/zcml/translationdir.rst
  30. +46 −0 docs/zcml/utility.rst
  31. +266 −0 docs/zcml/view.rst
  32. +830 −0 pyramid_zcml/__init__.py
  33. +5 −0 pyramid_zcml/configure.zcml
  34. +123 −0 pyramid_zcml/meta.zcml
  35. +1 −0 pyramid_zcml/tests/__init__.py
  36. +1 −0 pyramid_zcml/tests/fixtureapp/__init__.py
  37. +10 −0 pyramid_zcml/tests/fixtureapp/another.zcml
  38. +37 −0 pyramid_zcml/tests/fixtureapp/configure.zcml
  39. +8 −0 pyramid_zcml/tests/fixtureapp/models.py
  40. +1 −0 pyramid_zcml/tests/fixtureapp/subpackage/__init__.py
  41. +2 −0 pyramid_zcml/tests/fixtureapp/subpackage/templates/bar.pt
  42. +8 −0 pyramid_zcml/tests/fixtureapp/subpackage/yetanother.zcml
  43. +6 −0 pyramid_zcml/tests/fixtureapp/templates/fixture.pt
  44. +14 −0 pyramid_zcml/tests/fixtureapp/views.py
  45. +1 −0 pyramid_zcml/tests/localeapp/__init__.py
  46. +1 −0 pyramid_zcml/tests/localeapp/locale/GARBAGE
  47. +1 −0 pyramid_zcml/tests/localeapp/locale/be/LC_MESSAGES
  48. BIN pyramid_zcml/tests/localeapp/locale/de/LC_MESSAGES/deformsite.mo
  49. +31 −0 pyramid_zcml/tests/localeapp/locale/de/LC_MESSAGES/deformsite.po
  50. BIN pyramid_zcml/tests/localeapp/locale/en/LC_MESSAGES/deformsite.mo
  51. +31 −0 pyramid_zcml/tests/localeapp/locale/en/LC_MESSAGES/deformsite.po
  52. +1 −0 pyramid_zcml/tests/routesapp/__init__.py
  53. +12 −0 pyramid_zcml/tests/routesapp/configure.zcml
  54. +5 −0 pyramid_zcml/tests/routesapp/models.py
  55. +6 −0 pyramid_zcml/tests/routesapp/templates/fixture.pt
  56. +8 −0 pyramid_zcml/tests/routesapp/views.py
  57. +1,372 −0 pyramid_zcml/tests/tests.py
  58. +9 −0 setup.cfg
  59. +65 −0 setup.py
View
6 .gitignore
@@ -0,0 +1,6 @@
+env26/
+*.egg
+*.egg-info
+*.pyc
+.coverage
+dist/
View
5 CHANGES.txt
@@ -0,0 +1,5 @@
+Next release
+============
+
+- ...
+
View
2 docs/.gitignore
@@ -0,0 +1,2 @@
+_themes
+_build/
View
BIN docs/.static/logo_hi.gif
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
View
25 docs/.static/repoze.css
@@ -0,0 +1,25 @@
+@import url('default.css');
+body {
+ background-color: #006339;
+}
+
+div.document {
+ background-color: #dad3bd;
+}
+
+div.sphinxsidebar h3, h4, h5, a {
+ color: #127c56 !important;
+}
+
+div.related {
+ color: #dad3bd !important;
+ background-color: #00744a;
+}
+
+div.related a {
+ color: #dad3bd !important;
+}
+
+div.body p, div.body dd, div.body li {
+ text-align: left;
+}
View
88 docs/Makefile
@@ -0,0 +1,88 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS =
+SPHINXBUILD = ../env26/bin/sphinx-build
+PAPER =
+
+# Internal variables.
+PAPEROPT_a4 = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS = -d _build/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+
+.PHONY: help clean html web pickle htmlhelp latex changes linkcheck
+
+help:
+ @echo "Please use \`make <target>' where <target> is one of"
+ @echo " html to make standalone HTML files"
+ @echo " pickle to make pickle files (usable by e.g. sphinx-web)"
+ @echo " htmlhelp to make HTML files and a HTML help project"
+ @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+ @echo " changes to make an overview over all changed/added/deprecated items"
+ @echo " linkcheck to check all external links for integrity"
+
+clean:
+ -rm -rf _build/*
+
+html: _themes/
+ mkdir -p _build/html _build/doctrees
+ $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) _build/html
+ @echo
+ @echo "Build finished. The HTML pages are in _build/html."
+
+text:
+ mkdir -p _build/text _build/doctrees
+ $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) _build/text
+ @echo
+ @echo "Build finished. The HTML pages are in _build/text."
+
+pickle:
+ mkdir -p _build/pickle _build/doctrees
+ $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) _build/pickle
+ @echo
+ @echo "Build finished; now you can process the pickle files or run"
+ @echo " sphinx-web _build/pickle"
+ @echo "to start the sphinx-web server."
+
+web: pickle
+
+htmlhelp: _themes
+ mkdir -p _build/htmlhelp _build/doctrees
+ $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) _build/htmlhelp
+ @echo
+ @echo "Build finished; now you can run HTML Help Workshop with the" \
+ ".hhp project file in _build/htmlhelp."
+
+latex:
+ mkdir -p _build/latex _build/doctrees
+ $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) _build/latex
+ cp _static/*.png _build/latex
+ ./convert_images.sh
+ cp _static/latex-warning.png _build/latex
+ cp _static/latex-note.png _build/latex
+ @echo
+ @echo "Build finished; the LaTeX files are in _build/latex."
+ @echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
+ "run these through (pdf)latex."
+
+changes:
+ mkdir -p _build/changes _build/doctrees
+ $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) _build/changes
+ @echo
+ @echo "The overview file is in _build/changes."
+
+linkcheck:
+ mkdir -p _build/linkcheck _build/doctrees
+ $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) _build/linkcheck
+ @echo
+ @echo "Link check complete; look for any errors in the above output " \
+ "or in _build/linkcheck/output.txt."
+
+epub:
+ $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) _build/epub
+ @echo
+ @echo "Build finished. The epub file is in _build/epub."
+
+_themes:
+ git clone git://github.com/Pylons/pylons_sphinx_theme.git _themes
View
7 docs/api.rst
@@ -0,0 +1,7 @@
+.. _pyramid_zcml_api:
+
+:mod:`pyramid_zcml` API
+-----------------------
+
+.. automodule:: pyramid_zcml
+
View
209 docs/conf.py
@@ -0,0 +1,209 @@
+# -*- coding: utf-8 -*-
+#
+# pyramid_zcml documentation build configuration file
+#
+# This file is execfile()d with the current directory set to its containing
+# dir.
+#
+# The contents of this file are pickled, so don't put values in the
+# namespace that aren't pickleable (module imports are okay, they're
+# removed automatically).
+#
+# All configuration values have a default value; values that are commented
+# out serve to show the default value.
+
+# If your extensions are in another directory, add it here. If the
+# directory is relative to the documentation root, use os.path.abspath to
+# make it absolute, like shown here.
+#sys.path.append(os.path.abspath('some/directory'))
+
+import sys, os
+
+parent = os.path.dirname(os.path.dirname(__file__))
+sys.path.append(os.path.abspath(parent))
+wd = os.getcwd()
+os.chdir(parent)
+os.system('%s setup.py test -q' % sys.executable)
+os.chdir(wd)
+
+for item in os.listdir(parent):
+ if item.endswith('.egg'):
+ sys.path.append(os.path.join(parent, item))
+
+# General configuration
+# ---------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+extensions = [
+ 'sphinx.ext.autodoc',
+ 'sphinx.ext.intersphinx',
+ ]
+
+# Looks for pyramid's objects
+intersphinx_mapping = {
+ 'pyramid':
+ ('http://docs.pylonsproject.org/projects/pyramid/dev/', None)}
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['.templates']
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General substitutions.
+project = 'pyramid_zcml'
+copyright = '2010, Agendaless Consulting <chrism@plope.com>'
+
+# The default replacements for |version| and |release|, also used in various
+# other places throughout the built documents.
+#
+# The short X.Y version.
+version = '0.4'
+# The full version, including alpha/beta/rc tags.
+release = version
+
+# There are two options for replacing |today|: either, you set today to
+# some non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+today_fmt = '%B %d, %Y'
+
+# List of documents that shouldn't be included in the build.
+#unused_docs = []
+
+# List of directories, relative to source directories, that shouldn't be
+# searched for source files.
+#exclude_dirs = []
+
+# The reST default role (used for this markup: `text`) to use for all
+# documents.
+#default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+
+# Options for HTML output
+# -----------------------
+
+# Add and use Pylons theme
+sys.path.append(os.path.abspath('_themes'))
+html_theme_path = ['_themes']
+html_theme = 'pylons'
+
+# The style sheet to use for HTML and HTML Help pages. A file of that name
+# must exist either in Sphinx' static/ path, or in one of the custom paths
+# given in html_static_path.
+# html_style = 'repoze.css'
+
+# The name for this set of Sphinx documents. If None, it defaults to
+# "<project> v<release> documentation".
+#html_title = None
+
+# A shorter title for the navigation bar. Default is the same as
+# html_title.
+#html_short_title = None
+
+# The name of an image file (within the static path) to place at the top of
+# the sidebar.
+# html_logo = '.static/logo_hi.gif'
+
+# The name of an image file (within the static path) to use as favicon of
+# the docs. This file should be a Windows icon file (.ico) being 16x16 or
+# 32x32 pixels large.
+#html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets)
+# here, relative to this directory. They are copied after the builtin
+# static files, so a file named "default.css" will overwrite the builtin
+# "default.css".
+html_static_path = ['.static']
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page
+# bottom, using the given strftime format.
+html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+#html_use_modindex = True
+
+# If false, no index is generated.
+#html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, the reST sources are included in the HTML build as
+# _sources/<name>.
+#html_copy_source = True
+
+# If true, an OpenSearch description file will be output, and all pages
+# will contain a <link> tag referring to it. The value of this option must
+# be the base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = ''
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'atemplatedoc'
+
+
+# Options for LaTeX output
+# ------------------------
+
+# The paper size ('letter' or 'a4').
+#latex_paper_size = 'letter'
+
+# The font size ('10pt', '11pt' or '12pt').
+#latex_font_size = '10pt'
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+# author, document class [howto/manual]).
+latex_documents = [
+ ('index', 'pyramid_zcml.tex', 'pyramid_zcml Documentation',
+ 'Repoze Developers', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the
+# top of the title page.
+latex_logo = '.static/logo_hi.gif'
+
+# For "manual" documents, if this is true, then toplevel headings are
+# parts, not chapters.
+#latex_use_parts = False
+
+# Additional stuff for the LaTeX preamble.
+#latex_preamble = ''
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_use_modindex = True
View
306 docs/glossary.rst
@@ -0,0 +1,306 @@
+.. _glossary:
+
+Glossary
+========
+
+.. glossary::
+ :sorted:
+
+ Pyramid
+ A `web framework <http://pylonshq.com/pyramid>`_.
+
+ View handler
+ A view handler ties together
+ :meth:`pyramid.config.Configurator.add_route` and
+ :meth:`pyramid.config.Configurator.add_view` to make it more
+ convenient to register a collection of views as a single class when
+ using :term:`url dispatch`. See also :ref:`views_chapter`.
+
+ Pylons
+ `A lightweight Python web framework <http://pylonshq.com>`_.
+
+ URL dispatch
+ An alternative to :term:`traversal` as a mechanism for locating a a
+ :term:`view callable`. When you use a :term:`route` in your Pyramid
+ application via a :term:`route configuration`, you are using URL
+ dispatch. See the :ref:`urldispatch_chapter` for more information.
+
+ ZCML
+ `Zope Configuration Markup Language
+ <http://www.muthukadan.net/docs/zca.html#zcml>`_, an XML dialect
+ used by Zope and Pyramid for configuration tasks. ZCML
+ is capable of performing different types of :term:`configuration
+ declaration`, but its primary purpose in Pyramid is to
+ perform :term:`view configuration` and :term:`route configuration`
+ within the ``configure.zcml`` file in a Pyramid
+ application. You can use ZCML as an alternative to
+ :term:`imperative configuration`.
+
+ asset specification
+ A colon-delimited identifier for an :term:`asset`. The colon separates
+ a Python :term:`package` name from a package subpath. For example, the
+ asset specification ``my.package:static/baz.css`` identifies the file
+ named ``baz.css`` in the ``static`` subdirectory of the ``my.package``
+ Python :term:`package`. See :ref:`asset_specifications` for more info.
+
+ 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``, which will be an
+ instance of a :term:`request` object. A view callable is the primary
+ mechanism by which a developer writes user interface code within
+ Pyramid. See :ref:`views_chapter` for more information about Pyramid
+ view callables.
+
+ view
+ Common vernacular for a :term:`view callable`.
+
+ 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.
+
+ traversal
+ The act of descending "up" a tree of resource objects from a root
+ resource in order to find a context resource. The Pyramid
+ :term:`router` performs traversal of resource objects when a :term:`root
+ factory` is specified. See the :ref:`traversal_chapter` chapter for
+ more information. Traversal can be performed *instead* of :term:`URL
+ dispatch` or can be combined *with* URL dispatch. See
+ :ref:`hybrid_chapter` for more information about combining traversal and
+ URL dispatch (advanced).
+
+ 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.
+
+ 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
+ pattern matching and :term:`route predicate` statements. See
+ :ref:`urldispatch_chapter` for more information about route
+ 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 callable and it can
+ influence the response of a view callable. Pyramid views can be
+ configured via :term:`imperative configuration`, :term:`ZCML` or by a
+ special ``@view_config`` decorator coupled with a :term:`scan`. See
+ :ref:`view_config_chapter` for more information about view
+ configuration.
+
+ configuration declaration
+ An individual method call made to an instance of a Pyramid
+ :term:`Configurator` object which performs an arbitrary action, such as
+ registering a :term:`view configuration` (via the ``add_view`` method of
+ the configurator) or :term:`route configuration` (via the ``add_route``
+ method of the configurator).
+
+ request
+ A ``WebOb`` request object. See :ref:`webob_chapter` (narrative)
+ and :ref:`request_module` (API documentation) for information
+ about request objects.
+
+ scan
+ The term used by Pyramid to define the process of
+ importing and examining all code in a Python package or module for
+ :term:`configuration decoration`.
+
+ route
+ A single pattern matched by the :term:`url dispatch` subsystem, which
+ generally resolves to one or more :term:`view callable` objects. See
+ also :term:`url dispatch`.
+
+ asset
+ Any file contained within a Python :term:`package` which is *not*
+ a Python source code file.
+
+ asset specification
+ A colon-delimited identifier for an :term:`asset`. The colon separates
+ a Python :term:`package` name from a package subpath. For example, the
+ asset specification ``my.package:static/baz.css`` identifies the file
+ named ``baz.css`` in the ``static`` subdirectory of the ``my.package``
+ Python :term:`package`. See :ref:`asset_specifications` for more info.
+
+ package
+ A directory on disk which contains an ``__init__.py`` file, making
+ it recognizable to Python as a location which can be ``import`` -ed.
+ A package exists to contain :term:`module` files.
+
+ module
+ A Python source file; a file on the filesystem that typically ends with
+ the extension ``.py`` or ``.pyc``. Modules often live in a
+ :term:`package`.
+
+ configurator
+ An object used to do :term:`configuration declaration` within an
+ application. The most common configurator is an instance of the
+ ``pyramid.config.Configurator`` class.
+
+ 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
+ configuration` must evaluate to ``True`` for the associated route
+ to "match" the current request. If a route does not match the
+ current request, the next route (in definition order) is
+ attempted.
+
+ root factory
+ The "root factory" of an Pyramid application is called
+ on every request sent to the application. The root factory
+ returns the traversal root of an application. It is
+ conventionally named ``get_root``. An application may supply a
+ root factory to Pyramid during the construction of a
+ :term:`Configurator`. If a root factory is not supplied, the
+ application uses a default root object. Use of the default root
+ object is useful in application which use :term:`URL dispatch` for
+ all URL-to-view code mappings.
+
+ configuration decoration
+ Metadata implying one or more :term:`configuration declaration`
+ invocations. Often set by configuration Python :term:`decorator`
+ attributes, such as :class:`pyramid.view.view_config`, aka
+ ``@view_config``.
+
+ 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.
+ Pyramid provides several decorators, used for configuration and return
+ value modification purposes. See also `PEP 318
+ <http://www.python.org/dev/peps/pep-0318/>`_.
+
+ router
+ The :term:`WSGI` application created when you start a
+ Pyramid application. The router intercepts requests,
+ invokes traversal and/or URL dispatch, calls view functions, and
+ returns responses to the WSGI server on behalf of your
+ Pyramid application.
+
+ WSGI
+ `Web Server Gateway Interface <http://wsgi.org/>`_. This is a
+ Python standard for connecting web applications to web servers,
+ similar to the concept of Java Servlets. Pyramid requires
+ that your application be served as a WSGI application.
+
+ 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
+ within :term:`ZCML` attributes that name objects (such as the ZCML
+ "view" directive's "view" attribute): the colon (``:``) is not
+ used; in its place is a dot.
+
+ application registry
+ A registry of configuration information consulted by
+ Pyramid while servicing an application. An application
+ registry maps resource types to views, as well as housing other
+ application-specific component registrations. Every
+ Pyramid application has one (and only one) application
+ registry.
+
+ 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`).
+
+ Default view
+ The default view of a :term:`resource` is the view invoked when the
+ :term:`view name` is the empty string (``''``). This is the case when
+ :term:`traversal` exhausts the path elements in the PATH_INFO of a
+ request before it returns a :term:`context` resource.
+
+ Zope Component Architecture
+ The `Zope Component Architecture
+ <http://www.muthukadan.net/docs/zca.html>`_ (aka ZCA) is a system
+ which allows for application pluggability and complex dispatching
+ based on objects which implement an :term:`interface`.
+ Pyramid uses the ZCA "under the hood" to perform view
+ dispatching and other application configuration tasks.
+
+ Translation Directory
+ A translation directory is a :term:`gettext` translation
+ directory. It contains language folders, which themselves
+ contain ``LC_MESSAGES`` folders, which contain ``.mo`` files.
+ Each ``.mo`` file represents a set of translations for a language
+ in a :term:`translation domain`. The name of the ``.mo`` file
+ (minus the .mo extension) is the translation domain name.
+
+ Translation Domain
+ A string representing the "context" in which a translation was
+ made. For example the word "java" might be translated
+ differently if the translation domain is "programming-languages"
+ than would be if the translation domain was "coffee". A
+ translation domain is represnted by a collection of ``.mo`` files
+ within one or more :term:`translation directory` directories.
+
+ view mapper
+ A view mapper is a class which implements the
+ :class:`pyramid.interfaces.IViewMapperFactory` interface, which performs
+ view argument and return value mapping. This is a plug point for
+ extension builders, not normally used by "civilians".
+
+ authorization policy
+ An authorization policy in Pyramid 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` resource.
+
+ Locale Negotiator
+ An object supplying a policy determining which :term:`locale
+ name` best represents a given :term:`request`. It is used by the
+ :func:`pyramid.i18n.get_locale_name`, and
+ :func:`pyramid.i18n.negotiate_locale_name` functions, and
+ indirectly by :func:`pyramid.i18n.get_localizer`. The
+ :func:`pyramid.i18n.default_locale_negotiator` function
+ is an example of a locale negotiator.
+
+ Locale Name
+ A string like ``en``, ``en_US``, ``de``, or ``de_AT`` which
+ uniquely identifies a particular locale.
+
+ Default Locale Name
+ The :term:`locale name` used by an application when no explicit
+ locale name is set. See :ref:`localization_deployment_settings`.
+
+ Forbidden view
+ An :term:`exception view` invoked by Pyramid when the
+ developer explicitly raises a
+ ``pyramid.exceptions.Forbidden`` exception from within
+ :term:`view` code or :term:`root factory` code, or when the
+ :term:`view configuration` and :term:`authorization policy`
+ found for a request disallows a particular view invocation.
+ Pyramid provides a default implementation of a
+ forbidden view; it can be overridden. See
+ :ref:`changing_the_forbidden_view`.
+
+ Exception view
+ An exception view is a :term:`view callable` which may be
+ invoked by Pyramid when an exception is raised during
+ request processing. See :ref:`exception_views` for more
+ information.
+
+ Not Found view
+ An :term:`exception view` invoked by Pyramid when the
+ developer explicitly raises a ``pyramid.exceptions.NotFound``
+ exception from within :term:`view` code or :term:`root factory`
+ code, or when the current request doesn't match any :term:`view
+ configuration`. Pyramid provides a default
+ implementation of a not found view; it can be overridden. See
+ :ref:`changing_the_notfound_view`.
+
+ default permission
+ A :term:`permission` which is registered as the default for an
+ entire application. When a default permission is in effect,
+ every :term:`view configuration` registered with the system will
+ be effectively amended with a ``permission`` argument that will
+ require that the executing user possess the default permission in
+ order to successfully execute the associated :term:`view
+ callable` See also :ref:`setting_a_default_permission`.
View
65 docs/index.rst
@@ -0,0 +1,65 @@
+pyramid_zcml
+============
+
+Overview
+--------
+
+``pyramid_zcml`` is a package which provides ZCML directives for all built-in Pyramid configuration directives.
+
+Installation
+------------
+
+Install using setuptools, e.g. (within a virtualenv)::
+
+ $ easy_install pyramid_zcml
+
+Setup
+-----
+
+Once ``pyramid_zcml`` is installed, you must use the ``config.include``
+mechanism to include it into your Pyramid project's configuration. In your
+Pyramid project's ``__init__.py``:
+
+.. code-block:: python
+ :linenos:
+
+ import pyramid_zcml
+
+ config = Configurator(.....)
+ config.include(pyramid_zcml)
+
+At this point, it will be possible to use the
+:func:`pyramid_zcml.load_zcml` function as a method of the configurator,
+ala:
+
+.. code-block:: python
+ :linenos:
+
+ config.load_zcml(....)
+
+More Information
+----------------
+
+.. toctree::
+ :maxdepth: 1
+
+ api.rst
+ glossary.rst
+ zcml.rst
+
+
+Reporting Bugs / Development Versions
+-------------------------------------
+
+Visit http://github.com/Pylons/pyramid_zcml to download development or
+tagged versions.
+
+Visit http://github.com/Pylons/pyramid_zcml/issues to report bugs.
+
+Indices and tables
+------------------
+
+* :ref:`glossary`
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
View
32 docs/zcml.rst
@@ -0,0 +1,32 @@
+.. _zcml_directives:
+
+ZCML Directives
+===============
+
+Comprehensive reference material for every ZCML directive provided by Pyramid
+is available within this chapter. The ZCML directive documentation is
+organized alphabetically by directive name.
+
+.. toctree::
+ :maxdepth: 1
+
+ zcml/aclauthorizationpolicy
+ zcml/adapter
+ zcml/authtktauthenticationpolicy
+ zcml/asset
+ zcml/configure
+ zcml/default_permission
+ zcml/forbidden
+ zcml/include
+ zcml/localenegotiator
+ zcml/notfound
+ zcml/remoteuserauthenticationpolicy
+ zcml/renderer
+ zcml/repozewho1authenticationpolicy
+ zcml/route
+ zcml/scan
+ zcml/static
+ zcml/subscriber
+ zcml/translationdir
+ zcml/utility
+ zcml/view
View
35 docs/zcml/aclauthorizationpolicy.rst
@@ -0,0 +1,35 @@
+.. _aclauthorizationpolicy_directive:
+
+``aclauthorizationpolicy``
+--------------------------
+
+When this directive is used, authorization information is obtained
+from :term:`ACL` objects attached to :term:`resource` objects.
+
+Attributes
+~~~~~~~~~~
+
+None.
+
+Example
+~~~~~~~
+
+.. code-block:: xml
+ :linenos:
+
+ <aclauthorizationpolicy/>
+
+Alternatives
+~~~~~~~~~~~~
+
+You may create an instance of the
+:class:`pyramid.authorization.ACLAuthorizationPolicy` and pass it
+to the :class:`pyramid.config.Configurator` constructor as
+the ``authorization_policy`` argument during initial application
+configuration.
+
+See Also
+~~~~~~~~
+
+See also :ref:`authorization_policies_directives_section` and
+:ref:`security_chapter`.
View
47 docs/zcml/adapter.rst
@@ -0,0 +1,47 @@
+.. _adapter_directive:
+
+``adapter``
+-----------
+
+Register a :term:`Zope Component Architecture` "adapter".
+
+Attributes
+~~~~~~~~~~
+
+``factory``
+ The adapter factory (often a class).
+
+``provides``
+ The :term:`interface` that an adapter instance resulting from a
+ lookup will provide.
+
+``for``
+ Interfaces or classes to be adapted, separated by spaces,
+ e.g. ``interfaces.IFoo interfaces.IBar``.
+
+``name``
+ The adapter name.
+
+Example
+~~~~~~~
+
+.. code-block:: xml
+ :linenos:
+
+ <adapter
+ for=".foo.IFoo .bar.IBar"
+ provides=".interfaces.IMyAdapter"
+ factory=".adapters.MyAdapter"
+ />
+
+Alternatives
+~~~~~~~~~~~~
+
+Use the ``registerAdapter`` method of the ``registry`` attribute of a
+:term:`Configurator` instance during initial application setup.
+
+See Also
+~~~~~~~~
+
+None.
+
View
65 docs/zcml/asset.rst
@@ -0,0 +1,65 @@
+.. _asset_directive:
+
+``asset``
+---------
+
+The ``asset`` directive adds an asset override for a single
+static file/directory asset.
+
+Attributes
+~~~~~~~~~~
+
+``to_override``
+ A :term:`asset specification` specifying the asset to be
+ overridden.
+
+``override_with``
+ A :term:`asset specification` specifying the asset which
+ is used as the override.
+
+Examples
+~~~~~~~~
+
+.. topic:: Overriding a Single Asset File
+
+ .. code-block:: xml
+ :linenos:
+
+ <asset
+ to_override="some.package:templates/mytemplate.pt"
+ override_with="another.package:othertemplates/anothertemplate.pt"
+ />
+
+.. topic:: Overriding all Assets in a Package
+
+ .. code-block:: xml
+ :linenos:
+
+ <asset
+ to_override="some.package"
+ override_with="another.package"
+ />
+
+.. topic:: Overriding all Assets in a Subdirectory of a Package
+
+ .. code-block:: xml
+ :linenos:
+
+ <asset
+ to_override="some.package:templates/"
+ override_with="another.package:othertemplates/"
+ />
+
+Alternatives
+~~~~~~~~~~~~
+
+The :meth:`pyramid.config.Configurator.override_asset`
+method can be used instead of the ``resource`` ZCML directive.
+
+This directive can also be invoked as the ``resource`` ZCML directive for
+backwards compatibility purposes.
+
+See Also
+~~~~~~~~
+
+See also :ref:`asset_zcml_directive`.
View
102 docs/zcml/authtktauthenticationpolicy.rst
@@ -0,0 +1,102 @@
+.. _authtktauthenticationpolicy_directive:
+
+``authtktauthenticationpolicy``
+-------------------------------
+
+When this directive is used, authentication information is obtained
+from an :mod:`paste.auth.auth_tkt` cookie value, assumed to be set by
+a custom login form.
+
+Attributes
+~~~~~~~~~~
+
+``secret``
+ The ``secret`` is a string that will be used to sign the data
+ stored by the cookie. It is required and has no default.
+
+``callback``
+ The ``callback`` is a Python dotted name to a function passed the
+ string representing the userid stored in the cookie and the
+ request as positional arguments. The callback is expected to
+ return None if the user represented by the string doesn't exist or
+ a sequence of group identifiers (possibly empty) if the user does
+ exist. If ``callback`` is None, the userid will be assumed to
+ exist with no groups. It defaults to ``None``.
+
+``cookie_name``
+ The ``cookie_name`` is the name used for the cookie that contains
+ the user information. It defaults to ``auth_tkt``.
+
+``secure``
+ ``secure`` is a boolean value. If it's set to "true", the cookie
+ will only be sent back by the browser over a secure (HTTPS)
+ connection. It defaults to "false".
+
+``include_ip``
+ ``include_ip`` is a boolean value. If it's set to true, the
+ requesting IP address is made part of the authentication data in
+ the cookie; if the IP encoded in the cookie differs from the IP of
+ the requesting user agent, the cookie is considered invalid. It
+ defaults to "false".
+
+``timeout``
+ ``timeout`` is an integer value. It represents the maximum age in
+ seconds which the auth_tkt ticket will be considered valid. If
+ ``timeout`` is specified, and ``reissue_time`` is also specified,
+ ``reissue_time`` must be a smaller value than ``timeout``. It
+ defaults to ``None``, meaning that the ticket will be considered
+ valid forever.
+
+``reissue_time``
+ ``reissue_time`` is an integer value. If ``reissue_time`` is
+ specified, when we encounter a cookie that is older than the
+ reissue time (in seconds), but younger that the ``timeout``, a new
+ cookie will be issued. It defaults to ``None``, meaning that
+ authentication cookies are never reissued. A value of ``0`` means
+ reissue a cookie in the response to every request that requires
+ authentication.
+
+``max_age``
+ ``max_age`` is the maximum age of the auth_tkt *cookie*, in
+ seconds. This differs from ``timeout`` inasmuch as ``timeout``
+ represents the lifetime of the ticket contained in the cookie,
+ while this value represents the lifetime of the cookie itself.
+ When this value is set, the cookie's ``Max-Age`` and ``Expires``
+ settings will be set, allowing the auth_tkt cookie to last between
+ browser sessions. It is typically nonsensical to set this to a
+ value that is lower than ``timeout`` or ``reissue_time``, although
+ it is not explicitly prevented. It defaults to ``None``, meaning
+ (on all major browser platforms) that auth_tkt cookies will last
+ for the lifetime of the user's browser session.
+
+Example
+~~~~~~~
+
+.. code-block:: xml
+ :linenos:
+
+ <authtktauthenticationpolicy
+ secret="goshiamsosecret"
+ callback=".somemodule.somefunc"
+ cookie_name="mycookiename"
+ secure="false"
+ include_ip="false"
+ timeout="86400"
+ reissue_time="600"
+ max_age="31536000"
+ />
+
+Alternatives
+~~~~~~~~~~~~
+
+You may create an instance of the
+:class:`pyramid.authentication.AuthTktAuthenticationPolicy` and
+pass it to the :class:`pyramid.config.Configurator`
+constructor as the ``authentication_policy`` argument during initial
+application configuration.
+
+See Also
+~~~~~~~~
+
+See also :ref:`authentication_policies_directives_section` and
+:class:`pyramid.authentication.AuthTktAuthenticationPolicy`.
View
93 docs/zcml/configure.rst
@@ -0,0 +1,93 @@
+.. _configure_directive:
+
+``configure``
+-------------
+
+Because :term:`ZCML` is XML, and because XML requires a single root tag for
+each document, every ZCML file used by Pyramid must contain a ``configure``
+container directive, which acts as the root XML tag. It is a "container"
+directive because its only job is to contain other directives.
+
+Attributes
+~~~~~~~~~~
+
+``xmlns``
+ The default XML namespace used for subdirectives.
+
+Example
+~~~~~~~
+
+.. code-block:: xml
+ :linenos:
+
+ <configure xmlns="http://pylonshq.com/pyramid">
+
+ <!-- other directives -->
+
+ </configure>
+
+.. _word_on_xml_namespaces:
+
+A Word On XML Namespaces
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Usually, the start tag of the ``<configure>`` container tag has a
+default *XML namespace* associated with it. This is usually
+``http://pylonshq.com/pyramid``, named by the ``xmlns`` attribute of
+the ``configure`` start tag.
+
+Using the ``http://pylonshq.com/pyramid`` namespace as the default XML
+namespace isn't strictly necessary; you can use a different default namespace
+as the default. However, if you do, the declaration tags which are defined
+by Pyramid such as the ``view`` declaration tag will need to be defined in
+such a way that the XML parser that Pyramid uses knows which namespace the
+:mod:`pyramid` tags are associated with. For example, the following files
+are all completely equivalent:
+
+.. topic:: Use of A Non-Default XML Namespace
+
+ .. code-block:: xml
+ :linenos:
+
+ <configure xmlns="http://namespaces.zope.org/zope"
+ xmlns:pyramid="http://pylonshq.com/pyramid">
+
+ <include package="pyramid.includes" />
+
+ <pyramid:view
+ view="helloworld.hello_world"
+ />
+
+ </configure>
+
+.. topic:: Use of A Per-Tag XML Namespace Without A Default XML Namespace
+
+ .. code-block:: xml
+ :linenos:
+
+ <configure>
+
+ <include package="pyramid.includes" />
+
+ <view xmlns="http://pylonshq.com/pyramid"
+ view="helloworld.hello_world"
+ />
+
+ </configure>
+
+For more information about XML namespaces, see `this older, but simple
+XML.com article <http://www.xml.com/pub/a/1999/01/namespaces.html>`_.
+
+The conventions in this document assume that the default XML namespace
+is ``http://pylonshq.com/pyramid``.
+
+Alternatives
+~~~~~~~~~~~~
+
+None.
+
+See Also
+~~~~~~~~
+
+See also :ref:`helloworld_declarative`.
+
View
57 docs/zcml/default_permission.rst
@@ -0,0 +1,57 @@
+.. _default_permission_directive:
+
+``default_permission``
+-------------------------------
+
+Set the default permission to be used by all :term:`view
+configuration` registrations.
+
+This directive accepts a single attribute ,``name``, which should be
+used as the default permission string. An example of a permission
+string: ``view``. Adding a default permission makes it unnecessary to
+protect each view configuration with an explicit permission, unless
+your application policy requires some exception for a particular view.
+
+If a default permission is *not* set, views represented by view
+configuration registrations which do not explicitly declare a
+permission will be executable by entirely anonymous users (any
+authorization policy is ignored).
+
+There can be only one default permission active at a time within an
+application, thus the ``default_permission`` directive can only be
+used once in any particular set of ZCML.
+
+Attributes
+~~~~~~~~~~
+
+``name``
+ Must be a string representing a :term:`permission`,
+ e.g. ``view``.
+
+
+Example
+~~~~~~~
+
+.. code-block:: xml
+ :linenos:
+
+ <default_permission
+ name="view"
+ />
+
+Alternatives
+~~~~~~~~~~~~
+
+Using the ``default_permission`` argument to the
+:class:`pyramid.config.Configurator` constructor can be used
+to achieve the same purpose.
+
+Using the
+:meth:`pyramid.config.Configurator.set_default_permission`
+method can be used to achieve the same purpose when using imperative
+configuration.
+
+See Also
+~~~~~~~~
+
+See also :ref:`setting_a_default_permission`.
View
77 docs/zcml/forbidden.rst
@@ -0,0 +1,77 @@
+.. _forbidden_directive:
+
+``forbidden``
+-------------
+
+When Pyramid can't authorize execution of a view based on the
+:term:`authorization policy` in use, it invokes a :term:`forbidden view`.
+The default forbidden response has a 401 status code and is very plain, but
+it can be overridden as necessary using the ``forbidden`` ZCML directive.
+
+.. warning::
+
+ The ``forbidden`` ZCML directive is deprecated in Pyramid
+ version 1.3. Instead, you should use the :ref:`view_directive`
+ directive with a ``context`` that names the
+ :exc:`pyramid.exceptions.Forbidden` class. See
+ :ref:`changing_the_forbidden_view` form more information.
+
+Attributes
+~~~~~~~~~~
+
+``view``
+ The :term:`dotted Python name` to a :term:`view callable`. This
+ attribute is required unless a ``renderer`` attribute also exists.
+ If a ``renderer`` attribute exists on the directive, this attribute
+ defaults to a view that returns an empty dictionary (see
+ :ref:`views_which_use_a_renderer`).
+
+``attr``
+ The attribute of the view callable to use if ``__call__`` is not
+ correct (has the same meaning as in the context of
+ :ref:`view_directive`; see the description of ``attr``
+ there).
+
+``renderer``
+ This is either a single string term (e.g. ``json``) or a string
+ implying a path or :term:`asset specification`
+ (e.g. ``templates/views.pt``) used when the view returns a
+ non-:term:`response` object. This attribute has the same meaning as
+ it would in the context of :ref:`view_directive`; see the
+ description of ``renderer`` there).
+
+``wrapper``
+ The :term:`view name` (*not* an object dotted name) of another view
+ declared elsewhere in ZCML (or via the ``@view_config`` decorator)
+ which will receive the response body of this view as the
+ ``request.wrapped_body`` attribute of its own request, and the
+ response returned by this view as the ``request.wrapped_response``
+ attribute of its own request. This attribute has the same meaning
+ as it would in the context of :ref:`view_directive`; see the
+ description of ``wrapper`` there). Note that the wrapper view
+ *should not* be protected by any permission; behavior is undefined
+ if it does.
+
+Example
+~~~~~~~
+
+.. code-block:: xml
+ :linenos:
+
+ <forbidden
+ view="helloworld.views.forbidden_view"/>
+
+Alternatives
+~~~~~~~~~~~~
+
+Use the :ref:`view_directive` directive with a ``context`` that names
+the :exc:`pyramid.exceptions.Forbidden` class.
+
+Use the :meth:`pyramid.config.Configurator.add_view` method,
+passing it a ``context`` which is the
+:exc:`pyramid.exceptions.Forbidden` class.
+
+See Also
+~~~~~~~~
+
+See also :ref:`changing_the_forbidden_view`.
View
71 docs/zcml/include.rst
@@ -0,0 +1,71 @@
+.. _include_directive:
+
+``include``
+-----------
+
+The ``include`` directive includes configuration from an external ZCML
+file. Use of the ``include`` tag allows a user to split configuration
+across multiple ZCML files, and allows package distributors to provide
+default ZCML configuration for specific purposes which can be
+included by the integrator of the package as necessary.
+
+Attributes
+~~~~~~~~~~
+
+``package``
+ A :term:`dotted Python name` which references a Python :term:`package`.
+
+``file``
+ An absolute or relative filename which references a ZCML file.
+
+The ``package`` and ``file`` attributes can be used together or
+separately as necessary.
+
+Examples
+~~~~~~~~
+
+.. topic:: Loading the File Named ``configure.zcml`` from a Package Implicitly
+
+ .. code-block:: xml
+ :linenos:
+
+ <include package="some.package" />
+
+.. topic:: Loading the File Named ``other.zcml`` From the Current Package
+
+ .. code-block:: xml
+ :linenos:
+
+ <include file="other.zcml" />
+
+.. topic:: Loading a File From a Subdirectory of the Current Package
+
+ .. code-block:: xml
+ :linenos:
+
+ <include file="subdir/other.zcml" />
+
+.. topic:: Loading the File Named ``/absolute/path/other.zcml``
+
+ .. code-block:: xml
+ :linenos:
+
+ <include file="/absolute/path/other.zcml" />
+
+.. topic:: Loading the File Named ``other.zcml`` From a Package Explicitly
+
+ .. code-block:: xml
+ :linenos:
+
+ <include package="some.package" file="other.zcml" />
+
+Alternatives
+~~~~~~~~~~~~
+
+None.
+
+See Also
+~~~~~~~~
+
+See also :ref:`helloworld_declarative`.
+
View
39 docs/zcml/localenegotiator.rst
@@ -0,0 +1,39 @@
+.. _localenegotiator_directive:
+
+``localenegotiator``
+--------------------
+
+Set the :term:`locale negotiator` for the current configurator to
+support localization of text.
+
+Attributes
+~~~~~~~~~~
+
+``negotiator``
+
+ The :term:`dotted Python name` to a :term:`locale negotiator`
+ implementation. This attribute is required. If it begins with a
+ dot (``.``), the name will be considered relative to the directory
+ in which the ZCML file which contains this directive lives.
+
+Example
+~~~~~~~
+
+.. code-block:: xml
+ :linenos:
+
+ <localenegotiator
+ negotiator="some.package.module.my_locale_negotiator"
+ />
+
+Alternatives
+~~~~~~~~~~~~
+
+Use :meth:`pyramid.config.Configurator.set_locale_negotiator`
+method instance during initial application setup.
+
+See Also
+~~~~~~~~
+
+See also :ref:`activating_translation`.
+
View
77 docs/zcml/notfound.rst
@@ -0,0 +1,77 @@
+.. _notfound_directive:
+
+``notfound``
+------------
+
+.. warning::
+
+ The ``notfound`` ZCML directive is deprecated in Pyramid
+ version 1.0. Instead, you should use the :ref:`view_directive`
+ directive with a ``context`` that names the
+ :exc:`pyramid.exceptions.NotFound` class. See
+ :ref:`changing_the_notfound_view` form more information.
+
+When Pyramid can't map a URL to view code, it invokes a :term:`not found
+view`. The default not found view is very plain, but the view callable used
+can be configured via the ``notfound`` ZCML tag.
+
+Attributes
+~~~~~~~~~~
+
+``view``
+ The :term:`dotted Python name` to a :term:`view callable`. This
+ attribute is required unless a ``renderer`` attribute also exists.
+ If a ``renderer`` attribute exists on the directive, this attribute
+ defaults to a view that returns an empty dictionary (see
+ :ref:`views_which_use_a_renderer`).
+
+``attr``
+ The attribute of the view callable to use if ``__call__`` is not
+ correct (has the same meaning as in the context of
+ :ref:`view_directive`; see the description of ``attr``
+ there).
+
+``renderer``
+ This is either a single string term (e.g. ``json``) or a string
+ implying a path or :term:`asset specification`
+ (e.g. ``templates/views.pt``) used when the view returns a
+ non-:term:`response` object. This attribute has the same meaning as
+ it would in the context of :ref:`view_directive`; see the
+ description of ``renderer`` there).
+
+``wrapper``
+ The :term:`view name` (*not* an object dotted name) of another view
+ declared elsewhere in ZCML (or via the ``@view_config`` decorator)
+ which will receive the response body of this view as the
+ ``request.wrapped_body`` attribute of its own request, and the
+ response returned by this view as the ``request.wrapped_response``
+ attribute of its own request. This attribute has the same meaning
+ as it would in the context of :ref:`view_directive`; see
+ the description of ``wrapper`` there). Note that the wrapper view
+ *should not* be protected by any permission; behavior is undefined
+ if it does.
+
+Example
+~~~~~~~
+
+.. code-block:: xml
+ :linenos:
+
+ <notfound
+ view="helloworld.views.notfound_view"/>
+
+Alternatives
+~~~~~~~~~~~~
+
+Use the :ref:`view_directive` directive with a ``context`` that names
+the :exc:`pyramid.exceptions.NotFound` class.
+
+Use the :meth:`pyramid.config.Configurator.add_view` method,
+passing it a ``context`` which is the
+:exc:`pyramid.exceptions.NotFound` class.
+
+See Also
+~~~~~~~~
+
+See also :ref:`changing_the_notfound_view`.
+
View
51 docs/zcml/remoteuserauthenticationpolicy.rst
@@ -0,0 +1,51 @@
+.. _remoteuserauthenticationpolicy_directive:
+
+``remoteuserauthenticationpolicy``
+----------------------------------
+
+When this directive is used, authentication information is obtained
+from a ``REMOTE_USER`` key in the WSGI environment, assumed to
+be set by a WSGI server or an upstream middleware component.
+
+Attributes
+~~~~~~~~~~
+
+``environ_key``
+ The ``environ_key`` is the name that will be used to obtain the
+ remote user value from the WSGI environment. It defaults to
+ ``REMOTE_USER``.
+
+``callback``
+ The ``callback`` is a Python dotted name to a function passed the
+ string representing the remote user and the request as positional
+ arguments. The callback is expected to return None if the user
+ represented by the string doesn't exist or a sequence of group
+ identifiers (possibly empty) if the user does exist. If
+ ``callback`` is None, the userid will be assumed to exist with no
+ groups. It defaults to ``None``.
+
+Example
+~~~~~~~
+
+.. code-block:: xml
+ :linenos:
+
+ <remoteuserauthenticationpolicy
+ environ_key="REMOTE_USER"
+ callback=".somemodule.somefunc"
+ />
+
+Alternatives
+~~~~~~~~~~~~
+
+You may create an instance of the
+:class:`pyramid.authentication.RemoteUserAuthenticationPolicy` and
+pass it to the :class:`pyramid.config.Configurator`
+constructor as the ``authentication_policy`` argument during initial
+application configuration.
+
+See Also
+~~~~~~~~
+
+See also :ref:`authentication_policies_directives_section` and
+:class:`pyramid.authentication.RemoteUserAuthenticationPolicy`.
View
51 docs/zcml/renderer.rst
@@ -0,0 +1,51 @@
+.. _renderer_directive:
+
+``renderer``
+------------
+
+The ``renderer`` ZCML directive can be used to override an existing
+existing :term:`renderer` or to add a new renderer.
+
+Attributes
+~~~~~~~~~~
+
+``factory``
+ A :term:`dotted Python name` referencing a callable object that
+ accepts a renderer name and returns a :term:`renderer` object.
+
+``name``
+ The renderer name, which is a string.
+
+Examples
+~~~~~~~~
+
+.. topic:: Registering a Non-Template Renderer
+
+ .. code-block:: xml
+ :linenos:
+
+ <renderer
+ factory="some.renderer"
+ name="mynewrenderer"
+ />
+
+.. topic:: Registering a Template Renderer
+
+ .. code-block:: xml
+ :linenos:
+
+ <renderer
+ factory="some.jinja2.renderer"
+ name=".jinja2"
+ />
+
+Alternatives
+~~~~~~~~~~~~
+
+The :meth:`pyramid.config.Configurator.add_renderer` method
+is equivalent to the ``renderer`` ZCML directive.
+
+See Also
+~~~~~~~~
+
+See also :ref:`adding_and_overriding_renderers`.
View
53 docs/zcml/repozewho1authenticationpolicy.rst
@@ -0,0 +1,53 @@
+.. _repozewho1authenticationpolicy_directive:
+
+``repozewho1authenticationpolicy``
+----------------------------------
+
+When this directive is used, authentication information is obtained
+from a ``repoze.who.identity`` key in the WSGI environment, assumed to
+be set by :term:`repoze.who` middleware.
+
+Attributes
+~~~~~~~~~~
+
+``identifier_name``
+ The ``identifier_name`` controls the name used to look up the
+ :term:`repoze.who` "identifier" plugin within
+ ``request.environ['repoze.who.plugins']`` which is used by this
+ policy to "remember" and "forget" credentials. It defaults to
+ ``auth_tkt``.
+
+``callback``
+ The ``callback`` is a Python dotted name to a function passed the
+ repoze.who identity and the request as positional arguments. The
+ callback is expected to return None if the user represented by the
+ identity doesn't exist or a sequence of group identifiers
+ (possibly empty) if the user does exist. If ``callback`` is None,
+ the userid will be assumed to exist with no groups. It defaults
+ to ``None``.
+
+Example
+~~~~~~~
+
+.. code-block:: xml
+ :linenos:
+
+ <repozewho1authenticationpolicy
+ identifier_name="auth_tkt"
+ callback=".somemodule.somefunc"
+ />
+
+Alternatives
+~~~~~~~~~~~~
+
+You may create an instance of the
+:class:`pyramid.authentication.RepozeWho1AuthenticationPolicy` and
+pass it to the :class:`pyramid.config.Configurator`
+constructor as the ``authentication_policy`` argument during initial
+application configuration.
+
+See Also
+~~~~~~~~
+
+See also :ref:`authentication_policies_directives_section` and
+:class:`pyramid.authentication.RepozeWho1AuthenticationPolicy`.
View
223 docs/zcml/route.rst
@@ -0,0 +1,223 @@
+.. _route_directive:
+
+``route``
+---------
+
+The ``route`` directive adds a single :term:`route configuration` to
+the :term:`application registry`.
+
+Attributes
+~~~~~~~~~~
+
+``pattern``
+ The pattern of the route e.g. ``ideas/{idea}``. This attribute is
+ required. See :ref:`route_pattern_syntax` for information
+ about the syntax of route patterns.
+
+ .. note:: For backwards compatibility purposes, the ``path``
+ attribute can also be used instead of ``pattern``.
+
+``name``
+ The name of the route, e.g. ``myroute``. This attribute is
+ required. It must be unique among all defined routes in a given
+ configuration.
+
+``factory``
+ The :term:`dotted Python name` to a function that will generate a
+ Pyramid context object when this route matches.
+ e.g. ``mypackage.resources.MyResource``. If this argument is not
+ specified, a default root factory will be used.
+
+``view``
+ The :term:`dotted Python name` to a function that will be used as a
+ view callable when this route matches.
+ e.g. ``mypackage.views.my_view``.
+
+``xhr``
+ This value should be either ``True`` or ``False``. If this value is
+ specified and is ``True``, the :term:`request` must possess an
+ ``HTTP_X_REQUESTED_WITH`` (aka ``X-Requested-With``) header for this
+ route to match. This is useful for detecting AJAX requests issued
+ from jQuery, Prototype and other Javascript libraries. If this
+ predicate returns false, route matching continues.
+
+``traverse``
+ If you would like to cause the :term:`context` to be something other
+ than the :term:`root` object when this route matches, you can spell
+ a traversal pattern as the ``traverse`` argument. This traversal
+ pattern will be used as the traversal path: traversal will begin at
+ the root object implied by this route (either the global root, or
+ the object returned by the ``factory`` associated with this route).
+
+ The syntax of the ``traverse`` argument is the same as it is for
+ ``pattern``. For example, if the ``pattern`` provided to the
+ ``route`` directive is ``articles/{article}/edit``, and the
+ ``traverse`` argument provided to the ``route`` directive is
+ ``/{article}``, when a request comes in that causes the route to
+ match in such a way that the ``article`` match value is '1' (when
+ the request URI is ``/articles/1/edit``), the traversal path will be
+ generated as ``/1``. This means that the root object's
+ ``__getitem__`` will be called with the name ``1`` during the
+ traversal phase. If the ``1`` object exists, it will become the
+ :term:`context` of the request. :ref:`traversal_chapter` has more
+ information about traversal.
+
+ If the traversal path contains segment marker names which are not
+ present in the ``pattern`` argument, a runtime error will occur.
+ The ``traverse`` pattern should not contain segment markers that do
+ not exist in the ``pattern``.
+
+ A similar combining of routing and traversal is available when a
+ route is matched which contains a ``*traverse`` remainder marker in
+ its ``pattern`` (see :ref:`using_traverse_in_a_route_pattern`). The
+ ``traverse`` argument to the ``route`` directive allows you to
+ associate route patterns with an arbitrary traversal path without
+ using a a ``*traverse`` remainder marker; instead you can use other
+ match information.
+
+ Note that the ``traverse`` argument to the ``route`` directive is
+ ignored when attached to a route that has a ``*traverse`` remainder
+ marker in its pattern.
+
+``request_method``
+ A string representing an HTTP method name, e.g. ``GET``, ``POST``,
+ ``HEAD``, ``DELETE``, ``PUT``. If this argument is not specified,
+ this route will match if the request has *any* request method. If
+ this predicate returns false, route matching continues.
+
+``path_info``
+ The value of this attribute represents a regular expression pattern
+ that will be tested against the ``PATH_INFO`` WSGI environment
+ variable. If the regex matches, this predicate will be true. If
+ this predicate returns false, route matching continues.
+
+``request_param``
+ This value can be any string. A view declaration with this
+ attribute ensures that the associated route will only match when the
+ request has a key in the ``request.params`` dictionary (an HTTP
+ ``GET`` or ``POST`` variable) that has a name which matches the
+ supplied value. If the value supplied to the attribute has a ``=``
+ sign in it, e.g. ``request_params="foo=123"``, then the key
+ (``foo``) must both exist in the ``request.params`` dictionary, and
+ the value must match the right hand side of the expression (``123``)
+ for the route to "match" the current request. If this predicate
+ returns false, route matching continues.
+
+``header``
+ The value of this attribute represents an HTTP header name or a
+ header name/value pair. If the value contains a ``:`` (colon), it
+ will be considered a name/value pair (e.g. ``User-Agent:Mozilla/.*``
+ or ``Host:localhost``). The *value* of an attribute that represent
+ a name/value pair should be a regular expression. If the value does
+ not contain a colon, the entire value will be considered to be the
+ header name (e.g. ``If-Modified-Since``). If the value evaluates to
+ a header name only without a value, the header specified by the name
+ must be present in the request for this predicate to be true. If
+ the value evaluates to a header name/value pair, the header
+ specified by the name must be present in the request *and* the
+ regular expression specified as the value must match the header
+ value. Whether or not the value represents a header name or a
+ header name/value pair, the case of the header name is not
+ significant. If this predicate returns false, route matching
+ continues.
+
+``accept``
+ The value of this attribute represents a match query for one or more
+ mimetypes in the ``Accept`` HTTP request header. If this value is
+ specified, it must be in one of the following forms: a mimetype
+ match token in the form ``text/plain``, a wildcard mimetype match
+ token in the form ``text/*`` or a match-all wildcard mimetype match
+ token in the form ``*/*``. If any of the forms matches the
+ ``Accept`` header of the request, this predicate will be true. If
+ this predicate returns false, route matching continues.
+
+``custom_predicates``
+
+ This value should be a sequence of references to custom predicate
+ callables. Use custom predicates when no set of predefined
+ predicates does what you need. Custom predicates can be combined
+ with predefined predicates as necessary. Each custom predicate
+ callable should accept two arguments: ``info`` and ``request``
+ and should return either ``True`` or ``False`` after doing arbitrary
+ evaluation of the info and/or the request. If all custom and
+ non-custom predicate callables return ``True`` the associated route
+ will be considered viable for a given request. If any predicate
+ callable returns ``False``, route matching continues. Note that the
+ value ``info`` passed to a custom route predicate is a dictionary
+ containing matching information; see :ref:`custom_route_predicates`
+ for more information about ``info``.
+
+``view_context``
+ The :term:`dotted Python name` to a class or an interface that the
+ :term:`context` of the view should match for the view named by the
+ route to be used. This attribute is only useful if the ``view``
+ attribute is used. If this attribute is not specified, the default
+ (``None``) will be used.
+
+ If the ``view`` attribute is not provided, this attribute has no
+ effect.
+
+ This attribute can also be spelled as ``view_for`` or ``for_``;
+ these are valid older spellings.
+
+``view_permission``
+ The permission name required to invoke the view associated with this
+ route. e.g. ``edit``. (see :ref:`using_security_with_urldispatch`
+ for more information about permissions).
+
+ If the ``view`` attribute is not provided, this attribute has no
+ effect.
+
+ This attribute can also be spelled as ``permission``.
+
+``view_renderer``
+ This is either a single string term (e.g. ``json``) or a string
+ implying a path or :term:`asset specification`
+ (e.g. ``templates/views.pt``). If the renderer value is a single
+ term (does not contain a dot ``.``), the specified term will be used
+ to look up a renderer implementation, and that renderer
+ implementation will be used to construct a response from the view
+ return value. If the renderer term contains a dot (``.``), the
+ specified term will be treated as a path, and the filename extension
+ of the last element in the path will be used to look up the renderer
+ implementation, which will be passed the full path. The renderer
+ implementation will be used to construct a response from the view
+ return value. See :ref:`views_which_use_a_renderer` for more
+ information.
+
+ If the ``view`` attribute is not provided, this attribute has no
+ effect.
+
+ This attribute can also be spelled as ``renderer``.
+
+``view_attr``
+ The view machinery defaults to using the ``__call__`` method of the
+ view callable (or the function itself, if the view callable is a
+ function) to obtain a response dictionary. The ``attr`` value allows
+ you to vary the method attribute used to obtain the response. For
+ example, if your view was a class, and the class has a method named
+ ``index`` and you wanted to use this method instead of the class'
+ ``__call__`` method to return the response, you'd say
+ ``attr="index"`` in the view configuration for the view. This is
+ most useful when the view definition is a class.
+
+ If the ``view`` attribute is not provided, this attribute has no
+ effect.
+
+``use_global_views``
+ When a request matches this route, and view lookup cannot find a view
+ which has a 'route_name' predicate argument that matches the route,
+ try to fall back to using a view that otherwise matches the context,
+ request, and view name (but does not match the route name predicate).
+
+Alternatives
+~~~~~~~~~~~~
+
+You can also add a :term:`route configuration` via:
+
+- Using the :meth:`pyramid.config.Configurator.add_route` method.
+
+See Also
+~~~~~~~~
+
+See also :ref:`urldispatch_chapter`.
View
34 docs/zcml/scan.rst
@@ -0,0 +1,34 @@
+.. _scan_directive:
+
+``scan``
+--------
+
+To make use of :term:`configuration decoration` decorators, you must
+perform a :term:`scan`. A scan finds these decorators in code. The
+``scan`` ZCML directive tells Pyramid to begin such a scan.
+
+Attributes
+~~~~~~~~~~
+
+``package``
+ The package to scan or the single dot (``.``), meaning the
+ "current" package (the package in which the ZCML file lives).
+
+Example
+~~~~~~~
+
+.. code-block:: xml
+ :linenos:
+
+ <scan package="."/>
+
+Alternatives
+~~~~~~~~~~~~
+
+The :meth:`pyramid.config.Configurator.scan` method performs
+the same job as the ``scan`` ZCML directive.
+
+See Also
+~~~~~~~~
+
+See also :ref:`mapping_views_using_a_decorator_section`.
View
89 docs/zcml/static.rst
@@ -0,0 +1,89 @@
+.. _static_directive:
+
+``static``
+----------
+
+Use of the ``static`` ZCML directive or allows you to serve static
+resources (such as JavaScript and CSS files) within a
+Pyramid application. This mechanism makes static files
+available at a name relative to the application root URL.
+
+Attributes
+~~~~~~~~~~
+
+``name``
+ The (application-root-relative) URL prefix of the static directory.
+ For example, to serve static files from ``/static`` in most
+ applications, you would provide a ``name`` of ``static``.
+
+``path``
+ A path to a directory on disk where the static files live. This
+ path may either be 1) absolute (e.g. ``/foo/bar/baz``) 2)
+ Python-package-relative (e.g. (``packagename:foo/bar/baz``) or 3)
+ relative to the package directory in which the ZCML file which
+ contains the directive (e.g. ``foo/bar/baz``).
+
+``cache_max_age``
+ The number of seconds that the static resource can be cached, as
+ represented in the returned response's ``Expires`` and/or
+ ``Cache-Control`` headers, when any static file is served from this
+ directive. This defaults to 3600 (5 minutes). Optional.
+
+``permission``
+ Used to specify the :term:`permission` required by a user to execute
+ this static view. This value defaults to the string
+ ``__no_permission_required__``. The ``__no_permission_required__``
+ string is a special sentinel which indicates that, even if a
+ :term:`default permission` exists for the current application, the
+ static view should be renderered to completely anonymous users.
+ This default value is permissive because, in most web apps, static
+ resources seldom need protection from viewing. You should use this
+ option only if you register a static view which points at a
+ directory that contains resources which should be shown only if the
+ calling user has (according to the :term:`authorization policy`) a
+ particular permission.
+
+Examples
+~~~~~~~~
+
+.. topic:: Serving Static Files from an Absolute Path
+
+ .. code-block:: xml
+ :linenos:
+
+ <static
+ name="static"
+ path="/var/www/static"
+ />
+
+.. topic:: Serving Static Files from a Package-Relative Path
+
+ .. code-block:: xml
+ :linenos:
+
+ <static
+ name="static"
+ path="some_package:a/b/c/static"
+ />
+
+.. topic:: Serving Static Files from a Current-Package-Relative Path
+
+ .. code-block:: xml
+ :linenos:
+
+ <static
+ name="static"
+ path="static_files"
+ />
+
+Alternatives
+~~~~~~~~~~~~
+
+:meth:`pyramid.config.Configurator.add_static_view` can also
+be used to add a static view.
+
+See Also
+~~~~~~~~
+
+See also :ref:`static_assets_section` and
+:ref:`generating_static_asset_urls`.
View
45 docs/zcml/subscriber.rst
@@ -0,0 +1,45 @@
+.. _subscriber_directive:
+
+``subscriber``
+--------------
+
+The ``subscriber`` ZCML directive configures an :term:`subscriber`
+callable to listen for events broadcast by the Pyramid web
+framework.
+
+Attributes
+~~~~~~~~~~
+
+``for``
+ The class or :term:`interface` that you are subscribing the listener for,
+ e.g. :class:`pyramid.events.NewRequest`. Registering a subscriber for a
+ specific class or interface limits the event types that the subscriber
+ will receive to those specified by the interface or class. Default:
+ ``zope.interface.Interface`` (implying *any* event type).
+
+``handler``
+ A :term:`dotted Python name` which references an event handler
+ callable. The callable should accept a single argument: ``event``.
+ The return value of the callable is ignored.
+
+Examples
+~~~~~~~~
+
+.. code-block:: xml
+ :linenos:
+
+ <subscriber
+ for="pyramid.events.NewRequest"
+ handler=".subscribers.handle_new_request"
+ />
+
+Alternatives
+~~~~~~~~~~~~
+
+You can also register an event listener by using the
+:meth:`pyramid.config.Configurator.add_subscriber` method.
+
+See Also
+~~~~~~~~
+
+See also :ref:`events_chapter`.
View
64 docs/zcml/translationdir.rst
@@ -0,0 +1,64 @@
+.. _translationdir_directive:
+
+``translationdir``
+------------------
+
+Add a :term:`gettext` :term:`translation directory` to the current
+configuration for use in localization of text.
+
+Attributes
+~~~~~~~~~~
+
+``dir``
+ The path to the translation directory. This path may either be 1)
+ absolute (e.g. ``/foo/bar/baz``) 2) Python-package-relative
+ (e.g. ``packagename:foo/bar/baz``) or 3) relative to the package
+ directory in which the ZCML file which contains the directive
+ (e.g. ``foo/bar/baz``).
+
+Example 1
+~~~~~~~~~
+
+.. code-block:: xml
+ :linenos:
+
+ <!-- relative to configure.zcml file -->
+
+ <translationdir
+ dir="locale"
+ />
+
+Example 2
+~~~~~~~~~
+
+.. code-block:: xml
+ :linenos:
+
+ <!-- relative to another package -->
+
+ <translationdir
+ dir="another.package:locale"
+ />
+
+Example 3
+~~~~~~~~~
+
+.. code-block:: xml
+ :linenos:
+
+ <!-- an absolute directory name -->
+
+ <translationdir
+ dir="/usr/share/locale"
+ />
+
+Alternatives
+~~~~~~~~~~~~
+
+Use :meth:`pyramid.config.Configurator.add_translation_dirs`
+method instance during initial application setup.
+
+See Also
+~~~~~~~~
+
+See also :ref:`activating_translation`.
View
46 docs/zcml/utility.rst
@@ -0,0 +1,46 @@
+.. _utility_directive:
+
+``utility``
+-----------
+
+Register a :term:`Zope Component Architecture` "utility".
+
+Attributes
+~~~~~~~~~~
+
+``component``
+ The utility component (cannot be specified if ``factory`` is
+ specified).
+
+``factory``
+ A factory that creates a component (cannot be specified if
+ ``component`` is specified).
+
+``provides``
+ The :term:`interface` that an utility instance resulting from a
+ lookup will provide.
+
+``name``
+ The utility name.
+
+Example
+~~~~~~~
+
+.. code-block:: xml
+ :linenos:
+
+ <utility
+ provides=".interfaces.IMyUtility"
+ component=".utilities.MyUtility"
+ />
+
+Alternatives
+~~~~~~~~~~~~
+
+Use the ``registerUtility`` method of the ``registry`` attribute of a
+:term:`Configurator` instance during initial application setup.
+
+See Also
+~~~~~~~~
+
+None.
View
266 docs/zcml/view.rst
@@ -0,0 +1,266 @@
+.. _view_directive:
+
+``view``
+--------
+
+A ``view`` declaration directs Pyramid to create a single
+:term:`view configuration` registration in the current
+:term:`application registry`.
+
+The ``view`` ZCML directive has many possible attributes. Some of the
+attributes are descriptive or influence rendering. Other attributes
+are :term:`predicate` attributes, meaning that they imply an
+evaluation to true or false when view lookup is performed.
+
+*All* predicates named in a view configuration must evaluate to true
+in order for the view callable it names to be considered "invokable"
+for a given request. See :ref:`view_lookup` for a description of how
+a view configuration matches (or doesn't match) during a request.
+
+The possible attributes of the ``view`` ZCML directive are described
+below. They are divided into predicate and non-predicate categories.
+
+Attributes
+~~~~~~~~~~
+
+Non-Predicate Attributes
+########################
+
+``view``
+ The :term:`dotted Python name` to a :term:`view callable`. This
+ attribute is required unless a ``renderer`` attribute also exists.
+ If a ``renderer`` attribute exists on the directive, this attribute
+ defaults to a view that returns an empty dictionary (see
+ :ref:`views_which_use_a_renderer`).
+
+``permission``
+ The name of a *permission* that the user must possess in order to
+ call the view. See :ref:`view_security_section` for more
+ information about view security and permissions.
+
+``attr``
+ The view machinery defaults to using the ``__call__`` method of the
+ view callable (or the function itself, if the view callable is a
+ function) to obtain a response dictionary. The ``attr`` value
+ allows you to vary the method attribute used to obtain the response.
+ For example, if your view was a class, and the class has a method
+ named ``index`` and you wanted to use this method instead of the
+ class' ``__call__`` method to return the response, you'd say
+ ``attr="index"`` in the view configuration for the view. This is
+ most useful when the view definition is a class.
+
+``renderer``
+ This is either a single string term (e.g. ``json``) or a string
+ implying a path or :term:`asset specification`
+ (e.g. ``templates/views.pt``). If the renderer value is a single
+ term (does not contain a dot ``.``), the specified term will be used
+ to look up a renderer implementation, and that renderer
+ implementation will be used to construct a response from the view
+ return value. If the renderer term contains a dot (``.``), the
+ specified term will be treated as a path, and the filename extension
+ of the last element in the path will be used to look up the renderer
+ implementation, which will be passed the full path. The renderer
+ implementation will be used to construct a response from the view
+ return value.
+
+ Note that if the view itself returns a response (see
+ :ref:`the_response`), the specified renderer implementation is never
+ called.
+
+ When the renderer is a path, although a path is usually just a
+ simple relative pathname (e.g. ``templates/foo.pt``, implying that a
+ template named "foo.pt" is in the "templates" directory relative to
+ the directory in which the ZCML file is defined), a path can be
+ absolute, starting with a slash on UNIX or a drive letter prefix on
+ Windows. The path can alternately be a :term:`asset
+ specification` in the form
+ ``some.dotted.package_name:relative/path``, making it possible to
+ address template assets which live in a separate package.
+
+ The ``renderer`` attribute is optional. If it is not defined, the
+ "null" renderer is assumed (no rendering is performed and the value
+ is passed back to the upstream BFG machinery unmolested).
+
+``wrapper``
+ The :term:`view name` (*not* an object dotted name) of another view
+ declared elsewhere in ZCML (or via the ``@view_config`` decorator)
+ which will receive the response body of this view as the
+ ``request.wrapped_body`` attribute of its own request, and the
+ response returned by this view as the ``request.wrapped_response``
+ attribute of its own request. Using a wrapper makes it possible to
+ "chain" views together to form a composite response. The response
+ of the outermost wrapper view will be returned to the user. The
+ wrapper view will be found as any view is found: see
+ :ref:`view_lookup`. The "best" wrapper view will be found based on
+ the lookup ordering: "under the hood" this wrapper view is looked up
+ via ``pyramid.view.render_view_to_response(context, request,
+ 'wrapper_viewname')``. The context and request of a wrapper view is
+ the same context and request of the inner view. If this attribute
+ is unspecified, no view wrapping is done.
+
+Predicate Attributes
+####################
+
+``name``
+ The *view name*. Read the :ref:`traversal_chapter` to understand
+ the concept of a view name.
+
+``context``
+ A :term:`dotted Python name` representing the Python class that the
+ :term:`context` must be an instance of, *or* the :term:`interface`
+ that the :term:`context` must provide in order for this view to be
+ found and called. This predicate is true when the :term:`context`
+ is an instance of the represented class or if the :term:`context`
+ provides the represented interface; it is otherwise false. An
+ alternate name for this attribute is ``for`` (this is an older
+ spelling).
+
+``route_name``
+ *This attribute services an advanced feature that isn't often used
+ unless you want to perform traversal after a route has matched.*
+ This value must match the ``name`` of a ``<route>`` declaration (see
+ :ref:`urldispatch_chapter`) that must match before this view will be
+ called. Note that the ``route`` configuration referred to by
+ ``route_name`` usually has a ``*traverse`` token in the value of its
+ ``path``, representing a part of the path that will be used by
+ traversal against the result of the route's :term:`root factory`.
+ See :ref:`hybrid_chapter` for more information on using this
+ advanced feature.
+
+``request_type``
+ This value should be a :term:`dotted Python name` string
+ representing the :term:`interface` that the :term:`request` must
+ have in order for this view to be found and called. The presence of
+ this attribute is largely for backwards compatibility with
+ older iterations of this framework.
+
+``request_method``
+ This value can either be one of the strings 'GET', 'POST', 'PUT',
+ 'DELETE', or 'HEAD' representing an HTTP ``REQUEST_METHOD``. A view
+ declaration with this attribute ensures that the view will only be
+ called when the request's ``method`` (aka ``REQUEST_METHOD``) string
+ matches the supplied value.
+
+``request_param``
+ This value can be any string. A view declaration with this
+ attribute ensures that the view will only be called when the request
+ has a key in the ``request.params`` dictionary (an HTTP ``GET`` or
+ ``POST`` variable) that has a name which matches the supplied value.
+ If the value supplied to the attribute has a ``=`` sign in it,
+ e.g. ``request_params="foo=123"``, then the key (``foo``) must both
+ exist in the ``request.params`` dictionary, and the value must match
+ the right hand side of the expression (``123``) for the view to
+ "match" the current request.
+
+``containment``
+ This value should be a :term:`dotted Python name` string
+ representing the class that a graph traversal parent object of the
+ :term:`context` must be an instance of (or :term:`interface` that a
+ parent object must provide) in order for this view to be found and
+ called. Your resources must be "location-aware" to use this feature.
+ See :ref:`location_aware` for more information about
+ location-awareness.
+
+``xhr``
+ This value should be either ``True`` or ``False``. If this value is
+ specified and is ``True``, the :term:`request` must possess an
+ ``HTTP_X_REQUESTED_WITH`` (aka ``X-Requested-With``) header that has
+ the value ``XMLHttpRequest`` for this view to be found and called.
+ This is useful for detecting AJAX requests issued from jQuery,
+ Prototype and other Javascript libraries.
+
+``accept``
+ The value of this attribute represents a match query for one or more
+ mimetypes in the ``Accept`` HTTP request header. If this value is
+ specified, it must be in one of the following forms: a mimetype
+ match token in the form ``text/plain``, a wildcard mimetype match
+ token in the form ``text/*`` or a match-all wildcard mimetype match
+ token in the form ``*/*``. If any of the forms matches the
+ ``Accept`` header of the request, this predicate will be true.
+
+``header``
+ The value of this attribute represents an HTTP header name or a
+ header name/value pair. If the value contains a ``:`` (colon), it
+ will be considered a name/value pair (e.g. ``User-Agent:Mozilla/.*``
+ or ``Host:localhost``). The *value* of an attribute that represent
+ a name/value pair should be a regular expression. If the value does
+ not contain a colon, the entire value will be considered to be the
+ header name (e.g. ``If-Modified-Since``). If the value evaluates to
+ a header name only without a value, the header specified by the name
+ must be present in the request for this predicate to be true. If
+ the value evaluates to a header name/value pair, the header
+ specified by the name must be present in the request *and* the
+ regular expression specified as the value must match the header
+ value. Whether or not the value represents a header name or a
+ header name/value pair, the case of the header name is not
+ significant.
+
+``path_info``
+ The value of this attribute represents a regular expression pattern
+ that will be tested against the ``PATH_INFO`` WSGI environment
+ variable. If the regex matches, this predicate will be true.
+
+``custom_predicates``
+ This value should be a sequence of references to custom predicate
+ callables (e.g. ``dotted.name.one dotted.name.two``, if used in
+ ZCML; a :term:`dotted Python name` to each callable separated by a
+ space). Use custom predicates when no set of predefined predicates
+ do what you need. Custom predicates can be combined with predefined
+ predicates as necessary. Each custom predicate callable should
+ accept two arguments: ``context`` and ``request`` and should return
+ either ``True`` or ``False`` after doing arbitrary evaluation of the
+ context and/or the request. If all callables return ``True``, the
+ associated view callable will be considered viable for a given
+ request.
+
+``decorator``
+ A :term:`dotted Python name` to a function that will be used to decorate
+ the registered :term:`view callable`. The decorator function will be
+ called with the view callable as a single argument. The view callable it
+ is passed will accept ``(context, request)``. The decorator must return a
+ replacement view callable which also accepts ``(context, request)``.
+
+``mapper``
+ A :term:`dotted Python name` which refers to a :term:`view mapper`, or
+ ``None``. By default it is ``None``, which indicates that the view should
+ use the default view mapper. This plug-point is useful for Pyramid
+ extension developers, but it's not very useful for 'civilians' who are just
+ developing stock Pyramid applications.
+
+Examples
+~~~~~~~~
+
+.. topic:: Registering A Default View for a Class
+
+ .. code-block:: xml
+ :linenos:
+