Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

- Add paster template for starter_zcml

- Make docs render.

- Add "make_app" from pyramid.router.
  • Loading branch information...
commit 9389e5fda032b92ea829db165ee9da03739a2e5b 1 parent cb022e0
@mcdonc mcdonc authored
Showing with 1,930 additions and 10 deletions.
  1. +4 −0 docs/api.rst
  2. +29 −0 docs/glossary.rst
  3. +9 −0 docs/index.rst
  4. +1,403 −0 docs/narr.rst
  5. +83 −4 pyramid_zcml/__init__.py
  6. +11 −0 pyramid_zcml/paster_templates/starter_zcml/+package+/__init__.py_tmpl
  7. +17 −0 pyramid_zcml/paster_templates/starter_zcml/+package+/configure.zcml
  8. +3 −0  pyramid_zcml/paster_templates/starter_zcml/+package+/resources.py
  9. BIN  pyramid_zcml/paster_templates/starter_zcml/+package+/static/favicon.ico
  10. BIN  pyramid_zcml/paster_templates/starter_zcml/+package+/static/footerbg.png
  11. BIN  pyramid_zcml/paster_templates/starter_zcml/+package+/static/headerbg.png
  12. +8 −0 pyramid_zcml/paster_templates/starter_zcml/+package+/static/ie6.css
  13. BIN  pyramid_zcml/paster_templates/starter_zcml/+package+/static/middlebg.png
  14. +65 −0 pyramid_zcml/paster_templates/starter_zcml/+package+/static/pylons.css
  15. BIN  pyramid_zcml/paster_templates/starter_zcml/+package+/static/pyramid-small.png
  16. BIN  pyramid_zcml/paster_templates/starter_zcml/+package+/static/pyramid.png
  17. BIN  pyramid_zcml/paster_templates/starter_zcml/+package+/static/transparent.gif
  18. +75 −0 pyramid_zcml/paster_templates/starter_zcml/+package+/templates/mytemplate.pt_tmpl
  19. +18 −0 pyramid_zcml/paster_templates/starter_zcml/+package+/tests.py_tmpl
  20. +2 −0  pyramid_zcml/paster_templates/starter_zcml/+package+/views.py_tmpl
  21. +4 −0 pyramid_zcml/paster_templates/starter_zcml/CHANGES.txt_tmpl
  22. +4 −0 pyramid_zcml/paster_templates/starter_zcml/README.txt_tmpl
  23. +44 −0 pyramid_zcml/paster_templates/starter_zcml/development.ini_tmpl
  24. +27 −0 pyramid_zcml/paster_templates/starter_zcml/setup.cfg_tmpl
  25. +37 −0 pyramid_zcml/paster_templates/starter_zcml/setup.py_tmpl
  26. +83 −4 pyramid_zcml/tests/tests.py
  27. +4 −2 setup.py
