diff options
| -rw-r--r-- | docs/glossary.rst | 7 | ||||
| -rw-r--r-- | docs/narr/events.rst | 14 | ||||
| -rw-r--r-- | docs/narr/extending.rst | 5 | ||||
| -rw-r--r-- | docs/narr/hooks.rst | 6 | ||||
| -rw-r--r-- | docs/narr/hybrid.rst | 13 | ||||
| -rw-r--r-- | docs/narr/install.rst | 35 | ||||
| -rw-r--r-- | docs/narr/introduction.rst | 73 | ||||
| -rw-r--r-- | docs/narr/models.rst | 97 | ||||
| -rw-r--r-- | docs/narr/project.rst | 18 | ||||
| -rw-r--r-- | docs/narr/startup.rst | 6 | ||||
| -rw-r--r-- | docs/narr/templates.rst | 5 | ||||
| -rw-r--r-- | docs/narr/views.rst | 49 |
12 files changed, 175 insertions, 153 deletions
diff --git a/docs/glossary.rst b/docs/glossary.rst index e7b33b0c4..ca7aa539c 100644 --- a/docs/glossary.rst +++ b/docs/glossary.rst @@ -15,6 +15,13 @@ Glossary upstream), and status (representing the http status string). This is the interface defined for ``WebOb`` response objects. See :ref:`webob_chapter` for information about response objects. + Repoze + "Repoze" is essentially a "brand" of software developed by + `Agendaless Consulting <http://agendaless.com>`_ and a set of + contributors. The term has no special intrinsic meaning. The + project's `website <http://repoze.org>`_ has more information. + The software developed "under the brand" is available in a + `Subversion repository <http://svn.repoze.org>`_. Setuptools `Setuptools <http://peak.telecommunity.com/DevCenter/setuptools>`_ builds on Python's ``distutils`` to provide easier building, diff --git a/docs/narr/events.rst b/docs/narr/events.rst index 544c80744..028bacaa8 100644 --- a/docs/narr/events.rst +++ b/docs/narr/events.rst @@ -82,6 +82,14 @@ within the :term:`application registry` . Under this configuration, when the application is run, each time a new request or response is detected, a message will be printed to the console. +.. sidebar:: The ``INewResponse`` Event vs. Middleware + + Postprocessing a response is usually better handled in a WSGI + :term:`middleware` component than in subscriber code that is called + by an ``INewResponse`` event. The :mod:`repoze.bfg` + ``INewResponse`` event exists almost purely for symmetry with the + ``INewRequest`` event. + We know that ``INewRequest`` events have a ``request`` attribute, which is a :term:`WebOb` request, because the interface defined at ``repoze.bfg.interfaces.INewRequest`` says it must. Likewise, we know @@ -91,12 +99,6 @@ defined at ``repoze.bfg.interfaces.INewResponse`` says it must. These particular interfaces, along with others, are documented in the :ref:`events_module` API chapter. -.. note:: - - Usually postprocessing requests is better handled in middleware - components. The ``INewResponse`` event exists purely for symmetry - with ``INewRequest``, really. - The *subscriber* ZCML element takes two attributes: ``for``, and ``handler``. The value of ``for`` is the interface the subscriber is registered for. Registering a subscriber for a specific interface diff --git a/docs/narr/extending.rst b/docs/narr/extending.rst index 26520d2d0..e77f4cfbe 100644 --- a/docs/narr/extending.rst +++ b/docs/narr/extending.rst @@ -176,7 +176,10 @@ behavior will usually have the same ``for`` and ``name`` (and :term:`predicate` attributes, if used) as the original. These ``<view>`` declarations will point at "new" view code. The new view code itself will usually be cut-n-paste copies of view callables from -the original application with slight tweaks. For example:: +the original application with slight tweaks. For example: + +.. code-block:: xml + :linenos: <view for="theoriginalapplication.models.SomeModel" name="theview" diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst index 0fea7c64e..f5fc4233b 100644 --- a/docs/narr/hooks.rst +++ b/docs/narr/hooks.rst @@ -27,6 +27,7 @@ to the notfound view you want to use. Here's some sample code that implements a minimal NotFound view: .. code-block:: python + :linenos: from webob.exc import HTTPNotFound @@ -104,6 +105,7 @@ the view invocation was denied. The ``request`` is the current code that implements a minimal forbidden view: .. code-block:: python + :linenos: from repoze.bfg.chameleon_zpt import render_template_to_response @@ -345,6 +347,4 @@ The API that must be implemented by a class that provides The default context URL generator is available for perusal as the class ``TraversalContextURL`` in the `traversal module <http://svn.repoze.org/repoze.bfg/trunk/repoze/bfg/traversal.py>`_ of -the BFG subversion repository. - - +the :term:`Repoze` Subversion repository. diff --git a/docs/narr/hybrid.rst b/docs/narr/hybrid.rst index 8a83cd94e..d85e2f1af 100644 --- a/docs/narr/hybrid.rst +++ b/docs/narr/hybrid.rst @@ -23,12 +23,13 @@ factories and 3) the traversal algorithm, and the interactions between all of them. Therefore, use of this pattern is not recommended unless you *really* need to use it. -This is a advanced topic that has non-trivial corner cases; you may -need to understand more deeply how :mod:`repoze.bfg` works to -understand the concepts discussed in this chapter. To that end, it's -useful to read :ref:`router_chapter` to get a more holistic -understanding of what's happening "under the hood" to use this -feature. +.. warning:: Creating applications that use hybrid-mode features of + :mod:`repoze.bfg` is a advanced topic that exposes non-trivial + corner cases; you may need to understand more deeply how + :mod:`repoze.bfg` works to understand the concepts discussed in + this chapter. To that end, it's useful to read + :ref:`router_chapter` to get a more holistic understanding of + what's happening "under the hood" to use this feature. The Schism ---------- diff --git a/docs/narr/install.rst b/docs/narr/install.rst index 5bfdacaee..f23b3c819 100644 --- a/docs/narr/install.rst +++ b/docs/narr/install.rst @@ -13,25 +13,23 @@ done primarily under Python 2.4 and Python 2.5. :mod:`repoze.bfg` does *not* run under any version of Python before 2.4, and does *not* run under Python 3.X. -.. note:: You will need :term:`setuptools` installed - on within your Python system in order to run the ``easy_install`` - command. - -.. note:: Installation of :mod:`repoze.bfg` does not require the - compilation of any C code, so as long as you have a Python - interpreter that meets the above requirements, you do not need to - have development tools installed on the target machine to install +.. sidebar:: You Don't Need A Compiler + + Installation of :mod:`repoze.bfg` does not require the compilation + of any C code, so as long as you have a Python interpreter that + meets the requirements mentioned, you do not need to have + development tools installed on the target machine to install :mod:`repoze.bfg`. BFG is known to run properly on all popular Unix-like systems such as Linux, MacOS X, and FreeBSD. -:mod:`repoze.bfg` does run on Windows systems. However, none of its -developers use Windows as a primary development platform. Therefore, -most of the platform-specific documentation (excepting this chapter) -assumes you're using a UNIX system. If you're using a Windows system, -you'll need to transliterate command lines in the documentation to -their Windows equivalents. +:mod:`repoze.bfg` is also known to run on Windows systems. However, +none of its developers use Windows as a primary development platform. +Therefore, most of the platform-specific documentation (excepting this +chapter) assumes you're using a UNIX system. If you're using a Windows +system, you'll need to transliterate command lines in the +documentation to their Windows equivalents. :mod:`repoze.bfg` is also known to run on Google's App Engine. @@ -303,9 +301,6 @@ When you ``easy_install`` :mod:`repoze.bfg`, various Zope libraries, various Chameleon libraries, WebOb, Paste, PasteScript, and PasteDeploy libraries are installed. -Additionally, as shown in the next section, PasteScript (aka *paster*) -templates will be registered that make it easy to start a new -:mod:`repoze.bfg` project. - - - +Additionally, as shown in a following chapter, PasteScript (aka +*paster*) templates will be registered that make it easy to start a +new :mod:`repoze.bfg` project. diff --git a/docs/narr/introduction.rst b/docs/narr/introduction.rst index 7f36ee36a..0384e96bf 100644 --- a/docs/narr/introduction.rst +++ b/docs/narr/introduction.rst @@ -8,39 +8,11 @@ uses the :term:`WSGI` protocol to handle requests and responses. Similarities to Other Frameworks -------------------------------- -:mod:`repoze.bfg` was inspired by :term:`Zope`, :term:`Pylons` and -:term:`Django`. - -The :mod:`repoze.bfg` concept of :term:`traversal` is inspired by -:term:`Zope`. Additionally, :mod:`repoze.bfg` uses the :term:`Zope -Component Architecture` internally, as do Zope 2, Zope 3, and -:term:`Grok`. :mod:`repoze.bfg` application developers may use either -:term:`ZCML` (an XML dialect, used in Zope) or decorators to perform -various application configuration tasks. The decorator support is -provided by the :term:`Grok` project. Like Zope, :mod:`repoze.bfg` -allows you to create applications which do not need to be forked or -otherwise modified to be extended by a third party developer. - -The :mod:`repoze.bfg` concept of :term:`URL dispatch` is inspired by -:term:`Pylons`. Like Pylons, :mod:`repoze.bfg` is mostly policy-free. -It makes no assertions about which database you should use, and its -built-in templating facilities are only for convenience. In essence, -it only supplies a mechanism to map URLs to :term:`view` code, along -with a convention for calling those views. You are free to use -third-party components in your application that fit your needs. Also -like Pylons, :mod:`repoze.bfg` is dependent upon WSGI. - -The Django docs state that Django is *not* an "MVC" -(model/view/controller) framework in their `FAQ -<http://www.djangoproject.com/documentation/faq/>`_. -:mod:`repoze.bfg` isn't either. Django's documentation does a good -job of why explaining why they don't use "MVC" acronym: +.. sidebar:: Django's Authors Explain Why It Doesn't Use "MVC" Terminology Django appears to be a MVC framework, but you call the Controller the "view", and the View the "template". How come you don't use the - standard names? - - Well, the standard names are debatable. + standard names? Well, the standard names are debatable. In our interpretation of MVC, the "view" describes the data that gets presented to the user. It's not necessarily how the data looks, @@ -60,12 +32,41 @@ job of why explaining why they don't use "MVC" acronym: probably the framework itself: the machinery that sends a request to the appropriate view, according to the Django URL configuration. -:mod:`repoze.bfg` uses terminology similar to Django. The skeleton -code generator of :mod:`repoze.bfg` generates a directory layout very -similar to the directory layout suggested by the `Django Book -<http://www.djangobook.com/>`_ . Additionally, as suggested above, -the concepts of :term:`view`, :term:`model` and :term:`template` are -used by :mod:`repoze.bfg` as they would be by Django. +:mod:`repoze.bfg` was inspired by :term:`Zope`, :term:`Pylons` and +:term:`Django`. + +The :mod:`repoze.bfg` concept of :term:`traversal` is inspired by +:term:`Zope`. Additionally, :mod:`repoze.bfg` uses the :term:`Zope +Component Architecture` internally, as do Zope 2, Zope 3, and +:term:`Grok`. :mod:`repoze.bfg` application developers may use either +:term:`ZCML` (an XML dialect, used in Zope) or decorators to perform +various application configuration tasks. The decorator support is +provided by the :term:`Grok` project. Like Zope, :mod:`repoze.bfg` +allows you to create applications which do not need to be forked or +otherwise modified to be extended or overridden by a third party +developer. + +The :mod:`repoze.bfg` concept of :term:`URL dispatch` is inspired by +the :term:`Routes` system used by :term:`Pylons`. Like Pylons, +:mod:`repoze.bfg` is mostly policy-free. It makes no assertions about +which database you should use, and its built-in templating facilities +are only for convenience. In essence, it only supplies a mechanism to +map URLs to :term:`view` code, along with a convention for calling +those views. You are free to use third-party components in your +application that fit your needs. Also like Pylons, :mod:`repoze.bfg` +is dependent upon WSGI. + +The Django docs explain that Django is not an "MVC" +("model/view/controller") framework in their `FAQ +<http://www.djangoproject.com/documentation/faq/>`_. The sidebar to +the right has the Django authors' take on why "MVC" terminology +doesn't match the web very well. The concepts of :term:`view` and +:term:`model` are used by :mod:`repoze.bfg` as they would be by +Django. + +The skeleton code generator of :mod:`repoze.bfg` generates a directory +layout very similar to the directory layout suggested by the `Django +Book <http://www.djangobook.com/>`_ . Differences from Other Frameworks --------------------------------- diff --git a/docs/narr/models.rst b/docs/narr/models.rst index c8bea4939..535aa6ac3 100644 --- a/docs/narr/models.rst +++ b/docs/narr/models.rst @@ -160,21 +160,48 @@ works against model instances. Location-Aware Model Instances ------------------------------ +.. sidebar:: Using :mod:`repoze.bfg.traversalwrapper` + + If you'd rather not manage the ``__name__`` and ``__parent__`` + attributes of your models "by hand", an add on package named + :mod:`repoze.bfg.traversalwrapper` can help. + + In order to use this helper feature, you must first install the + :mod:`repoze.bfg.traversalwrapper` package (available via `SVN + <http://svn.repoze.org/repoze.bfg.traversalwrapper>`_), then + register its ``ModelGraphTraverser`` as the traversal policy, rather + than the default :mod:`repoze.bfg` traverser. The package contains + instructions. + + Once :mod:`repoze.bfg` is configured with this feature, you will no + longer need to manage the ``__parent__`` and ``__name__`` attributes + on graph objects "by hand". Instead, as necessary, during traversal + :mod:`repoze.bfg` will wrap each object (even the root object) in a + ``LocationProxy`` which will dynamically assign a ``__name__`` and a + ``__parent__`` to the traversed object (based on the last traversed + object and the name supplied to ``__getitem__``). The root object + will have a ``__name__`` attribute of ``None`` and a ``__parent__`` + attribute of ``None``. + Applications which use :term:`traversal` to locate the :term:`context` of a view must ensure that the model instances that make up the model -graph are "location aware". In order for :mod:`repoze.bfg` location, -security, URL-generation, and traversal functions (such as the -functions exposed in :ref:`location_module`, :ref:`traversal_module`, -and :ref:`url_module` as well as certain functions in -:ref:`security_module` ) to work properly against a instances in a -model graph, all nodes in the graph must be "location-aware". This -means they must have two attributes: ``__parent__`` and ``__name__``. +graph are "location aware". + +In order for :mod:`repoze.bfg` location, security, URL-generation, and +traversal functions (such as the functions exposed in +:ref:`location_module`, :ref:`traversal_module`, and :ref:`url_module` +as well as certain functions in :ref:`security_module` ) to work +properly against a instances in a model graph, all nodes in the graph +must be "location-aware". This means they must have two attributes: +``__parent__`` and ``__name__``. + The ``__parent__`` attribute should be a reference to the node's parent model instance in the graph. The ``__name__`` attribute should be the name that a node's parent refers to the node via -``__getitem__``. The ``__parent__`` of the root object should be -``None`` and its ``__name__`` should be the empty string. For -instance: +``__getitem__``. + +The ``__parent__`` of the root object should be ``None`` and its +``__name__`` should be the empty string. For instance: .. code-block:: python @@ -182,15 +209,6 @@ instance: __name__ = '' __parent__ = None -.. warning:: If your root model object has a ``__name__`` argument - that is not ``None`` or the empty string, URLs returned by the - ``repoze.bfg.url.model_url`` function and paths generated by the - ``repoze.bfg.traversal.model_path`` and - ``repoze.bfg.traversal.model_path_tuple`` APIs will be generated - improperly. The value of ``__name__`` will be prepended to every - path and URL generated (as opposed to a single leading slash or - empty tuple element). - A node returned from the root item's ``__getitem__`` method should have a ``__parent__`` attribute that is a reference to the root object, and its ``__name__`` attribute should match the name by which @@ -201,40 +219,15 @@ object's ``__getitem__`` should return objects that have a that matches the name by which they are retrieved via ``__getitem__``, and so on. -.. note:: - - If you'd rather not manage the ``__name__`` and ``__parent__`` - attributes of your models "by hand", an add-on package to - :mod:`repoze.bfg`` named :mod:`repoze.bfg.traversalwrapper` can help - you do this. +.. warning:: If your root model object has a ``__name__`` argument + that is not ``None`` or the empty string, URLs returned by the + ``repoze.bfg.url.model_url`` function and paths generated by the + ``repoze.bfg.traversal.model_path`` and + ``repoze.bfg.traversal.model_path_tuple`` APIs will be generated + improperly. The value of ``__name__`` will be prepended to every + path and URL generated (as opposed to a single leading slash or + empty tuple element). - In order to use this helper feature, you must first install the - :mod:`repoze.bfg.traversalwrapper` package (available from - `http://svn.repoze.org/repoze.bfg.traversalwrapper - <http://svn.repoze.org/repoze.bfg.traversalwrapper>`_), then - register its ``ModelGraphTraverser`` as the traversal policy, rather - than the default BFG ``ModelGraphTraverser``. To register the - :mod:`repoze.bfg.traversalwrapper` ``ModelGraphTraverser`` as the - traversal policy, your application will need to have the following - in its ``configure.zcml`` file: - - .. code-block:: xml - - <adapter - factory="repoze.bfg.traversalwrapper.ModelGraphTraverser" - provides="repoze.bfg.interfaces.ITraverser" - for="*" - /> - - If this statement is made in ZCML, you will no longer need to manage - the ``__parent__`` and ``__name__`` attributes on graph objects "by - hand". Instead, as necessary, during traversal :mod:`repoze.bfg` - will wrap each object (even the root object) in a ``LocationProxy`` - which will dynamically assign a ``__name__`` and a ``__parent__`` to - the traversed object (based on the last traversed object and the - name supplied to ``__getitem__``). The root object will have a - ``__name__`` attribute of ``None`` and a ``__parent__`` attribute - of ``None``. :mod:`repoze.bfg` API Functions That Act Against Models ------------------------------------------------------- diff --git a/docs/narr/project.rst b/docs/narr/project.rst index b80185979..776f6f9a8 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -254,6 +254,16 @@ Once the project is installed for development, you can run the application it represents using the ``paster serve`` command against the generated ``MyProject.ini`` configuration file: +.. sidebar:: Using ``mod_wsgi`` + + You can also use :term:`mod_wsgi` to serve your :mod:`repoze.bfg` + application using the Apache web server rather than the + "pure-Python" server that is started as a result of ``paster + serve``. See :ref:`modwsgi_tutorial` for details. However, it is + usually easier to develop an application using the ``paster serve`` + webserver, as exception and debugging output will be sent to the + console. + .. code-block:: bash :linenos: @@ -277,14 +287,6 @@ port 6543. development easier, as changes to Python code under :mod:`repoze.bfg` is not put into effect until the server restarts. -.. note:: You can also use :term:`mod_wsgi` to serve your - :mod:`repoze.bfg` application using the Apache web server rather - than the "pure-Python" server that is started as a result of - ``paster serve``. See :ref:`modwsgi_tutorial` for details. - However, it is usually easier to develop an application using the - ``paster serve`` webserver, as exception and debugging output will - be sent to the console. - Viewing the Application ----------------------- diff --git a/docs/narr/startup.rst b/docs/narr/startup.rst index d75e57029..37a7c8848 100644 --- a/docs/narr/startup.rst +++ b/docs/narr/startup.rst @@ -25,8 +25,10 @@ file to infer settings and starts a server listening on a port. For the purposes of this discussion, we'll assume that you are using this command to run your :mod:`repoze.bfg` application. -.. note:: ``paster serve`` is by no means the only way to start up and - serve a :mod:`repoze.bfg` application. Any :term:`WSGI` server is +.. sidebar:: Using :mod:`repoze.bfg` Without ``paster`` + + ``paster serve`` is by no means the only way to start up and serve + a :mod:`repoze.bfg` application. Any :term:`WSGI` server is capable of running a :mod:`repoze.bfg` application, and some WSGI servers (such as :term:`mod_wsgi`) don't require the :term:`PasteDeploy` framework's ``paster serve`` command to do diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst index e52d51c38..e7c20795e 100644 --- a/docs/narr/templates.rst +++ b/docs/narr/templates.rst @@ -215,8 +215,9 @@ engine writes a file in the same directory as the template file itself as a kind of cache, in order to do less work the next time the template needs to be read from disk. When using ``chameleon.core`` version 1.0b32 and lower, this filename is ``<template_name>.cache``. -When using ``chameleon.core`` version 1.0b33 and higher, this filename -is ``<template_name>.py``. If you see "strange" ``.py`` or ``.cache`` +When using ``chameleon.core`` version 1.0b33 and higher or the +``Chameleon`` (uppercase-C) package, this filename is +``<template_name>.py``. If you see "strange" ``.py`` or ``.cache`` files showing up in your ``templates`` directory, it is due to this feature. If you're using a version control system such as Subversion, you should cause it to ignore these files. Here's the contents of my diff --git a/docs/narr/views.rst b/docs/narr/views.rst index 4f67d9663..2e574cb14 100644 --- a/docs/narr/views.rst +++ b/docs/narr/views.rst @@ -1645,9 +1645,12 @@ configured view. Here's an example of a renderer registration in ZCML: - <renderer - name="amf" - factory="my.package.MyAMFRenderer"/> +.. 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 implementation in ``view`` @@ -1668,32 +1671,44 @@ thrown at rendering time. You can associate more than one filename extension with the same 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 page template renderer factory, use:: +Chameleon page template renderer factory, use: - <renderer - name=".zpt" - factory="repoze.bfg.chameleon_zpt.renderer_factory"/> +.. code-block:: xml + :linenos: + + <renderer + name=".zpt" + factory="repoze.bfg.chameleon_zpt.renderer_factory"/> To override 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:: +a variation on the following in your application's ZCML: - <renderer - name=".pt" - factory="my.package.pt_renderer"/> +.. code-block:: xml + :linenos: + + <renderer + name=".pt" + factory="my.package.pt_renderer"/> To override 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:: +variation on the following in your application's ZCML: - <renderer - name=".txt" - factory="my.package.text_renderer"/> +.. code-block:: xml + :linenos: + + <renderer + name=".txt" + factory="my.package.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): - <renderer - factory="repoze.bfg.renderers.json_renderer_factory"/> +.. code-block:: xml + :linenos: + + <renderer + factory="repoze.bfg.renderers.json_renderer_factory"/> |