Permalink
Browse files

- Most references to ZCML in narrative chapters have been removed or

  redirected to ``pyramid_zcml`` locations.
  • Loading branch information...
1 parent 47af907 commit c9c3c487bcaedeca97bb6463a00188b0dc01203a @mcdonc mcdonc committed Jan 18, 2011
View
@@ -26,8 +26,8 @@ Backwards Incompatibilities
- The ``pyramid.includes`` subpackage has been removed. ZCML files which use
include the package ``pyramid.includes`` (e.g. ``<include
- package="pyramid.includes">``) now must include the ``pyramid_zcml``
- package instead (e.g. ``<include package="pyramid_zcml"/>).
+ package="pyramid.includes"/>``) now must include the ``pyramid_zcml``
+ package instead (e.g. ``<include package="pyramid_zcml"/>``).
- The ``pyramid.view.action`` decorator has been removed from the Pyramid
core. Handlers are now a feature of the ``pyramid_handlers`` package. It
@@ -101,7 +101,10 @@ Documentation
"Renderers" chapter in a section named "Overriding A Renderer at Runtime".
- The "Declarative Configuration" narrative chapter has been removed (it was
- moved to the ``pyramid_zcml`` pakcage).
+ moved to the ``pyramid_zcml`` package).
+
+- Most references to ZCML in narrative chapters have been removed or
+ redirected to ``pyramid_zcml`` locations.
Deprecations
------------
@@ -79,12 +79,6 @@ This book is divided into four major parts:
:app:`Pyramid`. The API documentation is organized
alphabetically by module name.
-:ref:`zcml_reference`
-
- Comprehensive reference material for every :term:`ZCML directive`
- provided by :app:`Pyramid`. The ZCML directive documentation is
- organized alphabetically by directive name.
-
.. index::
single: repoze.zope2
single: Zope 3
@@ -453,34 +453,11 @@ Pyramid "Encourages Use of ZCML"
:term:`Zope Component Architecture` registry that :app:`Pyramid` uses for
application configuration. Often people claim that Pyramid "needs ZCML".
-Quick answer: it doesn't. At least not anymore. In :mod:`repoze.bfg` (the
-predecessor to Pyramid) versions 1.0 and and 1.1, an application needed to
-possess a ZCML file for it to begin executing successfully. However,
-:mod:`repoze.bfg` 1.2 and greater (including :app:`Pyramid` 1.0) includes a
-completely imperative mode for all configuration. You will be able to make
-"single file" apps in this mode, which should help people who need to see
-everything done completely imperatively. For example, the very most basic
-:app:`Pyramid` "helloworld" program has become something like:
-
-.. code-block:: python
- :linenos:
-
- from webob import Response
- from paste.httpserver import serve
- from pyramid.config import Configurator
-
- def hello_world(request):
- return Response('Hello world!')
-
- if __name__ == '__main__':
- config = Configurator()
- config.add_view(hello_world)
- app = config.make_wsgi_app()
- serve(app)
-
-In this mode, no ZCML is required at all, nor any other sort of frameworky
-frontend to application configuration. Hopefully this mode will allow people
-who are used to doing everything imperatively feel more comfortable.
+It doesn't. In :app:`Pyramid` 1.0, ZCML doesn't ship as part of the core;
+instead it ships in the :term:`pyramid_zcml` add-on package, which is
+completely optional. No ZCML is required at all to use :app:`Pyramid`, nor
+any other sort of frameworky declarative frontend to application
+configuration.
Pyramid Uses ZCML; ZCML is XML and I Don't Like XML
---------------------------------------------------
View
@@ -89,9 +89,9 @@ Glossary
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
+ setuptools configurations. A variant is used in dotted names within
+ configurator method arguments that name objects (such as the "add_view"
+ method's "view" and "context" attributes): the colon (``:``) is not
used; in its place is a dot.
view
@@ -116,8 +116,8 @@ Glossary
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. :app:`Pyramid` views can be
- configured via :term:`imperative configuration`, :term:`ZCML` or by a
- special ``@view_config`` decorator coupled with a :term:`scan`. See
+ configured via :term:`imperative configuration`, or by a special
+ ``@view_config`` decorator coupled with a :term:`scan`. See
:ref:`view_config_chapter` for more information about view
configuration.
@@ -377,29 +377,10 @@ Glossary
ultimately a :term:`view`). See also :term:`url dispatch`.
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.
-
- ZCML
- `Zope Configuration Markup Language
- <http://www.muthukadan.net/docs/zca.html#zcml>`_, an XML dialect
- used by Zope and :app:`Pyramid` for configuration tasks. ZCML
- is capable of performing different types of :term:`configuration
- declaration`, but its primary purpose in :app:`Pyramid` is to
- perform :term:`view configuration` and :term:`route configuration`
- within the ``configure.zcml`` file in a :app:`Pyramid`
- application. You can use ZCML as an alternative to
- :term:`imperative configuration`.
-
- ZCML directive
- A ZCML "tag" such as ``<view>`` or ``<route>``.
-
- ZCML declaration
- The concrete use of a :term:`ZCML directive` within a ZCML file.
+ Route configuration is the act of associating 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.
Zope Component Architecture
The `Zope Component Architecture
@@ -457,9 +438,9 @@ Glossary
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.
+ subscriber via :term:`imperative configuration` or via
+ :term:`configuration decoration`. See :ref:`events_chapter` for more
+ information.
request type
An attribute of a :term:`request` that allows for specialization
@@ -577,15 +558,13 @@ Glossary
also `PEP 318 <http://www.python.org/dev/peps/pep-0318/>`_.
configuration declaration
- An individual method call made to an instance of a
- :app:`Pyramid` :term:`Configurator` object which performs an
- arbitrary action, such as registering a :term:`view configuration`
- (via the ``view`` method of the configurator) or :term:`route
- configuration` (via the ``route`` method of the configurator). A
- set of configuration declarations is also usually implied via the
- use of a :term:`ZCML declaration` within an application, or a set
- of configuration declarations might be performed by a :term:`scan`
- of code in a package.
+ An individual method call made to an instance of a :app:`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). A set of configuration declarations is
+ also implied by the :term:`configuration decoration` detected by a
+ :term:`scan` of code in a package.
configuration decoration
Metadata implying one or more :term:`configuration declaration`
@@ -609,8 +588,8 @@ Glossary
declaration` required by your application.
declarative configuration
- The configuration mode in which you use :term:`ZCML` to make
- a set of :term:`configuration declaration` statements.
+ The configuration mode in which you use :term:`ZCML` to make a set of
+ :term:`configuration declaration` statements. See :term:`pyramid_zcml`.
Not Found view
An :term:`exception view` invoked by :app:`Pyramid` when the
@@ -862,3 +841,21 @@ Glossary
``request.matchdict`` when a :term:`URL dispatch` route has been matched.
Its keys are names as identified within the route pattern; its values are
the values matched by each pattern name.
+
+ pyramid_zcml
+ An add-on package to :app:`Pyramid` which allows applications to be
+ configured via ZCML. It is available on :term:`PyPI`. If you use
+ ``pyramid_zcml``, you can use ZCML as an alternative to
+ :term:`imperative configuration`.
+
+ ZCML
+ `Zope Configuration Markup Language
+ <http://www.muthukadan.net/docs/zca.html#zcml>`_, an XML dialect
+ used by Zope and :term:`pyramid_zcml` for configuration tasks.
+
+ ZCML directive
+ A ZCML "tag" such as ``<view>`` or ``<route>``.
+
+ ZCML declaration
+ The concrete use of a :term:`ZCML directive` within a ZCML file.
+
View
@@ -85,14 +85,12 @@ applications to various platforms.
Reference Material
==================
-Reference material includes API documentation and documentation of
-every :app:`Pyramid` :term:`ZCML directive`.
+Reference material includes documentation for every :app:`Pyramid` API.
.. toctree::
:maxdepth: 2
api
- zcml
Detailed Change History
=======================
View
@@ -97,7 +97,6 @@ API Reference
api/renderers
api/request
api/response
- api/router
api/scripting
api/security
api/settings
@@ -108,35 +107,6 @@ API Reference
api/view
api/wsgi
-.. _zcml_reference:
-
-ZCML Directive Reference
-@@@@@@@@@@@@@@@@@@@@@@@@
-
-.. 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
-
.. backmatter::
Glossary and Index
@@ -115,11 +115,8 @@ allowing the circumstance to go unreported, by default Pyramid raises a
running.
Conflict detection happens for any kind of configuration: imperative
-configuration, :term:`ZCML` configuration, or configuration that results from
-the execution of a :term:`scan`.
-
-.. note:: If you use, ZCML, its conflict detection algorithm is described in
- :ref:`zcml_conflict_detection`.
+configuration or configuration that results from the execution of a
+:term:`scan`.
Manually Resolving Conflicts
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -82,9 +82,6 @@ function found via a :term:`scan`.
decorated function for the decorator to have any effect. See
:func:`pyramid.subscriber` for more information.
-.. note:: You can also configure an event listener via ZCML. See
- :ref:`zcml_event_listener`.
-
Either of the above registration examples implies that every time the
:app:`Pyramid` framework emits an event object that supplies an
:class:`pyramid.events.NewRequest` interface, the ``mysubscriber`` function
View
@@ -70,9 +70,6 @@ Here's some sample code that implements a minimal NotFound view callable:
:exc:`pyramid.exceptions.NotFound` exception instance. If available, the
resource context will still be available as ``request.context``.
-For information about how to configure a not found view via :term:`ZCML`, see
-:ref:`notfound_zcml`.
-
.. index::
single: forbidden view
@@ -138,9 +135,6 @@ 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.
-For information about how to configure a forbidden view via :term:`ZCML`, see
-:ref:`forbidden_zcml`.
-
.. index::
single: request factory
@@ -185,8 +179,6 @@ already constructed a :term:`configurator` it can also be registered via the
config = Configurator()
config.set_request_factory(MyRequest)
-To use ZCML for the same purpose, see :ref:`changing_request_factory_zcml`.
-
.. index::
single: renderer globals
@@ -242,9 +234,6 @@ already constructed a :term:`configurator` it can also be registered via the
Another mechanism which allows event subscribers to add renderer global values
exists in :ref:`beforerender_event`.
-If you'd rather ZCML to register a renderer globals factory, see
-:ref:`adding_renderer_globals_zcml`.
-
.. index::
single: before render event
@@ -474,9 +463,6 @@ when the application :term:`root factory` returned an instance of the
``myapp.resources.MyRoot`` object. Otherwise it would use the default
:app:`Pyramid` traverser to do traversal.
-For information about how to configure an alternate traverser via
-:term:`ZCML`, see :ref:`changing_traverser_zcml`.
-
.. index::
single: url generator
View
@@ -890,9 +890,6 @@ will be merged into translations from a message catalog added earlier
if both translation directories contain translations for the same
locale and :term:`translation domain`.
-.. note:: You can also add a translation directory via ZCML. See
- :ref:`zcml_adding_a_translation_directory`
-
Setting the Locale
~~~~~~~~~~~~~~~~~~
@@ -1019,5 +1016,3 @@ For example:
config = Configurator()
config.set_locale_negotiator(my_locale_negotiator)
-.. note:: You can also add a custom locale negotiator via ZCML. See
- :ref:`zcml_adding_a_locale_negotiator`
@@ -26,7 +26,6 @@ and so therefore they are often referred to as "paster templates".
.. index::
single: paster templates
single: pyramid_starter paster template
- single: pyramid_starter_zcml paster template
single: pyramid_zodb paster template
single: pyramid_alchemy paster template
single: pyramid_routesalchemy paster template
@@ -45,8 +44,6 @@ each other on a number of axes:
- the mechanism they use to map URLs to code (:term:`traversal` or :term:`URL
dispatch`).
-- the type of configuration used (:term:`ZCML` vs. imperative configuration).
-
- whether or not the ``pyramid_beaker`` library is relied upon as the
sessioning implementation (as opposed to no sessioning or default
sessioning).
@@ -56,10 +53,6 @@ The included templates are these:
``pyramid_starter``
URL mapping via :term:`traversal` and no persistence mechanism.
-``pyramid_starter_zcml``
- URL mapping via :term:`traversal` and no persistence mechanism, using
- :term:`ZCML` (declarative configuration).
-
``pyramid_zodb``
URL mapping via :term:`traversal` and persistence via :term:`ZODB`.
@@ -400,10 +400,6 @@ factory.
Renderers can be registered imperatively using the
:meth:`pyramid.config.Configurator.add_renderer` API.
-.. note:: The tasks described in this section can also be performed via
- :term:`declarative configuration`. See
- :ref:`zcml_adding_and_overriding_renderers`.
-
For example, to add a renderer which renders views which have a
``renderer`` attribute that is a path that ends in ``.jinja2``:
Oops, something went wrong.

0 comments on commit c9c3c48

Please sign in to comment.