View
4 docs/api.rst
@@ -6,3 +6,7 @@
.. automodule:: pyramid_zcml
.. autofunction:: load_zcml(spec='configure.zcml')
+
+.. autofunction:: make_app(root_factory, package=None, filename='configure.zcml', settings=None)
+
+.. autofunction:: includeme
View
29 docs/glossary.rst
@@ -304,3 +304,32 @@ Glossary
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`.
+
+ renderer
+ A serializer that can be referred to via :term:`view
+ configuration` which converts a non-:term:`Response` return
+ values from a :term:`view` into a string (and ultimately a
+ response). Using a renderer can make writing views that require
+ templating or other serialization less tedious. See
+ :ref:`views_which_use_a_renderer` for more information.
+
+ renderer factory
+ A factory which creates a :term:`renderer`. See
+ :ref:`adding_and_overriding_renderers` for more information.
+
+ authentication policy
+ An authentication policy in Pyramid terms is a bit of
+ code which has an API which determines the current
+ :term:`principal` (or principals) associated with a request.
+
+ ZCML declaration
+ The concrete use of a :term:`ZCML directive` within a ZCML file.
+
+ ZCML directive
+ A ZCML "tag" such as ``<view>`` or ``<route>``.
+
+ Resource Location
+ The act of locating a :term:`context` resource given a :term:`request`.
+ :term:`Traversal` and :term:`URL dispatch` are the resource location
+ subsystems used by Pyramid.
+
View
9 docs/index.rst
@@ -38,6 +38,15 @@ the configurator, ala:
config.load_zcml(....)
+Usage
+-----
+
+.. toctree::
+ :maxdepth: 2
+
+ narr.rst
+
+
Directives and API
------------------
View
1,403 docs/narr.rst
@@ -0,0 +1,1403 @@
+.. _declarative_chapter:
+
+Declarative Configuration using ZCML
+====================================
+
+The mode of configuration detailed in the examples within the :term:`Pyramid`
+documentation is "imperative" configuration. This is the configuration mode
+in which a developer cedes the least amount of control to the framework; it's
+"imperative" because you express the configuration directly in Python code,
+and you have the full power of Python at your disposal as you issue
+configuration statements. However, another mode of configuration exists For
+Pyramid within ``pyramid_zcml`` named :term:`ZCML` which is *declarative*.
+In ZCML, configuration statements are made via an domain specific language
+implemented in XML. There is no opportunity for conditionals or loops.
+Declarative languages are less powerful than their imperative counterparts;
+this is attractive in environments where consistency is more important than
+brevity.
+
+A complete listing of ZCML directives is available within
+:ref:`zcml_directives`. This chapter provides an overview of how you might
+get started with ZCML and highlights some common tasks performed when you use
+ZCML.
+
+.. index::
+ single: declarative configuration
+
+.. _declarative_configuration:
+
+ZCML Configuration
+------------------
+
+A Pyramid application can be configured "declaratively", if so
+desired. Declarative configuration relies on *declarations* made external to
+the code in a configuration file format named :term:`ZCML` (Zope
+Configuration Markup Language), an XML dialect.
+
+A Pyramid application configured declaratively requires not
+one, but two files: a Python file and a :term:`ZCML` file.
+
+In a file named ``helloworld.py``:
+
+.. code-block:: python
+ :linenos:
+
+ from paste.httpserver import serve
+ from pyramid.response import Response
+ from pyramid.config import Configurator
+
+ def hello_world(request):
+ return Response('Hello world!')
+
+ if __name__ == '__main__':
+ config = Configurator()
+ config.include('pyramid_zcml')
+ config.load_zcml('configure.zcml')
+ app = config.make_wsgi_app()
+ serve(app, host='0.0.0.0')
+
+In a file named ``configure.zcml`` in the same directory as the
+previously created ``helloworld.py``:
+
+.. code-block:: xml
+ :linenos:
+
+ <configure xmlns="http://pylonshq.com/pyramid">
+
+ <include package="pyramid_zcml" />
+
+ <view
+ view="helloworld.hello_world"
+ />
+
+ </configure>
+
+This pair of files forms an application functionally equivalent to the
+application we created earlier in :ref:`imperative_configuration`.
+Let's examine the differences between that code listing and the code
+above.
+
+In :ref:`imperative_configuration`, we had the following lines within
+the ``if __name__ == '__main__'`` section of ``helloworld.py``:
+
+.. code-block:: python
+ :linenos:
+
+ if __name__ == '__main__':
+ config = Configurator()
+ config.add_view(hello_world)
+ app = config.make_wsgi_app()
+ serve(app, host='0.0.0.0')
+
+In our "declarative" code, we've removed the call to ``add_view`` and
+replaced it with a call to the :func:`pyramid_zcml.load_zcml` method so that
+it now reads as:
+
+.. code-block:: python
+ :linenos:
+
+ if __name__ == '__main__':
+ config = Configurator()
+ config.include('pyramid_zcml')
+ config.load_zcml('configure.zcml')
+ app = config.make_wsgi_app()
+ serve(app, host='0.0.0.0')
+
+Everything else is much the same.
+
+The ``config.include('pyramid_zcml')`` line makes the ``load_zcml`` method
+available on the configurator. The ``config.load_zcml('configure.zcml')``
+line tells the configurator to load configuration declarations from the file
+named ``configure.zcml`` which sits next to ``helloworld.py`` on the
+filesystem. Let's take a look at that ``configure.zcml`` file again:
+
+.. code-block:: xml
+ :linenos:
+
+ <configure xmlns="http://pylonshq.com/pyramid">
+
+ <include package="pyramid_zcml" />
+
+ <view
+ view="helloworld.hello_world"
+ />
+
+ </configure>
+
+Note that this file contains some XML, and that the XML contains a
+``<view>`` :term:`configuration declaration` tag that references a
+:term:`dotted Python name`. This dotted name refers to the
+``hello_world`` function that lives in our ``helloworld`` Python
+module.
+
+This ``<view>`` declaration tag performs the same function as the
+``add_view`` method that was employed within
+:ref:`imperative_configuration`. In fact, the ``<view>`` tag is
+effectively a "macro" which calls the
+:meth:`pyramid.config.Configurator.add_view` method on your
+behalf.
+
+The ``<view>`` tag is an example of a Pyramid declaration
+tag. Other such tags include ``<route>`` and ``<scan>``. Each of
+these tags is effectively a "macro" which calls methods of a
+:class:`pyramid.config.Configurator` object on your behalf.
+
+Essentially, using a :term:`ZCML` file and loading it from the
+filesystem allows us to put our configuration statements within this
+XML file rather as declarations, rather than representing them as
+method calls to a :term:`Configurator` object. Otherwise, declarative
+and imperative configuration are functionally equivalent.
+
+Using declarative configuration has a number of benefits, the primary
+benefit being that applications configured declaratively can be
+*overridden* and *extended* by third parties without requiring the
+third party to change application code. If you want to build a
+framework or an extensible application, using declarative
+configuration is a good idea.
+
+Declarative configuration has an obvious downside: you can't use
+plain-old-Python syntax you probably already know and understand to
+configure your application; instead you need to use :term:`ZCML`.
+
+.. index::
+ single: ZCML conflict detection
+
+.. _zcml_conflict_detection:
+
+ZCML Conflict Detection
+~~~~~~~~~~~~~~~~~~~~~~~
+
+A minor additional feature of ZCML is *conflict detection*. If you
+define two declaration tags within the same ZCML file which logically
+"collide", an exception will be raised, and the application will not
+start. For example, the following ZCML file has two conflicting
+``<view>`` tags:
+
+.. code-block:: xml
+ :linenos:
+
+ <configure xmlns="http://pylonshq.com/pyramid">
+
+ <include package="pyramid_zcml" />
+
+ <view
+ view="helloworld.hello_world"
+ />
+
+ <view
+ view="helloworld.hello_world"
+ />
+
+ </configure>
+
+If you try to use this ZCML file as the source of ZCML for an
+application, an error will be raised when you attempt to start the
+application. This error will contain information about which tags
+might have conflicted.
+
+.. index::
+ single: helloworld (declarative)
+
+.. _helloworld_declarative:
+
+Hello World, Goodbye World (Declarative)
+----------------------------------------
+
+Another almost entirely equivalent mode of application configuration
+exists named *declarative* configuration. Pyramid can be
+configured for the same "hello world" application "declaratively", if
+so desired.
+
+To do so, first, create a file named ``helloworld.py``:
+
+.. code-block:: python
+ :linenos:
+
+ from pyramid.config import Configurator
+ from pyramid.response import Response
+ from paste.httpserver import serve
+
+ def hello_world(request):
+ return Response('Hello world!')
+
+ def goodbye_world(request):
+ return Response('Goodbye world!')
+
+ if __name__ == '__main__':
+ config = Configurator()
+ config.include('pyramid_zcml')
+ config.load_zcml('configure.zcml')
+ app = config.make_wsgi_app()
+ serve(app, host='0.0.0.0')
+
+Then create a file named ``configure.zcml`` in the same directory as
+the previously created ``helloworld.py``:
+
+.. code-block:: xml
+ :linenos:
+
+ <configure xmlns="http://pylonshq.com/pyramid">
+
+ <include package="pyramid_zcml" />
+
+ <view
+ view="helloworld.hello_world"
+ />
+
+ <view
+ name="goodbye"
+ view="helloworld.goodbye_world"
+ />
+
+ </configure>
+
+This pair of files forms an application functionally equivalent to the
+application we created earlier in :ref:`helloworld_imperative`. We can run
+it the same way.
+
+.. code-block:: text
+
+ $ python helloworld.py
+ serving on 0.0.0.0:8080 view at http://127.0.0.1:8080
+
+Let's examine the differences between the code in that section and the code
+above. In :ref:`helloworld_imperative_appconfig`, we had the following lines
+within the ``if __name__ == '__main__'`` section of ``helloworld.py``:
+
+.. code-block:: python
+ :linenos:
+
+ if __name__ == '__main__':
+ config = Configurator()
+ config.add_view(hello_world)
+ config.add_view(goodbye_world, name='goodbye')
+ app = config.make_wsgi_app()
+ serve(app, host='0.0.0.0')
+
+In our "declarative" code, we've added a call to the
+:func:`pyramid_zcml.load_zcml` method with the value ``configure.zcml``, and
+we've removed the lines which read ``config.add_view(hello_world)`` and
+``config.add_view(goodbye_world, name='goodbye')``, so that it now reads as:
+
+.. code-block:: python
+ :linenos:
+
+ if __name__ == '__main__':
+ config = Configurator()
+ config.include('pyramid_zcml')
+ config.load_zcml('configure.zcml')
+ app = config.make_wsgi_app()
+ serve(app, host='0.0.0.0')
+
+Everything else is much the same.
+
+The ``config.load_zcml('configure.zcml')`` line tells the configurator
+to load configuration declarations from the ``configure.zcml`` file
+which sits next to ``helloworld.py``. Let's take a look at the
+``configure.zcml`` file now:
+
+.. code-block:: xml
+ :linenos:
+
+ <configure xmlns="http://pylonshq.com/pyramid">
+
+ <include package="pyramid_zcml" />
+
+ <view
+ view="helloworld.hello_world"
+ />
+
+ <view
+ name="goodbye"
+ view="helloworld.goodbye_world"
+ />
+
+ </configure>
+
+We already understand what the view code does, because the application
+is functionally equivalent to the application described in
+:ref:`helloworld_imperative`, but use of :term:`ZCML` is new. Let's
+break that down tag-by-tag.
+
+The ``<configure>`` Tag
+~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``configure.zcml`` ZCML file contains this bit of XML:
+
+.. code-block:: xml
+ :linenos:
+
+ <configure xmlns="http://pylonshq.com/pyramid">
+
+ <!-- other directives -->
+
+ </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.
+
+See also :ref:`configure_directive` and :ref:`word_on_xml_namespaces`.
+
+.. _the_include_tag:
+
+The ``<include>`` Tag
+~~~~~~~~~~~~~~~~~~~~~
+
+The ``configure.zcml`` ZCML file contains this bit of XML within the
+``<configure>`` root tag:
+
+.. code-block:: xml
+ :linenos:
+
+ <include package="pyramid_zcml" />
+
+This self-closing tag instructs Pyramid to load a ZCML file
+from the Python package with the :term:`dotted Python name`
+``pyramid_zcml``, as specified by its ``package`` attribute.
+This particular ``<include>`` declaration is required because it
+actually allows subsequent declaration tags (such as ``<view>``, which
+we'll see shortly) to be recognized. The ``<include>`` tag
+effectively just includes another ZCML file, causing its declarations
+to be executed. In this case, we want to load the declarations from
+the file named ``configure.zcml`` within the
+:mod:`pyramid_zcml` Python package. We know we want to load
+the ``configure.zcml`` from this package because ``configure.zcml`` is
+the default value for another attribute of the ``<include>`` tag named
+``file``. We could have spelled the include tag more verbosely, but
+equivalently as:
+
+.. code-block:: xml
+ :linenos:
+
+ <include package="pyramid_zcml"
+ file="configure.zcml"/>
+
+The ``<include>`` tag that includes the ZCML statements implied by the
+``configure.zcml`` file from the Python package named
+:mod:`pyramid_zcml` is basically required to come before any
+other named declaration in an application's ``configure.zcml``. If it
+is not included, subsequent declaration tags will fail to be
+recognized, and the configuration system will generate an error at
+startup. However, the ``<include package="pyramid_zcml"/>``
+tag needs to exist only in a "top-level" ZCML file, it needn't also
+exist in ZCML files *included by* a top-level ZCML file.
+
+See also :ref:`include_directive`.
+
+The ``<view>`` Tag
+~~~~~~~~~~~~~~~~~~
+
+The ``configure.zcml`` ZCML file contains these bits of XML *after* the
+``<include>`` tag, but *within* the ``<configure>`` root tag:
+
+.. code-block:: xml
+ :linenos:
+
+ <view
+ view="helloworld.hello_world"
+ />
+
+ <view
+ name="goodbye"
+ view="helloworld.goodbye_world"
+ />
+
+These ``<view>`` declaration tags direct Pyramid to create
+two :term:`view configuration` registrations. The first ``<view>``
+tag has an attribute (the attribute is also named ``view``), which
+points at a :term:`dotted Python name`, referencing the
+``hello_world`` function defined within the ``helloworld`` package.
+The second ``<view>`` tag has a ``view`` attribute which points at a
+:term:`dotted Python name`, referencing the ``goodbye_world`` function
+defined within the ``helloworld`` package. The second ``<view>`` tag
+also has an attribute called ``name`` with a value of ``goodbye``.
+
+These effect of the ``<view>`` tag declarations we've put into our
+``configure.zcml`` is functionally equivalent to the effect of lines
+we've already seen in an imperatively-configured application. We're
+just spelling things differently, using XML instead of Python.
+
+In our previously defined application, in which we added view
+configurations imperatively, we saw this code:
+
+.. ignore-next-block
+.. code-block:: python
+ :linenos:
+
+ config.add_view(hello_world)
+ config.add_view(goodbye_world, name='goodbye')
+
+Each ``<view>`` declaration tag encountered in a ZCML file effectively
+invokes the :meth:`pyramid.config.Configurator.add_view`
+method on the behalf of the developer. Various attributes can be
+specified on the ``<view>`` tag which influence the :term:`view
+configuration` it creates.
+
+Since the relative ordering of calls to
+:meth:`pyramid.config.Configurator.add_view` doesn't matter
+(see the sidebar entitled *View Dispatch and Ordering* within
+:ref:`adding_configuration`), the relative order of ``<view>`` tags in
+ZCML doesn't matter either. The following ZCML orderings are
+completely equivalent:
+
+.. topic:: Hello Before Goodbye
+
+ .. code-block:: xml
+ :linenos:
+
+ <view
+ view="helloworld.hello_world"
+ />
+
+ <view
+ name="goodbye"
+ view="helloworld.goodbye_world"
+ />
+
+.. topic:: Goodbye Before Hello
+
+ .. code-block:: xml
+ :linenos:
+
+ <view
+ name="goodbye"
+ view="helloworld.goodbye_world"
+ />
+
+ <view
+ view="helloworld.hello_world"
+ />
+
+We've now configured a Pyramid helloworld application
+declaratively. More information about this mode of configuration is
+available in :ref:`declarative_configuration` and within
+:ref:`zcml_reference`.
+
+.. index::
+ single: ZCML granularity
+
+ZCML Granularity
+~~~~~~~~~~~~~~~~
+
+It's extremely helpful to third party application "extenders" (aka
+"integrators") if the :term:`ZCML` that composes the configuration for an
+application is broken up into separate files which do very specific things.
+These more specific ZCML files can be reintegrated within the application's
+main ``configure.zcml`` via ``<include file="otherfile.zcml"/>``
+declarations. When ZCML files contain sets of specific declarations, an
+integrator can avoid including any ZCML he does not want by including only
+ZCML files which contain the declarations he needs. He is not forced to
+"accept everything" or "use nothing".
+
+For example, it's often useful to put all ``<route>`` declarations in a
+separate ZCML file, as ``<route>`` statements have a relative ordering that
+is extremely important to the application: if an extender wants to add a
+route to the "middle" of the routing table, he will always need to disuse all
+the routes and cut and paste the routing configuration into his own
+application. It's useful for the extender to be able to disuse just a
+*single* ZCML file in this case, accepting the remainder of the configuration
+from other :term:`ZCML` files in the original application.
+
+Granularizing ZCML is not strictly required. An extender can always disuse
+*all* your ZCML, choosing instead to copy and paste it into his own package,
+if necessary. However, doing so is considerate, and allows for the best
+reusability. Sometimes it's possible to include only certain ZCML files from
+an application that contain only the registrations you really need, omitting
+others. But sometimes it's not. For brute force purposes, when you're
+getting ``view`` or ``route`` registrations that you don't actually want in
+your overridden application, it's always appropriate to just *not include*
+any ZCML file from the overridden application. Instead, just cut and paste
+the entire contents of the ``configure.zcml`` (and any ZCML file included by
+the overridden application's ``configure.zcml``) into your own package and
+omit the ``<include package=""/>`` ZCML declaration in the overriding
+package's ``configure.zcml``.
+
+.. _zcml_scanning:
+
+Scanning via ZCML
+-----------------
+
+:term:`ZCML` can invoke a :term:`scan` via its ``<scan>`` directive. If a
+ZCML file is processed that contains a scan directive, the package the ZCML
+file points to is scanned.
+
+.. code-block:: python
+ :linenos:
+
+ # helloworld.py
+
+ from paste.httpserver import serve
+ from pyramid.response import Response
+ from pyramid.view import view_config
+
+ @view_config()
+ def hello(request):
+ return Response('Hello')
+
+ if __name__ == '__main__':
+ from pyramid.config import Configurator
+ config = Configurator()
+ config.include('pyramid_zcml')
+ config.load_zcml('configure.zcml')
+ app = config.make_wsgi_app()
+ serve(app, host='0.0.0.0')
+
+.. code-block:: xml
+ :linenos:
+
+ <configure xmlns="http://pylonshq.com/pyramid">
+
+ <!-- configure.zcml -->
+
+ <include package="pyramid_zcml"/>
+ <scan package="."/>
+
+ </configure>
+
+See also :ref:`scan_directive`.
+
+Which Mode Should I Use?
+------------------------
+
+A combination of imperative configuration, declarative configuration via ZCML
+and scanning can be used to configure any application. They are not mutually
+exclusive.
+
+Declarative configuraton was the more traditional form of configuration used
+in Pyramid applications; the first releases of Pyramid and all releases of
+Pyramid's predecessor named repoze.bfg included ZCML in the core. However,
+by virtue of this package, it has been externalized from the Pyramid core
+because it has proven that imperative mode configuration can be simpler to
+understand and document.
+
+However, you can choose to use imperative configuration, or declarative
+configuration via ZCML. Use the mode that best fits your brain as necessary.
+
+.. index::
+ single: ZCML view configuration
+
+.. _mapping_views_using_zcml_section:
+
+View Configuration Via ZCML
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You may associate a view with a URL by adding :ref:`view_directive`
+declarations via :term:`ZCML` in a ``configure.zcml`` file. An
+example of a view declaration in ZCML is as follows:
+
+.. code-block:: xml
+ :linenos:
+
+ <view
+ context=".resources.Hello"
+ view=".views.hello_world"
+ name="hello.html"
+ />
+
+The above maps the ``.views.hello_world`` view callable function to
+the following set of :term:`resource location` results:
+
+- A :term:`context` object which is an instance (or subclass) of the
+ Python class represented by ``.resources.Hello``
+
+- A :term:`view name` equalling ``hello.html``.
+
+.. note:: Values prefixed with a period (``.``) for the ``context``
+ and ``view`` attributes of a ``view`` declaration (such as those
+ above) mean "relative to the Python package directory in which this
+ :term:`ZCML` file is stored". So if the above ``view`` declaration
+ was made inside a ``configure.zcml`` file that lived in the
+ ``hello`` package, you could replace the relative ``.resources.Hello``
+ with the absolute ``hello.resources.Hello``; likewise you could
+ replace the relative ``.views.hello_world`` with the absolute
+ ``hello.views.hello_world``. Either the relative or absolute form
+ is functionally equivalent. It's often useful to use the relative
+ form, in case your package's name changes. It's also shorter to
+ type.
+
+You can also declare a *default view callable* for a :term:`resource` type:
+
+.. code-block:: xml
+ :linenos:
+
+ <view
+ context=".resources.Hello"
+ view=".views.hello_world"
+ />
+
+A *default view callable* simply has no ``name`` attribute. For the above
+registration, when a :term:`context` is found that is of the type
+``.resources.Hello`` and there is no :term:`view name` associated with the
+result of :term:`resource location`, the *default view callable* will be
+used. In this case, it's the view at ``.views.hello_world``.
+
+A default view callable can alternately be defined by using the empty
+string as its ``name`` attribute:
+
+.. code-block:: xml
+ :linenos:
+
+ <view
+ context=".resources.Hello"
+ view=".views.hello_world"
+ name=""
+ />
+
+You may also declare that a view callable is good for any context type
+by using the special ``*`` character as the value of the ``context``
+attribute:
+
+.. code-block:: xml
+ :linenos:
+
+ <view
+ context="*"
+ view=".views.hello_world"
+ name="hello.html"
+ />
+
+This indicates that when Pyramid identifies that the
+:term:`view name` is ``hello.html`` and the context is of any type,
+the ``.views.hello_world`` view callable will be invoked.
+
+A ZCML ``view`` declaration's ``view`` attribute can also name a
+class. In this case, the rules described in :ref:`class_as_view`
+apply for the class which is named.
+
+See :ref:`view_directive` for complete ZCML directive documentation.
+
+.. index::
+ single: ZCML directive; route
+
+.. _zcml_route_configuration:
+
+Configuring a Route via ZCML
+----------------------------
+
+Instead of using the imperative :meth:`pyramid.config.Configurator.add_route`
+method to add a new route, you can alternately use :term:`ZCML`.
+:ref:`route_directive` statements in a :term:`ZCML` file. For example, the
+following :term:`ZCML declaration` causes a route to be added to the
+application.
+
+.. code-block:: xml
+ :linenos:
+
+ <route
+ name="myroute"
+ pattern="/prefix/{one}/{two}"
+ view=".views.myview"
+ />
+
+.. note::
+
+ Values prefixed with a period (``.``) within the values of ZCML
+ attributes such as the ``view`` attribute of a ``route`` mean
+ "relative to the Python package directory in which this
+ :term:`ZCML` file is stored". So if the above ``route``
+ declaration was made inside a ``configure.zcml`` file that lived in
+ the ``hello`` package, you could replace the relative
+ ``.views.myview`` with the absolute ``hello.views.myview`` Either
+ the relative or absolute form is functionally equivalent. It's
+ often useful to use the relative form, in case your package's name
+ changes. It's also shorter to type.
+
+The order that routes are evaluated when declarative configuration is used
+is the order that they appear relative to each other in the ZCML file.
+
+See :ref:`route_directive` for full ``route`` ZCML directive
+documentation.
+
+.. index::
+ triple: view; zcml; static resource
+
+.. _zcml_static_assets_section:
+
+Serving Static Assets Using ZCML
+--------------------------------
+
+Use of the ``static`` ZCML directive makes static assets available at a name
+relative to the application root URL, e.g. ``/static``.
+
+Note that the ``path`` provided to the ``static`` ZCML directive may be a
+fully qualified :term:`asset specification`, a package-relative path, or
+an *absolute path*. The ``path`` with the value ``a/b/c/static`` of a
+``static`` directive in a ZCML file that resides in the "mypackage" package
+will resolve to a package-qualified assets such as
+``some_package:a/b/c/static``.
+
+Here's an example of a ``static`` ZCML directive that will serve files
+up under the ``/static`` URL from the ``/var/www/static`` directory of
+the computer which runs the Pyramid application using an
+absolute path.
+
+.. code-block:: xml
+ :linenos:
+
+ <static
+ name="static"
+ path="/var/www/static"
+ />
+
+Here's an example of a ``static`` directive that will serve files up
+under the ``/static`` URL from the ``a/b/c/static`` directory of the
+Python package named ``some_package`` using a fully qualified
+:term:`asset specification`.
+
+.. code-block:: xml
+ :linenos:
+
+ <static
+ name="static"
+ path="some_package:a/b/c/static"
+ />
+
+Here's an example of a ``static`` directive that will serve files up
+under the ``/static`` URL from the ``static`` directory of the Python
+package in which the ``configure.zcml`` file lives using a
+package-relative path.
+
+.. code-block:: xml
+ :linenos:
+
+ <static
+ name="static"
+ path="static"
+ />
+
+Whether you use for ``path`` a fully qualified asset specification,
+an absolute path, or a package-relative path, When you place your
+static files on the filesystem in the directory represented as the
+``path`` of the directive, you will then be able to view the static
+files in this directory via a browser at URLs prefixed with the
+directive's ``name``. For instance if the ``static`` directive's
+``name`` is ``static`` and the static directive's ``path`` is
+``/path/to/static``, ``http://localhost:6543/static/foo.js`` will
+return the file ``/path/to/static/dir/foo.js``. The static directory
+may contain subdirectories recursively, and any subdirectories may
+hold files; these will be resolved by the static view as you would
+expect.
+
+While the ``path`` argument can be a number of different things, the
+``name`` argument of the ``static`` ZCML directive can also be one of
+a number of things: a *view name* or a *URL*. The above examples have
+shown usage of the ``name`` argument as a view name. When ``name`` is
+a *URL* (or any string with a slash (``/``) in it), static assets
+can be served from an external webserver. In this mode, the ``name``
+is used as the URL prefix when generating a URL using
+:func:`pyramid.url.static_url`.
+
+For example, the ``static`` ZCML directive may be fed a ``name``
+argument which is ``http://example.com/images``:
+
+.. code-block:: xml
+ :linenos:
+
+ <static
+ name="http://example.com/images"
+ path="mypackage:images"
+ />
+
+Because the ``static`` ZCML directive is provided with a ``name`` argument
+that is the URL prefix ``http://example.com/images``, subsequent calls to
+:func:`pyramid.url.static_url` with paths that start with the ``path``
+argument passed to :meth:`pyramid.url.static_url` will generate a URL
+something like ``http://example.com/logo.png``. The external webserver
+listening on ``example.com`` must be itself configured to respond properly to
+such a request. The :func:`pyramid.url.static_url` API is discussed in more
+detail later in this chapter.
+
+The :meth:`pyramid.config.Configurator.add_static_view` method offers
+an imperative equivalent to the ``static`` ZCML directive. Use of the
+``add_static_view`` imperative configuration method is completely equivalent
+to using ZCML for the same purpose. See :ref:`static_assets_section` for
+more information.
+
+.. index::
+ pair: ZCML directive; asset
+
+.. _asset_zcml_directive:
+
+The ``asset`` ZCML Directive
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Instead of using :meth:`pyramid.config.Configurator.override_asset` during
+:term:`imperative configuration`, an equivalent ZCML directive can be used.
+The ZCML ``asset`` tag is a frontend to using
+:meth:`pyramid.config.Configurator.override_asset`.
+
+An individual Pyramid ``asset`` ZCML statement can override a
+single asset. For example:
+
+.. code-block:: xml
+ :linenos:
+
+ <asset
+ to_override="some.package:templates/mytemplate.pt"
+ override_with="another.package:othertemplates/anothertemplate.pt"
+ />
+
+The string value passed to both ``to_override`` and ``override_with``
+attached to an ``asset`` directive is called an "asset specification". The
+colon separator in a specification separates the *package name* from the
+*asset name*. The colon and the following asset name are optional. If they
+are not specified, the override attempts to resolve every lookup into a
+package from the directory of another package. For example:
+
+.. code-block:: xml
+ :linenos:
+
+ <asset
+ to_override="some.package"
+ override_with="another.package"
+ />
+
+Individual subdirectories within a package can also be overridden:
+
+.. code-block:: xml
+ :linenos:
+
+ <asset
+ to_override="some.package:templates/"
+ override_with="another.package:othertemplates/"
+ />
+
+If you wish to override an asset directory with another directory, you *must*
+make sure to attach the slash to the end of both the ``to_override``
+specification and the ``override_with`` specification. If you fail to attach
+a slash to the end of an asset specification that points to a directory, you
+will get unexpected results.
+
+The package name in an asset specification may start with a dot, meaning that
+the package is relative to the package in which the ZCML file resides. For
+example:
+
+.. code-block:: xml
+ :linenos:
+
+ <asset
+ to_override=".subpackage:templates/"
+ override_with="another.package:templates/"
+ />
+
+See also :ref:`asset_directive`.
+
+.. _zcml_authorization_policy:
+
+Enabling an Authorization Policy Via ZCML
+-----------------------------------------
+
+If you'd rather use :term:`ZCML` to specify an authorization policy
+than imperative configuration, modify the ZCML file loaded by your
+application (usually named ``configure.zcml``) to enable an
+authorization policy.
+
+For example, to enable a policy which compares the value of an "auth ticket"
+cookie passed in the request's environment which contains a reference to a
+single :term:`principal` against the principals present in any :term:`ACL`
+found in the resource tree when attempting to call some :term:`view`, modify
+your ``configure.zcml`` to look something like this:
+
+.. code-block:: xml
+ :linenos:
+
+ <configure xmlns="http://pylonshq.com/pyramid">
+
+ <!-- views and other directives before this... -->
+
+ <authtktauthenticationpolicy
+ secret="iamsosecret"/>
+
+ <aclauthorizationpolicy/>
+
+ </configure>
+
+"Under the hood", these statements cause an instance of the class
+:class:`pyramid.authentication.AuthTktAuthenticationPolicy` to be
+injected as the :term:`authentication policy` used by this application
+and an instance of the class
+:class:`pyramid.authorization.ACLAuthorizationPolicy` to be
+injected as the :term:`authorization policy` used by this application.
+
+Pyramid ships with a number of authorization and
+authentication policy ZCML directives that should prove useful. See
+:ref:`authentication_policies_directives_section` and
+:ref:`authorization_policies_directives_section` for more information.
+
+.. index::
+ pair: ZCML directive; authentication policy
+
+.. _authentication_policies_directives_section:
+
+Built-In Authentication Policy ZCML Directives
+----------------------------------------------
+
+Instead of configuring an authentication policy and authorization
+policy imperatively, Pyramid ships with a few "pre-chewed"
+authentication policy ZCML directives that you can make use of within
+your application.
+
+``authtktauthenticationpolicy``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When this directive is used, authentication information is obtained
+from an "auth ticket" cookie value, assumed to be set by a custom
+login form.
+
+An example of its usage, with all attributes fully expanded:
+
+.. 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"
+ path="/"
+ http_only="false"
+ />
+
+See :ref:`authtktauthenticationpolicy_directive` for details about
+this 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.
+
+An example of its usage, with all attributes fully expanded:
+
+.. code-block:: xml
+ :linenos:
+
+ <remoteuserauthenticationpolicy
+ environ_key="REMOTE_USER"
+ callback=".somemodule.somefunc"
+ />
+
+See :ref:`remoteuserauthenticationpolicy_directive` for detailed
+information.
+
+``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.
+
+An example of its usage, with all attributes fully expanded:
+
+.. code-block:: xml
+ :linenos:
+
+ <repozewho1authenticationpolicy
+ identifier_name="auth_tkt"
+ callback=".somemodule.somefunc"
+ />
+
+See :ref:`repozewho1authenticationpolicy_directive` for detailed
+information.
+
+.. index::
+ pair: ZCML directive; authorization policy
+
+.. _authorization_policies_directives_section:
+
+Built-In Authorization Policy ZCML Directives
+---------------------------------------------
+
+``aclauthorizationpolicy``
+
+When this directive is used, authorization information is obtained
+from :term:`ACL` objects attached to resources.
+
+An example of its usage, with all attributes fully expanded:
+
+.. code-block:: xml
+ :linenos:
+
+ <aclauthorizationpolicy/>
+
+In other words, it has no configuration attributes; its existence in a
+``configure.zcml`` file enables it.
+
+See :ref:`aclauthorizationpolicy_directive` for detailed information.
+
+.. _zcml_adding_and_overriding_renderers:
+
+Adding and Changing Renderers via ZCML
+--------------------------------------
+
+New templating systems and serializers can be associated with Pyramid
+renderer names. To this end, configuration declarations can be made which
+change an existing :term:`renderer factory` and which add a new renderer
+factory.
+
+Adding or changing an existing renderer via ZCML is accomplished via the
+:ref:`renderer_directive` ZCML directive.
+
+For example, to add a renderer which renders views which have a
+``renderer`` attribute that is a path that ends in ``.jinja2``:
+
+.. code-block:: xml
+ :linenos:
+
+ <renderer
+ name=".jinja2"
+ factory="my.package.MyJinja2Renderer"
+ />
+
+The ``factory`` attribute is a :term:`dotted Python name` that must
+point to an implementation of a :term:`renderer factory`.
+
+The ``name`` attribute is the renderer name.
+
+Registering a Renderer Factory
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+See :ref:`adding_a_renderer` for more information for the definition of a
+:term:`renderer factory`. Here's an example of the registration of a simple
+:term:`renderer factory` via ZCML:
+
+.. code-block:: xml
+ :linenos:
+
+ <renderer
+ name="amf"
+ factory="my.package.MyAMFRenderer"
+ />
+
+Adding the above ZCML to your application will allow you to use the
+``my.package.MyAMFRenderer`` renderer factory implementation in view
+configurations by subseqently referring to it as ``amf`` in the ``renderer``
+attribute of a :term:`view configuration`:
+
+.. code-block:: xml
+ :linenos:
+
+ <view
+ view="mypackage.views.my_view"
+ renderer="amf"
+ />
+
+Here's an example of the registration of a more complicated renderer
+factory, which expects to be passed a filesystem path:
+
+.. code-block:: xml
+ :linenos:
+
+ <renderer
+ name=".jinja2"
+ factory="my.package.MyJinja2Renderer"
+ />
+
+Adding the above ZCML to your application will allow you to use the
+``my.package.MyJinja2Renderer`` renderer factory implementation in
+view configurations by referring to any ``renderer`` which *ends in*
+``.jinja`` in the ``renderer`` attribute of a :term:`view
+configuration`:
+
+.. code-block:: xml
+ :linenos:
+
+ <view
+ view="mypackage.views.my_view"
+ renderer="templates/mytemplate.jinja2"
+ />
+
+When a :term:`view configuration` which has a ``name`` attribute that does
+contain a dot, such as ``templates/mytemplate.jinja2`` above is encountered at
+startup time, the value of the name attribute is split on its final dot. The
+second element of the split is typically the filename extension. This
+extension is used to look up a renderer factory for the configured view. Then
+the value of ``renderer`` is passed to the factory to create a renderer for the
+view. In this case, the view configuration will create an instance of a
+``Jinja2Renderer`` for each view configuration which includes anything ending
+with ``.jinja2`` as its ``renderer`` value. The ``name`` passed to the
+``Jinja2Renderer`` constructor will be whatever the user passed as
+``renderer=`` to the view configuration.
+
+See also :ref:`renderer_directive` and
+:meth:`pyramid.config.Configurator.add_renderer`.
+
+Changing an Existing Renderer
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can associate more than one filename extension with the same
+existing renderer implementation as necessary if you need to use a
+different file extension for the same kinds of templates. For
+example, to associate the ``.zpt`` extension with the Chameleon ZPT
+renderer factory, use:
+
+.. code-block:: xml
+ :linenos:
+
+ <renderer
+ name=".zpt"
+ factory="pyramid.chameleon_zpt.renderer_factory"
+ />
+
+After you do this, Pyramid will treat templates ending in
+both the ``.pt`` and ``.zpt`` filename extensions as Chameleon ZPT
+templates.
+
+To change the default mapping in which files with a ``.pt``
+extension are rendered via a Chameleon ZPT page template renderer, use
+a variation on the following in your application's ZCML:
+
+.. code-block:: xml
+ :linenos:
+
+ <renderer
+ name=".pt"
+ factory="my.package.pt_renderer"
+ />
+
+After you do this, the :term:`renderer factory` in
+``my.package.pt_renderer`` will be used to render templates which end
+in ``.pt``, replacing the default Chameleon ZPT renderer.
+
+To ochange the default mapping in which files with a ``.txt``
+extension are rendered via a Chameleon text template renderer, use a
+variation on the following in your application's ZCML:
+
+.. code-block:: xml
+ :linenos:
+
+ <renderer
+ name=".txt"
+ factory="my.package.text_renderer"
+ />
+
+After you do this, the :term:`renderer factory` in
+``my.package.text_renderer`` will be used to render templates which
+end in ``.txt``, replacing the default Chameleon text renderer.
+
+To associate a *default* renderer with *all* view configurations (even
+ones which do not possess a ``renderer`` attribute), use a variation
+on the following (ie. omit the ``name`` attribute to the renderer
+tag):
+
+.. code-block:: xml
+ :linenos:
+
+ <renderer
+ factory="pyramid.renderers.json_renderer_factory"
+ />
+
+See also :ref:`renderer_directive` and
+:meth:`pyramid.config.Configurator.add_renderer`.
+
+.. _zcml_adding_a_translation_directory:
+
+Adding a Translation Directory via ZCML
+---------------------------------------
+
+You can add a translation directory via ZCML by using the
+:ref:`translationdir_directive` ZCML directive:
+
+.. code-block:: xml
+ :linenos:
+
+ <translationdir dir="my.application:locale/"/>
+
+A message catalog in a translation directory added via
+:ref:`translationdir_directive` 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`.
+
+See also :ref:`translationdir_directive` and
+:ref:`adding_a_translation_directory`.
+
+.. _zcml_adding_a_locale_negotiator:
+
+Adding a Custom Locale Negotiator via ZCML
+------------------------------------------
+
+You can add a custom locale negotiator via ZCML by using the
+:ref:`localenegotiator_directive` ZCML directive:
+
+.. code-block:: xml
+ :linenos:
+
+ <localenegotiator
+ negotiator="my_application.my_module.my_locale_negotiator"
+ />
+
+See also :ref:`custom_locale_negotiator` and
+:ref:`localenegotiator_directive`.
+
+.. index::
+ pair: subscriber; ZCML directive
+
+.. _zcml_event_listener:
+
+Configuring an Event Listener via ZCML
+--------------------------------------
+
+You can configure an :term:`subscriber` by modifying your application's
+``configure.zcml``. Here's an example of a bit of XML you can add to the
+``configure.zcml`` file which registers the above ``mysubscriber`` function,
+which we assume lives in a ``subscribers.py`` module within your application:
+
+.. code-block:: xml
+ :linenos:
+
+ <subscriber
+ for="pyramid.events.NewRequest"
+ handler=".subscribers.mysubscriber"
+ />
+
+See also :ref:`subscriber_directive` and :ref:`events_chapter`.
+
+.. index::
+ single: not found view
+
+.. _notfound_zcml:
+
+Configuring a Not Found View via ZCML
+-------------------------------------
+
+If your application uses :term:`ZCML`, you can replace the Not Found view by
+placing something like the following ZCML in your ``configure.zcml`` file.
+
+.. code-block:: xml
+ :linenos:
+
+ <view
+ view="helloworld.views.notfound_view"
+ context="pyramid.exceptions.NotFound"
+ />
+
+Replace ``helloworld.views.notfound_view`` with the Python dotted name to the
+notfound view you want to use.
+
+See :ref:`changing_the_notfound_view` for more information.
+
+.. index::
+ single: forbidden view
+
+.. _forbidden_zcml:
+
+Configuring a Forbidden View via ZCML
+-------------------------------------
+
+If your application uses :term:`ZCML`, you can replace the Forbidden view by
+placing something like the following ZCML in your ``configure.zcml`` file.
+
+.. code-block:: xml
+ :linenos:
+
+ <view
+ view="helloworld.views.notfound_view"
+ context="pyramid.exceptions.Forbidden"
+ />
+
+Replace ``helloworld.views.forbidden_view`` with the Python dotted name to
+the forbidden view you want to use.
+
+See :ref:`changing_the_forbidden_view` for more information.
+
+.. _changing_traverser_zcml:
+
+Configuring an Alternate Traverser via ZCML
+-------------------------------------------
+
+Use an ``adapter`` stanza in your application's ``configure.zcml`` to
+change the default traverser:
+
+.. code-block:: xml
+ :linenos:
+
+ <adapter
+ factory="myapp.traversal.Traverser"
+ provides="pyramid.interfaces.ITraverser"
+ for="*"
+ />
+
+Or to register a traverser for a specific resource type:
+
+.. code-block:: xml
+ :linenos:
+
+ <adapter
+ factory="myapp.traversal.Traverser"
+ provides="pyramid.interfaces.ITraverser"
+ for="myapp.resources.MyRoot"
+ />
+
+See :ref:`changing_the_traverser` for more information.
+
+.. index::
+ single: url generator
+
+.. _changing_resource_url_zcml:
+
+Changing ``resource_url`` URL Generation via ZCML
+-------------------------------------------------
+
+You can change how :func:`pyramid.url.resource_url` generates a URL for a
+specific type of resource by adding an adapter statement to your
+``configure.zcml``.
+
+.. code-block:: xml
+ :linenos:
+
+ <adapter
+ factory="myapp.traversal.URLGenerator"
+ provides="pyramid.interfaces.IContextURL"
+ for="myapp.resources.MyRoot *"
+ />
+
+See :ref:`changing_resource_url` for more information.
+
+.. _changing_request_factory_zcml:
+
+Changing the Request Factory via ZCML
+-------------------------------------
+
+A ``MyRequest`` class can be registered via ZCML as a request factory through
+the use of the ZCML ``utility`` directive. In the below, we assume it lives
+in a package named ``mypackage.mymodule``.
+
+.. code-block:: xml
+ :linenos:
+
+ <utility
+ component="mypackage.mymodule.MyRequest"
+ provides="pyramid.interfaces.IRequestFactory"
+ />
+
+See :ref:`changing_the_request_factory` for more information.
+
+.. _adding_renderer_globals_zcml:
+
+Changing the Renderer Globals Factory via ZCML
+----------------------------------------------
+
+A renderer globals factory can be registered via ZCML as a through the use of
+the ZCML ``utility`` directive. In the below, we assume a
+``renderers_globals_factory`` function lives in a package named
+``mypackage.mymodule``.
+
+.. code-block:: xml
+ :linenos:
+
+ <utility
+ component="mypackage.mymodule.renderer_globals_factory"
+ provides="pyramid.interfaces.IRendererGlobalsFactory"
+ />
+
+See :ref:`adding_renderer_globals` for more information.
+
View
87 pyramid_zcml/__init__.py
@@ -2,6 +2,9 @@
import sys
import threading
+from paste.script.templates import Template
+from paste.util.template import paste_script_template_renderer
+
from zope.configuration.fields import GlobalInterface
from zope.configuration.fields import GlobalObject
from zope.configuration.fields import Tokens
@@ -765,7 +768,7 @@ def zcml_configure(name, package):
"""
registry = get_current_registry()
configurator = Configurator(registry=registry, package=package)
- configurator.add_directive('load_zcml', load_zcml)
+ configurator.include(includeme)
configurator.load_zcml(name)
actions = configurator._ctx.actions[:]
configurator.commit()
@@ -821,8 +824,84 @@ def load_zcml(self, spec='configure.zcml', lock=threading.Lock()):
finally:
lock.release()
self.manager.pop()
- return registry
+
+ return registry
+
+# note that ``options`` is a b/w compat alias for ``settings`` and
+# ``Configurator`` is a testing dep inj
+# XXX remove?
+def make_app(root_factory, package=None, filename='configure.zcml',
+ settings=None, options=None, Configurator=Configurator):
+ """ Return a Router object, representing a fully configured
+ Pyramid WSGI application.
+
+ .. warning:: Use of this function is deprecated as of
+ Pyramid 1.0. You should instead use a
+ :class:`pyramid.config.Configurator` instance to
+ perform startup configuration as shown in
+ :ref:`configuration_narr`.
+
+ ``root_factory`` must be a callable that accepts a :term:`request`
+ object and which returns a traversal root object. The traversal
+ root returned by the root factory is the *default* traversal root;
+ it can be overridden on a per-view basis. ``root_factory`` may be
+ ``None``, in which case a 'default default' traversal root is
+ used.
+
+ ``package`` is a Python :term:`package` or module representing the
+ application's package. It is optional, defaulting to ``None``.
+ ``package`` may be ``None``. If ``package`` is ``None``, the
+ ``filename`` passed or the value in the ``options`` dictionary
+ named ``configure_zcml`` must be a) absolute pathname to a
+ :term:`ZCML` file that represents the application's configuration
+ *or* b) a :term:`asset specification` to a :term:`ZCML` file in
+ the form ``dotted.package.name:relative/file/path.zcml``.
+
+ ``filename`` is the filesystem path to a ZCML file (optionally
+ relative to the package path) that should be parsed to create the
+ application registry. It defaults to ``configure.zcml``. It can
+ also be a ;term:`asset specification` in the form
+ ``dotted_package_name:relative/file/path.zcml``. Note that if any
+ value for ``configure_zcml`` is passed within the ``settings``
+ dictionary, the value passed as ``filename`` will be ignored,
+ replaced with the ``configure_zcml`` value.
+
+ ``settings``, if used, should be a dictionary containing runtime
+ settings (e.g. the key/value pairs in an app section of a
+ PasteDeploy file), with each key representing the option and the
+ key's value representing the specific option value,
+ e.g. ``{'reload_templates':True}``. Note that the keyword
+ parameter ``options`` is a backwards compatibility alias for the
+ ``settings`` keyword parameter.
+ """
+ settings = settings or options or {}
+ zcml_file = settings.get('configure_zcml', filename)
+ config = Configurator(package=package, settings=settings,
+ root_factory=root_factory, autocommit=True)
+ config.include(includeme)
+ config.hook_zca()
+ config.begin()
+ config.load_zcml(zcml_file)
+ config.end()
+ return config.make_wsgi_app()
+
+# paster template helper
+
+class PyramidTemplate(Template):
+ def pre(self, command, output_dir, vars): # pragma: no cover
+ vars['random_string'] = os.urandom(20).encode('hex')
+ return Template.pre(self, command, output_dir, vars)
+
+class StarterZCMLProjectTemplate(PyramidTemplate):
+ _template_dir = 'paster_templates/starter_zcml'
+ summary = 'pyramid starter project (using ZCML)'
+ template_renderer = staticmethod(paste_script_template_renderer)
+
+# includeme function for config.include'ability
def includeme(config):
- config.add_directive('load_zcml', load_zcml)
-
+ """ Function meant to be included via
+ :meth:`pyramid.config.Configurator.include`, which sets up the
+ Configurator with a ``load_zcml`` method."""
+ config.add_directive('load_zcml', load_zcml, action_wrap=False)
+
View
11 pyramid_zcml/paster_templates/starter_zcml/+package+/__init__.py_tmpl
@@ -0,0 +1,11 @@
+from pyramid.config import Configurator
+from {{package}}.resources import Root
+
+def main(global_config, **settings):
+ """ This function returns a Pyramid WSGI application.
+ """
+ zcml_file = settings.get('configure_zcml', 'configure.zcml')
+ config = Configurator(root_factory=Root, settings=settings)
+ config.load_zcml(zcml_file)
+ return config.make_wsgi_app()
+
View
17 pyramid_zcml/paster_templates/starter_zcml/+package+/configure.zcml
@@ -0,0 +1,17 @@
+<configure xmlns="http://pylonshq.com/pyramid">
+
+ <!-- this must be included for the view declarations to work -->
+ <include package="pyramid.includes" />
+
+ <view
+ context=".resources.Root"
+ view=".views.my_view"
+ renderer="templates/mytemplate.pt"
+ />
+
+ <static
+ name="static"
+ path="static"
+ />
+
+</configure>
View
3  pyramid_zcml/paster_templates/starter_zcml/+package+/resources.py
@@ -0,0 +1,3 @@
+class Root(object):
+ def __init__(self, request):
+ self.request = request
View
BIN  pyramid_zcml/paster_templates/starter_zcml/+package+/static/favicon.ico
Binary file not shown
View
BIN  pyramid_zcml/paster_templates/starter_zcml/+package+/static/footerbg.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
View
BIN  pyramid_zcml/paster_templates/starter_zcml/+package+/static/headerbg.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
View
8 pyramid_zcml/paster_templates/starter_zcml/+package+/static/ie6.css
@@ -0,0 +1,8 @@
+* html img,
+* html .png{position:relative;behavior:expression((this.runtimeStyle.behavior="none")&&(this.pngSet?this.pngSet=true:(this.nodeName == "IMG" && this.src.toLowerCase().indexOf('.png')>-1?(this.runtimeStyle.backgroundImage = "none",
+this.runtimeStyle.filter = "progid:DXImageTransform.Microsoft.AlphaImageLoader(src='" + this.src + "',sizingMethod='image')",
+this.src = "static/transparent.gif"):(this.origBg = this.origBg? this.origBg :this.currentStyle.backgroundImage.toString().replace('url("','').replace('")',''),
+this.runtimeStyle.filter = "progid:DXImageTransform.Microsoft.AlphaImageLoader(src='" + this.origBg + "',sizingMethod='crop')",
+this.runtimeStyle.backgroundImage = "none")),this.pngSet=true)
+);}
+#wrap{display:table;height:100%}
View
BIN  pyramid_zcml/paster_templates/starter_zcml/+package+/static/middlebg.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
View
65 pyramid_zcml/paster_templates/starter_zcml/+package+/static/pylons.css
@@ -0,0 +1,65 @@
+html,body,div,span,applet,object,iframe,h1,h2,h3,h4,h5,h6,p,blockquote,pre,a,abbr,acronym,address,big,cite,code,del,dfn,em,font,img,ins,kbd,q,s,samp,small,strike,strong,sub,sup,tt,var,b,u,i,center,dl,dt,dd,ol,ul,li,fieldset,form,label,legend,table,caption,tbody,tfoot,thead,tr,th,td{margin:0;padding:0;border:0;outline:0;font-size:100%;/* 16px */
+vertical-align:baseline;background:transparent;}
+body{line-height:1;}
+ol,ul{list-style:none;}
+blockquote,q{quotes:none;}
+blockquote:before,blockquote:after,q:before,q:after{content:'';content:none;}
+:focus{outline:0;}
+ins{text-decoration:none;}
+del{text-decoration:line-through;}
+table{border-collapse:collapse;border-spacing:0;}
+sub{vertical-align:sub;font-size:smaller;line-height:normal;}
+sup{vertical-align:super;font-size:smaller;line-height:normal;}
+ul,menu,dir{display:block;list-style-type:disc;margin:1em 0;padding-left:40px;}
+ol{display:block;list-style-type:decimal-leading-zero;margin:1em 0;padding-left:40px;}
+li{display:list-item;}
+ul ul,ul ol,ul dir,ul menu,ul dl,ol ul,ol ol,ol dir,ol menu,ol dl,dir ul,dir ol,dir dir,dir menu,dir dl,menu ul,menu ol,menu dir,menu menu,menu dl,dl ul,dl ol,dl dir,dl menu,dl dl{margin-top:0;margin-bottom:0;}
+ol ul,ul ul,menu ul,dir ul,ol menu,ul menu,menu menu,dir menu,ol dir,ul dir,menu dir,dir dir{list-style-type:circle;}
+ol ol ul,ol ul ul,ol menu ul,ol dir ul,ol ol menu,ol ul menu,ol menu menu,ol dir menu,ol ol dir,ol ul dir,ol menu dir,ol dir dir,ul ol ul,ul ul ul,ul menu ul,ul dir ul,ul ol menu,ul ul menu,ul menu menu,ul dir menu,ul ol dir,ul ul dir,ul menu dir,ul dir dir,menu ol ul,menu ul ul,menu menu ul,menu dir ul,menu ol menu,menu ul menu,menu menu menu,menu dir menu,menu ol dir,menu ul dir,menu menu dir,menu dir dir,dir ol ul,dir ul ul,dir menu ul,dir dir ul,dir ol menu,dir ul menu,dir menu menu,dir dir menu,dir ol dir,dir ul dir,dir menu dir,dir dir dir{list-style-type:square;}
+.hidden{display:none;}
+p{line-height:1.5em;}
+h1{font-size:1.75em;line-height:1.7em;font-family:helvetica,verdana;}
+h2{font-size:1.5em;line-height:1.7em;font-family:helvetica,verdana;}
+h3{font-size:1.25em;line-height:1.7em;font-family:helvetica,verdana;}
+h4{font-size:1em;line-height:1.7em;font-family:helvetica,verdana;}
+html,body{width:100%;height:100%;}
+body{margin:0;padding:0;background-color:#ffffff;position:relative;font:16px/24px "Nobile","Lucida Grande",Lucida,Verdana,sans-serif;}
+a{color:#1b61d6;text-decoration:none;}
+a:hover{color:#e88f00;text-decoration:underline;}
+body h1,
+body h2,
+body h3,
+body h4,
+body h5,
+body h6{font-family:"Neuton","Lucida Grande",Lucida,Verdana,sans-serif;font-weight:normal;color:#373839;font-style:normal;}
+#wrap{min-height:100%;}
+#header,#footer{width:100%;color:#ffffff;height:40px;position:absolute;text-align:center;line-height:40px;overflow:hidden;font-size:12px;vertical-align:middle;}
+#header{background:#000000;top:0;font-size:14px;}
+#footer{bottom:0;background:#000000 url(footerbg.png) repeat-x 0 top;position:relative;margin-top:-40px;clear:both;}
+.header,.footer{width:750px;margin-right:auto;margin-left:auto;}
+.wrapper{width:100%}
+#top,#top-small,#bottom{width:100%;}
+#top{color:#000000;height:230px;background:#ffffff url(headerbg.png) repeat-x 0 top;position:relative;}
+#top-small{color:#000000;height:60px;background:#ffffff url(headerbg.png) repeat-x 0 top;position:relative;}
+#bottom{color:#222;background-color:#ffffff;}
+.top,.top-small,.middle,.bottom{width:750px;margin-right:auto;margin-left:auto;}
+.top{padding-top:40px;}
+.top-small{padding-top:10px;}
+#middle{width:100%;height:100px;background:url(middlebg.png) repeat-x;border-top:2px solid #ffffff;border-bottom:2px solid #b2b2b2;}
+.app-welcome{margin-top:25px;}
+.app-name{color:#000000;font-weight:bold;}
+.bottom{padding-top:50px;}
+#left{width:350px;float:left;padding-right:25px;}
+#right{width:350px;float:right;padding-left:25px;}
+.align-left{text-align:left;}
+.align-right{text-align:right;}
+.align-center{text-align:center;}
+ul.links{margin:0;padding:0;}
+ul.links li{list-style-type:none;font-size:14px;}
+form{border-style:none;}
+fieldset{border-style:none;}
+input{color:#222;border:1px solid #ccc;font-family:sans-serif;font-size:12px;line-height:16px;}
+input[type=text],input[type=password]{width:205px;}
+input[type=submit]{background-color:#ddd;font-weight:bold;}
+/*Opera Fix*/
+body:before{content:"";height:100%;float:left;width:0;margin-top:-32767px;}
View
BIN  pyramid_zcml/paster_templates/starter_zcml/+package+/static/pyramid-small.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
View
BIN  pyramid_zcml/paster_templates/starter_zcml/+package+/static/pyramid.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
View
BIN  pyramid_zcml/paster_templates/starter_zcml/+package+/static/transparent.gif
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
View
75 pyramid_zcml/paster_templates/starter_zcml/+package+/templates/mytemplate.pt_tmpl
@@ -0,0 +1,75 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" xmlns:tal="http://xml.zope.org/namespaces/tal">
+<head>
+ <title>The Pyramid Web Application Development Framework</title>
+ <meta http-equiv="Content-Type" content="text/html;charset=UTF-8"/>
+ <meta name="keywords" content="python web application" />
+ <meta name="description" content="pyramid web application" />
+ <link rel="shortcut icon" href="${request.static_url('{{package}}:static/favicon.ico')}" />
+ <link rel="stylesheet" href="${request.static_url('{{package}}:static/pylons.css')}" type="text/css" media="screen" charset="utf-8" />
+ <link rel="stylesheet" href="http://fonts.googleapis.com/css?family=Neuton|Nobile:regular,i,b,bi&amp;subset=latin" type="text/css" media="screen" charset="utf-8" />
+ <!--[if lte IE 6]>
+ <link rel="stylesheet" href="${request.static_url('{{package}}:static/ie6.css')}" type="text/css" media="screen" charset="utf-8" />
+ <![endif]-->
+</head>
+<body>
+ <div id="wrap">
+ <div id="top">
+ <div class="top align-center">
+ <div><img src="${request.static_url('{{package}}:static/pyramid.png')}" width="750" height="169" alt="pyramid"/></div>
+ </div>
+ </div>
+ <div id="middle">
+ <div class="middle align-center">
+ <p class="app-welcome">
+ Welcome to <span class="app-name">${project}</span>, an application generated by<br/>
+ the Pyramid web application development framework.
+ </p>
+ </div>
+ </div>
+ <div id="bottom">
+ <div class="bottom">
+ <div id="left" class="align-right">
+ <h2>Search documentation</h2>
+ <form method="get" action="http://docs.pylonsproject.org/projects/pyramid/dev/search.html">
+ <input type="text" id="q" name="q" value="" />
+ <input type="submit" id="x" value="Go" />
+ </form>
+ </div>
+ <div id="right" class="align-left">
+ <h2>Pyramid links</h2>
+ <ul class="links">
+ <li>
+ <a href="http://pylonsproject.org">Pylons Website</a>
+ </li>
+ <li>
+ <a href="http://docs.pylonsproject.org/projects/pyramid/dev/#narrative-documentation">Narrative Documentation</a>
+ </li>
+ <li>
+ <a href="http://docs.pylonsproject.org/projects/pyramid/dev/#api-documentation">API Documentation</a>
+ </li>
+ <li>
+ <a href="http://docs.pylonsproject.org/projects/pyramid/dev/#tutorials">Tutorials</a>
+ </li>
+ <li>
+ <a href="http://docs.pylonsproject.org/projects/pyramid/dev/#change-history">Change History</a>
+ </li>
+ <li>
+ <a href="http://docs.pylonsproject.org/projects/pyramid/dev/#sample-applications">Sample Applications</a>
+ </li>
+ <li>
+ <a href="http://docs.pylonsproject.org/projects/pyramid/dev/#support-and-development">Support and Development</a>
+ </li>
+ <li>
+ <a href="irc://irc.freenode.net#pyramid">IRC Channel</a>
+ </li>
+ </ul>
+ </div>
+ </div>
+ </div>
+ </div>
+ <div id="footer">
+ <div class="footer">© Copyright 2008-2011, Agendaless Consulting.</div>
+ </div>
+</body>
+</html>
View
18 pyramid_zcml/paster_templates/starter_zcml/+package+/tests.py_tmpl
@@ -0,0 +1,18 @@
+import unittest
+
+from pyramid import testing
+
+class ViewTests(unittest.TestCase):
+ def setUp(self):
+ self.config = testing.setUp()
+
+ def tearDown(self):
+ testing.tearDown()
+
+ def test_my_view(self):
+ from {{package}}.views import my_view
+ request = testing.DummyRequest()
+ info = my_view(request)
+ self.assertEqual(info['project'], '{{project}}')
+
+
View
2  pyramid_zcml/paster_templates/starter_zcml/+package+/views.py_tmpl
@@ -0,0 +1,2 @@
+def my_view(request):
+ return {'project':'{{project}}'}
View
4 pyramid_zcml/paster_templates/starter_zcml/CHANGES.txt_tmpl
@@ -0,0 +1,4 @@
+0.0
+---
+
+- Initial version
View
4 pyramid_zcml/paster_templates/starter_zcml/README.txt_tmpl
@@ -0,0 +1,4 @@
+{{project}} README
+
+
+
View
44 pyramid_zcml/paster_templates/starter_zcml/development.ini_tmpl
@@ -0,0 +1,44 @@
+[app:{{project}}]
+use = egg:{{project}}
+reload_templates = true
+debug_authorization = false
+debug_notfound = false
+debug_routematch = false
+debug_templates = true
+default_locale_name = en
+
+[pipeline:main]
+pipeline =
+ egg:WebError#evalerror
+ {{project}}
+
+[server:main]
+use = egg:Paste#http
+host = 0.0.0.0
+port = 6543
+
+# Begin logging configuration
+
+[loggers]
+keys = root
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = INFO
+handlers = console
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(asctime)s %(levelname)-5.5s [%(name)s][%(threadName)s] %(message)s
+
+# End logging configuration
View
27 pyramid_zcml/paster_templates/starter_zcml/setup.cfg_tmpl
@@ -0,0 +1,27 @@
+[nosetests]
+match=^test
+nocapture=1
+cover-package={{package}}
+with-coverage=1
+cover-erase=1
+
+[compile_catalog]
+directory = {{package}}/locale
+domain = {{project}}
+statistics = true
+
+[extract_messages]
+add_comments = TRANSLATORS:
+output_file = {{package}}/locale/{{project}}.pot
+width = 80
+
+[init_catalog]
+domain = {{project}}
+input_file = {{package}}/locale/{{project}}.pot
+output_dir = {{package}}/locale
+
+[update_catalog]
+domain = {{project}}
+input_file = {{package}}/locale/{{project}}.pot
+output_dir = {{package}}/locale
+previous = true
View
37 pyramid_zcml/paster_templates/starter_zcml/setup.py_tmpl
@@ -0,0 +1,37 @@
+import os
+
+from setuptools import setup, find_packages
+
+here = os.path.abspath(os.path.dirname(__file__))
+README = open(os.path.join(here, 'README.txt')).read()
+CHANGES = open(os.path.join(here, 'CHANGES.txt')).read()
+
+requires = ['pyramid', 'WebError']
+
+setup(name='{{project}}',
+ version='0.0',
+ description='{{project}}',
+ long_description=README + '\n\n' + CHANGES,
+ classifiers=[
+ "Programming Language :: Python",
+ "Framework :: Pylons",
+ "Topic :: Internet :: WWW/HTTP",
+ "Topic :: Internet :: WWW/HTTP :: WSGI :: Application",
+ ],
+ author='',
+ author_email='',
+ url='',
+ keywords='web pyramid pylons',
+ packages=find_packages(),
+ include_package_data=True,
+ zip_safe=False,
+ install_requires=requires,
+ tests_require=requires,
+ test_suite="{{package}}",
+ entry_points = """\
+ [paste.app_factory]
+ main = {{package}}:main
+ """,
+ paster_plugins=['pyramid'],
+ )
+
View
87 pyramid_zcml/tests/tests.py
@@ -1166,8 +1166,8 @@ def tearDown(self):
def test_it(self):
from zope.configuration import xmlconfig
- import pyramid.includes
- xmlconfig.file('configure.zcml', package=pyramid.includes)
+ import pyramid_zcml
+ xmlconfig.file('configure.zcml', package=pyramid_zcml)
class TestRolledUpFactory(unittest.TestCase):
def _callFUT(self, *factories):
@@ -1234,7 +1234,7 @@ def _makeOne(self, autocommit=False, package=None):
from pyramid_zcml import load_zcml
from pyramid.config import Configurator
c = Configurator(autocommit=autocommit, package=package)
- c.add_directive('load_zcml', load_zcml)
+ c.add_directive('load_zcml', load_zcml, action_wrap=False)
return c
def test_load_zcml_default(self):
@@ -1292,7 +1292,7 @@ def test_it(self):
from pyramid_zcml import includeme
c = Configurator(autocommit=True)
c.include(includeme)
- self.failUnless(c.load_zcml.im_func.__docobj__ is load_zcml)
+ self.failUnless(c.load_zcml.im_func is load_zcml)
class IDummy(Interface):
pass
@@ -1323,6 +1323,56 @@ def action(self, discriminator, callable=None, args=(), kw={}, order=0):
def path(self, path):
return path
+class TestMakeApp(unittest.TestCase):
+ def setUp(self):
+ from zope.deprecation import __show__
+ __show__.off()
+ testing.setUp()
+
+ def tearDown(self):
+ from zope.deprecation import __show__
+ __show__.on()
+ testing.tearDown()
+
+ def _callFUT(self, *arg, **kw):
+ from pyramid_zcml import make_app
+ return make_app(*arg, **kw)
+
+ def test_it(self):
+ from pyramid_zcml import includeme
+ settings = {'a':1}
+ rootfactory = object()
+ app = self._callFUT(rootfactory, settings=settings,
+ Configurator=DummyConfigurator)
+ self.assertEqual(app.root_factory, rootfactory)
+ self.assertEqual(app.settings, settings)
+ self.assertEqual(app.zcml_file, 'configure.zcml')
+ self.assertEqual(app.zca_hooked, True)
+ self.assertEqual(app.included, [includeme])
+
+ def test_it_options_means_settings(self):
+ settings = {'a':1}
+ rootfactory = object()
+ app = self._callFUT(rootfactory, options=settings,
+ Configurator=DummyConfigurator)
+ self.assertEqual(app.root_factory, rootfactory)
+ self.assertEqual(app.settings, settings)
+ self.assertEqual(app.zcml_file, 'configure.zcml')
+
+ def test_it_with_package(self):
+ package = object()
+ rootfactory = object()
+ app = self._callFUT(rootfactory, package=package,
+ Configurator=DummyConfigurator)
+ self.assertEqual(app.package, package)
+
+ def test_it_with_custom_configure_zcml(self):
+ rootfactory = object()
+ settings = {'configure_zcml':'2.zcml'}
+ app = self._callFUT(rootfactory, filename='1.zcml', settings=settings,
+ Configurator=DummyConfigurator)
+ self.assertEqual(app.zcml_file, '2.zcml')
+
class Dummy:
pass
@@ -1370,3 +1420,32 @@ def acquire(self):
def release(self):
self.released = True
+class DummyConfigurator(object):
+ def __init__(self, registry=None, package=None, root_factory=None,
+ settings=None, autocommit=True):
+ self.root_factory = root_factory
+ self.package = package
+ self.settings = settings
+ self.autocommit = autocommit
+ self.included = []
+
+ def begin(self, request=None):
+ self.begun = True
+ self.request = request
+
+ def end(self):
+ self.ended = True
+
+ def include(self, func):
+ self.included.append(func)
+
+ def load_zcml(self, filename):
+ self.zcml_file = filename
+
+ def make_wsgi_app(self):
+ return self
+
+ def hook_zca(self):
+ self.zca_hooked = True
+
+
View
6 setup.py
@@ -1,6 +1,6 @@
##############################################################################
#
-# Copyright (c) 2008-2010 Agendaless Consulting and Contributors.
+# Copyright (c) 2008-2011 Agendaless Consulting and Contributors.
# All Rights Reserved.
#
# This software is subject to the provisions of the BSD-like license at
@@ -27,7 +27,7 @@
README = CHANGES = ''
install_requires=[
- 'pyramid',
+ 'pyramid', 'PasteScript',
]
if platform.system() == 'Java':
@@ -60,6 +60,8 @@
tests_require = tests_require,
test_suite="pyramid_zcml",
entry_points = """
+ [paste.paster_create_template]
+ pyramid_starter_zcml=pyramid_zcml:StarterZCMLProjectTemplate
"""
)
Please sign in to comment.
Something went wrong with that request. Please try again.