From fec0f0614c69dc7382fba367f8269479e2682058 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Mon, 25 Oct 2010 18:47:29 -0400 Subject: convert narrative docs to Pyramid --- docs/narr/MyProject/myproject/configure.zcml | 4 +- .../MyProject/myproject/templates/mytemplate.pt | 43 +++-- docs/narr/MyProject/setup.py | 8 +- docs/narr/configuration.rst | 74 ++++---- docs/narr/contextfinding.rst | 16 +- docs/narr/environment.rst | 18 +- docs/narr/events.rst | 56 +++--- docs/narr/extending.rst | 30 ++-- docs/narr/firstapp.rst | 100 +++++------ docs/narr/hooks.rst | 145 +++++++--------- docs/narr/hybrid.rst | 30 ++-- docs/narr/i18n.rst | 180 ++++++++++---------- docs/narr/install.rst | 86 +++++----- docs/narr/introduction.rst | 87 +++++----- docs/narr/models.rst | 40 ++--- docs/narr/project.rst | 134 +++++++-------- docs/narr/resources.rst | 40 ++--- docs/narr/router.rst | 62 +++---- docs/narr/security.rst | 158 ++++++++--------- docs/narr/startup.rst | 24 +-- docs/narr/static.rst | 72 ++++---- docs/narr/templates.rst | 138 +++++++-------- docs/narr/threadlocals.rst | 72 ++++---- docs/narr/traversal.rst | 48 +++--- docs/narr/unittesting.rst | 106 ++++++------ docs/narr/urldispatch.rst | 117 ++++++------- docs/narr/vhosting.rst | 48 +++--- docs/narr/views.rst | 187 +++++++++------------ docs/narr/webob.rst | 26 +-- docs/narr/zca.rst | 76 ++++----- 30 files changed, 1067 insertions(+), 1158 deletions(-) diff --git a/docs/narr/MyProject/myproject/configure.zcml b/docs/narr/MyProject/myproject/configure.zcml index 95b7355b1..1d0b3e61c 100644 --- a/docs/narr/MyProject/myproject/configure.zcml +++ b/docs/narr/MyProject/myproject/configure.zcml @@ -1,6 +1,6 @@ - + - + + ${project} Application - - + +

`${project}`, a `repoze.bfg` application

`${project}`, a `Pyramid` application

@@ -37,50 +35,49 @@

-
Search
repoze.bfg Documentation
+
Search
Pyramid Documentation

+ action="http://pylonshq.com/docs/pyramid/current/searchresults">
- +
-
repoze.bfg links
+
Pyramid links
- Narrative Documentation + href="http://pylonshq.com/docs/pyramid/current/#narrative-documentation">Narrative + Documentation
- API + href="http://pylonshq.com/docs/pyramid/current/#api-documentation">API Documentation
- - Tutorials + href="http://pylonshq.com/docs/pyramid/current/#tutorials">Tutorials
- - Change History + href="http://pylonshq.com/docs/pyramid/current/#change-history">Change + History
- Sample Applications + href="http://pylonshq.com/docs/pyramid/current/#sample-applications">Sample + Applications
- Support and Development + href="http://pylonshq.com/docs/pyramid/current/#support-and-development">Support + and Development
- IRC Channel + href="irc://irc.freenode.net#pylons">IRC Channel

+ - + + - + `` declaration tag performs the same function as the ``add_view`` method that was employed within :ref:`imperative_configuration`. In fact, the ```` tag is effectively a "macro" which calls the -:meth:`repoze.bfg.configuration.Configurator.add_view` method on your +:meth:`pyramid.configuration.Configurator.add_view` method on your behalf. -The ```` tag is an example of a :mod:`repoze.bfg` declaration +The ```` tag is an example of a :mod:`pyramid` declaration tag. Other such tags include ```` and ````. Each of these tags is effectively a "macro" which calls methods of a -:class:`repoze.bfg.configuration.Configurator` object on your behalf. +:class:`pyramid.configuration.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 @@ -234,9 +234,9 @@ start. For example, the following ZCML file has two conflicting .. code-block:: xml :linenos: - + - + - + @@ -366,7 +366,7 @@ The scanning machinery imports each module and subpackage in a package or module recursively, looking for special attributes attached to objects defined within a module. These special attributes are typically attached to code via the use of a :term:`decorator`. For -example, the :class:`repoze.bfg.view.bfg_view` decorator can be +example, the :class:`pyramid.view.bfg_view` decorator can be attached to a function or instance method. Once scanning is invoked, and :term:`configuration decoration` is @@ -375,8 +375,8 @@ found by the scanner, a set of calls are made to a the intent of the configuration decoration. In the example above, this is best represented as the scanner -translating the arguments to :class:`repoze.bfg.view.bfg_view` into a -call to the :meth:`repoze.bfg.configuration.Configurator.add_view` +translating the arguments to :class:`pyramid.view.bfg_view` into a +call to the :meth:`pyramid.configuration.Configurator.add_view` method, effectively: .. ignore-next-block @@ -391,9 +391,9 @@ A combination of imperative configuration, declarative configuration via ZCML and scanning can be used to configure any application. They are not mutually exclusive. -The :mod:`repoze.bfg` authors often recommend using mostly declarative +The :mod:`pyramid` authors often recommend using mostly declarative configuration, because it's the more traditional form of configuration -used in :mod:`repoze.bfg` applications, it can be overridden and +used in :mod:`pyramid` applications, it can be overridden and extended by third party deployers, and there are more examples for it "in the wild". diff --git a/docs/narr/contextfinding.rst b/docs/narr/contextfinding.rst index 6da10d641..cd504a571 100644 --- a/docs/narr/contextfinding.rst +++ b/docs/narr/contextfinding.rst @@ -11,24 +11,24 @@ framework must provide a mechanism to find and invoke code written by the application developer based on parameters present in the :term:`request`. -:mod:`repoze.bfg` uses two separate but cooperating subsystems to find +:mod:`pyramid` uses two separate but cooperating subsystems to find and invoke code written by the application developer: :term:`context finding` and :term:`view lookup`. -- A :mod:`repoze.bfg` :term:`context finding` subsystem is given a +- A :mod:`pyramid` :term:`context finding` subsystem is given a :term:`request`; it is responsible for finding a :term:`context` object and a :term:`view name` based on information present in the request. - Using the context and view name provided by :term:`context finding`, - the :mod:`repoze.bfg` :term:`view lookup` subsystem is provided with + the :mod:`pyramid` :term:`view lookup` subsystem is provided with a :term:`request`, a :term:`context` and a :term:`view name`. It is then responsible for finding and invoking a :term:`view callable`. A view callable is a specific bit of code written and registered by the application developer which receives the :term:`request` and which returns a :term:`response`. -These two subsystems are used by :mod:`repoze.bfg` serially: +These two subsystems are used by :mod:`pyramid` serially: first, a :term:`context finding` subsystem does its job. Then the result of context finding is passed to the :term:`view lookup` subsystem. The view lookup system finds a :term:`view callable` @@ -38,7 +38,7 @@ requesting user. .. sidebar:: What Good is A Context Finding Subsystem? - The :term:`URL dispatch` mode of :mod:`repoze.bfg` as well as many + The :term:`URL dispatch` mode of :mod:`pyramid` as well as many other web frameworks such as :term:`Pylons` or :term:`Django` actually collapse the two steps of context finding and view lookup into a single step. In these systems, a URL can map *directly* to @@ -51,14 +51,14 @@ requesting user. that do not provide a notion of a context. There are two separate :term:`context finding` subsystems in -:mod:`repoze.bfg`: :term:`traversal` and :term:`URL dispatch`. The +:mod:`pyramid`: :term:`traversal` and :term:`URL dispatch`. The subsystems are documented within this chapter. They can be used separately or they can be combined. Three chapters which follow describe :term:`context finding`: :ref:`traversal_chapter`, :ref:`urldispatch_chapter` and :ref:`hybrid_chapter`. There is only one :term:`view lookup` subsystem present in -:mod:`repoze.bfg`. Where appropriate, within this chapter, we +:mod:`pyramid`. Where appropriate, within this chapter, we describe how view lookup interacts with context finding. One chapter which follows describes :term:`view lookup`: :ref:`views_chapter`. @@ -113,6 +113,6 @@ in terms of traversing that graph. However, when you have a hierarchical data store, using traversal can provide significant advantages over using URL-based dispatch. -Since :mod:`repoze.bfg` provides support for both approaches, you can +Since :mod:`pyramid` provides support for both approaches, you can use either exclusively or combine them as you see fit. diff --git a/docs/narr/environment.rst b/docs/narr/environment.rst index ab789eb86..3b1f3d44f 100644 --- a/docs/narr/environment.rst +++ b/docs/narr/environment.rst @@ -19,7 +19,7 @@ Environment Variables and ``.ini`` File Settings ================================================ -:mod:`repoze.bfg` behavior can be configured through a combination of +:mod:`pyramid` behavior can be configured through a combination of operating system environment variables and ``.ini`` configuration file application section settings. The meaning of the environment variables and the configuration file settings overlap. @@ -32,7 +32,7 @@ variables and the configuration file settings overlap. The term "configuration file setting name" refers to a key in the ``.ini`` configuration for your application. The configuration file setting names documented in this chapter are reserved for -:mod:`repoze.bfg` use. You should not use them to indicate +:mod:`pyramid` use. You should not use them to indicate application-specific configuration settings. Reloading Templates @@ -145,7 +145,7 @@ Examples Let's presume your configuration file is named ``MyProject.ini``, and there is a section representing your application named ``[app:main]`` -within the file that represents your :mod:`repoze.bfg` application. +within the file that represents your :mod:`pyramid` application. The configuration file settings documented in the above "Config File Setting Name" column would go in the ``[app:main]`` section. Here's an example of such a section: @@ -159,14 +159,14 @@ an example of such a section: You can also use environment variables to accomplish the same purpose for settings documented as such. For example, you might start your -:mod:`repoze.bfg` application using the following command line: +:mod:`pyramid` application using the following command line: .. code-block:: python $ BFG_DEBUG_AUTHORIZATION=1 BFG_RELOAD_TEMPLATES=1 bin/paster serve \ MyProject.ini -If you started your application this way, your :mod:`repoze.bfg` +If you started your application this way, your :mod:`pyramid` application would behave in the same manner as if you had placed the respective settings in the ``[app:main]`` section of your application's ``.ini`` file. @@ -194,24 +194,24 @@ Understanding the Distinction Between ``reload_templates`` and ``reload_resource The difference between ``reload_resources`` and ``reload_templates`` is a bit subtle. Templates are themselves also treated by -:mod:`repoze.bfg` as :term:`pkg_resources` resource files (along with +:mod:`pyramid` as :term:`pkg_resources` resource files (along with static files and other resources), so the distinction can be confusing. It's helpful to read :ref:`overriding_resources_section` for some context about resources in general. -When ``reload_templates`` is true, :mod:`repoze.bfg` takes advantage +When ``reload_templates`` is true, :mod:`pyramid` takes advantage of the underlying templating systems' ability to check for file modifications to an individual template file. When ``reload_templates`` is true but ``reload_resources`` is *not* true, the template filename returned by pkg_resources is cached by -:mod:`repoze.bfg` on the first request. Subsequent requests for the +:mod:`pyramid` on the first request. Subsequent requests for the same template file will return a cached template filename. The underlying templating system checks for modifications to this particular file for every request. Setting ``reload_templates`` to ``True`` doesn't affect performance dramatically (although it should still not be used in production because it has some effect). -However, when ``reload_resources`` is true, :mod:`repoze.bfg` will not +However, when ``reload_resources`` is true, :mod:`pyramid` will not cache the template filename, meaning you can see the effect of changing the content of an overridden resource directory for templates without restarting the server after every change. Subsequent requests diff --git a/docs/narr/events.rst b/docs/narr/events.rst index dcdd3f094..99ea600fa 100644 --- a/docs/narr/events.rst +++ b/docs/narr/events.rst @@ -10,14 +10,14 @@ Using Events ============= -An *event* is an object broadcast by the :mod:`repoze.bfg` framework +An *event* is an object broadcast by the :mod:`pyramid` framework at interesting points during the lifetime of an application. You -don't need to use events in order to create most :mod:`repoze.bfg` +don't need to use events in order to create most :mod:`pyramid` applications, but they can be useful when you want to perform slightly advanced operations. For example, subscribing to an event can allow you to run some code as the result of every new request. -Events in :mod:`repoze.bfg` are always broadcast by the framework. +Events in :mod:`pyramid` are always broadcast by the framework. However, they only become useful when you register a *subscriber*. A subscriber is a function that accepts a single argument named `event`: @@ -33,7 +33,7 @@ when it's called. The mere existence of a subscriber function, however, is not sufficient to arrange for it to be called. To arrange for the subscriber to be called, you'll need to use the -:meth:`repoze.bfg.configurator.Configurator.add_subscriber` method to +:meth:`pyramid.configurator.Configurator.add_subscriber` method to register the subscriber imperatively, or via a decorator, or you'll need to use ZCML for the same purpose: @@ -41,45 +41,45 @@ need to use ZCML for the same purpose: You can imperatively configure a subscriber function to be called for some event type via the - :meth:`repoze.bfg.configuration.Configurator.add_subscriber` + :meth:`pyramid.configuration.Configurator.add_subscriber` method (see also :term:`Configurator`): .. code-block:: python :linenos: - from repoze.bfg.interfaces import INewRequest + from pyramid.interfaces import INewRequest from subscribers import mysubscriber # "config" below is assumed to be an instance of a - # repoze.bfg.configuration.Configurator object + # pyramid.configuration.Configurator object config.add_subscriber(mysubscriber, INewRequest) The first argument to - :meth:`repoze.bfg.configuration.Configurator.add_subscriber` is the + :meth:`pyramid.configuration.Configurator.add_subscriber` is the subscriber function (or a :term:`dotted Python name` which refers to a subscriber callable); the second argument is the event type. .. topic:: Configuring an Event Listener Using a Decorator You can configure a subscriber function to be called for some event - type via the :func:`repoze.bfg.events.subscriber` function. + type via the :func:`pyramid.events.subscriber` function. .. code-block:: python :linenos: - from repoze.bfg.interfaces import INewRequest - from repoze.bfg.events import subscriber + from pyramid.interfaces import INewRequest + from pyramid.events import subscriber @subscriber(INewRequest) def mysubscriber(event): event.request.foo = 1 - When the :func:`repoze.bfg.subscriber` decorator is used a + When the :func:`pyramid.subscriber` decorator is used a :term:`scan` must be performed against the package containing the decorated function for the decorator to have any effect. See - :func:`repoze.bfg.subscriber` for more information. + :func:`pyramid.subscriber` for more information. .. topic:: Configuring an Event Listener Through ZCML @@ -93,15 +93,15 @@ need to use ZCML for the same purpose: :linenos: See also :ref:`subscriber_directive`. Either of the above registration examples implies that every time the -:mod:`repoze.bfg` framework emits an event object that supplies an -:class:`repoze.bfg.interfaces.INewRequest` interface, the +:mod:`pyramid` framework emits an event object that supplies an +:class:`pyramid.interfaces.INewRequest` interface, the ``mysubscriber`` function will be called with an *event* object. As you can see, a subscription is made in terms of an @@ -113,7 +113,7 @@ The return value of a subscriber function is ignored. Subscribers to the same event type are not guaranteed to be called in any particular order relative to each other. -All the concrete :mod:`repoze.bfg` event types are documented in the +All the concrete :mod:`pyramid` event types are documented in the :ref:`events_module` API documentation. An Example @@ -139,31 +139,31 @@ times by adding the following ZCML to your application's :linenos: If you're not using ZCML, the -:meth:`repoze.bfg.configuration.Configurator.add_subscriber` method +:meth:`pyramid.configuration.Configurator.add_subscriber` method can alternately be used to perform the same job: .. ignore-next-block .. code-block:: python :linenos: - from repoze.bfg.interfaces import INewRequest - from repoze.bfg.interfaces import INewResponse + from pyramid.interfaces import INewRequest + from pyramid.interfaces import INewResponse from subscribers import handle_new_request from subscribers import handle_new_response # "config" below is assumed to be an instance of a - # repoze.bfg.configuration.Configurator object + # pyramid.configuration.Configurator object config.add_subscriber(handle_new_request, INewRequest) config.add_subscriber(handle_new_response, INewResponse) @@ -177,14 +177,14 @@ Each of our subscriber functions accepts an ``event`` object and prints an attribute of the event object. This begs the question: how can we know which attributes a particular event has? -We know that :class:`repoze.bfg.interfaces.INewRequest` event objects +We know that :class:`pyramid.interfaces.INewRequest` event objects have a ``request`` attribute, which is a :term:`request` object, because the interface defined at -:class:`repoze.bfg.interfaces.INewRequest` says it must. Likewise, we -know that :class:`repoze.bfg.interfaces.INewResponse` events have a +:class:`pyramid.interfaces.INewRequest` says it must. Likewise, we +know that :class:`pyramid.interfaces.INewResponse` events have a ``response`` attribute, which is a response object constructed by your application, because the interface defined at -:class:`repoze.bfg.interfaces.INewResponse` says it must -(:class:`repoze.bfg.interfaces.INewResponse` objects also have a +:class:`pyramid.interfaces.INewResponse` says it must +(:class:`pyramid.interfaces.INewResponse` objects also have a ``request``). diff --git a/docs/narr/extending.rst b/docs/narr/extending.rst index 3a9518020..490d0733f 100644 --- a/docs/narr/extending.rst +++ b/docs/narr/extending.rst @@ -1,12 +1,12 @@ .. _extending_chapter: -Extending An Existing :mod:`repoze.bfg` Application +Extending An Existing :mod:`pyramid` Application =================================================== -If the developer of a :mod:`repoze.bfg` application has obeyed certain +If the developer of a :mod:`pyramid` application has obeyed certain constraints while building that application, a third party should be able to change its behavior without needing to modify its source code. -The behavior of a :mod:`repoze.bfg` application that obeys certain +The behavior of a :mod:`pyramid` application that obeys certain constraints can be *overridden* or *extended* without modification. .. index:: @@ -16,14 +16,14 @@ Rules for Building An Extensible Application -------------------------------------------- There's only one rule you need to obey if you want to build a -maximally extensible :mod:`repoze.bfg` application: you should not use +maximally extensible :mod:`pyramid` application: you should not use any :term:`configuration decoration` or :term:`imperative configuration`. This means the application developer should avoid relying on :term:`configuration decoration` meant to be detected via -a :term:`scan`, and you mustn't configure your :mod:`repoze.bfg` +a :term:`scan`, and you mustn't configure your :mod:`pyramid` application *imperatively* by using any code which configures the application through methods of the :term:`Configurator` (except for -the :meth:`repoze.bfg.configuration.Configurator.load_zcml` method). +the :meth:`pyramid.configuration.Configurator.load_zcml` method). Instead, you must always use :term:`ZCML` for the equivalent purposes. :term:`ZCML` declarations that belong to an application can @@ -36,12 +36,12 @@ Fundamental Plugpoints ~~~~~~~~~~~~~~~~~~~~~~ The fundamental "plug points" of an application developed using -:mod:`repoze.bfg` are *routes*, *views*, and *resources*. Routes are +:mod:`pyramid` are *routes*, *views*, and *resources*. Routes are declarations made using the ZCML ```` directive. Views are declarations made using the ZCML ```` directive (or the ``@bfg_view`` decorator). Resources are files that are accessed by -repoze bfg using the :term:`pkg_resources` API such as static files -and templates. +:mod:`pyramid` using the :term:`pkg_resources` API such as static +files and templates. .. index:: single: ZCML granularity @@ -88,8 +88,8 @@ and/or imperative code. Extending an Application Which Possesses Configuration Decorators Or Which Does Configuration Imperatively ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -If you've inherited a :mod:`repoze.bfg` application which uses -:class:`repoze.bfg.view.bfg_view` decorators or which performs +If you've inherited a :mod:`pyramid` application which uses +:class:`pyramid.view.bfg_view` decorators or which performs configuration imperatively, one of two things may be true: - If you just want to *extend* the application, you can write @@ -101,10 +101,10 @@ configuration imperatively, one of two things may be true: *may* need to change the source code of the original application. If the only source of trouble is the existence of - :class:`repoze.bfg.view.bfg_view` decorators, you can just prevent a + :class:`pyramid.view.bfg_view` decorators, you can just prevent a :term:`scan` from happening (by omitting the ```` declaration from ZCML or omitting any call to the - :meth:`repoze.bfg.configuration.Configurator.scan` method). This + :meth:`pyramid.configuration.Configurator.scan` method). This will cause the decorators to do nothing. At this point, you will need to convert all the configuration done in decorators into equivalent :term:`ZCML` and add that ZCML to a separate Python @@ -132,7 +132,7 @@ The general pattern for extending an existing application looks something like this: - Create a new Python package. The easiest way to do this is to - create a new :mod:`repoze.bfg` application using the "paster" + create a new :mod:`pyramid` application using the "paster" template mechanism. See :ref:`creating_a_project` for more information. @@ -141,7 +141,7 @@ something like this: setup.py install``). - Change the ``configure.zcml`` in the new package to include the - original :mod:`repoze.bfg` application's ``configure.zcml`` via an + original :mod:`pyramid` application's ``configure.zcml`` via an include statement, e.g. ````. Alternately, if the original application writer anticipated overriding some things and not others, instead of including the diff --git a/docs/narr/firstapp.rst b/docs/narr/firstapp.rst index deac69fda..16410d07f 100644 --- a/docs/narr/firstapp.rst +++ b/docs/narr/firstapp.rst @@ -1,9 +1,9 @@ .. _firstapp_chapter: -Creating Your First :mod:`repoze.bfg` Application +Creating Your First :mod:`pyramid` Application ================================================= -We will walk through the creation of a tiny :mod:`repoze.bfg` +We will walk through the creation of a tiny :mod:`pyramid` application in this chapter. After we're finished creating it, we'll explain in more detail how the application works. @@ -20,7 +20,7 @@ explain in more detail how the application works. Hello World, Goodbye World (Imperative) --------------------------------------- -Here's one of the very simplest :mod:`repoze.bfg` applications, +Here's one of the very simplest :mod:`pyramid` applications, configured imperatively: .. code-block:: python @@ -28,7 +28,7 @@ configured imperatively: from webob import Response from paste.httpserver import serve - from repoze.bfg.configuration import Configurator + from pyramid.configuration import Configurator def hello_world(request): return Response('Hello world!') @@ -47,7 +47,7 @@ configured imperatively: When this code is inserted into a Python script named ``helloworld.py`` and executed by a Python interpreter which has the -:mod:`repoze.bfg` software installed, an HTTP server is started on TCP +:mod:`pyramid` software installed, an HTTP server is started on TCP port 8080. When port 8080 is visited by a browser on the root URL (``/``), the server will simply serve up the text "Hello world!" When visited by a browser on the URL ``/goodbye``, the server will serve up @@ -66,24 +66,24 @@ The above script defines the following set of imports: from webob import Response from paste.httpserver import serve - from repoze.bfg.configuration import Configurator + from pyramid.configuration import Configurator -:mod:`repoze.bfg` uses the :term:`WebOb` library as the basis for its +:mod:`pyramid` uses the :term:`WebOb` library as the basis for its :term:`request` and :term:`response` objects. The script uses the :class:`webob.Response` class later in the script to create a :term:`response` object. -Like many other Python web frameworks, :mod:`repoze.bfg` uses the +Like many other Python web frameworks, :mod:`pyramid` uses the :term:`WSGI` protocol to connect an application and a web server together. The :mod:`paste.httpserver` server is used in this example as a WSGI server for convenience, as the ``paste`` package is a -dependency of :mod:`repoze.bfg` itself. +dependency of :mod:`pyramid` itself. The script also imports the ``Configurator`` class from the -``repoze.bfg.configuration`` module. This class is used to configure -:mod:`repoze.bfg` for a particular application. An instance of this +``pyramid.configuration`` module. This class is used to configure +:mod:`pyramid` for a particular application. An instance of this class provides methods which help configure various parts of -:mod:`repoze.bfg` for a given application deployment. +:mod:`pyramid` for a given application deployment. View Callable Declarations ~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -107,7 +107,7 @@ The ``goodbye_world`` function returns a response instance with the body ``Goodbye world!``. Each of these functions is known as a :term:`view callable`. View -callables in a :mod:`repoze.bfg` application accept a single argument, +callables in a :mod:`pyramid` application accept a single argument, ``request`` and are expected to return a :term:`response` object. A view callable doesn't need to be a function; it can be represented via another type of object, like a class or an instance, but for our @@ -115,7 +115,7 @@ purposes here, a function serves us well. A view callable is always called with a :term:`request` object. A request object is a representation of an HTTP request sent to -:mod:`repoze.bfg` via the active :term:`WSGI` server. +:mod:`pyramid` via the active :term:`WSGI` server. A view callable is required to return a :term:`response` object because a response object has all the information necessary to @@ -182,9 +182,9 @@ code within the ``if`` block should only be run during a direct script execution. The ``config = Configurator()`` line above creates an instance of the -:class:`repoze.bfg.configuration.Configurator` class. The resulting +:class:`pyramid.configuration.Configurator` class. The resulting ``config`` object represents an API which the script uses to configure -this particular :mod:`repoze.bfg` application. Methods called on the +this particular :mod:`pyramid` application. Methods called on the Configurator will cause registrations to be made in a :term:`application registry` associated with the application. @@ -196,7 +196,7 @@ Beginning Configuration config.begin() -The :meth:`repoze.bfg.configuration.Configurator.begin` method tells +The :meth:`pyramid.configuration.Configurator.begin` method tells the system that application configuration has begun. In particular, this causes the :term:`application registry` associated with this configurator to become the "current" application registry, meaning @@ -224,7 +224,7 @@ Adding Configuration config.add_view(goodbye_world, name='goodbye') Each of these lines calls the -:meth:`repoze.bfg.configuration.Configurator.add_view` method. The +:meth:`pyramid.configuration.Configurator.add_view` method. The ``add_view`` method of a configurator registers a :term:`view configuration` within the :term:`application registry`. A :term:`view configuration` represents a set of circumstances related to the @@ -241,7 +241,7 @@ argument passed is the ``hello_world`` function. This line calls ``add_view`` with a *default* value for the :term:`predicate` argument, named ``name``. The ``name`` predicate defaults to a value equalling the empty string (``''``). This means that we're -instructing :mod:`repoze.bfg` to invoke the ``hello_world`` view +instructing :mod:`pyramid` to invoke the ``hello_world`` view callable when the :term:`view name` is the empty string. We'll learn in later chapters what a :term:`view name` is, and under which circumstances a request will have a view name that is the empty @@ -266,17 +266,17 @@ keyword argument to the ``add_view`` method narrows the set of circumstances which would cause the view configuration's callable to be invoked. In general, a greater number of predicates supplied along with a view configuration will more strictly limit the applicability -of its associated view callable. When :mod:`repoze.bfg` processes a +of its associated view callable. When :mod:`pyramid` processes a request, however, the view callable with the *most specific* view configuration (the view configuration that matches the most specific set of predicates) is always invoked. -In this application, :mod:`repoze.bfg` chooses the most specific view +In this application, :mod:`pyramid` chooses the most specific view callable based only on view :term:`predicate` applicability. The ordering of calls to -:meth:`repoze.bfg.configuration.Configurator.add_view` is never very +:meth:`pyramid.configuration.Configurator.add_view` is never very important. We can register ``goodbye_world`` first and -``hello_world`` second; :mod:`repoze.bfg` will still give us the most +``hello_world`` second; :mod:`pyramid` will still give us the most specific callable when a request is dispatched to it. Ending Configuration @@ -287,9 +287,9 @@ Ending Configuration config.end() -The :meth:`repoze.bfg.configuration.Configurator.end` method tells the +The :meth:`pyramid.configuration.Configurator.end` method tells the system that application configuration has ended. It is the inverse of -:meth:`repoze.bfg.configuration.Configurator.begin`. In particular, +:meth:`pyramid.configuration.Configurator.begin`. In particular, this causes the :term:`application registry` associated with this configurator to no longer be the "current" application registry, meaning that code which attempts to use the application registry @@ -315,7 +315,7 @@ WSGI Application Creation After configuring views and ending configuration, the script creates a WSGI *application* via the -:meth:`repoze.bfg.configuration.Configurator.make_wsgi_app` method. A +:meth:`pyramid.configuration.Configurator.make_wsgi_app` method. A call to ``make_wsgi_app`` implies that all configuration is finished (meaning all method calls to the configurator which set up views, and various other configuration settings have been performed). The @@ -326,8 +326,8 @@ Python applications. We don't discuss :term:`WSGI` in any depth within this book, however, you can learn more about it by visiting `wsgi.org `_. -The :mod:`repoze.bfg` application object, in particular, is an -instance of a class representing a :mod:`repoze.bfg` :term:`router`. +The :mod:`pyramid` application object, in particular, is an +instance of a class representing a :mod:`pyramid` :term:`router`. It has a reference to the :term:`application registry` which resulted from method calls to the configurator used to configure it. The :term:`router` consults the registry to obey the policy choices made @@ -363,7 +363,7 @@ Conclusion ~~~~~~~~~~ Our hello world application is one of the simplest possible -:mod:`repoze.bfg` applications, configured "imperatively". We can see +:mod:`pyramid` applications, configured "imperatively". We can see that it's configured imperatively because the full power of Python is available to us as we perform configuration tasks. @@ -376,7 +376,7 @@ Hello World, Goodbye World (Declarative) ---------------------------------------- Another almost entirely equivalent mode of application configuration -exists named *declarative* configuration. :mod:`repoze.bfg` can be +exists named *declarative* configuration. :mod:`pyramid` can be configured for the same "hello world" application "declaratively", if so desired. @@ -387,7 +387,7 @@ To do so, first, create a file named ``helloworld.py``: from webob import Response from paste.httpserver import serve - from repoze.bfg.configuration import Configurator + from pyramid.configuration import Configurator def hello_world(request): return Response('Hello world!') @@ -409,9 +409,9 @@ the previously created ``helloworld.py``: .. code-block:: xml :linenos: - + - + + - + + Because :term:`ZCML` is XML, and because XML requires a single root -tag for each document, every ZCML file used by :mod:`repoze.bfg` must +tag for each document, every ZCML file used by :mod:`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. @@ -521,18 +521,18 @@ The ``configure.zcml`` ZCML file contains this bit of XML within the .. code-block:: xml - + -This self-closing tag instructs :mod:`repoze.bfg` to load a ZCML file +This self-closing tag instructs :mod:`pyramid` to load a ZCML file from the Python package with the :term:`dotted Python name` -``repoze.bfg.includes``, as specified by its ``package`` attribute. +``pyramid.includes``, as specified by its ``package`` attribute. This particular ```` declaration is required because it actually allows subsequent declaration tags (such as ````, which we'll see shortly) to be recognized. The ```` 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:`repoze.bfg.includes` Python package. We know we want to load +:mod:`pyramid.includes` 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 ```` tag named ``file``. We could have spelled the include tag more verbosely, but @@ -541,16 +541,16 @@ equivalently as: .. code-block:: xml :linenos: - The ```` tag that includes the ZCML statements implied by the ``configure.zcml`` file from the Python package named -:mod:`repoze.bfg.includes` is basically required to come before any +:mod:`pyramid.includes` 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 ```` +startup. However, the ```` 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. @@ -574,7 +574,7 @@ The ``configure.zcml`` ZCML file contains these bits of XML *after* the view="helloworld.goodbye_world" /> -These ```` declaration tags direct :mod:`repoze.bfg` to create +These ```` declaration tags direct :mod:`pyramid` to create two :term:`view configuration` registrations. The first ```` tag has an attribute (the attribute is also named ``view``), which points at a :term:`dotted Python name`, referencing the @@ -600,13 +600,13 @@ configurations imperatively, we saw this code: config.add_view(goodbye_world, name='goodbye') Each ```` declaration tag encountered in a ZCML file effectively -invokes the :meth:`repoze.bfg.configuration.Configurator.add_view` +invokes the :meth:`pyramid.configuration.Configurator.add_view` method on the behalf of the developer. Various attributes can be specified on the ```` tag which influence the :term:`view configuration` it creates. Since the relative ordering of calls to -:meth:`repoze.bfg.configuration.Configurator.add_view` doesn't matter +:meth:`pyramid.configuration.Configurator.add_view` doesn't matter (see the sidebar entitled *View Dispatch and Ordering* within :ref:`adding_configuration`), the relative order of ```` tags in ZCML doesn't matter either. The following ZCML orderings are @@ -640,7 +640,7 @@ completely equivalent: view="helloworld.hello_world" /> -We've now configured a :mod:`repoze.bfg` helloworld application +We've now configured a :mod:`pyramid` helloworld application declaratively. More information about this mode of configuration is available in :ref:`declarative_configuration` and within :ref:`zcml_reference`. @@ -649,7 +649,7 @@ References ---------- For more information about the API of a :term:`Configurator` object, -see :class:`repoze.bfg.configuration.Configurator` . The equivalent +see :class:`pyramid.configuration.Configurator` . The equivalent ZCML declaration tags are introduced in :ref:`zcml_reference`. For more information about :term:`view configuration`, see diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst index e96cd510d..db933c525 100644 --- a/docs/narr/hooks.rst +++ b/docs/narr/hooks.rst @@ -3,7 +3,7 @@ Using Hooks =========== -"Hooks" can be used to influence the behavior of the :mod:`repoze.bfg` +"Hooks" can be used to influence the behavior of the :mod:`pyramid` framework in various ways. .. index:: @@ -14,7 +14,7 @@ framework in various ways. Changing the Not Found View --------------------------- -When :mod:`repoze.bfg` can't map a URL to view code, it invokes a +When :mod:`pyramid` can't map a URL to view code, it invokes a :term:`not found view`, which is a :term:`view callable`. A default notfound view exists. The default not found view can be overridden through application configuration. This override can be done via @@ -22,20 +22,20 @@ through application configuration. This override can be done via The :term:`not found view` callable is a view callable like any other. The :term:`view configuration` which causes it to be a "not found" -view consists only of naming the :exc:`repoze.bfg.exceptions.NotFound` +view consists only of naming the :exc:`pyramid.exceptions.NotFound` class as the ``context`` of the view configuration. .. topic:: Using Imperative Configuration If your application uses :term:`imperative configuration`, you can replace the Not Found view by using the - :meth:`repoze.bfg.configuration.Configurator.add_view` method to + :meth:`pyramid.configuration.Configurator.add_view` method to register an "exception view": .. code-block:: python :linenos: - from repoze.bfg.exceptions import NotFound + from pyramid.exceptions import NotFound from helloworld.views import notfound_view config.add_view(notfound_view, context=NotFound) @@ -54,7 +54,7 @@ class as the ``context`` of the view configuration. + context="pyramid.exceptions.NotFound"/> Replace ``helloworld.views.notfound_view`` with the Python dotted name to the notfound view you want to use. @@ -63,7 +63,7 @@ Like any other view, the notfound view must accept at least a ``request`` parameter, or both ``context`` and ``request``. The ``request`` is the current :term:`request` representing the denied action. The ``context`` (if used in the call signature) will be the -instance of the :exc:`repoze.bfg.exceptions.NotFound` exception that +instance of the :exc:`pyramid.exceptions.NotFound` exception that caused the view to be called. Here's some sample code that implements a minimal NotFound view @@ -79,7 +79,7 @@ callable: .. note:: When a NotFound view callable is invoked, it is passed a :term:`request`. The ``exception`` attribute of the request will - be an instance of the :exc:`repoze.bfg.exceptions.NotFound` + be an instance of the :exc:`pyramid.exceptions.NotFound` exception that caused the not found view to be called. The value of ``request.exception.args[0]`` will be a value explaining why the not found error was raised. This message will be different when @@ -89,7 +89,7 @@ callable: .. warning:: When a NotFound view callable accepts an argument list as described in :ref:`request_and_context_view_definitions`, the ``context`` passed as the first argument to the view callable will - be the :exc:`repoze.bfg.exceptions.NotFound` exception instance. + be the :exc:`pyramid.exceptions.NotFound` exception instance. If available, the *model* context will still be available as ``request.context``. @@ -101,7 +101,7 @@ callable: Changing the Forbidden View --------------------------- -When :mod:`repoze.bfg` can't authorize execution of a view based on +When :mod:`pyramid` can't authorize execution of a view based on the :term:`authorization policy` in use, it invokes a :term:`forbidden view`. The default forbidden response has a 401 status code and is very plain, but the view which generates it can be overridden as @@ -110,21 +110,21 @@ necessary using either :term:`imperative configuration` or The :term:`forbidden view` callable is a view callable like any other. The :term:`view configuration` which causes it to be a "not found" -view consists only of naming the :exc:`repoze.bfg.exceptions.Forbidden` +view consists only of naming the :exc:`pyramid.exceptions.Forbidden` class as the ``context`` of the view configuration. .. topic:: Using Imperative Configuration If your application uses :term:`imperative configuration`, you can replace the Forbidden view by using the - :meth:`repoze.bfg.configuration.Configurator.add_view` method to + :meth:`pyramid.configuration.Configurator.add_view` method to register an "exception view": .. code-block:: python :linenos: from helloworld.views import forbidden_view - from repoze.bfg.exceptions import Forbidden + from pyramid.exceptions import Forbidden config.add_view(forbidden_view, context=Forbidden) Replace ``helloworld.views.forbidden_view`` with a reference to the @@ -142,7 +142,7 @@ class as the ``context`` of the view configuration. + context="pyramid.exceptions.Forbidden"/> Replace ``helloworld.views.forbidden_view`` with the Python dotted name to the forbidden view you want to use. @@ -159,14 +159,14 @@ Here's some sample code that implements a minimal forbidden view: .. code-block:: python :linenos: - from repoze.bfg.chameleon_zpt import render_template_to_response + from pyramid.chameleon_zpt import render_template_to_response def forbidden_view(request): return render_template_to_response('templates/login_form.pt') .. note:: When a forbidden view callable is invoked, it is passed a :term:`request`. The ``exception`` attribute of the request will - be an instance of the :exc:`repoze.bfg.exceptions.Forbidden` + be an instance of the :exc:`pyramid.exceptions.Forbidden` exception that caused the forbidden view to be called. The value of ``request.exception.args[0]`` will be a value explaining why the forbidden was raised. This message will be different when the @@ -187,10 +187,10 @@ Here's some sample code that implements a minimal forbidden view: Changing the Traverser ---------------------- -The default :term:`traversal` algorithm that BFG uses is explained in -:ref:`traversal_algorithm`. Though it is rarely necessary, this -default algorithm can be swapped out selectively for a different -traversal pattern via configuration. +The default :term:`traversal` algorithm that :mod:`pyramid` uses is +explained in :ref:`traversal_algorithm`. Though it is rarely +necessary, this default algorithm can be swapped out selectively for a +different traversal pattern via configuration. Use an ``adapter`` stanza in your application's ``configure.zcml`` to change the default traverser: @@ -200,7 +200,7 @@ change the default traverser: @@ -238,16 +238,6 @@ a class that implements the following interface: as attributes of the ``request`` object. """ -.. warning:: In :mod:`repoze.bfg.` 1.0 and previous versions, the - traverser ``__call__`` method accepted a WSGI *environment* - dictionary rather than a :term:`request` object. The request - object passed to the traverser implements a dictionary-like API - which mutates and queries the environment, as a backwards - compatibility shim, in order to allow older code to work. - However, for maximum forward compatibility, traverser code - targeting :mod:`repoze.bfg` 1.1 and higher should expect a - request object directly. - More than one traversal algorithm can be active at the same time. For instance, if your :term:`root factory` returns more than one type of object conditionally, you could claim that an alternate traverser @@ -261,37 +251,32 @@ traverser would be used. For example: If the above stanza was added to a ``configure.zcml`` file, -:mod:`repoze.bfg` would use the ``myapp.traversal.Traverser`` only +:mod:`pyramid` would use the ``myapp.traversal.Traverser`` only when the application :term:`root factory` returned an instance of the ``myapp.models.MyRoot`` object. Otherwise it would use the default -:mod:`repoze.bfg` traverser to do traversal. - -Example implementations of alternate traversers can be found "in the -wild" within `repoze.bfg.traversalwrapper -`_ and -`repoze.bfg.metatg `_. +:mod:`pyramid` traverser to do traversal. .. index:: single: url generator -Changing How :mod:`repoze.bfg.url.model_url` Generates a URL +Changing How :mod:`pyramid.url.model_url` Generates a URL ------------------------------------------------------------ When you add a traverser as described in :ref:`changing_the_traverser`, it's often convenient to continue to -use the :func:`repoze.bfg.url.model_url` API. However, since the way +use the :func:`pyramid.url.model_url` API. However, since the way traversal is done will have been modified, the URLs it generates by default may be incorrect. If you've added a traverser, you can change how -:func:`repoze.bfg.url.model_url` generates a URL for a specific type +:func:`pyramid.url.model_url` generates a URL for a specific type of :term:`context` by adding an adapter stanza for -:class:`repoze.bfg.interfaces.IContextURL` to your application's +:class:`pyramid.interfaces.IContextURL` to your application's ``configure.zcml``: .. code-block:: xml @@ -299,19 +284,19 @@ of :term:`context` by adding an adapter stanza for In the above example, the ``myapp.traversal.URLGenerator`` class will -be used to provide services to :func:`repoze.bfg.url.model_url` any +be used to provide services to :func:`pyramid.url.model_url` any time the :term:`context` passed to ``model_url`` is of class ``myapp.models.MyRoot``. The asterisk following represents the type of interface that must be possessed by the :term:`request` (in this case, any interface, represented by asterisk). The API that must be implemented by a class that provides -:class:`repoze.bfg.interfaces.IContextURL` is as follows: +:class:`pyramid.interfaces.IContextURL` is as follows: .. code-block:: python :linenos: @@ -332,23 +317,23 @@ The API that must be implemented by a class that provides """ Return a URL that points to the context """ The default context URL generator is available for perusal as the -class :class:`repoze.bfg.traversal.TraversalContextURL` in the +class :class:`pyramid.traversal.TraversalContextURL` in the `traversal module -`_ of -the :term:`Repoze` Subversion repository. +`_ of +the :term:`Pylons` GitHub Pyramid repository. .. _changing_the_request_factory: Changing the Request Factory ---------------------------- -Whenever :mod:`repoze.bfg` handles a :term:`WSGI` request, it creates +Whenever :mod:`pyramid` handles a :term:`WSGI` request, it creates a :term:`request` object based on the WSGI environment it has been passed. By default, an instance of the -:class:`repoze.bfg.request.Request` class is created to represent the +:class:`pyramid.request.Request` class is created to represent the request object. -The class (aka "factory") that :mod:`repoze.bfg` uses to create a +The class (aka "factory") that :mod:`pyramid` uses to create a request object instance can be changed by passing a ``request_factory`` argument to the constructor of the :term:`configurator`. This argument can be either a callable or a @@ -357,7 +342,7 @@ request object instance can be changed by passing a .. code-block:: python :linenos: - from repoze.bfg.request import Request + from pyramid.request import Request class MyRequest(Request): pass @@ -374,20 +359,20 @@ In the below, we assume it lives in a package named Lastly, if you're doing imperative configuration, and you'd rather do it after you've already constructed a :term:`configurator` it can also be registered via the -:meth:`repoze.bfg.configuration.Configurator.set_request_factory` +:meth:`pyramid.configuration.Configurator.set_request_factory` method: .. code-block:: python :linenos: - from repoze.bfg.configuration import Configurator - from repoze.bfg.request import Request + from pyramid.configuration import Configurator + from pyramid.request import Request class MyRequest(Request): pass @@ -400,17 +385,17 @@ method: Adding Renderer Globals ----------------------- -Whenever :mod:`repoze.bfg` handles a request to perform a rendering +Whenever :mod:`pyramid` handles a request to perform a rendering (after a view with a ``renderer=`` configuration attribute is invoked, or when the any of the methods beginning with ``render`` within the -:mod:`repoze.bfg.renderers` module are called), *renderer globals* can +:mod:`pyramid.renderers` module are called), *renderer globals* can be injected into the *system* values sent to the renderer. By default, no renderer globals are injected, and the "bare" system values (such as ``request``, ``context``, and ``renderer_name``) are the only values present in the system dictionary passed to every renderer. -A callback that :mod:`repoze.bfg` will call every time a renderer is +A callback that :mod:`pyramid` will call every time a renderer is invoked can be added by passing a ``renderer_globals_factory`` argument to the constructor of the :term:`configurator`. This callback can either be a callable object or a :term:`dotted Python @@ -441,19 +426,19 @@ named ``mypackage.mymodule``. Lastly, if you're doing imperative configuration, and you'd rather do it after you've already constructed a :term:`configurator` it can also be registered via the -:meth:`repoze.bfg.configuration.Configurator.set_renderer_globals_factory` +:meth:`pyramid.configuration.Configurator.set_renderer_globals_factory` method: .. code-block:: python :linenos: - from repoze.bfg.configuration import Configurator + from pyramid.configuration import Configurator def renderer_globals_factory(system): return {'a':1} @@ -466,12 +451,12 @@ method: Using Response Callbacks ------------------------ -Unlike many other web frameworks, :mod:`repoze.bfg` does not eagerly +Unlike many other web frameworks, :mod:`pyramid` does not eagerly create a global response object. Adding a :term:`response callback` allows an application to register an action to be performed against a response object once it is created, usually in order to mutate it. -The :meth:`repoze.bfg.request.Request.add_response_callback` method is +The :meth:`pyramid.request.Request.add_response_callback` method is used to register a response callback. A response callback is a callable which accepts two positional @@ -496,15 +481,15 @@ value of ``None``. Response callbacks are called in the order they're added (first-to-most-recently-added). All response callbacks are called -*after* the :class:`repoze.bfg.interfaces.INewResponse` event is sent. +*after* the :class:`pyramid.interfaces.INewResponse` event is sent. Errors raised by response callbacks are not handled specially. They -will be propagated to the caller of the :mod:`repoze.bfg` router +will be propagated to the caller of the :mod:`pyramid` router application. A response callback has a lifetime of a *single* request. If you want a response callback to happen as the result of *every* request, you must re-register the callback into every new request (perhaps within a -subscriber of a :class:`repoze.bfg.interfaces.INewRequest` event). +subscriber of a :class:`pyramid.interfaces.INewRequest` event). .. _using_finished_callbacks: @@ -512,11 +497,11 @@ Using Finished Callbacks ------------------------ A :term:`finished callback` is a function that will be called -unconditionally by the :mod:`repoze.bfg` :term:`router` at the very +unconditionally by the :mod:`pyramid` :term:`router` at the very end of request processing. A finished callback can be used to perform an action at the end of a request unconditionally. -The :meth:`repoze.bfg.request.Request.add_finished_callback` method is +The :meth:`pyramid.request.Request.add_finished_callback` method is used to register a finished callback. A finished callback is a callable which accepts a single positional @@ -558,32 +543,32 @@ enters a response callback will be an exception object instead of its default value of ``None``. Errors raised by finished callbacks are not handled specially. They -will be propagated to the caller of the :mod:`repoze.bfg` router +will be propagated to the caller of the :mod:`pyramid` router application. A finished callback has a lifetime of a *single* request. If you want a finished callback to happen as the result of *every* request, you must re-register the callback into every new request (perhaps within a -subscriber of a :class:`repoze.bfg.interfaces.INewRequest` event). +subscriber of a :class:`pyramid.interfaces.INewRequest` event). .. _registering_configuration_decorators: Registering Configuration Decorators ------------------------------------ -Decorators such as :class:`repoze.bfg.view.bfg_view` don't change the +Decorators such as :class:`pyramid.view.bfg_view` don't change the behavior of the functions or classes they're decorating. Instead, when a :term:`scan` is performed, a modified version of the function -or class is registered with :mod:`repoze.bfg`. +or class is registered with :mod:`pyramid`. You may wish to have your own decorators that offer such behaviour. This is possible by using the :term:`Venusian` package in -the same way that it is used by :mod:`repoze.bfg`. +the same way that it is used by :mod:`pyramid`. By way of example, let's suppose you want to write a decorator that registers the function it wraps with a :term:`Zope Component Architecture` "utility" within the :term:`application registry` -provided by :mod:`repoze.bfg`. The application registry and the +provided by :mod:`pyramid`. The application registry and the utility inside the registry is likely only to be available once your application's configuration is at least partially completed. A normal decorator would fail as it would be executed before the configuration @@ -596,7 +581,7 @@ follows: :linenos: import venusian - from repoze.bfg.threadlocal import get_current_registry + from pyramid.threadlocal import get_current_registry from mypackage.interfaces import IMyUtility class registerFunction(object): @@ -631,7 +616,7 @@ performed, enabling you to set up the utility in advance: :linenos: from paste.httpserver import serve - from repoze.bfg.configuration import Configurator + from pyramid.configuration import Configurator class UtilityImplementation: @@ -655,7 +640,3 @@ performed, enabling you to set up the utility in advance: For full details, please read the `Venusian documentation `_. -.. note:: - - Application-developer-registerable configuration decorators were - introduced in :mod:`repoze.bfg` 1.3. diff --git a/docs/narr/hybrid.rst b/docs/narr/hybrid.rst index 021162d0b..cdac3642a 100644 --- a/docs/narr/hybrid.rst +++ b/docs/narr/hybrid.rst @@ -3,11 +3,11 @@ Combining Traversal and URL Dispatch ==================================== -When you write most :mod:`repoze.bfg` applications, you'll be using +When you write most :mod:`pyramid` applications, you'll be using one or the other of two available :term:`context finding` subsystems: traversal or URL dispatch. However, to solve a limited set of problems, it's useful to use *both* traversal and URL dispatch -together within the same application. :mod:`repoze.bfg` makes this +together within the same application. :mod:`pyramid` makes this possible via *hybrid* applications. .. warning:: @@ -24,7 +24,7 @@ A Review of Non-Hybrid Applications ----------------------------------- When used according to the tutorials in its documentation -:mod:`repoze.bfg` is a "dual-mode" framework: the tutorials explain +:mod:`pyramid` is a "dual-mode" framework: the tutorials explain how to create an application in terms of using either :term:`url dispatch` *or* :term:`traversal`. This chapter details how you might combine these two dispatch mechanisms, but we'll review how they work @@ -58,7 +58,7 @@ named by the ``view`` attribute is invoked. Typically, an application that uses only URL dispatch won't perform any configuration in ZCML that includes a ```` declaration and won't have any calls to -:meth:`repoze.bfg.configuration.Configurator.add_view` in its startup +:meth:`pyramid.configuration.Configurator.add_view` in its startup code. Traversal Only @@ -88,13 +88,13 @@ called when the URL ``/bazbuz`` is visited. An application that uses :term:`traversal` exclusively to map URLs to code usually won't have any ZCML ```` declarations nor will it make any calls to the -:meth:`repoze.bfg.configuration.Configurator.add_route` method. +:meth:`pyramid.configuration.Configurator.add_route` method. Hybrid Applications ------------------- Either traversal or url dispatch alone can be used to create a -:mod:`repoze.bfg` application. However, it is also possible to +:mod:`pyramid` application. However, it is also possible to combine the concepts of traversal and url dispatch when building an application: the result is a hybrid application. In a hybrid application, traversal is performed *after* a particular route has @@ -173,11 +173,11 @@ match is straightforward. When a route is matched: argument, the *global* :term:`root factory` will be called to generate a :term:`root` object. The global root factory is the callable implied by the ``root_factory`` argument passed to - :class:`repoze.bfg.configuration.Configurator` at application + :class:`pyramid.configuration.Configurator` at application startup time. - If a ``root_factory`` argument is not provided to the - :class:`repoze.bfg.configuration.Configurator` at startup time, a + :class:`pyramid.configuration.Configurator` at startup time, a *default* root factory is used. The default root factory is used to generate a root object. @@ -224,7 +224,7 @@ invoking a specific view callable named directly within the matched route's configuration. Because the pattern of the above route ends with ``*traverse``, when this -route configuration is matched during a request, :mod:`repoze.bfg` +route configuration is matched during a request, :mod:`pyramid` will attempt to use :term:`traversal` against the :term:`root` object implied by the :term:`root factory` implied by the route's configuration. Once :term:`traversal` has found a :term:`context`, @@ -281,7 +281,7 @@ to do. We could have also used our ``root_factory`` callable as the ``root_factory`` argument of the - :class:`repoze.bfg.configuration.Configurator` constructor instead + :class:`pyramid.configuration.Configurator` constructor instead of associating it with a particular route inside the route's configuration. Every hybrid route configuration that is matched but which does *not* name a ``factory``` attribute will use the use @@ -299,7 +299,7 @@ returned from the root factory. In the above example, the If the URL that matched a route with the pattern ``:foo/:bar/*traverse``, is ``http://example.com/one/two/a/b/c``, the traversal path used against the root object will be ``a/b/c``. As a result, -:mod:`repoze.bfg` will attempt to traverse through the edges ``a``, +:mod:`pyramid` will attempt to traverse through the edges ``a``, ``b``, and ``c``, beginning at the root object. In our above example, this particular set of traversal steps will mean @@ -397,7 +397,7 @@ Using the ``traverse`` Argument In a Route Definition Rather than using the ``*traverse`` remainder marker in a pattern, you can use the ``traverse`` argument to the -:meth:`repoze.bfg.configuration.Configurator.add_route`` method or the +:meth:`pyramid.configuration.Configurator.add_route`` method or the ``traverse`` attribute of the :ref:`route_directive` ZCML directive. (either method is equivalent). @@ -481,8 +481,8 @@ Using ``*subpath`` in a Route Pattern There are certain extremely rare cases when you'd like to influence the traversal :term:`subpath` when a route matches without actually performing traversal. For instance, the -:func:`repoze.bfg.wsgi.wsgiapp2` decorator and the -:class:`repoze.bfg.view.static` helper attempt to compute +:func:`pyramid.wsgi.wsgiapp2` decorator and the +:class:`pyramid.view.static` helper attempt to compute ``PATH_INFO`` from the request's subpath, so it's useful to be able to influence this value. @@ -501,7 +501,7 @@ commonly in route declarations that look like this: /> Where ``.views.static_view`` is an instance of -:class:`repoze.bfg.view.static`. This effectively tells the static +:class:`pyramid.view.static`. This effectively tells the static helper to traverse everything in the subpath as a filename. Corner Cases diff --git a/docs/narr/i18n.rst b/docs/narr/i18n.rst index cab327bb8..aaa1962e8 100644 --- a/docs/narr/i18n.rst +++ b/docs/narr/i18n.rst @@ -15,14 +15,11 @@ one language or cultural context. :term:`Localization` (l10n) is the process of displaying the user interface of an internationalized application in a *particular* language or cultural context. -:mod:`repoze.bfg` offers internationalization and localization +:mod:`pyramid` offers internationalization and localization subsystems that can be used to translate the text of buttons, error messages and other software- and template-defined values into the native language of a user of your application. -.. note: The APIs and functionality described in this chapter are new - as of :mod:`repoze.bfg` version 1.3. - .. index:: single: translation string pair: domain; translation @@ -38,18 +35,18 @@ text values into the languages used by your application's users. This markup creates a :term:`translation string`. A translation string is an object that behaves mostly like a normal Unicode object, except that it also carries around extra information related to its job as part of -the :mod:`repoze.bfg` translation machinery. +the :mod:`pyramid` translation machinery. Using The ``TranslationString`` Class ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The most primitive way to create a translation string is to use the -:class:`repoze.bfg.i18n.TranslationString` callable: +:class:`pyramid.i18n.TranslationString` callable: .. code-block:: python :linenos: - from repoze.bfg.i18n import TranslationString + from pyramid.i18n import TranslationString ts = TranslationString('Add') This creates a Unicode-like object that is a TranslationString. @@ -62,7 +59,7 @@ This creates a Unicode-like object that is a TranslationString. :term:`Django` i18n, using a TranslationString is a lot like using "lazy" versions of related gettext APIs. -The first argument to :class:`repoze.bfg.i18n.TranslationString` is +The first argument to :class:`pyramid.i18n.TranslationString` is the ``msgid``; it is required. It represents the key into the translation mappings provided by a particular localization. The ``msgid`` argument must be a Unicode object or an ASCII string. The @@ -71,7 +68,7 @@ msgid may optionally contain *replacement markers*. For instance: .. code-block:: python :linenos: - from repoze.bfg.i18n import TranslationString + from pyramid.i18n import TranslationString ts = TranslationString('Add ${number}') Within the string above, ``${number}`` is a replacement marker. It @@ -82,7 +79,7 @@ replacement marker itself: .. code-block:: python :linenos: - from repoze.bfg.i18n import TranslationString + from pyramid.i18n import TranslationString ts = TranslationString('Add ${number}', mapping={'number':1}) Any number of replacement markers can be present in the msgid value, @@ -97,7 +94,7 @@ translations of the same msgid, in case they conflict. .. code-block:: python :linenos: - from repoze.bfg.i18n import TranslationString + from pyramid.i18n import TranslationString ts = TranslationString('Add ${number}', mapping={'number':1}, domain='form') @@ -126,7 +123,7 @@ identifiers unrelated to their default text: .. code-block:: python :linenos: - from repoze.bfg.i18n import TranslationString + from pyramid.i18n import TranslationString ts = TranslationString('add-number', default='Add ${number}', domain='form', mapping={'number':1}) @@ -140,7 +137,7 @@ Using the ``TranslationStringFactory`` Class ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Another way to generate a translation string is to use the -:attr:`repoze.bfg.i18n.TranslationStringFactory` object. This object +:attr:`pyramid.i18n.TranslationStringFactory` object. This object is a *translation string factory*. Basically a translation string factory presets the ``domain`` value of any :term:`translation string` generated by using it. For example: @@ -148,8 +145,8 @@ generated by using it. For example: .. code-block:: python :linenos: - from repoze.bfg.i18n import TranslationStringFactory - _ = TranslationStringFactory('bfg') + from pyramid.i18n import TranslationStringFactory + _ = TranslationStringFactory('pyramid') ts = _('Add ${number}', msgid='add-number', mapping={'number':1}) .. note:: We assigned the translation string factory to the name @@ -157,26 +154,26 @@ generated by using it. For example: file generation tools. After assigning ``_`` to the result of a -:func:`repoze.bfg.i18n.TranslationStringFactory`, the subsequent -result of calling ``_`` will be a -:class:`repoze.bfg.i18n.TranslationString` instance. Even though a -``domain`` value was not passed to ``_`` (as would have been necessary -if the :class:`repoze.bfg.i18n.TranslationString` constructor were -used instead of a translation string factory), the ``domain`` -attribute of the resulting translation string will be ``bfg``. As a -result, the previous code example is completely equivalent (except for -spelling) to: +:func:`pyramid.i18n.TranslationStringFactory`, the subsequent result +of calling ``_`` will be a :class:`pyramid.i18n.TranslationString` +instance. Even though a ``domain`` value was not passed to ``_`` (as +would have been necessary if the +:class:`pyramid.i18n.TranslationString` constructor were used instead +of a translation string factory), the ``domain`` attribute of the +resulting translation string will be ``pyramid``. As a result, the +previous code example is completely equivalent (except for spelling) +to: .. code-block:: python :linenos: - from repoze.bfg.i18n import TranslationString as _ + from pyramid.i18n import TranslationString as _ ts = _('Add ${number}', msgid='add-number', mapping={'number':1}, - domain='bfg') + domain='pyramid') You can set up your own translation string factory much like the one provided above by using the -:class:`repoze.bfg.i18n.TranslationStringFactory` class. For example, +:class:`pyramid.i18n.TranslationStringFactory` class. For example, if you'd like to create a translation string factory which presets the ``domain`` value of generated translation strings to ``form``, you'd do something like this: @@ -184,7 +181,7 @@ do something like this: .. code-block:: python :linenos: - from repoze.bfg.i18n import TranslationStringFactory + from pyramid.i18n import TranslationStringFactory _ = TranslationStringFactory('form') ts = _('Add ${number}', msgid='add-number', mapping={'number':1}) @@ -193,7 +190,7 @@ factory is best practice. Using your own unique translation domain allows another person to reuse your application without needing to merge your translation files with his own. Instead, he can just include your package's :term:`translation directory` via the -:meth:`repoze.bfg.configuration.Configurator.add_translation_dirs` +:meth:`pyramid.configuration.Configurator.add_translation_dirs` method. .. note:: @@ -210,7 +207,7 @@ method. Working With ``gettext`` Translation Files ------------------------------------------ -The basis of :mod:`repoze.bfg` translation services is +The basis of :mod:`pyramid` translation services is GNU :term:`gettext`. Once your application source code files and templates are marked up with translation markers, you can work on translations by creating various kinds of gettext files. @@ -218,7 +215,7 @@ by creating various kinds of gettext files. .. note:: The steps a developer must take to work with :term:`gettext` - :term:`message catalog` files within a :mod:`repoze.bfg` + :term:`message catalog` files within a :mod:`pyramid` application are very similar to the steps a :term:`Pylons` developer must take to do the same. See the `Pylons internationalization documentation @@ -249,7 +246,7 @@ GNU gettext uses three types of files in the translation framework, makes the localized program run faster. The tool for working with :term:`gettext` translation files related to -a :mod:`repoze.bfg` application is :term:`Babel`. +a :mod:`pyramid` application is :term:`Babel`. .. index:: single: Babel @@ -262,13 +259,13 @@ Installing Babel In order for the commands related to working with ``gettext`` translation files to work properly, you will need to have :term:`Babel` installed into the same environment in which -:mod:`repoze.bfg` is installed. +:mod:`pyramid` is installed. Installation on UNIX ++++++++++++++++++++ If the :term:`virtualenv` into which you've installed your -:mod:`repoze.bfg` application lives in ``/my/virtualenv``, you can +:mod:`pyramid` application lives in ``/my/virtualenv``, you can install Babel like so: .. code-block:: bash @@ -280,7 +277,7 @@ Installation on Windows +++++++++++++++++++++++ If the :term:`virtualenv` into which you've installed your -:mod:`repoze.bfg` application lives in ``C:\my\virtualenv``, you can +:mod:`pyramid` application lives in ``C:\my\virtualenv``, you can install Babel like so: .. code-block:: bash @@ -336,7 +333,7 @@ Extracting Messages from Code and Templates Once :term:`Babel` is installed and your application's ``setup.py`` file has the correct message extractor references, you may extract a message catalog template from the code and :term:`Chameleon` templates -which reside in your :mod:`repoze.bfg` application. You run a +which reside in your :mod:`pyramid` application. You run a ``setup.py`` command to extract the messages: .. code-block:: bash @@ -356,11 +353,11 @@ The name ``myapplication`` above in the filename ``myapplication.pot`` denotes the :term:`translation domain` of the translations that must be performed to localize your application. By default, the translation domain is the :term:`project` name of your -:mod:`repoze.bfg` application. +:mod:`pyramid` application. To change the translation domain of the extracted messages in your project, edit the ``setup.cfg`` file of your application, The default -``setup.cfg`` file of a Paster-generated :mod:`repoze.bfg` application +``setup.cfg`` file of a Paster-generated :mod:`pyramid` application has stanzas in it that look something like the following: .. code-block:: ini @@ -439,7 +436,7 @@ Once the file is there, it can be worked on by a human translator. One tool which may help with this is `Poedit `_. -Note that :mod:`repoze.bfg` itself ignores the existence of all +Note that :mod:`pyramid` itself ignores the existence of all ``.po`` files. For a running application to have translations available, a ``.mo`` file must exist. See :ref:`compiling_message_catalog`. @@ -480,7 +477,7 @@ translations, compile ``.po`` files to ``.mo`` files:: This will create a ``.mo`` file for each ``.po`` file in your application. As long as the :term:`translation directory` in which the ``.mo`` file ends up in is configured into your application, these -translations will be available to :mod:`repoze.bfg`. +translations will be available to :mod:`pyramid`. .. index:: single: localizer @@ -491,8 +488,8 @@ Using a Localizer A :term:`localizer` is an object that allows you to perform translation or pluralization "by hand" in an application. You may use -the :func:`repoze.bfg.i18n.get_localizer` function to obtain a -:term:`localizer`. :func:`repoze.bfg.i18n.get_localizer`. This +the :func:`pyramid.i18n.get_localizer` function to obtain a +:term:`localizer`. :func:`pyramid.i18n.get_localizer`. This function will return either the localizer object implied by the active :term:`locale negotiator` or a default localizer object if no explicit locale negotiator is registered. @@ -500,7 +497,7 @@ locale negotiator is registered. .. code-block:: python :linenos: - from repoze.bfg.i18n import get_localizer + from pyramid.i18n import get_localizer def aview(request): locale = get_localizer(request) @@ -521,20 +518,21 @@ translation in a view component of an application might look like so: .. code-block:: python :linenos: - from repoze.bfg.i18n import get_localizer - from repoze.bfg.i18n import TranslationString + from pyramid.i18n import get_localizer + from pyramid.i18n import TranslationString - ts = TranslationString('Add ${number}', mapping={'number':1}, domain='bfg') + ts = TranslationString('Add ${number}', mapping={'number':1}, + domain='pyramid') def aview(request): localizer = get_localizer(request) translated = localizer.translate(ts) # translation string # ... use translated ... -The :func:`repoze.bfg.i18n.get_localizer` function will return a -:class:`repoze.bfg.i18n.Localizer` object bound to the locale name +The :func:`pyramid.i18n.get_localizer` function will return a +:class:`pyramid.i18n.Localizer` object bound to the locale name represented by the request. The translation returned from its -:meth:`repoze.bfg.i18n.Localizer.translate` method will depend on the +:meth:`pyramid.i18n.Localizer.translate` method will depend on the ``domain`` attribute of the provided translation string as well as the locale of the localizer. @@ -575,7 +573,7 @@ information attached to those objects is ignored. .. code-block:: python :linenos: - from repoze.bfg.i18n import get_localizer + from pyramid.i18n import get_localizer def aview(request): localizer = get_localizer(request) @@ -593,12 +591,12 @@ Obtaining the Locale Name for a Request --------------------------------------- You can obtain the locale name related to a request by using the -:func:`repoze.bfg.i18n.get_locale_name` function. +:func:`pyramid.i18n.get_locale_name` function. .. code-block:: python :linenos: - from repoze.bfg.i18n import get_locale_name + from pyramid.i18n import get_locale_name def aview(request): locale_name = get_locale_name(request) @@ -609,17 +607,17 @@ locale negotiator returns ``None``. You can change the default locale name by changing the ``default_locale_name`` setting; see :ref:`default_locale_name_setting`. -Once :func:`repoze.bfg.i18n.get_locale_name` is first run, the locale +Once :func:`pyramid.i18n.get_locale_name` is first run, the locale name is stored on the request object. Subsequent calls to -:func:`repoze.bfg.i18n.get_locale_name` will return the stored locale +:func:`pyramid.i18n.get_locale_name` will return the stored locale name without invoking the :term:`locale negotiator`. To avoid this -caching, you can use the :func:`repoze.bfg.i18n.negotiate_locale_name` +caching, you can use the :func:`pyramid.i18n.negotiate_locale_name` function: .. code-block:: python :linenos: - from repoze.bfg.i18n import negotiate_locale_name + from pyramid.i18n import negotiate_locale_name def aview(request): locale_name = negotiate_locale_name(request) @@ -630,7 +628,7 @@ You can also obtain the locale name related to a request using the .. code-block:: python :linenos: - from repoze.bfg.i18n import get_localizer + from pyramid.i18n import get_localizer def aview(request): localizer = get_localizer(request) @@ -638,7 +636,7 @@ You can also obtain the locale name related to a request using the Obtaining the locale name as an attribute of a localizer is equivalent to obtaining a locale name by calling the -:func:`repoze.bfg.i18n.get_locale_name` function. +:func:`pyramid.i18n.get_locale_name` function. .. index:: single: date and currency formatting (i18n) @@ -647,7 +645,7 @@ to obtaining a locale name by calling the Performing Date Formatting and Currency Formatting -------------------------------------------------- -:mod:`repoze.bfg` does not itself perform date and currency formatting +:mod:`pyramid` does not itself perform date and currency formatting for different locales. However, :term:`Babel` can help you do this via the :class:`babel.core.Locale` class. The `Babel documentation for this class @@ -657,7 +655,7 @@ related locale operations. See :ref:`installing_babel` for information about how to install Babel. The :class:`babel.core.Locale` class requires a :term:`locale name` as -an argument to its constructor. You can use :mod:`repoze.bfg` APIs to +an argument to its constructor. You can use :mod:`pyramid` APIs to obtain the locale name for a request to pass to the :class:`babel.core.Locale` constructor; see :ref:`obtaining_the_locale_name`. For example: @@ -666,7 +664,7 @@ obtain the locale name for a request to pass to the :linenos: from babel.core import Locale - from repoze.bfg.i18n import get_locale_name + from pyramid.i18n import get_locale_name def aview(request): locale_name = get_locale_name(request) @@ -714,20 +712,20 @@ through translation before being rendered: .. 1.2.3 The features represented by attributes of the ``i18n`` namespace of -Chameleon will also consult the :mod:`repoze.bfg` translations. +Chameleon will also consult the :mod:`pyramid` translations. See `http://chameleon.repoze.org/docs/latest/i18n.html#the-i18n-namespace `_. .. note:: - Unlike when Chameleon is used outside of :mod:`repoze.bfg`, when it - is used *within* :mod:`repoze.bfg`, it does not support use of the + Unlike when Chameleon is used outside of :mod:`pyramid`, when it + is used *within* :mod:`pyramid`, it does not support use of the ``zope.i18n`` translation framework. Applications which use - :mod:`repoze.bfg` should use the features documented in this + :mod:`pyramid` should use the features documented in this chapter rather than ``zope.i18n``. -Third party :mod:`repoze.bfg` template renderers might not provide +Third party :mod:`pyramid` template renderers might not provide this support out of the box and may need special code to do an equivalent. For those, you can always use the more manual translation facility described in :ref:`performing_a_translation`. @@ -741,16 +739,16 @@ facility described in :ref:`performing_a_translation`. Localization-Related Deployment Settings ---------------------------------------- -A :mod:`repoze.bfg` application will have a ``default_locale_name`` +A :mod:`pyramid` application will have a ``default_locale_name`` setting. This value represents the :term:`default locale name` used when the :term:`locale negotiator` returns ``None``. Pass it to the -:mod:`repoze.bfg.configuration.Configurator` constructor at startup +:mod:`pyramid.configuration.Configurator` constructor at startup time: .. code-block:: python :linenos: - from repoze.bfg.configuration import Configurator + from pyramid.configuration import Configurator config = Configurator(settings={'default_locale_name':'de'}) You may alternately supply a ``default_locale_name`` via an @@ -769,13 +767,13 @@ application's Paster ``.ini`` file: If this value is not supplied via the Configurator constructor or via a Paste config file, it will default to ``en``. -If this setting is supplied within the :mod:`repoze.bfg` application +If this setting is supplied within the :mod:`pyramid` application ``.ini`` file, it will be available as a settings key: .. code-block:: python :linenos: - from repoze.bfg.setttings import get_settings + from pyramid.setttings import get_settings settings = get_settings() default_locale_name = settings['default_locale_name'] @@ -786,7 +784,7 @@ Other systems provide an API that returns the set of "available languages" as indicated by the union of all languages in all translation directories on disk at the time of the call to the API. -It is by design that :mod:`repoze.bfg` doesn't supply such an API. +It is by design that :mod:`pyramid` doesn't supply such an API. Instead, the application itself is responsible for knowing the "available languages". The rationale is this: any particular application deployment must always know which languages it should be translatable @@ -808,7 +806,7 @@ allowed to be translated to instead of relying on the framework to divine this information from translation directory file info. You can set up a system to allow a deployer to select available -languages based on convention by using the :mod:`repoze.bfg.settings` +languages based on convention by using the :mod:`pyramid.settings` mechanism: Allow a deployer to modify your application's PasteDeploy .ini file: @@ -824,7 +822,7 @@ Then as a part of the code of a custom :term:`locale negotiator`: .. code-block:: py - from repoze.bfg.settings import get_settings + from pyramid.settings import get_settings languages = get_settings()['available_languages'].split() This is only a suggestion. You can create your own "available @@ -840,7 +838,7 @@ languages" configuration scheme as necessary. Activating Translation ---------------------- -By default, a :mod:`repoze.bfg` application performs no translation. +By default, a :mod:`pyramid` application performs no translation. To turn translation on, you must: - add at least one :term:`translation directory` to your application. @@ -851,7 +849,7 @@ Adding a Translation Directory ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :term:`gettext` is the underlying machinery behind the -:mod:`repoze.bfg` translation machinery. A translation directory is a +:mod:`pyramid` translation machinery. A translation directory is a directory organized to be useful to :term:`gettext`. A translation directory usually includes a listing of language directories, each of which itself includes an ``LC_MESSAGES`` directory. Each @@ -862,7 +860,7 @@ to provide translations to your application. Adding a :term:`translation directory` registers all of its constituent :term:`message catalog` files (all of the ``.mo`` files found within all ``LC_MESSAGES`` directories within each locale -directory in the translation directory) within your :mod:`repoze.bfg` +directory in the translation directory) within your :mod:`pyramid` application to be available to use for translation services. You may add a translation directory to your application's @@ -871,7 +869,7 @@ configuration using either imperative configuration or ZCML. .. topic:: Using Imperative Configuration You can add a translation directory imperatively by using the - :meth:`repoze.bfg.configuration.Configurator.add_translation_dirs` + :meth:`pyramid.configuration.Configurator.add_translation_dirs` during application startup. For example: @@ -879,7 +877,7 @@ configuration using either imperative configuration or ZCML. .. code-block:: python :linenos: - from repoze.bfg.configuration import Configurator + from pyramid.configuration import Configurator config.begin() config.add_translation_dirs('my.application:locale/', 'another.application:locale/') @@ -887,7 +885,7 @@ configuration using either imperative configuration or ZCML. config.end() A message catalog in a translation directory added via - :meth:`repoze.bfg.configuration.Configurator.add_translation_dirs` + :meth:`pyramid.configuration.Configurator.add_translation_dirs` 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`. @@ -913,7 +911,7 @@ Setting the Locale When the *default locale negotiator* (see :ref:`default_locale_negotiator`) is in use, you can inform -:mod:`repoze.bfg` of the current locale name by doing any of these +:mod:`pyramid` of the current locale name by doing any of these things before any translations need to be performed: - Set the ``_LOCALE_`` attribute of the request to a valid locale name @@ -947,10 +945,10 @@ A :term:`locale negotiator` informs the operation of a :term:`localizer` by telling it what :term:`locale name` is related to a particular request. A locale negotiator is a bit of code which accepts a request and which returns a :term:`locale name`. It is -consulted when :meth:`repoze.bfg.i18n.Localizer.translate` or -:meth:`repoze.bfg.i18n.Localizer.pluralize` is invoked. It is also -consulted when :func:`repoze.bfg.i18n.get_locale_name` or -:func:`repoze.bfg.i18n.negotiate_locale_name` is invoked. +consulted when :meth:`pyramid.i18n.Localizer.translate` or +:meth:`pyramid.i18n.Localizer.pluralize` is invoked. It is also +consulted when :func:`pyramid.i18n.get_locale_name` or +:func:`pyramid.i18n.negotiate_locale_name` is invoked. .. _default_locale_negotiator: @@ -961,7 +959,7 @@ Most applications can make use of the default locale negotiator, which requires no additional coding or configuration. The default locale negotiator implementation named -:class:`repoze.bfg.i18n.default_locale_negotiator` uses the following +:class:`pyramid.i18n.default_locale_negotiator` uses the following set of steps to dermine the locale name. - First, the negotiator looks for the ``_LOCALE_`` attribute of the @@ -1005,7 +1003,7 @@ Here's an implementation of a simple locale negotiator: return locale_name If a locale negotiator returns ``None``, it signifies to -:mod:`repoze.bfg` that the default application locale name should be +:mod:`pyramid` that the default application locale name should be used. You may add your newly created locale negotiator to your application's @@ -1015,7 +1013,7 @@ configuration using either imperative configuration or ZCML. Pass an object which can act as the negotiator (or a :term:`dotted Python name` referring to the object) as the ``locale_negotiator`` - argument of the :class:`repoze.bfg.configuration.Configurator` + argument of the :class:`pyramid.configuration.Configurator` instance during application startup. For example: @@ -1023,11 +1021,11 @@ configuration using either imperative configuration or ZCML. .. code-block:: python :linenos: - from repoze.bfg.configuration import Configurator + from pyramid.configuration import Configurator config = Configurator(locale_negotiator=my_locale_negotiator) Alternately, use the - :meth:`repoze.bfg.configuration.Configurator.set_locale_negotiator` + :meth:`pyramid.configuration.Configurator.set_locale_negotiator` method. For example: @@ -1035,7 +1033,7 @@ configuration using either imperative configuration or ZCML. .. code-block:: python :linenos: - from repoze.bfg.configuration import Configurator + from pyramid.configuration import Configurator config = Configurator() config.begin() config.set_locale_negotiator(my_locale_negotiator) diff --git a/docs/narr/install.rst b/docs/narr/install.rst index 014a11d7e..5b6d810dd 100644 --- a/docs/narr/install.rst +++ b/docs/narr/install.rst @@ -1,6 +1,6 @@ .. _installing_chapter: -Installing :mod:`repoze.bfg` +Installing :mod:`pyramid` ============================ .. index:: @@ -10,22 +10,22 @@ Before You Install ------------------ You will need `Python `_ version 2.4 or better to -run :mod:`repoze.bfg`. +run :mod:`pyramid`. .. sidebar:: Python Versions - As of this writing, :mod:`repoze.bfg` has been tested under Python - 2.4.6, Python 2.5.4 and Python 2.6.2, and Python 2.7a1. To ensure - backwards compatibility, development of :mod:`repoze.bfg` is + As of this writing, :mod:`pyramid` has been tested under Python + 2.4.6, Python 2.5.4 and Python 2.6.2, and Python 2.7. To ensure + backwards compatibility, development of :mod:`pyramid` is currently done primarily under Python 2.4 and Python 2.5. - :mod:`repoze.bfg` does not run under any version of Python before + :mod:`pyramid` does not run under any version of Python before 2.4, and does not yet run under Python 3.X. -:mod:`repoze.bfg` is known to run on all popular Unix-like systems +:mod:`pyramid` is known to run on all popular Unix-like systems such as Linux, MacOS X, and FreeBSD as well as on Windows platforms. It is also known to run on Google's App Engine and :term:`Jython`. -:mod:`repoze.bfg` installation does not require the compilation of any +:mod:`pyramid` installation does not require the compilation of any C code, so you need only a Python interpreter that meets the requirements mentioned. @@ -60,7 +60,7 @@ Source Compile Method It's useful to use a Python interpreter that *isn't* the "system" Python interpreter to develop your software. The authors of -:mod:`repoze.bfg` tend not to use the system Python for development +:mod:`pyramid` tend not to use the system Python for development purposes; always a self-compiled one. Compiling Python is usually easy, and often the "system" Python is compiled with options that aren't optimal for web development. @@ -126,24 +126,24 @@ extensions `_. .. _installing_unix: -Installing :mod:`repoze.bfg` on a UNIX System +Installing :mod:`pyramid` on a UNIX System --------------------------------------------- -It is best practice to install :mod:`repoze.bfg` into a "virtual" +It is best practice to install :mod:`pyramid` into a "virtual" Python environment in order to obtain isolation from any "system" packages you've got installed in your Python version. This can be done by using the :term:`virtualenv` package. Using a virtualenv will -also prevent :mod:`repoze.bfg` from globally installing versions of +also prevent :mod:`pyramid` from globally installing versions of packages that are not compatible with your system Python. -To set up a virtualenv in which to install :mod:`repoze.bfg`, first +To set up a virtualenv in which to install :mod:`pyramid`, first ensure that :term:`setuptools` is installed. Invoke ``import setuptools`` within the Python interpreter you'd like to run -:mod:`repoze.bfg` under: +:mod:`pyramid` under: .. code-block:: text - [chrism@vitaminf bfg]$ python + [chrism@vitaminf pyramid]$ python Python 2.4.5 (#1, Aug 29 2008, 12:27:37) [GCC 4.0.1 (Apple Inc. build 5465)] on darwin Type "help", "copyright", "credits" or "license" for more information. @@ -218,15 +218,15 @@ following: .. code-block:: text - $ virtualenv --no-site-packages bfgenv - New python executable in bfgenv/bin/python + $ virtualenv --no-site-packages env + New python executable in env/bin/python Installing setuptools.............done. .. warning:: Using ``--no-site-packages`` when generating your virtualenv is *very important*. This flag provides the necessary isolation for running the set of packages required by - :mod:`repoze.bfg`. If you do not specify ``--no-site-packages``, - it's possible that :mod:`repoze.bfg` will not install properly into + :mod:`pyramid`. If you do not specify ``--no-site-packages``, + it's possible that :mod:`pyramid` will not install properly into the virtualenv, or, even if it does, may not run properly, depending on the packages you've already got installed into your Python's "main" site-packages dir. @@ -236,19 +236,18 @@ following: to create a virtualenv as a normal user. You should perform any following commands that mention a "bin" -directory from within the ``bfgenv`` virtualenv dir. +directory from within the ``env`` virtualenv dir. -Installing :mod:`repoze.bfg` Into the Virtual Python Environment +Installing :mod:`pyramid` Into the Virtual Python Environment ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -After you've got your ``bfgenv`` virtualenv installed, you may install -:mod:`repoze.bfg` itself using the following commands from within the -virtualenv (``bfgenv``) directory: +After you've got your ``env`` virtualenv installed, you may install +:mod:`pyramid` itself using the following commands from within the +virtualenv (``env``) directory: .. code-block:: text - $ bin/easy_install -i http://dist.repoze.org/bfg/current/simple \ - repoze.bfg + $ bin/easy_install pyramid This command will take longer than the previous ones to complete, as it downloads and installs a number of dependencies. @@ -258,7 +257,7 @@ downloads and installs a number of dependencies. .. _installing_windows: -Installing :mod:`repoze.bfg` on a Windows System +Installing :mod:`pyramid` on a Windows System ------------------------------------------------- #. Install, or find `Python 2.6 @@ -289,51 +288,50 @@ Installing :mod:`repoze.bfg` on a Windows System .. code-block:: text - c:\> c:\Python26\Scripts\virtualenv --no-site-packages bfgenv + c:\> c:\Python26\Scripts\virtualenv --no-site-packages env -#. Switch to the ``bfgenv`` directory: +#. Switch to the ``env`` directory: .. code-block:: text - c:\> cd bfgenv + c:\> cd env #. (Optional) Consider using ``bin\activate.bat`` to make your shell environment wired to use the virtualenv. #. Use ``easy_install`` pointed at the "current" index to get - :mod:`repoze.bfg` and its direct dependencies installed: + :mod:`pyramid` and its direct dependencies installed: .. code-block:: text - c:\bfgenv> Scripts\easy_install -i \ - http://dist.repoze.org/bfg/current/simple repoze.bfg + c:\env> Scripts\easy_install pyramid .. index:: single: installing on Google App Engine -Installing :mod:`repoze.bfg` on Google App Engine +Installing :mod:`pyramid` on Google App Engine ------------------------------------------------- :ref:`appengine_tutorial` documents the steps required to install a -:mod:`repoze.bfg` application on Google App Engine. +:mod:`pyramid` application on Google App Engine. -Installing :mod:`repoze.bfg` on Jython +Installing :mod:`pyramid` on Jython -------------------------------------- -:mod:`repoze.bfg` is known to work under :term:`Jython` version 2.5.1. +:mod:`pyramid` is known to work under :term:`Jython` version 2.5.1. Install :term:`Jython`, and then follow the installation steps for -:mod:`repoze.bfg` on your platform described in one of the sections +:mod:`pyramid` on your platform described in one of the sections entitled :ref:`installing_unix` or :ref:`installing_windows` above, replacing the ``python`` command with ``jython`` as necessary. The steps are exactly the same except you should use the ``jython`` command name instead of the ``python`` command name. -One caveat exists to using :mod:`repoze.bfg` under Jython: the +One caveat exists to using :mod:`pyramid` under Jython: the :term:`Chameleon` templating engine, which is the default templating -engine for :mod:`repoze.bfg` does not work on Jython. +engine for :mod:`pyramid` does not work on Jython. The ``repoze.bfg.jinja2`` distribution provides templating for -:mod:`repoze.bfg` using the :term:`Jinja2` templating system. You may +:mod:`pyramid` using the :term:`Jinja2` templating system. You may install it like so using the ``easy_install`` command for Jython: .. code-block:: python @@ -341,7 +339,7 @@ install it like so using the ``easy_install`` command for Jython: $ easy_install repoze.bfg.jinja2 Once this is done, you can use this command to get started with a -:mod:`repoze.bfg` sample application that uses the Jinja2 templating +:mod:`pyramid` sample application that uses the Jinja2 templating engine: .. code-block:: python @@ -354,10 +352,10 @@ about the ``paster create`` command. What Gets Installed ------------------- -When you ``easy_install`` :mod:`repoze.bfg`, various Zope libraries, +When you ``easy_install`` :mod:`pyramid`, various Zope libraries, various Chameleon libraries, WebOb, Paste, PasteScript, and PasteDeploy libraries are installed. Additionally, as chronicled in :ref:`project_narr`, PasteScript (aka *paster*) templates will be registered that make it easy to start a -new :mod:`repoze.bfg` project. +new :mod:`pyramid` project. diff --git a/docs/narr/introduction.rst b/docs/narr/introduction.rst index b13da0a0d..a50ea0f1f 100644 --- a/docs/narr/introduction.rst +++ b/docs/narr/introduction.rst @@ -6,7 +6,7 @@ single: frameworks vs. libraries single: framework -:mod:`repoze.bfg` Introduction +:mod:`pyramid` Introduction ============================== If they are judged only by differences in user interface, most web @@ -17,14 +17,14 @@ page served by another application might be a listing of songs. These applications probably won't serve the same set of customers. However, although they're not very similar on the surface, both a ledger-serving application and a song-serving application can be -written using :mod:`repoze.bfg`. +written using :mod:`pyramid`. -:mod:`repoze.bfg` is a very general open source Python web +:mod:`pyramid` is a very general open source Python web *framework*. As a framework, its primary job is to make it easier for a developer to create an arbitrary web application. The type of application being created isn't really important; it could be a spreadsheet, a corporate intranet, or an "oh-so-Web-2.0" social -networking platform. :mod:`repoze.bfg` is general enough that it can +networking platform. :mod:`pyramid` is general enough that it can be used in a wide variety of circumstances. .. sidebar:: Frameworks vs. Libraries @@ -44,60 +44,56 @@ be used in a wide variety of circumstances. own via a set of libraries if the framework provides a set of facilities that fits your application requirements. -The first release of :mod:`repoze.bfg` was made in July of 2008. +The first release of :mod:`pyramid` was made in July of 2008. Since its first release, we've tried to ensure that it maintains the following attributes: Simplicity - :mod:`repoze.bfg` attempts to be a *"pay only for what you eat"* + :mod:`pyramid` attempts to be a *"pay only for what you eat"* framework which delivers results even if you have only partial knowledge. Other frameworks may expect you to understand many concepts and technologies fully before you can be truly productive. - :mod:`repoze.bfg` doesn't force you to use any particular technology + :mod:`pyramid` doesn't force you to use any particular technology to produce an application, and we try to keep the core set of concepts you need to understand to a minimum. A Sense of Fun - Developing a :mod:`repoze.bfg` application should not feel + Developing a :mod:`pyramid` application should not feel "enterprisey". We like to keep things down-to-earth. Minimalism - :mod:`repoze.bfg` provides only the very basics: *URL to code + :mod:`pyramid` provides only the very basics: *URL to code mapping*, *templating*, *security*, and *resources*. There is not much more to the framework than these pieces: you are expected to provide the rest. Documentation - Because :mod:`repoze.bfg` is minimal, it's relatively easy to keep + Because :mod:`pyramid` is minimal, it's relatively easy to keep its documentation up-to-date, which is helpful to bring new developers up to speed. It's our goal that nothing remain - undocumented about :mod:`repoze.bfg`. + undocumented about :mod:`pyramid`. Speed - :mod:`repoze.bfg` is faster than many other popular Python web + :mod:`pyramid` is faster than many other popular Python web frameworks for common tasks such as templating and simple response generation. The "hardware is cheap" mantra has its limits when you're responsible for managing a great many machines: the fewer you need, the less pain you'll have. Familiarity - The :mod:`repoze.bfg` framework is a canonization of practices that + The :mod:`pyramid` framework is a canonization of practices that "fit the brains" of its authors. Trustability - :mod:`repoze.bfg` is developed conservatively and tested + :mod:`pyramid` is developed conservatively and tested exhaustively. *If it ain't tested, it's broke.* Every release of - :mod:`repoze.bfg` has 100% statement coverage via unit tests. + :mod:`pyramid` has 100% statement coverage via unit tests. Openness - Like :term:`Python`, the :mod:`repoze.bfg` software is distributed + Like :term:`Python`, the :mod:`pyramid` software is distributed under a `permissive open source license `_. -This book usually refers to the framework by its full package name, -:mod:`repoze.bfg`. However, it is often referred to as just "BFG" -(the "repoze-dot" dropped) in conversation. - .. index:: single: Repoze single: Agendaless Consulting @@ -106,7 +102,7 @@ This book usually refers to the framework by its full package name, What Is Repoze? --------------- -:mod:`repoze.bfg` is a member of the collection of software published +:mod:`pyramid` is a member of the collection of software published under the :term:`Repoze` "brand". :term:`Repoze` software is written by :term:`Agendaless Consulting` and a community of contributors. The `Repoze website `_ describes the Repoze brand in @@ -116,38 +112,41 @@ number of packages. Each package is useful in isolation. The ``repoze`` namespace package represents that the software is written by a notional community rather than representing a collection of software that is meant to be used as a unit. For example, even though -``repoze.bfg`` shares the same namespace as another popular Repoze +``pyramid`` shares the same namespace as another popular Repoze package, ``repoze.who``, these two packages are otherwise unrelated and can be used separately. .. index:: - single: repoze.bfg and other frameworks + single: pyramid and other frameworks single: Zope single: Pylons single: Django single: MVC -:mod:`repoze.bfg` and Other Web Frameworks +:mod:`pyramid` and Other Web Frameworks ------------------------------------------ -:mod:`repoze.bfg` was inspired by :term:`Zope`, :term:`Pylons` and -:term:`Django`. As a result, :mod:`repoze.bfg` borrows several +Until the end of 2010, :mod:`pyramid` was known as :mod:`repoze.bfg`; +it was merged into the Pylons project at the end of 2010. + +:mod:`pyramid` was inspired by :term:`Zope`, :term:`Pylons` and +:term:`Django`. As a result, :mod:`pyramid` borrows several concepts and features from each, combining them into a unique web framework. -Many features of :mod:`repoze.bfg` trace their origins back to -:term:`Zope`. Like Zope applications, :mod:`repoze.bfg` applications +Many features of :mod:`pyramid` trace their origins back to +:term:`Zope`. Like Zope applications, :mod:`pyramid` applications can be configured via a set of declarative configuration files. Like -Zope applications, :mod:`repoze.bfg` applications can be easily +Zope applications, :mod:`pyramid` applications can be easily extended: if you obey certain constraints, the application you produce can be reused, modified, re-integrated, or extended by third-party developers without forking the original application. The concepts of -:term:`traversal` and declarative security in :mod:`repoze.bfg` were +:term:`traversal` and declarative security in :mod:`pyramid` were pioneered first in Zope. -The :mod:`repoze.bfg` concept of :term:`URL dispatch` is inspired by +The :mod:`pyramid` 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 +:mod:`pyramid` is mostly policy-free. It makes no assertions about which database you should use, and its built-in templating facilities are included only for convenience. In essence, it only supplies a mechanism to map URLs to :term:`view` code, along with a set of @@ -155,44 +154,44 @@ conventions for calling those views. You are free to use third-party components that fit your needs in your applications. The concepts of :term:`view` and :term:`model` are used by -:mod:`repoze.bfg` mostly as they would be by Django. -:mod:`repoze.bfg` has a documentation culture more like Django's than +:mod:`pyramid` mostly as they would be by Django. +:mod:`pyramid` has a documentation culture more like Django's than like Zope's. -Like :term:`Pylons`, but unlike :term:`Zope`, a :mod:`repoze.bfg` +Like :term:`Pylons`, but unlike :term:`Zope`, a :mod:`pyramid` application developer may use completely imperative code to perform common framework configuration tasks such as adding a view or a route. In Zope, :term:`ZCML` is typically required for similar purposes. In :term:`Grok`, a Zope-based web framework, :term:`decorator` objects and class-level declarations are used for this purpose. -:mod:`repoze.bfg` supports :term:`ZCML` and decorator-based +:mod:`pyramid` supports :term:`ZCML` and decorator-based configuration, but does not require either. See :ref:`configuration_narr` for more information. Also unlike :term:`Zope` and unlike other "full-stack" frameworks such -as :term:`Django`, :mod:`repoze.bfg` makes no assumptions about which +as :term:`Django`, :mod:`pyramid` makes no assumptions about which persistence mechanisms you should use to build an application. Zope -applications are typically reliant on :term:`ZODB`; :mod:`repoze.bfg` +applications are typically reliant on :term:`ZODB`; :mod:`pyramid` allows you to build :term:`ZODB` applications, but it has no reliance on the ZODB software. Likewise, :term:`Django` tends to assume that you want to store your application's data in a relational database. -:mod:`repoze.bfg` makes no such assumption; it allows you to use a +:mod:`pyramid` makes no such assumption; it allows you to use a relational database but doesn't encourage or discourage the decision. Other Python web frameworks advertise themselves as members of a class of web frameworks named `model-view-controller `_ frameworks. Insofar as this term has been claimed to represent a class of web -frameworks, :mod:`repoze.bfg` also generally fits into this class. +frameworks, :mod:`pyramid` also generally fits into this class. -.. sidebar:: You Say BFG is MVC, But Where's The Controller? +.. sidebar:: You Say :mod:`pyramid` is MVC, But Where's The Controller? - The :mod:`repoze.bfg` authors believe that the MVC pattern just - doesn't really fit the web very well. In a :mod:`repoze.bfg` + The :mod:`pyramid` authors believe that the MVC pattern just + doesn't really fit the web very well. In a :mod:`pyramid` application, there are models, which store data, and views, which present the data stored in models. However, no facility provided by the framework actually maps to the concept of a "controller". - So :mod:`repoze.bfg` is actually an "MV" framework rather than an + So :mod:`pyramid` is actually an "MV" framework rather than an "MVC" framework. "MVC", however, is close enough as a general classification moniker for purposes of comparison with other web frameworks. diff --git a/docs/narr/models.rst b/docs/narr/models.rst index c6f896119..f2b3182a5 100644 --- a/docs/narr/models.rst +++ b/docs/narr/models.rst @@ -3,20 +3,20 @@ Models A :term:`model` class is typically a simple Python class defined in a module. References to these classes and instances of such classes are -omnipresent in :mod:`repoze.bfg`: +omnipresent in :mod:`pyramid`: -- Model instances make up the graph that :mod:`repoze.bfg` is +- Model instances make up the graph that :mod:`pyramid` is willing to walk over when :term:`traversal` is used. - The ``context`` and ``containment`` arguments to - :meth:`repoze.bfg.configuration.Configurator.add_view` often + :meth:`pyramid.configuration.Configurator.add_view` often reference a model class. - A :term:`root factory` returns a model instance. - A model instance is generated as a result of :term:`url dispatch` (see the ``factory`` argument to - :meth:`repoze.bfg.configuration.Configurator.add_route`). + :meth:`pyramid.configuration.Configurator.add_route`). - A model instance is exposed to :term:`view` code as the :term:`context` of a view. @@ -31,16 +31,16 @@ mutating that data. different notion of the definition of a "model". When using the API of common ORM packages, its conception of "model" is almost certainly not the same conception of "model" used by - :mod:`repoze.bfg`. In particular, it can be unnatural to think of - :mod:`repoze.bfg` model objects as "models" if you develop your + :mod:`pyramid`. In particular, it can be unnatural to think of + :mod:`pyramid` model objects as "models" if you develop your application using :term:`traversal` and a relational database. When you develop such applications, the object graph *might* be composed completely of "model" objects (as defined by the ORM) but it also - might not be. The things that :mod:`repoze.bfg` refers to as + might not be. The things that :mod:`pyramid` refers to as "models" in such an application may instead just be stand-ins that perform a query and generate some wrapper *for* an ORM "model" or set of ORM models. This naming overlap is slightly unfortunate. - However, many :mod:`repoze.bfg` applications (especially ones which + However, many :mod:`pyramid` applications (especially ones which use :term:`ZODB`) do indeed traverse a graph full of literal model nodes. Each node in the graph is a separate persistent object that is stored within a database. This was the use case considered when @@ -200,10 +200,10 @@ Defining a Graph of Model Instances for Traversal ------------------------------------------------- When :term:`traversal` is used (as opposed to a purely :term:`url -dispatch` based application), :mod:`repoze.bfg` expects to be able to +dispatch` based application), :mod:`pyramid` expects to be able to traverse a graph composed of model instances. Traversal begins at a root model, and descends into the graph recursively via each found -model's ``__getitem__`` method. :mod:`repoze.bfg` imposes the +model's ``__getitem__`` method. :mod:`pyramid` imposes the following policy on model instance nodes in the graph: - Nodes which contain other nodes (aka "container" nodes) must supply @@ -238,13 +238,13 @@ Location-Aware Model Instances :mod:`repoze.bfg.traversalwrapper` package (available via `SVN `_), then register its ``ModelGraphTraverser`` as the traversal policy, rather - than the default :mod:`repoze.bfg` traverser. The package contains + than the default :mod:`pyramid` traverser. The package contains instructions. - Once :mod:`repoze.bfg` is configured with this feature, you will no + Once :mod:`pyramid` 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 + :mod:`pyramid` 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 @@ -255,7 +255,7 @@ 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 +In order for :mod:`pyramid` 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 @@ -289,9 +289,9 @@ and so on. .. warning:: If your root model object has a ``__name__`` argument that is not ``None`` or the empty string, URLs returned by the - :func:`repoze.bfg.url.model_url` function and paths generated by - the :func:`repoze.bfg.traversal.model_path` and - :func:`repoze.bfg.traversal.model_path_tuple` APIs will be + :func:`pyramid.url.model_url` function and paths generated by + the :func:`pyramid.traversal.model_path` and + :func:`pyramid.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). @@ -300,7 +300,7 @@ and so on. single: model API functions single: url generation (traversal) -:mod:`repoze.bfg` API Functions That Act Against Models +:mod:`pyramid` API Functions That Act Against Models ------------------------------------------------------- A model instance is used as the :term:`context` argument provided to a @@ -317,8 +317,8 @@ conveniently locate one object "inside" another. Some APIs in :ref:`security_module` accept a model object as a parameter. For example, the -:func:`repoze.bfg.security.has_permission` API accepts a "context" (a +:func:`pyramid.security.has_permission` API accepts a "context" (a model object) as one of its arguments; the ACL is obtained from this model or one of its ancestors. Other APIs in the -:mod:`repoze.bfg.security` module also accept :term:`context` as an +:mod:`pyramid.security` module also accept :term:`context` as an argument, and a context is always a model. diff --git a/docs/narr/project.rst b/docs/narr/project.rst index acd55ea55..0e18f0924 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -1,13 +1,13 @@ .. _project_narr: -Creating a :mod:`repoze.bfg` Project +Creating a :mod:`pyramid` Project ==================================== -It's possible to create a :mod:`repoze.bfg` application completely +It's possible to create a :mod:`pyramid` application completely manually, but it's usually more convenient to use a template to -generate a basic :mod:`repoze.bfg` application structure. +generate a basic :mod:`pyramid` application structure. -:mod:`repoze.bfg` comes with templates that you can use to generate a +:mod:`pyramid` comes with templates that you can use to generate a project. Each template makes different configuration assumptions about what type of application you're trying to construct. @@ -17,17 +17,17 @@ templates". .. index:: single: paster templates - single: bfg_starter paster template - single: bfg_zodb paster template - single: bfg_alchemy paster template - single: bfg_routesalchemy paster template + single: pyramid_starter paster template + single: pyramid_zodb paster template + single: pyramid_alchemy paster template + single: pyramid_routesalchemy paster template .. _additional_paster_templates: -Paster Templates Included with :mod:`repoze.bfg` +Paster Templates Included with :mod:`pyramid` ------------------------------------------------ -The convenience ``paster`` templates included with :mod:`repoze.bfg` +The convenience ``paster`` templates included with :mod:`pyramid` differ from each other on two axes: - the persistence mechanism they offer (no persistence mechanism, @@ -38,17 +38,17 @@ differ from each other on two axes: The included templates are these: -``bfg_starter`` +``pyramid_starter`` URL mapping via :term:`traversal` and no persistence mechanism. -``bfg_zodb`` +``pyramid_zodb`` URL mapping via :term:`traversal` and persistence via :term:`ZODB` -``bfg_routesalchemy`` +``pyramid_routesalchemy`` URL mapping via :term:`URL dispatch` and persistence via :term:`SQLAlchemy` -``bfg_alchemy`` +``pyramid_alchemy`` URL mapping via :term:`traversal` and persistence via :term:`SQLAlchemy` @@ -72,26 +72,26 @@ Creating the Project In :ref:`installing_chapter`, you created a virtual Python environment via the ``virtualenv`` command. To start a -:mod:`repoze.bfg` :term:`project`, use the ``paster`` facility +:mod:`pyramid` :term:`project`, use the ``paster`` facility installed within the virtualenv. In :ref:`installing_chapter` we -called the virtualenv directory ``bfgenv``; the following command +called the virtualenv directory ``env``; the following command assumes that our current working directory is that directory. -We'll choose the ``bfg_starter`` template for this purpose. +We'll choose the ``pyramid_starter`` template for this purpose. .. code-block:: text - $ bin/paster create -t bfg_starter + $ bin/paster create -t pyramid_starter The above command uses the ``paster`` command to create a project -using the ``bfg_starter`` template. The ``create`` version of paster -invokes the creation of a project from a template. To use a different -template, such as ``bfg_routesalchemy``, you'd just change the last -argument. For example: +using the ``pyramid_starter`` template. The ``create`` version of +paster invokes the creation of a project from a template. To use a +different template, such as ``pyramid_routesalchemy``, you'd just +change the last argument. For example: .. code-block:: text - $ bin/paster create -t bfg_routesalchemy + $ bin/paster create -t pyramid_routesalchemy ``paster create`` will ask you a single question: the *name* of the project. You should use a string without spaces and with only letters @@ -100,23 +100,23 @@ project we name ``MyProject``: .. code-block:: text - $ bin/paster create -t bfg_starter + $ bin/paster create -t pyramid_starter Selected and implied templates: - repoze.bfg#bfg repoze.bfg starter project + pyramid#bfg pyramid starter project Enter project name: MyProject Variables: egg: MyProject package: myproject project: MyProject - Creating template bfg + Creating template pyramid Creating directory ./MyProject # ... more output ... - Running /Users/chrism/projects/repoze/bfg/bin/python setup.py egg_info + Running /Users/chrism/projects/pyramid/bin/python setup.py egg_info .. note:: You can skip the interrogative question about a project name during ``paster create`` by adding the project name to the - command line, e.g. ``paster create -t bfg_starter MyProject``. + command line, e.g. ``paster create -t pyramid_starter MyProject``. As a result of invoking the ``paster create`` command, a project is created in a directory named ``MyProject``. That directory is a @@ -133,7 +133,7 @@ and debug your application. The ``MyProject`` project directory contains an additional subdirectory named ``myproject`` (note the case difference) representing a Python :term:`package` which holds very simple -:mod:`repoze.bfg` sample code. This is where you'll edit your +:mod:`pyramid` sample code. This is where you'll edit your application's Python code and templates. .. index:: @@ -203,7 +203,7 @@ Here's sample output from a test run: The tests themselves are found in the ``tests.py`` module in your ``paster create`` -generated project. Within a project generated by -the ``bfg_starter`` template, a single sample test exists. +the ``pyramid_starter`` template, a single sample test exists. .. index:: single: interactive shell @@ -215,7 +215,7 @@ The Interactive Shell Once you've installed your program for development using ``setup.py develop``, you can use an interactive Python shell to examine your -:mod:`repoze.bfg` application :term:`model` and :term:`view` objects +:mod:`pyramid` application :term:`model` and :term:`view` objects from a Python prompt. To do so, use the ``paster`` shell command with the ``bfgshell`` argument: @@ -241,7 +241,7 @@ the name ``main`` as a section name: .. code-block:: text - [chrism@vitaminf bfgshellenv]$ ../bin/paster --plugin=repoze.bfg bfgshell \ + [chrism@vitaminf bfgshellenv]$ ../bin/paster --plugin=pyramid bfgshell \ MyProject.ini main Python 2.4.5 (#1, Aug 29 2008, 12:27:37) [GCC 4.0.1 (Apple Inc. build 5465)] on darwin @@ -250,7 +250,7 @@ the name ``main`` as a section name: .. note:: You *might* get away without passing - ``--plugin=repoze.bfg`` to the bfgshell command. + ``--plugin=pyramid`` to the bfgshell command. If you have `IPython `_ installed in the interpreter you use to invoke the ``paster`` command, @@ -262,12 +262,12 @@ standard Python interpreter shell unconditionally. .. code-block:: text - [chrism@vitaminf bfgshellenv]$ ../bin/paster --plugin=repoze.bfg bfgshell \ + [chrism@vitaminf bfgshellenv]$ ../bin/paster --plugin=pyramid bfgshell \ --disable-ipython MyProject.ini main You should always use a section name argument that refers to the actual ``app`` section within the Paste configuration file that points -at your :mod:`repoze.bfg` application *without any middleware +at your :mod:`pyramid` application *without any middleware wrapping*. In particular, a section name is inappropriate as the second argument to "bfgshell" if the configuration section it names is a ``pipeline`` rather than an ``app``. For example, if you have the @@ -292,7 +292,7 @@ The command you use to invoke the interactive shell should be: .. code-block:: text - [chrism@vitaminf bfgshellenv]$ ../bin/paster --plugin=repoze.bfg bfgshell \ + [chrism@vitaminf bfgshellenv]$ ../bin/paster --plugin=pyramid bfgshell \ MyProject.ini myapp If you use ``main`` as the section name argument instead of ``myapp`` @@ -330,14 +330,14 @@ Here's sample output from a run of ``paster serve``: Starting server in PID 16601. serving on 0.0.0.0:6543 view at http://127.0.0.1:6543 -By default, :mod:`repoze.bfg` applications generated from a ``paster`` +By default, :mod:`pyramid` applications generated from a ``paster`` template will listen on TCP port 6543. During development, it's often useful to run ``paster serve`` using its ``--reload`` option. When ``--reload`` is passed to ``paster serve``, changes to any Python module your project uses will cause the server to restart. This typically makes development easier, as -changes to Python code made within a :mod:`repoze.bfg` application is +changes to Python code made within a :mod:`pyramid` application is not put into effect until the server restarts. For example: @@ -357,16 +357,16 @@ runtime behavior, see :ref:`environment_chapter`. Using an Alternate WSGI Server ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The code generated by :mod:`repoze.bfg` ``paster`` templates assumes +The code generated by :mod:`pyramid` ``paster`` templates assumes that you will be using the ``paster serve`` command to start your application while you do development. However, ``paster serve`` is by -no means the only way to start up and serve a :mod:`repoze.bfg` +no means the only way to start up and serve a :mod:`pyramid` application. As we saw in :ref:`configuration_narr`, ``paster serve`` -needn't be invoked at all to run a :mod:`repoze.bfg` application. The -use of ``paster serve`` to run a :mod:`repoze.bfg` application is +needn't be invoked at all to run a :mod:`pyramid` application. The +use of ``paster serve`` to run a :mod:`pyramid` application is purely conventional based on the output of its ``paster`` templates. -Any :term:`WSGI` server is capable of running a :mod:`repoze.bfg` +Any :term:`WSGI` server is capable of running a :mod:`pyramid` application. Some WSGI servers don't require the :term:`PasteDeploy` framework's ``paster serve`` command to do server process management at all. Each :term:`WSGI` server has its own documentation about how @@ -376,7 +376,7 @@ concepts are largely the same, whatever server you happen to use. One popular production alternative to a ``paster``-invoked server is :term:`mod_wsgi`. You can also use :term:`mod_wsgi` to serve your -:mod:`repoze.bfg` application using the Apache web server rather than +:mod:`pyramid` application using the Apache web server rather than any "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 a ``paster serve`` @@ -393,7 +393,7 @@ your browser like what is displayed in the following image: .. image:: project.png This is the page shown by default when you visit an unmodified -``paster create`` -generated ``bfg_starter`` application in a browser. +``paster create`` -generated ``pyramid_starter`` application in a browser. .. index:: single: project structure @@ -401,11 +401,11 @@ This is the page shown by default when you visit an unmodified The Project Structure --------------------- -Our generated :mod:`repoze.bfg` ``bfg_starter`` application is a +Our generated :mod:`pyramid` ``pyramid_starter`` application is a setuptools :term:`project` (named ``MyProject``), which contains a Python :term:`package` (which is *also* named ``myproject``, but lowercased; the paster template generates a project which contains a -package that shares its name except for case). All :mod:`repoze.bfg` +package that shares its name except for case). All :mod:`pyramid` ``paster`` -generated projects share a similar structure. The ``MyProject`` project we've generated has the following directory @@ -480,7 +480,7 @@ shared by all the applications, servers and :term:`middleware` defined within the configuration file. By default it contains one key ``debug``, which is set to ``true``. This key is used by various components to decide whether to act in a "debugging" mode. -``repoze.bfg`` itself does not do anything at all with this parameter, +``pyramid`` itself does not do anything at all with this parameter, and neither does any template-generated application. The ``[app:main]`` section represents configuration for your @@ -529,7 +529,7 @@ module). You can provide startup-time configuration parameters to your application by requiring more settings in this section. The ``reload_templates`` setting in the ``[app:main]`` section is a -:mod:`repoze.bfg` -specific setting which is passed into the +:mod:`pyramid` -specific setting which is passed into the framework. If it exists, and its value is ``true``, :term:`Chameleon` template changes will not require an application restart to be detected. See :ref:`reload_templates_section` for more information. @@ -539,7 +539,7 @@ detected. See :ref:`reload_templates_section` for more information. turned on. The ``debug_templates`` setting in the ``[app:main]`` section is a -:mod:`repoze.bfg` -specific setting which is passed into the +:mod:`pyramid` -specific setting which is passed into the framework. If it exists, and its value is ``true``, :term:`Chameleon` template exceptions will contained more detailed and helpful information about the error than when this value is ``false``. See @@ -550,7 +550,7 @@ information about the error than when this value is ``false``. See turned on. Various other settings may exist in this section having to do with -debugging or influencing runtime behavior of a :mod:`repoze.bfg` +debugging or influencing runtime behavior of a :mod:`pyramid` application. See :ref:`environment_chapter` for more information about these settings. @@ -561,9 +561,9 @@ will create a new thread for each request. .. note:: - In general, :mod:`repoze.bfg` applications generated from ``paster + In general, :mod:`pyramid` applications generated from ``paster templates`` should be threading-aware. It is not required that a - :mod:`repoze.bfg` application be nonblocking as all application code + :mod:`pyramid` application be nonblocking as all application code will run in its own thread, provided by the server you're using. See the :term:`PasteDeploy` documentation for more information about @@ -620,7 +620,7 @@ those files are checked into version control. ``zip_safe`` indicates that this package is not safe to use as a zipped egg; instead it will always unpack as a directory, which is more convenient. ``install_requires`` and ``tests_require`` indicate that this package -depends on the ``repoze.bfg`` package. ``test_suite`` points at the +depends on the ``pyramid`` package. ``test_suite`` points at the package for our application, which means all tests found in the package will be run when ``setup.py test`` is invoked. We examined ``entry_points`` in our discussion of the ``MyProject.ini`` file; this @@ -699,7 +699,7 @@ The ``myproject`` :term:`package` lives inside the ``MyProject`` application. These are purely conventions established by the ``paster`` template: -:mod:`repoze.bfg` doesn't insist that you name things in any +:mod:`pyramid` doesn't insist that you name things in any particular way. .. index:: @@ -716,13 +716,13 @@ the :term:`application registry`. It looks like so: :language: xml #. Line 1 provides the root node and namespaces for the configuration - language. ``http://namespaces.repoze.org/bfg`` is the default XML + language. ``http://pylonshq.com/pyramid`` is the default XML namespace. Add-on packages may require other namespaces. -#. Line 3 initializes :mod:`repoze.bfg` -specific configuration - directives by including the ``repoze.bfg.includes`` package. This +#. Line 3 initializes :mod:`pyramid` -specific configuration + directives by including the ``pyramid.includes`` package. This causes all of the ZCML within the ``configure.zcml`` of the - ``repoze.bfg.includes`` package to be "included" in this + ``pyramid.includes`` package to be "included" in this configuration file's scope. Effectively this means that we can use (for this example) the ``view`` and ``static`` directives which follow later in this file. @@ -765,9 +765,9 @@ the :term:`application registry`. It looks like so: ``views.py`` ~~~~~~~~~~~~ -Much of the heavy lifting in a :mod:`repoze.bfg` application comes in +Much of the heavy lifting in a :mod:`pyramid` application comes in the form of *view callables*. A :term:`view callable` is the main -tool of a :mod:`repoze.bfg` web application developer; it is a bit of +tool of a :mod:`pyramid` web application developer; it is a bit of code which accepts a :term:`request` and which returns a :term:`response`. @@ -825,13 +825,13 @@ named ``MyModel`` that provides the behavior. #. Line 4 defines an instance of MyModel as the root. #. Line 6 is a "root factory" function that will be called by the - :mod:`repoze.bfg` *Router* for each request when it wants to find + :mod:`pyramid` *Router* for each request when it wants to find the root of the object graph. Conventionally this is called ``get_root``. In a "real" application, the root object would not be such a simple object. Instead, it would be an object that could access some -persistent data store, such as a database. :mod:`repoze.bfg` doesn't +persistent data store, such as a database. :mod:`pyramid` doesn't make any assumption about which sort of datastore you'll want to use, so the sample application uses an instance of :class:`myproject.models.MyModel` to represent the root. @@ -850,12 +850,12 @@ which advertises an entry point for use by our :term:`PasteDeploy` :linenos: #. Line 1 imports the :term:`Configurator` class from - :mod:`repoze.bfg.configuration` that we use later. + :mod:`pyramid.configuration` that we use later. #. Line 2 imports the ``get_root`` function from :mod:`myproject.models` that we use later. -#. Lines 4-13 define a function that returns a :mod:`repoze.bfg` +#. Lines 4-13 define a function that returns a :mod:`pyramid` WSGI application. This function is meant to be called by the :term:`PasteDeploy` framework as a result of running ``paster serve``. @@ -894,8 +894,8 @@ The ``tests.py`` module includes unit tests for your application. This sample ``tests.py`` file has a single unit test defined within it. This test is executed when you run ``python setup.py test``. You may add more tests here as you build your application. You are not -required to write tests to use :mod:`repoze.bfg`, this file is simply +required to write tests to use :mod:`pyramid`, this file is simply provided as convenience and example. See :ref:`unittesting_chapter` for more information about writing -:mod:`repoze.bfg` unit tests. +:mod:`pyramid` unit tests. diff --git a/docs/narr/resources.rst b/docs/narr/resources.rst index d28e6438b..621db577d 100644 --- a/docs/narr/resources.rst +++ b/docs/narr/resources.rst @@ -22,7 +22,7 @@ example, each of the following is a resource: in it (if it possessed an ``__init__.py`` it would *be* a package). The use of resources is quite common in most web development projects. -For example, when you create a :mod:`repoze.bfg` application using one +For example, when you create a :mod:`pyramid` application using one of the available "paster" templates, as described in :ref:`creating_a_project`, the directory representing the application contains a Python :term:`package`. Within that Python package, there @@ -36,9 +36,9 @@ files. Understanding Resources ----------------------- -Let's imagine you've created a :mod:`repoze.bfg` application that uses +Let's imagine you've created a :mod:`pyramid` application that uses a :term:`Chameleon` ZPT template via the -:func:`repoze.bfg.chameleon_zpt.render_template_to_response` API. For +:func:`pyramid.chameleon_zpt.render_template_to_response` API. For example, the application might address the resource named ``templates/some_template.pt`` using that API within a ``views.py`` file inside a ``myapp`` package: @@ -47,29 +47,29 @@ file inside a ``myapp`` package: .. code-block:: python :linenos: - from repoze.bfg.chameleon_zpt import render_template_to_response + from pyramid.chameleon_zpt import render_template_to_response render_template_to_response('templates/some_template.pt') -"Under the hood", when this API is called, :mod:`repoze.bfg` attempts +"Under the hood", when this API is called, :mod:`pyramid` attempts to make sense out of the string ``templates/some_template.pt`` provided by the developer. To do so, it first finds the "current" package. The "current" package is the Python package in which the ``views.py`` module which contains this code lives. This would be the ``myapp`` package, according to our example so far. By resolving the -current package, :mod:`repoze.bfg` has enough information to locate +current package, :mod:`pyramid` has enough information to locate the actual template file. These are the elements it needs: - The *package name* (``myapp``) - The *resource name* (``templates/some_template.pt``) -:mod:`repoze.bfg` uses the :term:`pkg_resources` API to resolve the +:mod:`pyramid` uses the :term:`pkg_resources` API to resolve the package name and resource name to an absolute (operating-system-specific) file name. It eventually passes this resolved absolute filesystem path to the Chameleon templating engine, which then uses it to load, parse, and execute the template file. -Package names often contain dots. For example, ``repoze.bfg`` is a +Package names often contain dots. For example, ``pyramid`` is a package. Resource names usually look a lot like relative UNIX file paths. @@ -82,8 +82,8 @@ Overriding Resources -------------------- It can often be useful to override specific resources "from outside" a -given :mod:`repoze.bfg` application. For example, you may wish to -reuse an existing :mod:`repoze.bfg` application more or less +given :mod:`pyramid` application. For example, you may wish to +reuse an existing :mod:`pyramid` application more or less unchanged. However, some specific template file owned by the application might have inappropriate HTML, or some static resource (such as a logo file or some CSS file) might not be appropriate. You @@ -95,7 +95,7 @@ customers (such as a CMS application, or some bug tracking application), and you want to make arbitrary visual modifications to a particular application deployment without forking the underlying code. -To this end, :mod:`repoze.bfg` contains a feature that makes it +To this end, :mod:`pyramid` contains a feature that makes it possible to "override" one resource with one or more other resources. In support of this feature, a :term:`ZCML` directive exists named ``resource``. The ``resource`` directive allows you to *override* the @@ -106,10 +106,10 @@ following kinds of resources defined in any Python package: - A directory containing multiple Chameleon templates. - Individual static files served up by an instance of the - ``repoze.bfg.view.static`` helper class. + ``pyramid.view.static`` helper class. - A directory of static files served up by an instance of the - ``repoze.bfg.view.static`` helper class. + ``pyramid.view.static`` helper class. - Any other resource (or set of resources) addressed by code that uses the setuptools :term:`pkg_resources` API. @@ -118,7 +118,7 @@ Usually, overriding a resource in an existing application means performing the following steps: - Create a new Python package. The easiest way to do this is to - create a new :mod:`repoze.bfg` application using the "paster" + create a new :mod:`pyramid` application using the "paster" template mechanism. See :ref:`creating_a_project` for more information. @@ -129,7 +129,7 @@ performing the following steps: - Change the ``configure.zcml`` in the new package to include one or more ``resource`` ZCML directives (see :ref:`resource_directive` below). The new package's ``configure.zcml`` should then include - the original :mod:`repoze.bfg` application's ``configure.zcml`` via + the original :mod:`pyramid` application's ``configure.zcml`` via an include statement, e.g. ````. @@ -142,7 +142,7 @@ performing the following steps: for more information about this setting. Note that overriding resources is not the only way to extend or modify -the behavior of an existing :mod:`repoze.bfg` application. A "heavier +the behavior of an existing :mod:`pyramid` application. A "heavier hammer" way to do the same thing is explained in :ref:`extending_chapter`. The heavier hammer way allows you to replace a :term:`view` wholesale rather than resources that might be @@ -157,7 +157,7 @@ The ``override_resource`` API ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ An individual call to -:meth:`repoze.bfg.configuration.Configurator.override_resource` can +:meth:`pyramid.configuration.Configurator.override_resource` can override a single resource. For example: .. ignore-next-block @@ -213,7 +213,7 @@ will need to register two overrides. The package name in a specification may start with a dot, meaning that the package is relative to the package in which the configuration construction file resides (or the ``package`` argument to the -:class:`repoze.bfg.configuration.Configurator` class construction). +:class:`pyramid.configuration.Configurator` class construction). For example: .. ignore-next-block @@ -245,12 +245,12 @@ The ``resource`` ZCML Directive ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Instead of using -:meth:`repoze.bfg.configuration.Configurator.override_resource` during +:meth:`pyramid.configuration.Configurator.override_resource` during :term:`imperative configuration`, an equivalent can be used to perform all the tasks described above within :term:`ZCML`. The ZCML ``resource`` tag is a frontend to using ``override_resource``. -An individual :mod:`repoze.bfg` ``resource`` ZCML statement can +An individual :mod:`pyramid` ``resource`` ZCML statement can override a single resource. For example: .. code-block:: xml diff --git a/docs/narr/router.rst b/docs/narr/router.rst index 4b27b4b39..6bc17caf0 100644 --- a/docs/narr/router.rst +++ b/docs/narr/router.rst @@ -8,35 +8,35 @@ Request Processing ================== -Once a :mod:`repoze.bfg` application is up and running, it is ready to +Once a :mod:`pyramid` application is up and running, it is ready to accept requests and return responses. What happens from the time a :term:`WSGI` request enters a -:mod:`repoze.bfg` application through to the point that -:mod:`repoze.bfg` hands off a response back to WSGI for upstream +:mod:`pyramid` application through to the point that +:mod:`pyramid` hands off a response back to WSGI for upstream processing? #. A user initiates a request from his browser to the hostname and - port number of the WSGI server used by the :mod:`repoze.bfg` + port number of the WSGI server used by the :mod:`pyramid` application. -#. The WSGI server used by the :mod:`repoze.bfg` application passes +#. The WSGI server used by the :mod:`pyramid` application passes the WSGI environment to the ``__call__`` method of the - :mod:`repoze.bfg` :term:`router` object. + :mod:`pyramid` :term:`router` object. #. A :term:`request` object is created based on the WSGI environment. #. The :term:`application registry` and the :term:`request` object created in the last step are pushed on to the :term:`thread local` - stack that :mod:`repoze.bfg` uses to allow the functions named - :func:`repoze.bfg.threadlocal.get_current_request` and - :func:`repoze.bfg.threadlocal.get_current_registry` to work. + stack that :mod:`pyramid` uses to allow the functions named + :func:`pyramid.threadlocal.get_current_request` and + :func:`pyramid.threadlocal.get_current_registry` to work. -#. A :class:`repoze.bfg.interfaces.INewRequest` :term:`event` is sent +#. A :class:`pyramid.interfaces.INewRequest` :term:`event` is sent to any subscribers. #. If any :term:`route` has been defined within application - configuration, the :mod:`repoze.bfg` :term:`router` calls a + configuration, the :mod:`pyramid` :term:`router` calls a :term:`URL dispatch` "route mapper." The job of the mapper is to examine the request to determine whether any user-defined :term:`route` matches the current WSGI environment. The @@ -46,7 +46,7 @@ processing? ``matched_route`` attributes are added to the request object; the former contains a dictionary representign the matched dynamic elements of the request's ``PATH_INFO`` value, the latter contains - the :class:`repoze.bfg.interfaces.IRoute` object representing the + the :class:`pyramid.interfaces.IRoute` object representing the route which matched. The root object associated with the route found is also generated: if the :term:`route configuration` which matched has an associated a ``factory`` argument, this factory is @@ -59,7 +59,7 @@ processing? argument passed to the Configurator constructor was ``None``, a default root factory is used to generate a root object. -#. The :mod:`repoze.bfg` router calls a "traverser" function with the +#. The :mod:`pyramid` router calls a "traverser" function with the root object and the request. The traverser function attempts to traverse the root object (using any existing ``__getitem__`` on the root object and subobjects) to find a :term:`context`. If the root @@ -74,37 +74,37 @@ processing? they can be accessed via e.g. ``request.context`` within :term:`view` code. -#. A :class:`repoze.bfg.interfaces.IContextFound` :term:`event` is +#. A :class:`pyramid.interfaces.IContextFound` :term:`event` is sent to any subscribers. -#. :mod:`repoze.bfg` looks up a :term:`view` callable using the +#. :mod:`pyramid` looks up a :term:`view` callable using the context, the request, and the view name. If a view callable doesn't exist for this combination of objects (based on the type of the context, the type of the request, and the value of the view name, and any :term:`predicate` attributes applied to the view - configuration), :mod:`repoze.bfg` raises a - :class:`repoze.bfg.exceptions.NotFound` exception, which is meant + configuration), :mod:`pyramid` raises a + :class:`pyramid.exceptions.NotFound` exception, which is meant to be caught by a surrounding exception handler. -#. If a view callable was found, :mod:`repoze.bfg` attempts to call +#. If a view callable was found, :mod:`pyramid` attempts to call the view function. #. If an :term:`authorization policy` is in use, and the view was - protected by a :term:`permission`, :mod:`repoze.bfg` passes the + protected by a :term:`permission`, :mod:`pyramid` passes the context, the request, and the view_name to a function which determines whether the view being asked for can be executed by the requesting user, based on credential information in the request and security information attached to the context. If it returns - ``True``, :mod:`repoze.bfg` calls the view callable to obtain a + ``True``, :mod:`pyramid` calls the view callable to obtain a response. If it returns ``False``, it raises a - :class:`repoze.bfg.exceptions.Forbidden` exception, which is meant + :class:`pyramid.exceptions.Forbidden` exception, which is meant to be called by a surrounding exception handler. #. If any exception was raised within a :term:`root factory`, by :term:`traversal`, by a :term:`view callable` or by - :mod:`repoze.bfg` itself (such as when it raises - :class:`repoze.bfg.exceptions.NotFound` or - :class:`repoze.bfg.exceptions.Forbidden`), the router catches the + :mod:`pyramid` itself (such as when it raises + :class:`pyramid.exceptions.NotFound` or + :class:`pyramid.exceptions.Forbidden`), the router catches the exception, and attaches it to the request as the ``exception`` attribute. It then attempts to find a :term:`exception view` for the exception that was caught. If it finds an exception view @@ -114,26 +114,26 @@ processing? #. The following steps occur only when a :term:`response` could be successfully generated by a normal :term:`view callable` or an - :term:`exception view` callable. :mod:`repoze.bfg` will attempt to + :term:`exception view` callable. :mod:`pyramid` will attempt to execute any :term:`response callback` functions attached via - :meth:`repoze.bfg.request.Request.add_response_callback`. A - :class:`repoze.bfg.interfaces.INewResponse` :term:`event` is then + :meth:`pyramid.request.Request.add_response_callback`. A + :class:`pyramid.interfaces.INewResponse` :term:`event` is then sent to any subscribers. The response object's ``app_iter``, ``status``, and ``headerlist`` attributes are then used to generate a WSGI response. The response is sent back to the upstream WSGI server. -#. :mod:`repoze.bfg` will attempt to execute any :term:`finished +#. :mod:`pyramid` will attempt to execute any :term:`finished callback` functions attached via - :meth:`repoze.bfg.request.Request.add_finished_callback`. + :meth:`pyramid.request.Request.add_finished_callback`. #. The :term:`thread local` stack is popped. .. image:: router.png This is a very high-level overview that leaves out various details. -For more detail about subsystems invoked by the BFG router such as -traversal, URL dispatch, views, and event processing, see +For more detail about subsystems invoked by the :mod:`pyramid` router +such as traversal, URL dispatch, views, and event processing, see :ref:`contextfinding_chapter`, :ref:`views_chapter`, and :ref:`events_chapter`. diff --git a/docs/narr/security.rst b/docs/narr/security.rst index 85ab9ef58..25d1c2ecf 100644 --- a/docs/narr/security.rst +++ b/docs/narr/security.rst @@ -6,7 +6,7 @@ Security ======== -:mod:`repoze.bfg` provides an optional declarative authorization +:mod:`pyramid` provides an optional declarative authorization system that prevents a :term:`view` from being invoked when the user represented by credentials in the :term:`request` does not have an appropriate level of access within a particular :term:`context`. @@ -43,38 +43,18 @@ Here's how it works at a high level: Authorization is enabled by modifying your application to include an :term:`authentication policy` and :term:`authorization policy`. -:mod:`repoze.bfg` comes with a variety of implementations of these -policies. To provide maximal flexibility, :mod:`repoze.bfg` also +:mod:`pyramid` comes with a variety of implementations of these +policies. To provide maximal flexibility, :mod:`pyramid` also allows you to create custom authentication policies and authorization policies. -.. warning:: - - Various systems exist for adding authentication and authorization - to arbitrary web frameworks. Two of these, :mod:`repoze.who` and - :mod:`repoze.what` are even written under the same Repoze "flag" as - :mod:`repoze.bfg`! However, neither :mod:`repoze.who` nor - :mod:`repoze.what` is required to add authorization or - authentication to a :mod:`repoze.bfg` application. In fact, unless - you have very specific requirements that include some sort of - "single sign on" or you need to integrate authorization across - multiple non-:mod:`repoze.bfg` Python applications, you can - probably safely ignore the existence of both :mod:`repoze.who` and - :mod:`repoze.what`. Those packages are useful when adding - authentication and authorization to a web framework such as Pylons - which has no built-in authentication or authorization machinery. - Because :mod:`repoze.bfg` already has facilities for authentication - and authorization built in, the use of :mod:`repoze.who` or - :mod:`repoze.what` is not required within :mod:`repoze.bfg` - applications. - .. index:: single: authorization policy Enabling an Authorization Policy -------------------------------- -By default, :mod:`repoze.bfg` enables no authorization policy. All +By default, :mod:`pyramid` enables no authorization policy. All views are accessible by completely anonymous users. In order to begin protecting views from execution based on security settings, you need to enable an authorization policy. @@ -86,14 +66,14 @@ Enabling an Authorization Policy Imperatively ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Passing an ``authorization_policy`` argument to the constructor of the -:class:`repoze.bfg.configuration.Configurator` class enables an +:class:`pyramid.configuration.Configurator` class enables an authorization policy. You must also enable an :term:`authentication policy` in order to enable the authorization policy. This is because authorization, in general, depends upon authentication. Use the ``authentication_policy`` argument to the -:class:`repoze.bfg.configuration.Configurator` class during +:class:`pyramid.configuration.Configurator` class during application setup to specify an authentication policy. For example: @@ -102,9 +82,9 @@ For example: .. code-block:: python :linenos: - from repoze.bfg.configuration import Configurator - from repoze.bfg.authentication import AuthTktAuthenticationPolicy - from repoze.bfg.authorization import ACLAuthorizationPolicy + from pyramid.configuration import Configurator + from pyramid.authentication import AuthTktAuthenticationPolicy + from pyramid.authorization import ACLAuthorizationPolicy authentication_policy = AuthTktAuthenticationPolicy('seekrit') authorization_policy = ACLAuthorizationPolicy() config = Configurator(authentication_policy=authentication_policy, @@ -126,8 +106,8 @@ authorization policies, it is an error to pass an authentication policy without the authorization policy or vice versa to a :term:`Configurator` constructor. -See also the :mod:`repoze.bfg.authorization` and -:mod:`repoze.bfg.authentication` modules for alternate implementations +See also the :mod:`pyramid.authorization` and +:mod:`pyramid.authentication` modules for alternate implementations of authorization and authentication policies. Enabling an Authorization Policy Via ZCML @@ -148,7 +128,7 @@ this: .. code-block:: xml :linenos: - + @@ -160,13 +140,13 @@ this: "Under the hood", these statements cause an instance of the class -:class:`repoze.bfg.authentication.AuthTktAuthenticationPolicy` to be +:class:`pyramid.authentication.AuthTktAuthenticationPolicy` to be injected as the :term:`authentication policy` used by this application and an instance of the class -:class:`repoze.bfg.authorization.ACLAuthorizationPolicy` to be +:class:`pyramid.authorization.ACLAuthorizationPolicy` to be injected as the :term:`authorization policy` used by this application. -:mod:`repoze.bfg` ships with a number of authorization and +:mod:`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. @@ -207,7 +187,7 @@ may be performed via the ``@bfg_view`` decorator: .. code-block:: python :linenos: - from repoze.bfg.view import bfg_view + from pyramid.view import bfg_view from models import Blog @bfg_view(context=Blog, name='add_entry.html', permission='add') @@ -216,7 +196,7 @@ may be performed via the ``@bfg_view`` decorator: pass Or the same thing can be done using the -:meth:`repoze.bfg.configuration.Configurator.add_view` method: +:meth:`pyramid.configuration.Configurator.add_view` method: .. ignore-next-block .. code-block:: python @@ -242,7 +222,7 @@ registered view always be executable by entirely anonymous users: any authorization policy in effect is ignored. In support of making it easier to configure applications which are -"secure by default", :mod:`repoze.bfg` allows you to configure a +"secure by default", :mod:`pyramid` allows you to configure a *default* permission. If supplied, the default permission is used as the permission string to all view registrations which don't otherwise name a ``permission`` argument. @@ -251,10 +231,10 @@ These APIs are in support of configuring a default permission for an application: - The ``default_permission`` constructor argument to the - :mod:`repoze.bfg.configuration.Configurator` constructor. + :mod:`pyramid.configuration.Configurator` constructor. - The - :meth:`repoze.bfg.configuration.Configurator.set_default_permission` + :meth:`pyramid.configuration.Configurator.set_default_permission` method. - The :ref:`default_permission_directive` ZCML directive. @@ -265,7 +245,7 @@ that view registration, and the view-configuration-named permission is used. .. note:: All APIs and ZCML directives related to default permissions - are new in :mod:`repoze.bfg` 1.3. + are new in :mod:`pyramid` 1.3. .. index:: single: ACL @@ -276,7 +256,7 @@ used. Assigning ACLs to your Model Objects ------------------------------------ -When the default :mod:`repoze.bfg` :term:`authorization policy` +When the default :mod:`pyramid` :term:`authorization policy` determines whether a user possesses a particular permission in a :term:`context`, it examines the :term:`ACL` associated with the context. An ACL is associated with a context by virtue of the @@ -291,8 +271,8 @@ class: .. code-block:: python :linenos: - from repoze.bfg.security import Everyone - from repoze.bfg.security import Allow + from pyramid.security import Everyone + from pyramid.security import Allow class Blog(object): __acl__ = [ @@ -307,8 +287,8 @@ Or, if your models are persistent, an ACL might be specified via the .. code-block:: python :linenos: - from repoze.bfg.security import Everyone - from repoze.bfg.security import Allow + from pyramid.security import Everyone + from pyramid.security import Allow class Blog(object): pass @@ -339,8 +319,8 @@ Here's an example ACL: .. code-block:: python :linenos: - from repoze.bfg.security import Everyone - from repoze.bfg.security import Allow + from pyramid.security import Everyone + from pyramid.security import Allow __acl__ = [ (Allow, Everyone, 'view'), @@ -349,7 +329,7 @@ Here's an example ACL: ] The example ACL indicates that the -:data:`repoze.bfg.security.Everyone` principal -- a special +:data:`pyramid.security.Everyone` principal -- a special system-defined principal indicating, literally, everyone -- is allowed to view the blog, the ``group:editors`` principal is allowed to add to and edit the blog. @@ -360,8 +340,8 @@ Everyone, 'view')``, ``(Allow, 'group:editors', 'add')``, and ``(Allow, 'group:editors', 'edit')``. The first element of any ACE is either -:data:`repoze.bfg.security.Allow`, or -:data:`repoze.bfg.security.Deny`, representing the action to take when +:data:`pyramid.security.Allow`, or +:data:`pyramid.security.Deny`, representing the action to take when the ACE matches. The second element is a :term:`principal`. The third argument is a permission or sequence of permission names. @@ -369,7 +349,7 @@ A principal is usually a user id, however it also may be a group id if your authentication system provides group information and the effective :term:`authentication policy` policy is written to respect group information. For example, the -:class:`repoze.bfg.authentication.RepozeWho1AuthenicationPolicy` +:class:`pyramid.authentication.RepozeWho1AuthenicationPolicy` enabled by the ``repozewho1authenticationpolicy`` ZCML directive respects group information if you configure it with a ``callback``. See :ref:`authentication_policies_directives_section` for more @@ -381,9 +361,9 @@ order dictated by the ACL*. So if you have an ACL like this: .. code-block:: python :linenos: - from repoze.bfg.security import Everyone - from repoze.bfg.security import Allow - from repoze.bfg.security import Deny + from pyramid.security import Everyone + from pyramid.security import Allow + from pyramid.security import Deny __acl__ = [ (Allow, Everyone, 'view'), @@ -398,9 +378,9 @@ like this: .. code-block:: python :linenos: - from repoze.bfg.security import Everyone - from repoze.bfg.security import Allow - from repoze.bfg.security import Deny + from pyramid.security import Everyone + from pyramid.security import Allow + from pyramid.security import Deny __acl__ = [ (Deny, Everyone, 'view'), @@ -419,8 +399,8 @@ ACE, as below. .. code-block:: python :linenos: - from repoze.bfg.security import Everyone - from repoze.bfg.security import Allow + from pyramid.security import Everyone + from pyramid.security import Allow __acl__ = [ (Allow, Everyone, 'view'), @@ -435,18 +415,18 @@ ACE, as below. Special Principal Names ----------------------- -Special principal names exist in the :mod:`repoze.bfg.security` +Special principal names exist in the :mod:`pyramid.security` module. They can be imported for use in your own code to populate -ACLs, e.g. :data:`repoze.bfg.security.Everyone`. +ACLs, e.g. :data:`pyramid.security.Everyone`. -:data:`repoze.bfg.security.Everyone` +:data:`pyramid.security.Everyone` Literally, everyone, no matter what. This object is actually a string "under the hood" (``system.Everyone``). Every user "is" the principal named Everyone during every request, even if a security policy is not in use. -:data:`repoze.bfg.security.Authenticated` +:data:`pyramid.security.Authenticated` Any user with credentials as determined by the current security policy. You might think of it as any user that is "logged in". @@ -460,12 +440,12 @@ ACLs, e.g. :data:`repoze.bfg.security.Everyone`. Special Permissions ------------------- -Special permission names exist in the :mod:`repoze.bfg.security` +Special permission names exist in the :mod:`pyramid.security` module. These can be imported for use in ACLs. .. _all_permissions: -:data:`repoze.bfg.security.ALL_PERMISSIONS` +:data:`pyramid.security.ALL_PERMISSIONS` An object representing, literally, *all* permissions. Useful in an ACL like so: ``(Allow, 'fred', ALL_PERMISSIONS)``. The @@ -482,7 +462,7 @@ Special ACEs ------------ A convenience :term:`ACE` is defined representing a deny to everyone -of all permissions in :data:`repoze.bfg.security.DENY_ALL`. This ACE +of all permissions in :data:`pyramid.security.DENY_ALL`. This ACE is often used as the *last* ACE of an ACL to explicitly cause inheriting authorization policies to "stop looking up the traversal tree" (effectively breaking any inheritance). For example, an ACL @@ -493,17 +473,17 @@ authorization policy is in effect might look like so: .. code-block:: python :linenos: - from repoze.bfg.security import Allow - from repoze.bfg.security import DENY_ALL + from pyramid.security import Allow + from pyramid.security import DENY_ALL __acl__ = [ (Allow, 'fred', 'view'), DENY_ALL ] -"Under the hood", the :data:`repoze.bfg.security.DENY_ALL` ACE equals +"Under the hood", the :data:`pyramid.security.DENY_ALL` ACE equals the following: .. code-block:: python - from repoze.bfg.security import ALL_PERMISSIONS + from pyramid.security import ALL_PERMISSIONS __acl__ = [ (Deny, Everyone, ALL_PERMISSIONS) ] .. index:: @@ -545,7 +525,7 @@ location-awareness. See also :ref:`location_aware`. Changing the Forbidden View --------------------------- -When :mod:`repoze.bfg` denies a view invocation due to an +When :mod:`pyramid` denies a view invocation due to an authorization denial, the special ``forbidden`` view is invoked. "Out of the box", this forbidden view is very plain. See :ref:`changing_the_forbidden_view` within :ref:`hooks_chapter` for @@ -586,20 +566,20 @@ also contain security debugging information in its body. Debugging Imperative Authorization Failures ------------------------------------------- -The :func:`repoze.bfg.security.has_permission` API is used to check +The :func:`pyramid.security.has_permission` API is used to check security within view functions imperatively. It returns instances of objects that are effectively booleans. But these objects are not raw ``True`` or ``False`` objects, and have information attached to them about why the permission was allowed or denied. The object will be -one of :data:`repoze.bfg.security.ACLAllowed`, -:data:`repoze.bfg.security.ACLDenied`, -:data:`repoze.bfg.security.Allowed`, or -:data:`repoze.bfg.security.Denied`, as documented in +one of :data:`pyramid.security.ACLAllowed`, +:data:`pyramid.security.ACLDenied`, +:data:`pyramid.security.Allowed`, or +:data:`pyramid.security.Denied`, as documented in :ref:`security_module`. At the very minimum these objects will have a ``msg`` attribute, which is a string indicating why the permission was denied or allowed. Introspecting this information in the debugger or via print statements when a call to -:func:`repoze.bfg.security.has_permission` fails is often useful. +:func:`pyramid.security.has_permission` fails is often useful. .. index:: pair: ZCML directive; authentication policy @@ -610,7 +590,7 @@ Built-In Authentication Policy ZCML Directives ---------------------------------------------- Instead of configuring an authentication policy and authorization -policy imperatively, :mod:`repoze.bfg` ships with a few "pre-chewed" +policy imperatively, :mod:`pyramid` ships with a few "pre-chewed" authentication policy ZCML directives that you can make use of within your application. @@ -715,8 +695,8 @@ See :ref:`aclauthorizationpolicy_directive` for detailed information. Creating Your Own Authentication Policy --------------------------------------- -:mod:`repoze.bfg` ships with a number of useful out-of-the-box -security policies (see :mod:`repoze.bfg.authentication`). However, +:mod:`pyramid` ships with a number of useful out-of-the-box +security policies (see :mod:`pyramid.authentication`). However, creating your own authentication policy is often necessary when you want to control the "horizontal and vertical" of how your users authenticate. Doing so is a matter of creating an instance of something @@ -725,7 +705,7 @@ that implements the following interface: .. code-block:: python class AuthenticationPolicy(object): - """ An object representing a BFG authentication policy. """ + """ An object representing a Pyramid authentication policy. """ def authenticated_userid(self, request): """ Return the authenticated userid or ``None`` if no authenticated userid can be found. """ @@ -747,7 +727,7 @@ that implements the following interface: current user on subsequent requests. """ After you do so, you can pass an instance of such a class into the -:class:`repoze.bfg.configuration.Configurator` class at configuration +:class:`pyramid.configuration.Configurator` class at configuration time as ``authentication_policy`` to use it. .. index:: @@ -759,19 +739,19 @@ Creating Your Own Authorization Policy -------------------------------------- An authorization policy is a policy that allows or denies access after -a user has been authenticated. By default, :mod:`repoze.bfg` will use -the :class:`repoze.bfg.authorization.ACLAuthorizationPolicy` if an +a user has been authenticated. By default, :mod:`pyramid` will use +the :class:`pyramid.authorization.ACLAuthorizationPolicy` if an authentication policy is activated and an authorization policy isn't otherwise specified. In some cases, it's useful to be able to use a different authorization policy than the default -:class:`repoze.bfg.authorization.ACLAuthorizationPolicy`. For +:class:`pyramid.authorization.ACLAuthorizationPolicy`. For example, it might be desirable to construct an alternate authorization policy which allows the application to use an authorization mechanism that does not involve :term:`ACL` objects. -:mod:`repoze.bfg` ships with only a single default authorization +:mod:`pyramid` ships with only a single default authorization policy, so you'll need to create your own if you'd like to use a different one. Creating and using your own authorization policy is a matter of creating an instance of an object that implements the @@ -780,7 +760,7 @@ following interface: .. code-block:: python class IAuthorizationPolicy(object): - """ An object representing a BFG authorization policy. """ + """ An object representing a Pyramid authorization policy. """ def permits(self, context, principals, permission): """ Return True if any of the principals is allowed the permission in the current context, else return False """ @@ -790,5 +770,5 @@ following interface: permission """ After you do so, you can pass an instance of such a class into the -:class:`repoze.bfg.configuration.Configurator` class at configuration +:class:`pyramid.configuration.Configurator` class at configuration time as ``authorization_policy`` to use it. diff --git a/docs/narr/startup.rst b/docs/narr/startup.rst index 5b4365229..ef118d857 100644 --- a/docs/narr/startup.rst +++ b/docs/narr/startup.rst @@ -3,7 +3,7 @@ Startup ======= -When you cause :mod:`repoze.bfg` to start up in a console window, +When you cause :mod:`pyramid` to start up in a console window, you'll see something much like this show up on the console: .. code-block:: text @@ -24,11 +24,11 @@ The Startup Process ------------------- The easiest and best-documented way to start and serve a -:mod:`repoze.bfg` application is to use the ``paster serve`` command +:mod:`pyramid` application is to use the ``paster serve`` command against a :term:`PasteDeploy` ``.ini`` file. This uses the ``.ini`` 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. +command to run your :mod:`pyramid` application. Here's a high-level time-ordered overview of what happens when you press ``return`` after running ``paster serve MyProject.ini``. @@ -44,16 +44,16 @@ press ``return`` after running ``paster serve MyProject.ini``. the ``.ini`` file. This section represents the configuration of a :term:`WSGI` application that will be served. If you're using a simple application (e.g. an ``[app:main]`` section of a - default-generated :mod:`repoze.bfg` project), the application + default-generated :mod:`pyramid` project), the application :term:`entry point` or :term:`dotted Python name` will be named on the ``use=`` line within the section's configuration. If, instead of a simple application, you're using a WSGI :term:`pipeline` (e.g. a ``[pipeline:main]`` section), the application named on the - "last" element will refer to your :mod:`repoze.bfg` application. + "last" element will refer to your :mod:`pyramid` application. If instead of a simple application or a pipeline, you're using a Paste "composite" (e.g. ``[composite:main]``), refer to the documentation for that particular composite to understand how to - make it refer to your :mod:`repoze.bfg` application. + make it refer to your :mod:`pyramid` application. #. The application's *constructor* (named by the entry point reference or dotted Python name on the ``use=`` line) is passed the key/value @@ -61,10 +61,10 @@ press ``return`` after running ``paster serve MyProject.ini``. constructor is meant to return a :term:`router` instance, which is a :term:`WSGI` application. - For :mod:`repoze.bfg` applications, the constructor will be a + For :mod:`pyramid` applications, the constructor will be a function named ``app`` in the ``run.py`` file within the :term:`package` in which your application lives. If this function - succeeds, it will return a :mod:`repoze.bfg` :term:`router` + succeeds, it will return a :mod:`pyramid` :term:`router` instance. Here's the contents of an example ``run.py`` module: .. literalinclude:: MyProject/myproject/run.py @@ -93,7 +93,7 @@ press ``return`` after running ``paster serve MyProject.ini``. 'debug_notfound':'false'}``. #. The ``app`` function first constructs a - :class:`repoze.bfg.configuration.Configurator` instance, passing + :class:`pyramid.configuration.Configurator` instance, passing ``get_root`` to it as its ``root_factory`` argument, and ``settings`` dictionary captured via the ``**settings`` kwarg as its ``settings`` argument. @@ -109,7 +109,7 @@ press ``return`` after running ``paster serve MyProject.ini``. 'debug_authorization':'false', 'debug_notfound':'false'}``. #. The ``app`` function then calls the - :meth:`repoze.bfg.configuration.Configurator.load_zcml` method, + :meth:`pyramid.configuration.Configurator.load_zcml` method, passing in a ``zcml_file`` value. ``zcml_file`` is the value of the ``configure_zcml`` setting or a default of ``configure.zcml``. This filename is relative to the run.py file that the ``app`` @@ -121,13 +121,13 @@ press ``return`` after running ``paster serve MyProject.ini``. succeeds, an :term:`application registry` is populated using all the :term:`ZCML declaration` statements present in the file. -#. The :meth:`repoze.bfg.configuration.Configurator.make_wsgi_app` +#. The :meth:`pyramid.configuration.Configurator.make_wsgi_app` method is called. The result is a :term:`router` instance. The router is associated with the :term:`application registry` implied by the configurator previously populated by ZCML. The router is a WSGI application. -#. A :class:`repoze.bfg.interfaces.IApplicationCreated` event is +#. A :class:`pyramid.interfaces.IApplicationCreated` event is emitted (see :ref:`events_chapter` for more information about events). diff --git a/docs/narr/static.rst b/docs/narr/static.rst index b2d481ba5..02ee68eb6 100644 --- a/docs/narr/static.rst +++ b/docs/narr/static.rst @@ -1,9 +1,9 @@ Static Resources ================ -:mod:`repoze.bfg` makes it possible to serve up "static" (non-dynamic) +:mod:`pyramid` makes it possible to serve up "static" (non-dynamic) resources from a directory on a filesystem. This chapter describes -how to configure :mod:`repoze.bfg` to do so. +how to configure :mod:`pyramid` to do so. .. index:: triple: view; zcml; static resource @@ -15,8 +15,8 @@ Serving Static Resources Using a ZCML Directive ----------------------------------------------- Use of the ``static`` ZCML directive or the -:meth:`repoze.bfg.configuration.configurator.add_static_view` method -is the preferred way to instruct :mod:`repoze.bfg` to serve static +:meth:`pyramid.configuration.configurator.add_static_view` method +is the preferred way to instruct :mod:`pyramid` to serve static resources such as JavaScript and CSS files. This mechanism makes static files available at a name relative to the application root URL, e.g. ``/static``. @@ -30,7 +30,7 @@ package will resolve to a package-qualified resource such as 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 :mod:`repoze.bfg` application using an +the computer which runs the :mod:`pyramid` application using an absolute path. .. code-block:: xml @@ -67,9 +67,6 @@ package-relative path. path="static" /> -.. note:: The :ref:`static_directive` ZCML directive is new in - :mod:`repoze.bfg` 1.1. - Whether you use for ``path`` a fully qualified resource specification, an absolute path, or a package-relative path, When you place your static files on the filesystem in the directory represented as the @@ -90,20 +87,20 @@ shown usage of the ``name`` argument as a view name. When ``name`` is a *URL* (or any string with a slash (``/``) in it), static resources can be served from an external webserver. In this mode, the ``name`` is used as the URL prefix when generating a URL using -:func:`repoze.bfg.url.static_url`. +:func:`pyramid.url.static_url`. .. note:: - Using :func:`repoze.bfg.url.static_url` in conjunction with a - :meth:`repoze.bfg.configuration.Configurator.add_static_view` makes + Using :func:`pyramid.url.static_url` in conjunction with a + :meth:`pyramid.configuration.Configurator.add_static_view` makes it possible to put static media on a separate webserver during production (if the ``name`` argument to - :meth:`repoze.bfg.configuration.Configurator.add_static_view` is a + :meth:`pyramid.configuration.Configurator.add_static_view` is a URL), while keeping static media package-internal and served by the development webserver during development (if the ``name`` argument - to :meth:`repoze.bfg.configuration.Configurator.add_static_view` is + to :meth:`pyramid.configuration.Configurator.add_static_view` is a view name). To create such a circumstance, we suggest using the - :func:`repoze.bfg.settings.get_settings` API in conjunction with a + :func:`pyramid.settings.get_settings` API in conjunction with a setting in the application ``.ini`` file named ``media_location``. Then set the value of ``media_location`` to either a view name or a URL depending on whether the application is being run in @@ -125,16 +122,16 @@ argument which is ``http://example.com/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:`repoze.bfg.url.static_url` with paths that +subsequent calls to :func:`pyramid.url.static_url` with paths that start with the ``path`` argument passed to -:meth:`repoze.bfg.configuration.Configurator.add_static_view` will +:meth:`pyramid.configuration.Configurator.add_static_view` 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:`repoze.bfg.url.static_url` API is discussed in more detail +:func:`pyramid.url.static_url` API is discussed in more detail later in this chapter. -The :meth:`repoze.bfg.configuration.Configurator.add_static_view` +The :meth:`pyramid.configuration.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. @@ -150,15 +147,12 @@ Generating Static Resource URLs When a :ref:`static_directive` ZCML directive or a call to the ``add_static_view`` method of a -:class:`repoze.bfg.configuration.Configurator` is used to register a +:class:`pyramid.configuration.Configurator` is used to register a static resource directory, a special helper API named -:func:`repoze.bfg.static_url` can be used to generate the appropriate +:func:`pyramid.static_url` can be used to generate the appropriate URL for a package resource that lives in one of the directories named by the static registration ``path`` attribute. -.. note:: The :func:`repoze.bfg.url.static_url` API is new in - :mod:`repoze.bfg` 1.1. - For example, let's assume you create a set of ``static`` declarations in ZCML like so: @@ -183,7 +177,7 @@ visits a URL which begins with ``/static1``, and the resources in the begins with ``/static2``. You needn't generate the URLs to static resources "by hand" in such a -configuration. Instead, use the :func:`repoze.bfg.url.static_url` API +configuration. Instead, use the :func:`pyramid.url.static_url` API to generate them for you. For example, let's imagine that the following code lives in a module that shares the same directory as the above ZCML file: @@ -191,8 +185,8 @@ above ZCML file: .. code-block:: python :linenos: - from repoze.bfg.url import static_url - from repoze.bfg.chameleon_zpt import render_template_to_response + from pyramid.url import static_url + from pyramid.chameleon_zpt import render_template_to_response def my_view(request): css_url = static_url('resources/1/foo.css', request) @@ -206,17 +200,17 @@ If the request "application URL" of the running system is ``http://example.com/static1/foo.css``. The ``js_url`` generated above would be ``http://example.com/static2/foo.js``. -One benefit of using the :func:`repoze.bfg.url.static_url` function +One benefit of using the :func:`pyramid.url.static_url` function rather than constructing static URLs "by hand" is that if you need to change the ``name`` of a static URL declaration in ZCML, the generated URLs will continue to resolve properly after the rename. -URLs may also be generated by :func:`repoze.bfg.url.static_url` to -static resources that live *outside* the :mod:`repoze.bfg` +URLs may also be generated by :func:`pyramid.url.static_url` to +static resources that live *outside* the :mod:`pyramid` application. This will happen when the ``name`` argument provided to the ``static`` ZCML directive or the -:meth:`repoze.bfg.configuration.Configurator.add_static_view` API -associated with the path fed to :func:`repoze.bfg.url.static_url` is a +:meth:`pyramid.configuration.Configurator.add_static_view` API +associated with the path fed to :func:`pyramid.url.static_url` is a *URL* instead of a view name. For example, the ``name`` argument given to either the ZCML directive or the configurator API may be ``http://example.com`` while the the ``path`` given may be @@ -251,23 +245,23 @@ static resources to only be available when the :term:`context` of the view is of a particular type, or when the request is of a particular type. -The :class:`repoze.bfg.view.static` helper class is used to perform +The :class:`pyramid.view.static` helper class is used to perform this task. This class creates an object that is capable acting as a -:mod:`repoze.bfg` view callable which serves static resources from a +:mod:`pyramid` view callable which serves static resources from a directory. For instance, to serve files within a directory located on your filesystem at ``/path/to/static/dir`` mounted at the URL path ``/static`` in your application, create an instance of the -:class:`repoze.bfg.view.static` class inside a ``static.py`` file in +:class:`pyramid.view.static` class inside a ``static.py`` file in your application root as below. .. ignore-next-block .. code-block:: python :linenos: - from repoze.bfg.view import static + from pyramid.view import static static_view = static('/path/to/static/dir') -.. note:: the argument to :class:`repoze.bfg.view.static` can also be +.. note:: the argument to :class:`pyramid.view.static` can also be a relative pathname, e.g. ``my/static`` (meaning relative to the Python package of the module in which the view is being defined). It can also be a :term:`resource specification` @@ -278,7 +272,7 @@ your application root as below. Subsequently, you may wire this view up to be accessible as ``/static`` using either the -:mod:`repoze.bfg.configuration.Configurator.add_view` method or the +:mod:`pyramid.configuration.Configurator.add_view` method or the ```` ZCML directive in your application's ``configure.zcml`` against either the class or interface that represents your root object. For example (ZCML): @@ -293,7 +287,7 @@ object. For example (ZCML): /> In this case, ``.models.Root`` refers to the class of which your -:mod:`repoze.bfg` application's root object is an instance. +:mod:`pyramid` application's root object is an instance. You can also provide a ``context`` of ``*`` if you want the name ``static`` to be accessible as the static view against any model. @@ -301,7 +295,7 @@ This will also allow ``/static/foo.js`` to work, but it will allow for ``/anything/static/foo.js`` too, as long as ``anything`` itself is resolvable. -Note that you cannot use the :func:`repoze.bfg.static_url` API to +Note that you cannot use the :func:`pyramid.static_url` API to generate URLs against resources made accessible by registering a custom static view. diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst index 3dcc77e43..f3536363c 100644 --- a/docs/narr/templates.rst +++ b/docs/narr/templates.rst @@ -4,18 +4,18 @@ Templates ========= A :term:`template` is a file on disk which can be used to render -dynamic data provided by a :term:`view`. :mod:`repoze.bfg` offers a +dynamic data provided by a :term:`view`. :mod:`pyramid` offers a number of ways to perform templating tasks out of the box, and provides add-on templating support through a set of bindings packages. -Out of the box, :mod:`repoze.bfg` provides templating via the +Out of the box, :mod:`pyramid` provides templating via the :term:`Chameleon` templating library. :term:`Chameleon` provides support for two different types of templates: :term:`ZPT` templates and text templates. Before discussing how built-in templates are used in detail, we'll discuss two ways to render templates within -:mod:`repoze.bfg` in general: directly, and via renderer +:mod:`pyramid` in general: directly, and via renderer configuration. .. index:: @@ -28,11 +28,11 @@ Templates Used Directly ----------------------- The most straightforward way to use a template within -:mod:`repoze.bfg` is to cause it to be rendered directly within a +:mod:`pyramid` is to cause it to be rendered directly within a :term:`view callable`. You may use whatever API is supplied by a given templating engine to do so. -:mod:`repoze.bfg` provides various APIs that allow you to render +:mod:`pyramid` provides various APIs that allow you to render templates directly from within a view callable. For example, if there is a :term:`Chameleon` ZPT template named ``foo.pt`` in a directory in your application named ``templates``, you can render the template from @@ -41,7 +41,7 @@ within the body of a view callable like so: .. code-block:: python :linenos: - from repoze.bfg.renderers import render_to_response + from pyramid.renderers import render_to_response def sample_view(request): return render_to_response('templates/foo.pt', @@ -51,16 +51,16 @@ within the body of a view callable like so: .. warning:: Earlier iterations of this documentation (pre-version-1.3) encouraged the application developer to use ZPT-specific APIs such as - :func:`repoze.bfg.chameleon_zpt.render_template_to_response`, - :func:`repoze.bfg.chameleon_zpt.render_template_to_iterable`, and - :func:`repoze.bfg.chameleon_zpt.render_template` to render + :func:`pyramid.chameleon_zpt.render_template_to_response`, + :func:`pyramid.chameleon_zpt.render_template_to_iterable`, and + :func:`pyramid.chameleon_zpt.render_template` to render templates directly. This style of rendering still works, but at least for purposes of this documentation, those functions are deprecated. Application developers are encouraged instead to use - the functions available in the :mod:`repoze.bfg.renderers` module + the functions available in the :mod:`pyramid.renderers` module to perform rendering tasks. This set of functions works to render templates for all renderer extensions registered with - :mod:`repoze.bfg`. + :mod:`pyramid`. The ``sample_view`` :term:`view callable` above returns a :term:`response` object which contains the body of the @@ -86,7 +86,7 @@ example: .. code-block:: python :linenos: - from repoze.bfg.renderers import render_to_response + from pyramid.renderers import render_to_response def sample_view(request): return render_to_response('mypackage:templates/foo.pt', @@ -102,7 +102,7 @@ specifications will continue to work properly if you move the code containing them around. In the examples above we pass in a keyword argument named ``request`` -representing the current :mod:`repoze.bfg` request. Passing a request +representing the current :mod:`pyramid` request. Passing a request keyword argument will cause the ``render_to_response`` function to supply the renderer with more correct system values (see :ref:`renderer_system_values`), because most of the information @@ -111,12 +111,12 @@ If you care about the correct system values being provided to the renderer being called (in particular, if your template relies on the name ``request`` or ``context``, or if you've configured special :term:`renderer globals` make sure to pass ``request`` as a keyword -argument in every call to to a ``repoze.bfg.renderers.render_*`` +argument in every call to to a ``pyramid.renderers.render_*`` function. Every view must return a :term:`response` object (except for views which use a :term:`renderer` named via view configuration, which we'll -see shortly). The :func:`repoze.bfg.renders.render_to_response` +see shortly). The :func:`pyramid.renders.render_to_response` function is a shortcut function that actually returns a response object. @@ -125,14 +125,14 @@ return a response object. If you call a "response-ignorant" API that returns information you'd like to use as a response (such as when you render a template to a string), you must construct your own response object as necessary with the string as the body. For example, the -:func:`repoze.bfg.renderers.render` API returns a string. We can +:func:`pyramid.renderers.render` API returns a string. We can manufacture a :term:`response` object directly, and use that string as the body of the response: .. code-block:: python :linenos: - from repoze.bfg.renderers import render + from pyramid.renderers import render from webob import Response def sample_view(request): @@ -143,16 +143,16 @@ the body of the response: return response Because :term:`view callable` functions are typically the only code in -:mod:`repoze.bfg` that need to know anything about templates, and +:mod:`pyramid` that need to know anything about templates, and because view functions are very simple Python, you can use whatever templating system you're most comfortable with within -:mod:`repoze.bfg`. Install the templating system, import its API +:mod:`pyramid`. Install the templating system, import its API functions into your views module, use those APIs to generate a string, then return that string as the body of a :term:`WebOb` :term:`Response` object. For example, here's an example of using raw `Mako -`_ from within a :mod:`repoze.bfg` +`_ from within a :mod:`pyramid` :term:`view`: .. ignore-next-block @@ -170,22 +170,24 @@ For example, here's an example of using raw `Mako You probably wouldn't use this particular snippet in a project, because it's easier to use the Mako renderer bindings which already -exist for :mod:`repoze.bfg` named ``repoze.bfg.mako`` (available from +exist for :mod:`pyramid` named ``repoze.bfg.mako`` (available from `PyPI `_). But if your favorite templating system is not supported as a renderer extension -for BFG, you can create your own simple conmbination as shown above. +for :mod:`pyramid`, you can create your own simple combination as +shown above. .. note:: - If you use third-party templating languages without cooperating BFG - bindings directly within view callables, the auto-template-reload - strategy explained in :ref:`reload_templates_section` will not be - available, nor will the template resource overriding capability - explained in :ref:`overriding_resources_section` be available, nor - will it be possible to use any template using that language as a + If you use third-party templating languages without cooperating + :mod:`pyramid` bindings directly within view callables, the + auto-template-reload strategy explained in + :ref:`reload_templates_section` will not be available, nor will the + template resource overriding capability explained in + :ref:`overriding_resources_section` be available, nor will it be + possible to use any template using that language as a :term:`renderer`. However, it's reasonably easy to write custom - templating system binding packages for use under :mod:`repoze.bfg` - so that templates written in the language can be used as renderers. + templating system binding packages for use under :mod:`pyramid` so + that templates written in the language can be used as renderers. See :ref:`adding_and_overriding_renderers` for instructions on how to create your own template renderer and :ref:`available_template_system_bindings` for example packages. @@ -196,12 +198,12 @@ may set attributes on the response that influence these values. Here's an example of changing the content-type and status of the response object returned by -:func:`repoze.bfg.renderers.render_to_response`: +:func:`pyramid.renderers.render_to_response`: .. code-block:: python :linenos: - from repoze.bfg.renderers.render_to_response + from pyramid.renderers.render_to_response def sample_view(request): response = render_to_response('templates/foo.pt', @@ -212,12 +214,12 @@ response object returned by return response Here's an example of manufacturing a response object using the result -of :func:`repoze.bfg.renderers.render` (a string): +of :func:`pyramid.renderers.render` (a string): .. code-block:: python :linenos: - from repoze.bfg.renderers import render + from pyramid.renderers import render from webob import Response def sample_view(request): result = render('mypackage:templates/foo.pt', @@ -239,13 +241,13 @@ System Values Used During Rendering ----------------------------------- When a template is rendered using -:func:`repoze.bfg.renderers.render_to_response` or -:func:`repoze.bfg.renderers.render`, the renderer representing the +:func:`pyramid.renderers.render_to_response` or +:func:`pyramid.renderers.render`, the renderer representing the template will be provided with a number of *system* values. These values are provided in a dictionary to the renderer and include: ``context`` - The current :mod:`repoze.bfg` context if ``request`` was provided as + The current :mod:`pyramid` context if ``request`` was provided as a keyword argument or ``None``. ``request`` @@ -268,7 +270,7 @@ these names available as top-level template variables. Templates Used as Renderers via Configuration --------------------------------------------- -Instead of using the :func:`repoze.bfg.renderers.render_to_response` +Instead of using the :func:`pyramid.renderers.render_to_response` API within the body of a view function directly to render a specific template to a response, you may associate a template written in a supported templating language with a view indirectly by specifying it @@ -285,14 +287,14 @@ The association of a template as a renderer for a :term:`view configuration` makes it possible to replace code within a :term:`view callable` that handles the rendering of a template. -Here's an example of using a :class:`repoze.bfg.view.bfg_view` +Here's an example of using a :class:`pyramid.view.bfg_view` decorator to specify a :term:`view configuration` that names a template renderer: .. code-block:: python :linenos: - from repoze.bfg.view import bfg_view + from pyramid.view import bfg_view @bfg_view(renderer='templates/foo.pt') def my_view(request): @@ -302,8 +304,8 @@ template renderer: in the dictionary result returned from a renderer-configured view callable in order to ensure that the "most correct" system values are supplied to the renderer as it is when you use - :func:`repoze.bfg.renderers.render` or - :func:`repoze.bfg.renderers.render_to_response`. This is handled + :func:`pyramid.renderers.render` or + :func:`pyramid.renderers.render_to_response`. This is handled automatically. Similar renderer configuration can be done imperatively and via @@ -325,11 +327,11 @@ a :term:`resource specification` in the form address template resources which live in another package. Not just any template from any arbitrary templating system may be used -as a renderer. Bindings must exist specifically for :mod:`repoze.bfg` +as a renderer. Bindings must exist specifically for :mod:`pyramid` to use a templating language template as a renderer. Currently, -:mod:`repoze.bfg` has built-in support for two Chameleon templating +:mod:`pyramid` has built-in support for two Chameleon templating languages: ZPT and text. See :ref:`built_in_renderers` for a -discussion of their details. :mod:`repoze.bfg` also supports the use +discussion of their details. :mod:`pyramid` also supports the use of :term:`Jinja2` templates as renderers. See :ref:`available_template_system_bindings`. @@ -375,9 +377,9 @@ imperatively. See :ref:`renderer_system_values`. :term:`Chameleon` ZPT Templates ------------------------------- -Like :term:`Zope`, :mod:`repoze.bfg` uses :term:`ZPT` (Zope Page +Like :term:`Zope`, :mod:`pyramid` uses :term:`ZPT` (Zope Page Templates) as its default templating language. However, -:mod:`repoze.bfg` uses a different implementation of the :term:`ZPT` +:mod:`pyramid` uses a different implementation of the :term:`ZPT` specification than Zope does: the :term:`Chameleon` templating engine. The Chameleon engine complies largely with the `Zope Page Template `_ template @@ -401,7 +403,7 @@ the template as a :term:`renderer` like so: .. code-block:: python :linenos: - from repoze.bfg.view import bfg_view + from pyramid.view import bfg_view @bfg_view(renderer='templates/foo.pt') def my_view(request): @@ -417,7 +419,7 @@ A Sample ZPT Template ~~~~~~~~~~~~~~~~~~~~~ Here's what a simple :term:`Chameleon` ZPT template used under -:mod:`repoze.bfg` might look like: +:mod:`pyramid` might look like: .. code-block:: xml :linenos: @@ -433,7 +435,7 @@ Here's what a simple :term:`Chameleon` ZPT template used under

pyramid web application framework.

@@ -441,8 +443,8 @@ Here's what a simple :term:`Chameleon` ZPT template used under Note the use of :term:`Genshi` -style ``${replacements}`` above. This is one of the ways that :term:`Chameleon` ZPT differs from standard ZPT. The above template expects to find a ``project`` key in the set -of keywords passed in to it via :func:`repoze.bfg.renderers.render` or -:func:`repoze.bfg.renderers.render_to_response`. Typical ZPT +of keywords passed in to it via :func:`pyramid.renderers.render` or +:func:`pyramid.renderers.render_to_response`. Typical ZPT attribute-based syntax (e.g. ``tal:content`` and ``tal:replace``) also works in these templates. @@ -450,31 +452,31 @@ works in these templates. single: ZPT macros single: Chameleon ZPT macros -Using ZPT Macros in :mod:`repoze.bfg` +Using ZPT Macros in :mod:`pyramid` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ When a :term:`renderer` is used to render a template, -:mod:`repoze.bfg` makes at least two top-level names available to the +:mod:`pyramid` makes at least two top-level names available to the template by default: ``context`` and ``request``. One of the common needs in ZPT-based templates is to use one template's "macros" from within a different template. In Zope, this is typically handled by retrieving the template from the ``context``. But having a hold of -the context in :mod:`repoze.bfg` is not helpful: templates cannot -usually be retrieved from models. To use macros in :mod:`repoze.bfg`, +the context in :mod:`pyramid` is not helpful: templates cannot +usually be retrieved from models. To use macros in :mod:`pyramid`, you need to make the macro template itself available to the rendered template by passing the template in which the macro is defined (or even the macro itself) *into* the rendered template. To make a macro available to the rendered template, you can retrieve a different -template using the :func:`repoze.bfg.renderers.get_renderer` API, +template using the :func:`pyramid.renderers.get_renderer` API, and pass it in to the template being rendered. For example, using a -:term:`view configuration` via a :class:`repoze.bfg.view.bfg_view` +:term:`view configuration` via a :class:`pyramid.view.bfg_view` decorator that uses a :term:`renderer`: .. code-block:: python :linenos: - from repoze.bfg.renderers import get_renderer - from repoze.bfg.view import bfg_view + from pyramid.renderers import get_renderer + from pyramid.view import bfg_view @bfg_view(renderer='templates/mytemplate.pt') def my_view(request): @@ -517,7 +519,7 @@ And ``templates/mytemplate.pt`` might look like so: Templating with :term:`Chameleon` Text Templates ------------------------------------------------ -:mod:`repoze.bfg` also allows for the use of templates which are +:mod:`pyramid` also allows for the use of templates which are composed entirely of non-XML text via :term:`Chameleon`. To do so, you can create templates that are entirely composed of text except for ``${name}`` -style substitution points. @@ -534,7 +536,7 @@ which renders this template: .. code-block:: python :linenos: - from repoze.bfg.view import bfg_view + from pyramid.view import bfg_view @bfg_view(renderer='templates/mytemplate.txt') def my_view(request): @@ -592,7 +594,7 @@ Automatically Reloading Templates It's often convenient to see changes you make to a template file appear immediately without needing to restart the application process. -:mod:`repoze.bfg` allows you to configure your application development +:mod:`pyramid` allows you to configure your application development environment so that a change to a template will be automatically detected, and the template will be reloaded on the next rendering. @@ -623,7 +625,7 @@ Nicer Exceptions in Templates ----------------------------- The exceptions raised by Chameleon templates when a rendering fails -are sometimes less than helpful. :mod:`repoze.bfg` allows you to +are sometimes less than helpful. :mod:`pyramid` allows you to configure your application development environment so that exceptions generated by Chameleon during template compilation and execution will contain nicer debugging information. @@ -663,12 +665,12 @@ on, an exception resulting from the same problem might end like so:: RuntimeError: Caught exception rendering template. - Expression: ``wrong`` - - Filename: /home/fred/env/bfgzodb/bfgzodb/templates/mytemplate.pt - - Arguments: renderer_name: bfgzodb:templates/mytemplate.pt + - Filename: /home/fred/env/proj/proj/templates/mytemplate.pt + - Arguments: renderer_name: proj:templates/mytemplate.pt template: xincludes: request: - project: bfgzodb + project: proj macros: context: view: @@ -706,7 +708,7 @@ templates. Available Add-On Template System Bindings ----------------------------------------- -Jinja2 template bindings are available for :mod:`repoze.bfg` in the +Jinja2 template bindings are available for :mod:`pyramid` in the ``repoze.bfg.jinja2`` package. It lives in the Repoze Subversion repository at `http://svn.repoze.org/repoze.bfg.jinja2 `_; it is also available from diff --git a/docs/narr/threadlocals.rst b/docs/narr/threadlocals.rst index df7023a1a..4fef96ef1 100644 --- a/docs/narr/threadlocals.rst +++ b/docs/narr/threadlocals.rst @@ -14,15 +14,15 @@ true global variable, one thread or process serving the application may receive a different value than another thread or process when that variable is "thread local". -When a request is processed, :mod:`repoze.bfg` makes two :term:`thread +When a request is processed, :mod:`pyramid` makes two :term:`thread local` variables available to the application: a "registry" and a "request". -Why and How :mod:`repoze.bfg` Uses Thread Local Variables +Why and How :mod:`pyramid` Uses Thread Local Variables --------------------------------------------------------- -How are thread locals beneficial to :mod:`repoze.bfg` and application -developers who use :mod:`repoze.bfg`? Well, usually they're decidedly +How are thread locals beneficial to :mod:`pyramid` and application +developers who use :mod:`pyramid`? Well, usually they're decidedly **not**. Using a global or a thread local variable in any application usually makes it a lot harder to understand for a casual reader. Use of a thread local or a global is usually just a way to avoid passing @@ -30,21 +30,21 @@ some value around between functions, which is itself usually a very bad idea, at least if code readability counts as an important concern. For historical reasons, however, thread local variables are indeed -consulted by various :mod:`repoze.bfg` API functions. For example, -the implementation of the :mod:`repoze.bfg.security` function named -:func:`repoze.bfg.security.authenticated_userid` retrieves the thread +consulted by various :mod:`pyramid` API functions. For example, +the implementation of the :mod:`pyramid.security` function named +:func:`pyramid.security.authenticated_userid` retrieves the thread local :term:`application registry` as a matter of course to find an :term:`authentication policy`. It uses the -:func:`repoze.bfg.threadlocal.get_current_registry` function to +:func:`pyramid.threadlocal.get_current_registry` function to retrieve the application registry, from which it looks up the authentication policy; it then uses the authentication policy to -retrieve the authenticated user id. This is how :mod:`repoze.bfg` +retrieve the authenticated user id. This is how :mod:`pyramid` allows arbitrary authentication policies to be "plugged in". -When they need to do so, :mod:`repoze.bfg` internals use two API +When they need to do so, :mod:`pyramid` internals use two API functions to retrieve the :term:`request` and :term:`application -registry`: :func:`repoze.bfg.threadlocal.get_current_request` and -:func:`repoze.bfg.threadlocal.get_current_registry`. The former +registry`: :func:`pyramid.threadlocal.get_current_request` and +:func:`pyramid.threadlocal.get_current_registry`. The former returns the "current" request; the latter returns the "current" registry. Both ``get_current_*`` functions retrieve an object from a thread-local data structure. These API functions are documented in @@ -52,15 +52,15 @@ thread-local data structure. These API functions are documented in These values are thread locals rather than true globals because one Python process may be handling multiple simultaneous requests or even -multiple :mod:`repoze.bfg` applications. If they were true globals, -:mod:`repoze.bfg` could not handle multiple simultaneous requests or -allow more than one :mod:`repoze.bfg` application instance to exist in +multiple :mod:`pyramid` applications. If they were true globals, +:mod:`pyramid` could not handle multiple simultaneous requests or +allow more than one :mod:`pyramid` application instance to exist in a single Python process. -Because one :mod:`repoze.bfg` application is permitted to call -*another* :mod:`repoze.bfg` application from its own :term:`view` code +Because one :mod:`pyramid` application is permitted to call +*another* :mod:`pyramid` application from its own :term:`view` code (perhaps as a :term:`WSGI` app with help from the -:func:`repoze.bfg.wsgi.wsgiapp2` decorator), these variables are +:func:`pyramid.wsgi.wsgiapp2` decorator), these variables are managed in a *stack* during normal system operations. The stack instance itself is a `threading.local `_. @@ -71,34 +71,34 @@ pushes the application's registry and the request on to the stack. At the end of a request, the stack is popped. The topmost request and registry on the stack are considered "current". Therefore, when the system is operating normally, the very definition of "current" is -defined entirely by the behavior of a repoze.bfg :term:`Router`. +defined entirely by the behavior of a pyramid :term:`Router`. However, during unit testing, no Router code is ever invoked, and the definition of "current" is defined by the boundary between calls to -the :meth:`repoze.bfg.configuration.Configurator.begin` and -:meth:`repoze.bfg.configuration.Configurator.end` methods (or between -calls to the :func:`repoze.bfg.testing.setUp` and -:func:`repoze.bfg.testing.tearDown` functions). These functions push +the :meth:`pyramid.configuration.Configurator.begin` and +:meth:`pyramid.configuration.Configurator.end` methods (or between +calls to the :func:`pyramid.testing.setUp` and +:func:`pyramid.testing.tearDown` functions). These functions push and pop the threadlocal stack when the system is under test. See :ref:`test_setup_and_teardown` for the definitions of these functions. -Scripts which use :mod:`repoze.bfg` machinery but never actually start +Scripts which use :mod:`pyramid` machinery but never actually start a WSGI server or receive requests via HTTP such as scripts which use -the :mod:`repoze.bfg.scripting` API will never cause any Router code -to be executed. However, the :mod:`repoze.bfg.scripting` APIs also +the :mod:`pyramid.scripting` API will never cause any Router code +to be executed. However, the :mod:`pyramid.scripting` APIs also push some values on to the thread locals stack as a matter of course. Such scripts should expect the -:func:`repoze.bfg.threadlocal.get_current_request` function to always +:func:`pyramid.threadlocal.get_current_request` function to always return ``None``, and should expect the -:func:`repoze.bfg.threadlocal.get_current_registry` function to return +:func:`pyramid.threadlocal.get_current_registry` function to return exactly the same :term:`application registry` for every request. Why You Shouldn't Abuse Thread Locals ------------------------------------- You probably should almost never use the -:func:`repoze.bfg.threadlocal.get_current_request` or -:func:`repoze.bfg.threadlocal.get_current_registry` functions, except +:func:`pyramid.threadlocal.get_current_request` or +:func:`pyramid.threadlocal.get_current_registry` functions, except perhaps in tests. In particular, it's almost always a mistake to use ``get_current_request`` or ``get_current_registry`` in application code because its usage makes it possible to write code that can be @@ -131,12 +131,12 @@ follows: - Neither ``get_current_request`` nor ``get_current_registry`` should ever be called within application-specific forks of third-party library code. The library you've forked almost certainly has - nothing to do with :mod:`repoze.bfg`, and making it dependent on - :mod:`repoze.bfg` (rather than making your :mod:`repoze.bfg` + nothing to do with :mod:`pyramid`, and making it dependent on + :mod:`pyramid` (rather than making your :mod:`pyramid` application depend upon it) means you're forming a dependency in the wrong direction. -Use of the :func:`repoze.bfg.threadlocal.get_current_request` function +Use of the :func:`pyramid.threadlocal.get_current_request` function in application code *is* still useful in very limited circumstances. As a rule of thumb, usage of ``get_current_request`` is useful **within code which is meant to eventually be removed**. For @@ -153,10 +153,10 @@ time, the older implementation code is disused and the hack that uses ``get_current_request`` is removed. This would be an appropriate place to use the ``get_current_request``. -Use of the :func:`repoze.bfg.threadlocal.get_current_registry` +Use of the :func:`pyramid.threadlocal.get_current_registry` function should be limited to testing scenarios. The registry made current by use of the -:meth:`repoze.bfg.configuration.Configurator.begin` method during a -test (or via :func:`repoze.bfg.testing.setUp`) when you do not pass +:meth:`pyramid.configuration.Configurator.begin` method during a +test (or via :func:`pyramid.testing.setUp`) when you do not pass one in is available to you via this API. diff --git a/docs/narr/traversal.rst b/docs/narr/traversal.rst index bcad6dd07..545e7b3e2 100644 --- a/docs/narr/traversal.rst +++ b/docs/narr/traversal.rst @@ -55,9 +55,9 @@ can run the ``cat`` command: The contents of ``myfile`` are now printed on the user's behalf. -:mod:`repoze.bfg` is very much like this inexperienced UNIX user as it +:mod:`pyramid` is very much like this inexperienced UNIX user as it uses :term:`traversal` against an object graph. In this analogy, we -can map the ``cat`` program to the :mod:`repoze.bfg` concept of a +can map the ``cat`` program to the :mod:`pyramid` concept of a :term:`view callable`: it is a program that can be run against some :term:`context` as the result of :term:`view lookup`. The file being operated on in this analogy is the :term:`context` object; the context @@ -68,7 +68,7 @@ as a stop condition is analogous to :term:`traversal`. The analogy we've used is not *exactly* correct, because, while the naive user already knows which command he wants to invoke before he -starts "traversing" (``cat``), :mod:`repoze.bfg` needs to obtain that +starts "traversing" (``cat``), :mod:`pyramid` needs to obtain that information from the path being traversed itself. In :term:`traversal`, the "command" meant to be invoked is a :term:`view callable`. A view callable is derived via :term:`view lookup` from @@ -136,9 +136,9 @@ the traversal process *after* traversal finds a context object. The combination of the :term:`context` object and the :term:`view name` found via traversal is used later in the same request by a -separate :mod:`repoze.bfg` subsystem -- the :term:`view lookup` +separate :mod:`pyramid` subsystem -- the :term:`view lookup` subsystem -- to find a :term:`view callable` later within the same -request. How :mod:`repoze.bfg` performs view lookup is explained +request. How :mod:`pyramid` performs view lookup is explained within the :ref:`views_chapter` chapter. .. index:: @@ -152,11 +152,11 @@ The Object Graph ---------------- When your application uses :term:`traversal` to resolve URLs to code, -your application must supply an *object graph* to :mod:`repoze.bfg`. +your application must supply an *object graph* to :mod:`pyramid`. This graph is represented by a :term:`root` object. In order to supply a root object for an application, at system startup -time, the :mod:`repoze.bfg` :term:`Router` is configured with a +time, the :mod:`pyramid` :term:`Router` is configured with a callback known as a :term:`root factory`. The root factory is supplied by the application developer as the ``root_factory`` argument to the application's :term:`Configurator`. @@ -180,8 +180,8 @@ named ``config``: config = Configurator(root_factory=Root) Using the ``root_factory`` argument to a -:class:`repoze.bfg.configuration.Configurator` constructor tells your -:mod:`repoze.bfg` application to call this root factory to generate a +:class:`pyramid.configuration.Configurator` constructor tells your +:mod:`pyramid` application to call this root factory to generate a root object whenever a request enters the application. This root factory is also known as the global root factory. A root factory can alternately be passed to the ``Configurator`` as a :term:`dotted @@ -197,15 +197,7 @@ with a database connection or another persistence mechanism. A root object is often an instance of a class which has a ``__getitem__`` method. -.. warning:: In :mod:`repoze.bfg` 1.0 and prior versions, the root - factory was passed a WSGI *environment* object (a dictionary) while - in :mod:`repoze.bfg` 1.1+ it is passed a :term:`request` object. - For backwards compatibility purposes, the request object passed to - the root factory has a dictionary-like interface that emulates the - WSGI environment, so code expecting the argument to be a dictionary - will continue to work. - -If no :term:`root factory` is passed to the :mod:`repoze.bfg` +If no :term:`root factory` is passed to the :mod:`pyramid` :term:`Configurator` constructor, or the ``root_factory`` is specified as the value ``None``, a *default* root factory is used. The default root factory always returns an object that has no child nodes. @@ -234,7 +226,7 @@ root factory always returns an object that has no child nodes. Items contained within the object graph are sometimes analogous to the concept of :term:`model` objects used by many other frameworks (and -:mod:`repoze.bfg` APIs often refers to them as "models", as well). +:mod:`pyramid` APIs often refers to them as "models", as well). They are typically instances of Python classes. The object graph consists of *container* nodes and *leaf* nodes. @@ -277,7 +269,7 @@ until all path segments are exhausted. The Traversal Algorithm ----------------------- -This section will attempt to explain the :mod:`repoze.bfg` traversal +This section will attempt to explain the :mod:`pyramid` traversal algorithm. We'll provide a description of the algorithm, a diagram of how the algorithm works, and some example traversal scenarios that might help you understand how the algorithm operates against a @@ -286,7 +278,7 @@ specific object graph. We'll also talk a bit about :term:`view lookup`. The :ref:`views_chapter` chapter discusses :term:`view lookup` in detail, and it is the canonical source for information about views. -Technically, :term:`view lookup` is a :mod:`repoze.bfg` subsystem that +Technically, :term:`view lookup` is a :mod:`pyramid` subsystem that is separated from traversal entirely. However, we'll describe the fundamental behavior of view lookup in the examples in the next few sections to give you an idea of how traversal and view lookup @@ -306,7 +298,7 @@ When a user requests a page from your :mod:`traversal` -powered application, the system uses this algorithm to find a :term:`context` and a :term:`view name`. -#. The request for the page is presented to the :mod:`repoze.bfg` +#. The request for the page is presented to the :mod:`pyramid` :term:`router` in terms of a standard :term:`WSGI` request, which is represented by a WSGI environment and a WSGI ``start_response`` callable. @@ -371,7 +363,7 @@ and a :term:`view name`. Once :term:`context` and :term:`view name` and associated attributes such as the :term:`subpath` are located, the job of :term:`traversal` is finished. It passes back the information it obtained to its -caller, the :mod:`repoze.bfg` :term:`Router`, which subsequently +caller, the :mod:`pyramid` :term:`Router`, which subsequently invokes :term:`view lookup` with the context and view name information. @@ -453,7 +445,7 @@ lookup asks the :term:`application registry` this question: the class ``Bar``. Let's say that view lookup finds no matching view type. In this -circumstance, the :mod:`repoze.bfg` :term:`router` returns the result +circumstance, the :mod:`pyramid` :term:`router` returns the result of the :term:`not found view` and the request ends. However, for this graph:: @@ -524,7 +516,7 @@ expected to return a response. ``context`` attribute of the request object, e.g. ``request.context``. The :term:`view name` is available as the ``view_name`` attribute of the request object, - e.g. ``request.view_name``. Other :mod:`repoze.bfg` -specific + e.g. ``request.view_name``. Other :mod:`pyramid` -specific request attributes are also available as described in :ref:`special_request_attributes`. @@ -532,15 +524,15 @@ References ---------- A tutorial showing how :term:`traversal` can be used within a -:mod:`repoze.bfg` application exists in :ref:`bfg_wiki_tutorial`. +:mod:`pyramid` application exists in :ref:`bfg_wiki_tutorial`. See the :ref:`views_chapter` chapter for detailed information about :term:`view lookup`. -The :mod:`repoze.bfg.traversal` module contains API functions that +The :mod:`pyramid.traversal` module contains API functions that deal with traversal, such as traversal invocation from within application code. -The :func:`repoze.bfg.url.model_url` function generates a URL when +The :func:`pyramid.url.model_url` function generates a URL when given an object retrieved from an object graph. diff --git a/docs/narr/unittesting.rst b/docs/narr/unittesting.rst index a8005888f..d6f854187 100644 --- a/docs/narr/unittesting.rst +++ b/docs/narr/unittesting.rst @@ -46,15 +46,15 @@ measure of assurance that your "units" work together, as they will be expected to when your application is run in production. The suggested mechanism for unit and integration testing of a -:mod:`repoze.bfg` application is the Python :mod:`unittest` module. +:mod:`pyramid` application is the Python :mod:`unittest` module. Although this module is named :mod:`unittest`, it is actually capable of driving both unit and integration tests. A good :mod:`unittest` tutorial is available within `Dive Into Python `_ by Mark Pilgrim. -:mod:`repoze.bfg` provides a number of facilities that make unit and +:mod:`pyramid` provides a number of facilities that make unit and integration tests easier to write. The facilities become particularly -useful when your code calls into :mod:`repoze.bfg` -related framework +useful when your code calls into :mod:`pyramid` -related framework functions. .. index:: @@ -67,16 +67,16 @@ functions. Test Set Up and Tear Down -------------------------- -:mod:`repoze.bfg` uses a "global" (actually :term:`thread local`) data +:mod:`pyramid` uses a "global" (actually :term:`thread local`) data structure to hold on to two items: the current :term:`request` and the current :term:`application registry`. These data structures are -available via the :func:`repoze.bfg.threadlocal.get_current_request` -and :func:`repoze.bfg.threadlocal.get_current_registry` functions, +available via the :func:`pyramid.threadlocal.get_current_request` +and :func:`pyramid.threadlocal.get_current_registry` functions, respectively. See :ref:`threadlocals_chapter` for information about these functions and the data structures they return. If your code uses these ``get_current_*`` functions or calls -:mod:`repoze.bfg` code which uses ``get_current_*`` functions, you +:mod:`pyramid` code which uses ``get_current_*`` functions, you will need to construct a :term:`Configurator` and call its ``begin`` method within the ``setUp`` method of your unit test and call the same configurator's ``end`` method within the ``tearDown`` method of your @@ -91,7 +91,7 @@ of a single test. Here's an example of using this feature: :linenos: import unittest - from repoze.bfg.configuration import Configurator + from pyramid.configuration import Configurator class MyTest(unittest.TestCase): def setUp(self): @@ -102,31 +102,31 @@ of a single test. Here's an example of using this feature: self.config.end() The above will make sure that -:func:`repoze.bfg.threadlocal.get_current_registry` will return the +:func:`pyramid.threadlocal.get_current_registry` will return the :term:`application registry` associated with the ``config`` Configurator instance when -:func:`repoze.bfg.threadlocal.get_current_registry` is called in a +:func:`pyramid.threadlocal.get_current_registry` is called in a test case method attached to ``MyTest``. Each test case method attached to ``MyTest`` will use an isolated registry. -The :meth:`repoze.bfg.configuration.Configurator.begin` method accepts +The :meth:`pyramid.configuration.Configurator.begin` method accepts various arguments that influence the code run during the test. See the :ref:`configuration_module` chapter for information about the API of a :term:`Configurator`, including its ``begin`` and ``end`` methods. -If you also want to make :func:`repoze.bfg.get_current_request` +If you also want to make :func:`pyramid.get_current_request` return something other than ``None`` during the course of a single test, you can pass a :term:`request` object into the -:meth:`repoze.bfg.configuration.Configurator.begin` method of the +:meth:`pyramid.configuration.Configurator.begin` method of the Configurator within the ``setUp`` method of your test: .. code-block:: python :linenos: import unittest - from repoze.bfg.configuration import Configurator - from repoze.bfg import testing + from pyramid.configuration import Configurator + from pyramid import testing class MyTest(unittest.TestCase): def setUp(self): @@ -140,12 +140,12 @@ Configurator within the ``setUp`` method of your test: If you pass a :term:`request` object into the ``begin`` method of the configurator within your test case's ``setUp``, any test method attached to the ``MyTest`` test case that directly or indirectly calls -:func:`repoze.bfg.threadlocal.get_current_request` will receive the +:func:`pyramid.threadlocal.get_current_request` will receive the request you passed into the ``begin`` method. Otherwise, during -testing, :func:`repoze.bfg.threadlocal.get_current_request` will +testing, :func:`pyramid.threadlocal.get_current_request` will return ``None``. We use a "dummy" request implementation supplied by -:class:`repoze.bfg.testing.DummyRequest` because it's easier to -construct than a "real" :mod:`repoze.bfg` request object. +:class:`pyramid.testing.DummyRequest` because it's easier to +construct than a "real" :mod:`pyramid` request object. What? ~~~~~ @@ -153,8 +153,8 @@ What? Thread local data structures are always a bit confusing, especially when they're used by frameworks. Sorry. So here's a rule of thumb: if you don't *know* whether you're calling code that uses the -:func:`repoze.bfg.threadlocal.get_current_registry` or -:func:`repoze.bfg.threadlocal.get_current_request` functions, or you +:func:`pyramid.threadlocal.get_current_registry` or +:func:`pyramid.threadlocal.get_current_request` functions, or you don't care about any of this, but you still want to write test code, just always create a Configurator instance and call its ``begin`` method within the ``setUp`` of a unit test, then subsequently call its @@ -163,27 +163,27 @@ anything if the application you're testing does not call any ``get_current*`` function. .. index:: - single: repoze.bfg.testing + single: pyramid.testing single: Configurator testing API -Using the ``Configurator`` and ``repoze.bfg.testing`` APIs in Unit Tests +Using the ``Configurator`` and ``pyramid.testing`` APIs in Unit Tests ------------------------------------------------------------------------ -The ``Configurator`` API and the ``repoze.bfg.testing`` module +The ``Configurator`` API and the ``pyramid.testing`` module provide a number of functions which can be used during unit testing. These functions make :term:`configuration declaration` calls to the current :term:`application registry`, but typically register a "stub" or "dummy" feature in place of the "real" feature that the code would call if it was being run normally. -For example, let's imagine you want to unit test a :mod:`repoze.bfg` +For example, let's imagine you want to unit test a :mod:`pyramid` view function. .. code-block:: python :linenos: def view_fn(request): - from repoze.bfg.chameleon_zpt import render_template_to_response + from pyramid.chameleon_zpt import render_template_to_response if 'say' in request.params: return render_template_to_response('templates/submitted.pt', say=request.params['say']) @@ -191,17 +191,17 @@ view function. Without invoking any startup code or using the testing API, an attempt to run this view function in a unit test will result in an error. -When a :mod:`repoze.bfg` application starts normally, it will populate +When a :mod:`pyramid` application starts normally, it will populate a :term:`application registry` using :term:`configuration declaration` calls made against a :term:`Configurator` (sometimes deferring to the application's ``configure.zcml`` :term:`ZCML` file via ``load_zcml``). But if this application registry is not created and populated -(e.g. with an :meth:`repoze.bfg.configuration.Configurator.add_view` +(e.g. with an :meth:`pyramid.configuration.Configurator.add_view` :term:`configuration declaration` or ``view`` declarations in :term:`ZCML`), like when you invoke application code via a unit test, -:mod:`repoze.bfg` API functions will tend to fail. +:mod:`pyramid` API functions will tend to fail. -The testing API provided by :mod:`repoze.bfg` allows you to simulate +The testing API provided by :mod:`pyramid` allows you to simulate various application registry registrations for use under a unit testing framework without needing to invoke the actual application configuration implied by its ``run.py``. For example, if you wanted @@ -213,8 +213,8 @@ used the testing API. :linenos: import unittest - from repoze.bfg.configuration import Configurator - from repoze.bfg import testing + from pyramid.configuration import Configurator + from pyramid import testing class MyTest(unittest.TestCase): def setUp(self): @@ -241,7 +241,7 @@ used the testing API. renderer.assert_(say='Yo') In the above example, we create a ``MyTest`` test case that inherits -from :mod:`unittest.TestCase`. If it's in our :mod:`repoze.bfg` +from :mod:`unittest.TestCase`. If it's in our :mod:`pyramid` application, it will be found when ``setup.py test`` is run. It has two test methods. @@ -249,23 +249,23 @@ The first test method, ``test_view_fn_not_submitted`` tests the ``view_fn`` function in the case that no "form" values (represented by request.params) have been submitted. Its first line registers a "dummy template renderer" named ``templates/show.pt`` via the -:meth:`repoze.bfg.configuration.Configurator.testing_add_template` +:meth:`pyramid.configuration.Configurator.testing_add_template` method; this method returns a -:class:`repoze.bfg.testing.DummyTemplateRenderer` instance which we +:class:`pyramid.testing.DummyTemplateRenderer` instance which we hang on to for later. -We then create a :class:`repoze.bfg.testing.DummyRequest` object which +We then create a :class:`pyramid.testing.DummyRequest` object which simulates a WebOb request object API. A -:class:`repoze.bfg.testing.DummyRequest` is a request object that -requires less setup than a "real" :mod:`repoze.bfg` request. We call +:class:`pyramid.testing.DummyRequest` is a request object that +requires less setup than a "real" :mod:`pyramid` request. We call the function being tested with the manufactured request. When the function is called, -:func:`repoze.bfg.chameleon_zpt.render_template_to_response` will call +:func:`pyramid.chameleon_zpt.render_template_to_response` will call the "dummy" template renderer object instead of the real template renderer object. When the dummy renderer is called, it will set attributes on itself corresponding to the non-path keyword arguments provided to the -:func:`repoze.bfg.chameleon_zpt.render_template_to_response` function. +:func:`pyramid.chameleon_zpt.render_template_to_response` function. We check that the ``say`` parameter sent into the template rendering function was ``Hello`` in this specific example. The ``assert_`` method of the renderer we've created will raise an @@ -281,15 +281,15 @@ attribute is ``Yo``, as this is what is expected of the view function in the branch it's testing. Note that the test calls the -:meth:`repoze.bfg.configuration.Configurator.begin` method in its +:meth:`pyramid.configuration.Configurator.begin` method in its ``setUp`` method and the ``end`` method of the same in its ``tearDown`` method. If you use any of the -:class:`repoze.bfg.configuration.Configurator` APIs during testing, be +:class:`pyramid.configuration.Configurator` APIs during testing, be sure to use this pattern in your test case's ``setUp`` and ``tearDown``; these methods make sure you're using a "fresh" :term:`application registry` per test run. -See the :ref:`testing_module` chapter for the entire :mod:`repoze.bfg` +See the :ref:`testing_module` chapter for the entire :mod:`pyramid` -specific testing API. This chapter describes APIs for registering a security policy, registering models at paths, registering event listeners, registering views and view permissions, and classes @@ -306,22 +306,22 @@ See also the various methods of the :term:`Configurator` documented in Creating Integration Tests -------------------------- -In :mod:`repoze.bfg`, a *unit test* typically relies on "mock" or +In :mod:`pyramid`, a *unit test* typically relies on "mock" or "dummy" implementations to give the code under test only enough context to run. "Integration testing" implies another sort of testing. In the context -of a :mod:`repoze.bfg`, integration test, the test logic tests the +of a :mod:`pyramid`, integration test, the test logic tests the functionality of some code *and* its integration with the rest of the -:mod:`repoze.bfg` framework. +:mod:`pyramid` framework. -In :mod:`repoze.bfg` applications that use :term:`ZCML`, you can +In :mod:`pyramid` applications that use :term:`ZCML`, you can create an integration test by *loading its ZCML* in the test's setup -code. This causes the entire :mod:`repoze.bfg` environment to be set +code. This causes the entire :mod:`pyramid` environment to be set up and torn down as if your application was running "for real". This is a heavy-hammer way of making sure that your tests have enough context to run properly, and it tests your code's integration with the -rest of :mod:`repoze.bfg`. +rest of :mod:`pyramid`. Let's demonstrate this by showing an integration test for a view. The below test assumes that your application's package name is ``myapp``, @@ -335,14 +335,14 @@ environment. import unittest - from repoze.bfg.configuration import Configurator - from repoze.bfg import testing + from pyramid.configuration import Configurator + from pyramid import testing class ViewIntegrationTests(unittest.TestCase): def setUp(self): """ This sets up the application registry with the registrations your application declares in its configure.zcml - (including dependent registrations for repoze.bfg itself). + (including dependent registrations for pyramid itself). """ import myapp self.config = Configurator(package=myapp) @@ -367,7 +367,7 @@ environment. str(len(body)))) Unless you cannot avoid it, you should prefer writing unit tests that -use the :class:`repoze.bfg.configuration,Configurator` API to set up +use the :class:`pyramid.configuration,Configurator` API to set up the right "mock" registrations rather than creating an integration test. Unit tests will run faster (because they do less for each test) and the result of a unit test is usually easier to make assertions diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst index 62a588187..6e7c82f56 100644 --- a/docs/narr/urldispatch.rst +++ b/docs/narr/urldispatch.rst @@ -6,7 +6,7 @@ URL Dispatch ============ -The URL dispatch feature of :mod:`repoze.bfg` allows you to either +The URL dispatch feature of :mod:`pyramid` allows you to either augment or replace :term:`traversal` as a :term:`context finding` mechanism, allowing URL pattern matching to have the "first crack" at resolving a given URL to :term:`context` and :term:`view name`. @@ -15,14 +15,14 @@ Although it is a "context-finding" mechanism, ironically, using URL dispatch exclusively allows you to avoid thinking about your application in terms of "contexts" and "view names" entirely. -Many applications don't need :mod:`repoze.bfg` features -- such as +Many applications don't need :mod:`pyramid` features -- such as declarative security via an :term:`authorization policy` -- that benefit from having any visible separation between :term:`context finding` and :term:`view lookup`. To this end, URL dispatch provides a handy syntax that allows you to effectively map URLs *directly* to :term:`view` code in such a way that you needn't think about your application in terms of "context finding" at all. This makes developing -a :mod:`repoze.bfg` application seem more like developing an +a :mod:`pyramid` application seem more like developing an application in a system that is "context-free", such as :term:`Pylons` or :term:`Django`. @@ -37,7 +37,7 @@ data. The presence of :ref:`route_directive` statements in a :term:`ZCML` file used by your application or the presence of calls to the -:meth:`repoze.bfg.configuration.Configurator.add_route` method in +:meth:`pyramid.configuration.Configurator.add_route` method in imperative configuration within your application is a sign that you're using :term:`URL dispatch`. @@ -45,20 +45,20 @@ High-Level Operational Overview ------------------------------- If route configuration is present in an application, the -:mod:`repoze.bfg` :term:`Router` checks every incoming request against +:mod:`pyramid` :term:`Router` checks every incoming request against an ordered set of URL matching patterns present in a *route map*. If any route pattern matches the information in the :term:`request` -provided to :mod:`repoze.bfg`, a route-specific :term:`context` and +provided to :mod:`pyramid`, a route-specific :term:`context` and :term:`view name` will be generated. In this circumstance, -:mod:`repoze.bfg` will shortcut :term:`traversal`, and will invoke +:mod:`pyramid` will shortcut :term:`traversal`, and will invoke :term:`view lookup` using the context and view name generated by URL dispatch. If the matched route names a :term:`view callable` in its configuration, that view callable will be invoked when view lookup is performed. However, if no route pattern matches the information in the -:term:`request` provided to :mod:`repoze.bfg`, it will fail over to +:term:`request` provided to :mod:`pyramid`, it will fail over to using :term:`traversal` to perform context finding and view lookup. Route Configuration @@ -67,7 +67,7 @@ Route Configuration :term:`Route configuration` is the act of adding a new :term:`route` to an application. A route has a *pattern*, representing a pattern meant to match against the ``PATH_INFO`` portion of a URL, and a -*name*, which is used by developers within a :mod:`repoze.bfg` +*name*, which is used by developers within a :mod:`pyramid` application to uniquely identify a particular route when generating a URL. It also optionally has a ``factory``, a set of :term:`route predicate` parameters, and a set of :term:`view` parameters. @@ -81,7 +81,7 @@ configuration` or via :term:`ZCML`. Both are completely equivalent. Configuring a Route Imperatively via The ``add_route`` Configurator Method ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The :meth:`repoze.bfg.configuration.Configurator.add_route` method +The :meth:`pyramid.configuration.Configurator.add_route` method adds a single :term:`route configuration` to the :term:`application registry`. Here's an example: @@ -89,7 +89,7 @@ registry`. Here's an example: .. code-block:: python # "config" below is presumed to be an instance of the - # repoze.bfg.configuration.Configurator class; "myview" is assumed + # pyramid.configuration.Configurator class; "myview" is assumed # to be a "view callable" function from views import myview config.add_route('myroute', '/prefix/:one/:two', view=myview) @@ -101,7 +101,7 @@ Configuring a Route via ZCML ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Instead of using the imperative -:meth:`repoze.bfg.configuration.Configurator.add_route` method to add +:meth:`pyramid.configuration.Configurator.add_route` method to add a new route, you can alternately use :term:`ZCML`. For example, the following :term:`ZCML declaration` causes a route to be added to the application. @@ -174,7 +174,7 @@ Route View Callable Registration and Lookup Details !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! When a ``view`` attribute is attached to a route configuration, -:mod:`repoze.bfg` ensures that a :term:`view configuration` is +:mod:`pyramid` ensures that a :term:`view configuration` is registered that will always be found when the route pattern is matched during a request. To do so: @@ -196,8 +196,8 @@ during a request. To do so: to service requests that match the route pattern. In this way, we supply a shortcut to the developer. Under the hood, -:mod:`repoze.bfg` still consumes the :term:`context finding` and -:term:`view lookup` subsystems provided by :mod:`repoze.bfg`, but in a +:mod:`pyramid` still consumes the :term:`context finding` and +:term:`view lookup` subsystems provided by :mod:`pyramid`, but in a way which does not require that a developer understand either of them if he doesn't want or need to. It also means that we can allow a developer to combine :term:`URL dispatch` and :term:`traversal` in @@ -211,7 +211,7 @@ various exceptional cases as documented in :ref:`hybrid_chapter`. Route Pattern Syntax ~~~~~~~~~~~~~~~~~~~~ -The syntax of the pattern matching language used by :mod:`repoze.bfg` +The syntax of the pattern matching language used by :mod:`pyramid` URL dispatch in the *pattern* argument is straightforward; it is close to that of the :term:`Routes` system used by :term:`Pylons`. @@ -368,7 +368,7 @@ a result of traversing a graph. The order that routes are evaluated when they are defined via :term:`ZCML` is the order in which they appear in the ZCML relative to each other. For routes added via the -:mod:`repoze.bfg.configuration.Configurator.add_route` method, the +:mod:`pyramid.configuration.Configurator.add_route` method, the order that routes are evaluated is the order in which they are added to the configuration imperatively. @@ -415,7 +415,7 @@ possible to supply a different :term:`context` object to the view related to each particular route. Supplying a different context for each route is useful when you're -trying to use a :mod:`repoze.bfg` :term:`authorization policy` to +trying to use a :mod:`pyramid` :term:`authorization policy` to provide declarative "context-sensitive" security checks; each context can maintain a separate :term:`ACL`, as in :ref:`using_security_with_urldispatch`. It is also useful when you @@ -449,7 +449,7 @@ represent neither predicates nor view configuration information. ``factory`` A Python object (often a function or a class) or a :term:`dotted Python name` to such an object that will generate a - :mod:`repoze.bfg` :term:`context` object when this route + :mod:`pyramid` :term:`context` object when this route matches. For example, ``mypackage.models.MyFactoryClass``. If this argument is not specified, the traversal root factory will be used. @@ -496,7 +496,7 @@ represent neither predicates nor view configuration information. about the syntax of route paths. If the path doesn't match the current URL, route matching continues. - .. note:: In :mod:`repoze.bfg` 1.2 and prior, this argument existed + .. note:: In earlier releases of this framework, this argument existed as ``path``. ``path`` continues to work as an alias for ``pattern``. @@ -648,7 +648,7 @@ Custom Route Predicates ~~~~~~~~~~~~~~~~~~~~~~~ Each of the predicate callables fed to the ``custom_predicates`` -argument of :meth:`repoze.bfg.configuration.Configurator.add_route` or +argument of :meth:`pyramid.configuration.Configurator.add_route` or the ``custom_predicates`` ZCML attribute must be a callable accepting two arguments. The first argument passed to a custom predicate is a dictionary conventionally named ``info``. The second argument is the @@ -657,7 +657,7 @@ current :term:`request` object. The ``info`` dictionary has a number of contained values: ``match`` is a dictionary: it represents the arguments matched in the URL by the route. ``route`` is an object representing the route which was -matched (see :class:`repoze.bfg.interfaces.IRoute` for the API of such +matched (see :class:`pyramid.interfaces.IRoute` for the API of such a route object). ``info['match']`` is useful when predicates need access to the route @@ -750,7 +750,7 @@ The above predicate, when added to a number of route configurations ensures that the year match argument is '2010' if and only if the route name is 'ymd', 'ym', or 'y'. -See also :class:`repoze.bfg.interfaces.IRoute` for more API +See also :class:`pyramid.interfaces.IRoute` for more API documentation about a route object. Route Matching @@ -760,9 +760,9 @@ The main purpose of route configuration is to match (or not match) the ``PATH_INFO`` present in the WSGI environment provided during a request against a URL path pattern. -The way that :mod:`repoze.bfg` does this is very simple. When a +The way that :mod:`pyramid` does this is very simple. When a request enters the system, for each route configuration declaration -present in the system, :mod:`repoze.bfg` checks the ``PATH_INFO`` +present in the system, :mod:`pyramid` checks the ``PATH_INFO`` against the pattern declared. If any route matches, the route matching process stops. The @@ -785,7 +785,7 @@ skipped and route matching continues through the ordered set of routes. If no route matches after all route patterns are exhausted, -:mod:`repoze.bfg` falls back to :term:`traversal` to do :term:`context +:mod:`pyramid` falls back to :term:`traversal` to do :term:`context finding` and :term:`view lookup`. .. index:: @@ -816,7 +816,7 @@ When the URL pattern associated with a particular route configuration is matched by a request, an object named ``matched_route`` is added as an attribute of the :term:`request` object. Thus, ``request.matched_route`` will be an object implementing the -:class:`repoze.bfg.interfaces.IRoute` interface which matched the +:class:`pyramid.interfaces.IRoute` interface which matched the request. The most useful attribute of the route object is ``name``, which is the name of the route that matched. @@ -909,7 +909,7 @@ might add to your application: view="mypackage.views.tag_view" /> -The above configuration will allow :mod:`repoze.bfg` to service URLs +The above configuration will allow :mod:`pyramid` to service URLs in these forms: .. code-block:: text @@ -1059,7 +1059,7 @@ Or provide the literal string ``/`` as the pattern: Generating Route URLs --------------------- -Use the :func:`repoze.bfg.url.route_url` function to generate URLs +Use the :func:`pyramid.url.route_url` function to generate URLs based on route patterns. For example, if you've configured a route in ZCML with the ``name`` "foo" and the ``pattern`` ":a/:b/:c", you might do this. @@ -1068,13 +1068,13 @@ do this. .. code-block:: python :linenos: - from repoze.bfg.url import route_url + from pyramid.url import route_url url = route_url('foo', request, a='1', b='2', c='3') This would return something like the string ``http://example.com/1/2/3`` (at least if the current protocol and hostname implied ``http:/example.com``). See the -:func:`repoze.bfg.url.route_url` API documentation for more +:func:`pyramid.url.route_url` API documentation for more information. .. index:: @@ -1086,7 +1086,7 @@ Redirecting to Slash-Appended Routes ------------------------------------ For behavior like Django's ``APPEND_SLASH=True``, use the -:func:`repoze.bfg.view.append_slash_notfound_view` view as the +:func:`pyramid.view.append_slash_notfound_view` view as the :term:`Not Found view` in your application. When this view is the Not Found view (indicating that no view was found), and any routes have been defined in the configuration of your application, if the value of @@ -1134,51 +1134,49 @@ stanza: :linenos: -Or use the :meth:`repoze.bfg.configuration.Configurator.add_view` +Or use the :meth:`pyramid.configuration.Configurator.add_view` method if you don't use ZCML: .. code-block:: python :linenos: - from repoze.bfg.exceptions import NotFound - from repoze.bfg.view import append_slash_notfound_view + from pyramid.exceptions import NotFound + from pyramid.view import append_slash_notfound_view config.add_view(append_slash_notfound_view, context=NotFound) See :ref:`view_module` and :ref:`changing_the_notfound_view` for more information about the slash-appending not found view and for a more general description of how to configure a not found view. -.. note:: This feature is new as of :mod:`repoze.bfg` 1.1. - Custom Not Found View With Slash Appended Routes ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -There can only be one :term:`Not Found view` in any :mod:`repoze.bfg` +There can only be one :term:`Not Found view` in any :mod:`pyramid` application. Even if you use -:func:`repoze.bfg.view.append_slash_notfound_view` as the Not Found -view, :mod:`repoze.bfg` still must generate a ``404 Not Found`` +:func:`pyramid.view.append_slash_notfound_view` as the Not Found +view, :mod:`pyramid` still must generate a ``404 Not Found`` response when it cannot redirect to a slash-appended URL; this not found response will be visible to site users. If you don't care what this 404 response looks like, and only you need redirections to slash-appended route URLs, you may use the -:func:`repoze.bfg.view.append_slash_notfound_view` object as the Not +:func:`pyramid.view.append_slash_notfound_view` object as the Not Found view as described above. However, if you wish to use a *custom* notfound view callable when a URL cannot be redirected to a slash-appended URL, you may wish to use an instance of the -:class:`repoze.bfg.view.AppendSlashNotFoundViewFactory` class as the +:class:`pyramid.view.AppendSlashNotFoundViewFactory` class as the Not Found view, supplying a :term:`view callable` to be used as the custom notfound view as the first argument to its constructor. For instance: .. code-block:: python - from repoze.bfg.exceptions import NotFound - from repoze.bfg.view import AppendSlashNotFoundViewFactory + from pyramid.exceptions import NotFound + from pyramid.view import AppendSlashNotFoundViewFactory def notfound_view(context, request): return HTTPNotFound('It aint there, stop trying!') @@ -1190,9 +1188,6 @@ The ``notfound_view`` supplied must adhere to the two-argument view callable calling convention of ``(context, request)`` (``context`` will be the exception object). -.. note:: The :class:`repoze.bfg.view.AppendSlashNotFoundViewFactory` - class is new as of BFG 1.3. - .. _cleaning_up_after_a_request: Cleaning Up After a Request @@ -1211,7 +1206,7 @@ Instead of putting this cleanup logic in the root factory, however, you can cause a subscriber to be fired when a new request is detected; the subscriber can do this work. -For example, let's say you have a ``mypackage`` :mod:`repoze.bfg` +For example, let's say you have a ``mypackage`` :mod:`pyramid` application package that uses SQLAlchemy, and you'd like the current SQLAlchemy database session to be removed after each request. Put the following in the ``mypackage.run`` module: @@ -1236,7 +1231,7 @@ Then in the ``configure.zcml`` of your package, inject the following: .. code-block:: xml - Or, if you don't use ZCML, but you do use a :term:`scan` add a @@ -1244,8 +1239,8 @@ subscriber decorator: .. code-block:: python - from repoze.bfg.events import subscriber - from repoze.bfg.interfaces import INewRequest + from pyramid.events import subscriber + from pyramid.interfaces import INewRequest @subscriber(INewRequest) def handle_teardown(event): @@ -1257,8 +1252,8 @@ method of a :term:`Configurator`. .. code-block:: python - from repoze.bfg.interfaces import INewRequest - from repoze.bfg.configuration imoport Configurator + from pyramid.interfaces import INewRequest + from pyramid.configuration imoport Configurator def handle_teardown(event): environ = event.request.environ @@ -1274,7 +1269,7 @@ is destroyed (usually at the end of every request). .. note:: This is only an example. In particular, it is not necessary to cause ``DBSession.remove`` to be called as the result of an event listener in an application generated from any - :mod:`repoze.bfg` paster template, because these all use the + :mod:`pyramid` paster template, because these all use the ``repoze.tm2`` middleware. The cleanup done by ``DBSession.remove`` is unnecessary when ``repoze.tm2`` middleware is in the WSGI pipeline. @@ -1284,10 +1279,10 @@ is destroyed (usually at the end of every request). .. _using_security_with_urldispatch: -Using :mod:`repoze.bfg` Security With URL Dispatch +Using :mod:`pyramid` Security With URL Dispatch -------------------------------------------------- -:mod:`repoze.bfg` provides its own security framework which consults an +:mod:`pyramid` provides its own security framework which consults an :term:`authorization policy` before allowing any application code to be called. This framework operates in terms of an access control list, which is stored as an ``__acl__`` attribute of a context object. @@ -1309,7 +1304,7 @@ Such a ``factory`` might look like so: self.__acl__ = [ (Allow, 'editor', 'view') ] If the route ``archives/:article`` is matched, and the article number -is ``1``, :mod:`repoze.bfg` will generate an ``Article`` +is ``1``, :mod:`pyramid` will generate an ``Article`` :term:`context` with an ACL on it that allows the ``editor`` principal the ``view`` permission. Obviously you can do more generic things than inspect the routes match dict to see if the ``article`` argument @@ -1317,11 +1312,11 @@ matches a particular string; our sample ``Article`` factory class is not very ambitious. .. note:: See :ref:`security_chapter` for more information about - :mod:`repoze.bfg` security and ACLs. + :mod:`pyramid` security and ACLs. References ---------- A tutorial showing how :term:`URL dispatch` can be used to create a -:mod:`repoze.bfg` application exists in :ref:`bfg_sql_wiki_tutorial`. +:mod:`pyramid` application exists in :ref:`bfg_sql_wiki_tutorial`. diff --git a/docs/narr/vhosting.rst b/docs/narr/vhosting.rst index 9050ae8b5..69ef4b72f 100644 --- a/docs/narr/vhosting.rst +++ b/docs/narr/vhosting.rst @@ -6,21 +6,21 @@ Virtual Hosting =============== -"Virtual hosting" is, loosely, the act of serving a :mod:`repoze.bfg` -application or a portion of a :mod:`repoze.bfg` application under a +"Virtual hosting" is, loosely, the act of serving a :mod:`pyramid` +application or a portion of a :mod:`pyramid` application under a URL space that it does not "naturally" inhabit. -:mod:`repoze.bfg` provides facilities for serving an application under +:mod:`pyramid` provides facilities for serving an application under a URL "prefix", as well as serving a *portion* of a :term:`traversal` based application under a root URL. Hosting an Application Under a URL Prefix ----------------------------------------- -:mod:`repoze.bfg` supports a common form of virtual hosting whereby -you can host a :mod:`repoze.bfg` application as a "subset" of some -other site (e.g. under ``http://example.com/mybfgapplication/`` as -opposed to under ``http://example.com/``). +:mod:`pyramid` supports a common form of virtual hosting whereby you +can host a :mod:`pyramid` application as a "subset" of some other site +(e.g. under ``http://example.com/mypyramidapplication/`` as opposed to +under ``http://example.com/``). If you use a "pure Python" environment, this functionality is provided by Paste's `urlmap `_ @@ -29,8 +29,8 @@ by Paste's `urlmap `_ hosting translation for you "under the hood". If you use the ``urlmap`` composite application "in front" of a -:mod:`repoze.bfg` application or if you use :term:`mod_wsgi` to serve -up a :mod:`repoze.bfg` application, nothing special needs to be done +:mod:`pyramid` application or if you use :term:`mod_wsgi` to serve +up a :mod:`pyramid` application, nothing special needs to be done within the application for URLs to be generated that contain a prefix. :mod:`paste.urlmap` and :term:`mod_wsgi` manipulate the :term:`WSGI` environment in such a way that the ``PATH_INFO`` and @@ -41,16 +41,16 @@ a ``urlmap`` composite. .. code-block:: ini - [app:mybfgapp] - use = egg:mybfgapp#app + [app:mypyramidapp] + use = egg:mypyramidapp#app [composite:main] use = egg:Paste#urlmap - /bfgapp = bfgapp + /pyramidapp = mypyramidapp -This "roots" the :mod:`repoze.bfg` application at the prefix -``/bfgapp`` and serves up the composite as the "main" application in -the file. +This "roots" the :mod:`pyramid` application at the prefix +``/pyramidapp`` and serves up the composite as the "main" application +in the file. .. note:: If you're using an Apache server to proxy to a Paste ``urlmap`` composite, you may have to use the `ProxyPreserveHost @@ -69,10 +69,10 @@ work for you: .. code-block:: apache :linenos: - WSGIScriptAlias /bfgapp /Users/chrism/projects/modwsgi/env/bfg.wsgi + WSGIScriptAlias /pyramidapp /Users/chrism/projects/modwsgi/env/pyramid.wsgi -In the above configuration, we root a :mod:`repoze.bfg` application at -``/bfgapp`` within the Apache configuration. +In the above configuration, we root a :mod:`pyramid` application at +``/pyramidapp`` within the Apache configuration. .. index:: single: virtual root @@ -80,12 +80,12 @@ In the above configuration, we root a :mod:`repoze.bfg` application at Virtual Root Support -------------------- -:mod:`repoze.bfg` also supports "virtual roots", which can be used in +:mod:`pyramid` also supports "virtual roots", which can be used in :term:`traversal` -based (but not :term:`URL dispatch` -based) applications. Virtual root support is useful when you'd like to host some model in a -:mod:`repoze.bfg` object graph as an application under a URL pathname +:mod:`pyramid` object graph as an application under a URL pathname that does not include the model path itself. For example, you might want to serve the object at the traversal path ``/cms`` as an application reachable via ``http://example.com/`` (as opposed to @@ -97,7 +97,7 @@ that is the absolute pathname to the model object in the traversal graph that should behave as the "root" model. As a result, the traversal machinery will respect this value during traversal (prepending it to the PATH_INFO before traversal starts), and the -:func:`repoze.bfg.url.model_url` API will generate the "correct" +:func:`pyramid.url.model_url` API will generate the "correct" virtually-rooted URLs. An example of an Apache ``mod_proxy`` configuration that will host the @@ -122,7 +122,7 @@ is below: `_ module be available in the Apache environment you're using. -For a :mod:`repoze.bfg` application running under :term:`mod_wsgi`, +For a :mod:`pyramid` application running under :term:`mod_wsgi`, the same can be achieved using ``SetEnv``: .. code-block:: apache @@ -139,10 +139,10 @@ Further Documentation and Examples ---------------------------------- The API documentation in :ref:`traversal_module` documents a -:func:`repoze.bfg.traversal.virtual_root` API. When called, it +:func:`pyramid.traversal.virtual_root` API. When called, it returns the virtual root object (or the physical root object if no virtual root has been specified). :ref:`modwsgi_tutorial` has detailed information about using -:term:`mod_wsgi` to serve :mod:`repoze.bfg` applications. +:term:`mod_wsgi` to serve :mod:`pyramid` applications. diff --git a/docs/narr/views.rst b/docs/narr/views.rst index 74c39371e..f52df9557 100644 --- a/docs/narr/views.rst +++ b/docs/narr/views.rst @@ -3,7 +3,7 @@ Views ===== -The primary job of any :mod:`repoze.bfg` application is is to find and +The primary job of any :mod:`pyramid` application is is to find and invoke a :term:`view callable` when a :term:`request` reaches the application. View callables are bits of code written by you -- the application developer -- which do something interesting in response to @@ -11,7 +11,7 @@ a request made to your application. .. note:: - A :mod:`repoze.bfg` :term:`view callable` is often referred to in + A :mod:`pyramid` :term:`view callable` is often referred to in conversational shorthand as a :term:`view`. In this documentation, however, we need to use less ambiguous terminology because there are significant differences between view *configuration*, the code @@ -39,12 +39,12 @@ View Callables -------------- No matter how a view callable is eventually found, all view callables -used by :mod:`repoze.bfg` must be constructed in the same way, and +used by :mod:`pyramid` must be constructed in the same way, and must return the same kind of return value. Most view callables accept a single argument named ``request``. This argument represents a :term:`WebOb` :term:`Request` object as -represented to :mod:`repoze.bfg` by the upstream :term:`WSGI` server. +represented to :mod:`pyramid` by the upstream :term:`WSGI` server. A view callable may always return a :term:`WebOb` :term:`Response` object directly. It may optionally return another arbitrary @@ -87,8 +87,6 @@ callable implemented as a function: Defining a View Callable as a Class ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. note:: This feature is new as of :mod:`repoze.bfg` 0.8.1. - A view callable may also be a class instead of a function. When a view callable is a class, the calling semantics are slightly different than when it is a function or another non-class callable. When a view @@ -250,14 +248,14 @@ app_iter Furthermore, a view needn't *always* return a Response object. If a view happens to return something which does not implement the WebOb -Response interface, :mod:`repoze.bfg` will attempt to use a +Response interface, :mod:`pyramid` will attempt to use a :term:`renderer` to construct a response. For example: .. code-block:: python :linenos: from webob import Response - from repoze.bfg.view import bfg_view + from pyramid.view import bfg_view @bfg_view(renderer='json') def hello_world(request): @@ -268,7 +266,7 @@ dictionary does not implement the :term:`WebOb` response interface, so you might believe that this example would fail. However, since a ``renderer`` is associated with the view callable through its :term:`view configuration` (in this case, using a ``renderer`` -argument passed to :func:`repoze.bfg.view.bfg_view`), if the view does +argument passed to :func:`pyramid.view.bfg_view`), if the view does *not* return a Response object, the renderer will attempt to convert the result of the view to a response on the developer's behalf. Of course, if no renderer is associated with a view's configuration, @@ -320,8 +318,6 @@ such as ``401 Unauthorized``. Writing View Callables Which Use a Renderer ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. note:: This feature is new as of :mod:`repoze.bfg` 1.1 - View callables needn't always return a WebOb Response object. Instead, they may return an arbitrary Python object, with the expectation that a :term:`renderer` will convert that object into a @@ -360,7 +356,7 @@ If the :term:`view callable` associated with a :term:`view configuration` returns a Response object directly (an object with the attributes ``status``, ``headerlist`` and ``app_iter``), any renderer associated with the view configuration is ignored, and the response is -passed back to :mod:`repoze.bfg` unmolested. For example, if your +passed back to :mod:`pyramid` unmolested. For example, if your view callable returns an instance of the :class:`webob.exc.HTTPFound` class as a response, no renderer will be employed. @@ -388,7 +384,7 @@ ZCML directive (see :ref:`adding_and_overriding_renderers`). Built-In Renderers ~~~~~~~~~~~~~~~~~~ -Several built-in "renderers" exist in :mod:`repoze.bfg`. These +Several built-in "renderers" exist in :mod:`pyramid`. These renderers can be used in the ``renderer`` attribute of view configurations. @@ -414,7 +410,7 @@ representation of the dictionary: :linenos: from webob import Response - from repoze.bfg.view import bfg_view + from pyramid.view import bfg_view @bfg_view(renderer='string') def hello_world(request): @@ -453,7 +449,7 @@ view will render the returned dictionary to a JSON serialization: :linenos: from webob import Response - from repoze.bfg.view import bfg_view + from pyramid.view import bfg_view @bfg_view(renderer='json') def hello_world(request): @@ -576,7 +572,7 @@ Varying Attributes of Rendered Responses ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Before a response that is constructed as the result of the use of a -:term:`renderer` is returned to :mod:`repoze.bfg`, several attributes +:term:`renderer` is returned to :mod:`pyramid`, several attributes of the request are examined which have the potential to influence response behavior. @@ -613,7 +609,7 @@ attribute to the request before returning a result: .. code-block:: python :linenos: - from repoze.bfg.view import bfg_view + from pyramid.view import bfg_view @bfg_view(name='gone', renderer='templates/gone.pt') def myview(request): @@ -632,14 +628,14 @@ Adding and Overriding Renderers ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ New templating systems and serializers can be associated with -:mod:`repoze.bfg` renderer names. To this end, configuration +:mod:`pyramid` renderer names. To this end, configuration declarations can be made which override an existing :term:`renderer factory` and which add a new renderer factory. Adding or overriding a renderer is accomplished via :term:`ZCML` or via imperative configuration. Renderers can be registered imperatively using the -:meth:`repoze.bfg.configuration.Configurator.add_renderer` API or via +:meth:`pyramid.configuration.Configurator.add_renderer` API or via the :ref:`renderer_directive` ZCML directive. For example, to add a renderer which renders views which have a @@ -740,7 +736,7 @@ attribute of a :term:`view configuration`: .. code-block:: python :linenos: - from repoze.bfg.view import bfg_view + from pyramid.view import bfg_view @bfg_view(renderer='amf') def myview(request): @@ -774,7 +770,7 @@ configuration`: .. code-block:: python :linenos: - from repoze.bfg.view import bfg_view + from pyramid.view import bfg_view @bfg_view(renderer='templates/mytemplate.jinja2') def myview(request): @@ -795,7 +791,7 @@ passed to the ``Jinja2Renderer`` constructor will usually be a renderer factory implementation should be able to deal with either. See also :ref:`renderer_directive` and -:meth:`repoze.bfg.configuration.Configurator.add_renderer`. +:meth:`pyramid.configuration.Configurator.add_renderer`. Overriding an Existing Renderer +++++++++++++++++++++++++++++++ @@ -811,9 +807,9 @@ renderer factory, use: + factory="pyramid.chameleon_zpt.renderer_factory"/> -After you do this, :mod:`repoze.bfg` will treat templates ending in +After you do this, :mod:`pyramid` will treat templates ending in both the ``.pt`` and ``.zpt`` filename extensions as Chameleon ZPT templates. @@ -856,10 +852,10 @@ tag): :linenos: + factory="pyramid.renderers.json_renderer_factory"/> See also :ref:`renderer_directive` and -:meth:`repoze.bfg.configuration.Configurator.add_renderer`. +:meth:`pyramid.configuration.Configurator.add_renderer`. .. index:: single: view exceptions @@ -870,25 +866,25 @@ Using Special Exceptions In View Callables ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Usually when a Python exception is raised within a view callable, -:mod:`repoze.bfg` allows the exception to propagate all the way out to +:mod:`pyramid` allows the exception to propagate all the way out to the :term:`WSGI` server which invoked the application. However, for convenience, two special exceptions exist which are -always handled by :mod:`repoze.bfg` itself. These are -:exc:`repoze.bfg.exceptions.NotFound` and -:exc:`repoze.bfg.exceptions.Forbidden`. Both are exception classes +always handled by :mod:`pyramid` itself. These are +:exc:`pyramid.exceptions.NotFound` and +:exc:`pyramid.exceptions.Forbidden`. Both are exception classes which accept a single positional constructor argument: a ``message``. -If :exc:`repoze.bfg.exceptions.NotFound` is raised within view code, +If :exc:`pyramid.exceptions.NotFound` is raised within view code, the result of the :term:`Not Found View` will be returned to the user agent which performed the request. -If :exc:`repoze.bfg.exceptions.Forbidden` is raised within view code, +If :exc:`pyramid.exceptions.Forbidden` is raised within view code, the result of the :term:`Forbidden View` will be returned to the user agent which performed the request. In all cases, the message provided to the exception constructor is -made available to the view which :mod:`repoze.bfg` invokes as +made available to the view which :mod:`pyramid` invokes as ``request.exception.args[0]``. .. index:: @@ -900,14 +896,14 @@ Exception Views ~~~~~~~~~~~~~~~~ The machinery which allows the special -:exc:`repoze.bfg.exceptions.NotFound` and -:exc:`repoze.bfg.exceptions.Forbidden` exceptions to be caught by +:exc:`pyramid.exceptions.NotFound` and +:exc:`pyramid.exceptions.Forbidden` exceptions to be caught by specialized views as described in :ref:`special_exceptions_in_callables` can also be used by application developers to convert arbitrary exceptions to responses. To register a view that should be called whenever a particular -exception is raised from with :mod:`repoze.bfg` view code, use the +exception is raised from with :mod:`pyramid` view code, use the exception class or one of its superclasses as the ``context`` of a view configuration which points at a view callable you'd like to generate a response. @@ -949,8 +945,8 @@ exception view registration: .. code-block:: python :linenos: - from repoze.bfg.view import bfg_view - from repoze.bfg.exceptions import NotFound + from pyramid.view import bfg_view + from pyramid.exceptions import NotFound from webob.exc import HTTPNotFound @bfg_view(context=NotFound, route_name='home') @@ -990,24 +986,24 @@ Handling Form Submissions in View Callables (Unicode and Character Set Issues) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Most web applications need to accept form submissions from web -browsers and various other clients. In :mod:`repoze.bfg`, form +browsers and various other clients. In :mod:`pyramid`, form submission handling logic is always part of a :term:`view`. For a general overview of how to handle form submission data using the :term:`WebOb` API, see :ref:`webob_chapter` and `"Query and POST variables" within the WebOb documentation `_. -:mod:`repoze.bfg` defers to WebOb for its request and response +:mod:`pyramid` defers to WebOb for its request and response implementations, and handling form submission data is a property of the request implementation. Understanding WebOb's request API is the key to understanding how to process form submission data. There are some defaults that you need to be aware of when trying to -handle form submission data in a :mod:`repoze.bfg` view. Because +handle form submission data in a :mod:`pyramid` view. Because having high-order (non-ASCII) characters in data contained within form submissions is exceedingly common, and because the UTF-8 encoding is the most common encoding used on the web for non-ASCII character data, and because working and storing Unicode values is much saner than -working with and storing bytestrings, :mod:`repoze.bfg` configures the +working with and storing bytestrings, :mod:`pyramid` configures the :term:`WebOb` request machinery to attempt to decode form submission values into Unicode from the UTF-8 character set implicitly. This implicit decoding happens when view code obtains form field values via @@ -1016,7 +1012,7 @@ the :term:`WebOb` ``request.params``, ``request.GET``, or these APIs). For example, let's assume that the following form page is served up to -a browser client, and its ``action`` points at some :mod:`repoze.bfg` +a browser client, and its ``action`` points at some :mod:`pyramid` view code: .. code-block:: xml @@ -1037,7 +1033,7 @@ view code: -The ``myview`` view code in the :mod:`repoze.bfg` application *must* +The ``myview`` view code in the :mod:`pyramid` application *must* expect that the values returned by ``request.params`` will be of type ``unicode``, as opposed to type ``str``. The following will work to accept a form post from the above form: @@ -1063,7 +1059,7 @@ decode already-decoded (``unicode``) values obtained from lastname = request.params['lastname'].decode('utf-8') For implicit decoding to work reliably, youshould ensure that every -form you render that posts to a :mod:`repoze.bfg` view is rendered via +form you render that posts to a :mod:`pyramid` view is rendered via a response that has a ``;charset=UTF-8`` in its ``Content-Type`` header; or, as in the form above, with a ``meta http-equiv`` tag that implies that the charset is UTF-8 within the HTML ``head`` of the page @@ -1092,20 +1088,9 @@ you for response content types that are textual (e.g. ``text/html``, ``application/xml``, etc) as it is rendered. If you are using your own response object, you will need to ensure you do this yourself. -.. note:: The behavior that form values are decoded to Unicode - implicitly when no content type header exists was introduced in - :mod:`repoze.bfg` 0.7.0. Previous versions of :mod:`repoze.bfg` - performed no implicit decoding of form values: it returned the - values from ``request.GET``, ``request.POST`` and - ``request.params`` as bytestrings. Code written before 0.7.0 that - depended on the values from ``request.params``, ``request.GET`` and - ``request.POST`` being returned as bytestrings must at this point - be rewritten to use ``request.str_params``, ``request.str_GET`` or - ``request.str_POST``, which indeed will return bytestrings. - .. note:: Only the *values* of request params obtained via ``request.params``, ``request.GET`` or ``request.POST`` are decoded - to Unicode objects implicitly in :mod:`repoze.bfg`'s default + to Unicode objects implicitly in the :mod:`pyramid` default configuration. The keys are still strings. .. index:: @@ -1117,7 +1102,7 @@ View Configuration: Mapping a Context to a View ----------------------------------------------- A developer makes a :term:`view callable` available for use within a -:mod:`repoze.bfg` application via :term:`view configuration`. A view +:mod:`pyramid` application via :term:`view configuration`. A view configuration associates a view callable with a set of statements about the set of circumstances which must be true for the view callable to be invoked. @@ -1134,12 +1119,12 @@ View configuration is performed in one of three ways: :ref:`view_directive`. - by running a :term:`scan` against application source code which has - a :class:`repoze.bfg.view.bfg_view` decorator attached to a Python - object as per :class:`repoze.bfg.view.bfg_view` and + a :class:`pyramid.view.bfg_view` decorator attached to a Python + object as per :class:`pyramid.view.bfg_view` and :ref:`mapping_views_using_a_decorator_section`. -- by using the :meth:`repoze.bfg.configuration.Configurator.add_view` - method as per :meth:`repoze.bfg.configuration.Configurator.add_view` +- by using the :meth:`pyramid.configuration.Configurator.add_view` + method as per :meth:`pyramid.configuration.Configurator.add_view` and :ref:`mapping_views_using_imperative_config_section`. Each of these mechanisms is completely equivalent to the other. @@ -1148,7 +1133,7 @@ A view configuration might also be performed by virtue of :term:`route configuration`. View configuration via route configuration is performed in one of the following two ways: -- by using the :meth:`repoze.bfg.configuration.Configurator.add_route` +- by using the :meth:`pyramid.configuration.Configurator.add_route` method to create a route with a ``view`` argument. - by adding a ```` declaration that uses a ``view`` attribute to @@ -1230,7 +1215,7 @@ Non-Predicate Arguments The ``renderer`` attribute is optional. If it is not defined, the "null" renderer is assumed (no rendering is performed and the value - is passed back to the upstream :mod:`repoze.bfg` machinery + is passed back to the upstream :mod:`pyramid` machinery unmolested). Note that if the view callable itself returns a :term:`response` (see :ref:`the_response`), the specified renderer implementation is never called. @@ -1247,7 +1232,7 @@ Non-Predicate Arguments is found: see :ref:`view_lookup`. The "best" wrapper view will be found based on the lookup ordering: "under the hood" this wrapper view is looked up via - ``repoze.bfg.view.render_view_to_response(context, request, + ``pyramid.view.render_view_to_response(context, request, 'wrapper_viewname')``. The context and request of a wrapper view is the same context and request of the inner view. @@ -1415,8 +1400,6 @@ Predicate Arguments If ``custom_predicates`` is not specified, no custom predicates are used. - .. note:: This feature is new as of :mod:`repoze.bfg` 1.2. - .. index:: single: ZCML view configuration @@ -1502,7 +1485,7 @@ attribute: name="hello.html" /> -This indicates that when :mod:`repoze.bfg` identifies that the +This indicates that when :mod:`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. @@ -1521,7 +1504,7 @@ View Configuration Using the ``@bfg_view`` Decorator ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ For better locality of reference, you may use the -:class:`repoze.bfg.view.bfg_view` decorator to associate your view +:class:`pyramid.view.bfg_view` decorator to associate your view functions with URLs instead of using :term:`ZCML` or imperative configuration for the same purpose. @@ -1538,22 +1521,22 @@ configuration for the same purpose. Usage of the ``bfg_view`` decorator is a form of :term:`declarative configuration`, like ZCML, but in decorator form. -:class:`repoze.bfg.view.bfg_view` can be used to associate :term:`view +:class:`pyramid.view.bfg_view` can be used to associate :term:`view configuration` information -- as done via the equivalent ZCML -- with -a function that acts as a :mod:`repoze.bfg` view callable. All ZCML +a function that acts as a :mod:`pyramid` view callable. All ZCML :ref:`view_directive` attributes (save for the ``view`` attribute) are available in decorator form and mean precisely the same thing. -An example of the :class:`repoze.bfg.view.bfg_view` decorator might -reside in a :mod:`repoze.bfg` application module ``views.py``: +An example of the :class:`pyramid.view.bfg_view` decorator might +reside in a :mod:`pyramid` application module ``views.py``: .. ignore-next-block .. code-block:: python :linenos: from models import MyModel - from repoze.bfg.view import bfg_view - from repoze.bfg.chameleon_zpt import render_template_to_response + from pyramid.view import bfg_view + from pyramid.chameleon_zpt import render_template_to_response @bfg_view(name='my_view', request_method='POST', context=MyModel, permission='read', renderer='templates/my.pt') @@ -1589,7 +1572,7 @@ All arguments to ``bfg_view`` may be omitted. For example: :linenos: from webob import Response - from repoze.bfg.view import bfg_view + from pyramid.view import bfg_view @bfg_view() def my_view(request): @@ -1603,8 +1586,8 @@ requests with any request method / request type / request param / route name / containment. The mere existence of a ``@bfg_view`` decorator doesn't suffice to -perform view configuration. To make :mod:`repoze.bfg` process your -:class:`repoze.bfg.view.bfg_view` declarations, you *must* do one of +perform view configuration. To make :mod:`pyramid` process your +:class:`pyramid.view.bfg_view` declarations, you *must* do one of the following: - If you are using :term:`ZCML`, insert the following boilerplate into @@ -1615,21 +1598,21 @@ the following: - If you are using :term:`imperative configuration`, use the ``scan`` - method of a :class:`repoze.bfg.configuration.Configurator`: + method of a :class:`pyramid.configuration.Configurator`: .. code-block:: python # config is assumed to be an instance of the - # repoze.bfg.configuration.Configurator class + # pyramid.configuration.Configurator class config.scan() Please see :ref:`decorations_and_code_scanning` for detailed information about what happens when code is scanned for configuration declarations resulting from use of decorators like -:class:`repoze.bfg.view.bfg_view`. +:class:`pyramid.view.bfg_view`. See :ref:`configuration_module` for additional API arguments to the -:meth:`repoze.bfg.configuration.Configurator.scan` method. For +:meth:`pyramid.configuration.Configurator.scan` method. For example, the method allows you to supply a ``package`` argument to better control exactly *which* code will be scanned. This is the same value implied by the ``package`` attribute of the ZCML ```` @@ -1638,7 +1621,7 @@ directive (see :ref:`scan_directive`). ``@bfg_view`` Placement +++++++++++++++++++++++ -A :class:`repoze.bfg.view.bfg_view` decorator can be placed in various +A :class:`pyramid.view.bfg_view` decorator can be placed in various points in your application. If your view callable is a function, it may be used as a function @@ -1647,7 +1630,7 @@ decorator: .. code-block:: python :linenos: - from repoze.bfg.view import bfg_view + from pyramid.view import bfg_view from webob import Response @bfg_view(name='edit') @@ -1664,7 +1647,7 @@ function. For example: :linenos: from webob import Response - from repoze.bfg.view import bfg_view + from pyramid.view import bfg_view @bfg_view() class MyView(object): @@ -1674,7 +1657,7 @@ function. For example: def __call__(self): return Response('hello') -You can use the :class:`repoze.bfg.view.bfg_view` decorator as a +You can use the :class:`pyramid.view.bfg_view` decorator as a simple callable to manually decorate classes in Python 2.5 and below without the decorator syntactic sugar, if you wish: @@ -1682,7 +1665,7 @@ without the decorator syntactic sugar, if you wish: :linenos: from webob import Response - from repoze.bfg.view import bfg_view + from pyramid.view import bfg_view class MyView(object): def __init__(self, request): @@ -1693,14 +1676,14 @@ without the decorator syntactic sugar, if you wish: my_view = bfg_view()(MyView) -More than one :class:`repoze.bfg.view.bfg_view` decorator can be +More than one :class:`pyramid.view.bfg_view` decorator can be stacked on top of any number of others. Each decorator creates a separate view registration. For example: .. code-block:: python :linenos: - from repoze.bfg.view import bfg_view + from pyramid.view import bfg_view from webob import Response @bfg_view(name='edit') @@ -1710,18 +1693,13 @@ separate view registration. For example: This registers the same view under two different names. -.. note:: :class:`repoze.bfg.view.bfg_view` decorator stacking is a - feature new in :mod:`repoze.bfg` 1.1. Previously, these decorators - could not be stacked without the effect of the "upper" decorator - cancelling the effect of the decorator "beneath" it. - The decorator can also be used against class methods: .. code-block:: python :linenos: from webob import Response - from repoze.bfg.view import bfg_view + from pyramid.view import bfg_view class MyView(object): def __init__(self, request): @@ -1750,7 +1728,7 @@ equivalently as the below: :linenos: from webob import Response - from repoze.bfg.view import bfg_view + from pyramid.view import bfg_view @bfg_view(attr='amethod', name='hello') class MyView(object): @@ -1760,11 +1738,6 @@ equivalently as the below: def amethod(self): return Response('hello') -.. note:: The ability to use the :class:`repoze.bfg.view.bfg_view` - decorator as a method decorator is new in :mod:`repoze.bfg` - version 1.1. Previously it could only be used as a class or - function decorator. - .. index:: single: add_view @@ -1773,7 +1746,7 @@ equivalently as the below: View Configuration Using the ``add_view`` Method of a Configurator ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The :meth:`repoze.bfg.configuration.Configurator.add_view` method +The :meth:`pyramid.configuration.Configurator.add_view` method within :ref:`configuration_module` is used to configure a view imperatively. The arguments to this method are very similar to the arguments that you provide to the ``@bfg_view`` decorator. For @@ -1788,13 +1761,13 @@ example: return Response('hello!') # config is assumed to be an instance of the - # repoze.bfg.configuration.Configurator class + # pyramid.configuration.Configurator class config.add_view(hello_world, name='hello.html') The first argument, ``view``, is required. It must either be a Python object which is the view itself or a :term:`dotted Python name` to such an object. All other arguments are optional. See -:meth:`repoze.bfg.configuration.Configurator.add_view` for more +:meth:`pyramid.configuration.Configurator.add_view` for more information. .. index:: @@ -1932,7 +1905,7 @@ user does not possess the ``add`` permission relative to the current View Lookup and Invocation -------------------------- -:term:`View lookup` is the :mod:`repoze.bfg` subsystem responsible for +:term:`View lookup` is the :mod:`pyramid` subsystem responsible for finding an invoking a :term:`view callable`. The view lookup subsystem is passed a :term:`context`, a :term:`view name`, and the :term:`request` object. These three bits of information are referred @@ -1953,7 +1926,7 @@ For any given request, a view with five predicates will always be found and evaluated before a view with two, for example. All predicates must match for the associated view to be called. -This does not mean however, that :mod:`repoze.bfg` "stops looking" +This does not mean however, that :mod:`pyramid` "stops looking" when it finds a view registration with predicates that don't match. If one set of view predicates does not match, the "next most specific" view (if any) view is consulted for predicates, and so on, until a @@ -1962,7 +1935,7 @@ first view with a set of predicates all of which match the request environment will be invoked. If no view can be found which has predicates which allow it to be -matched up with the request, :mod:`repoze.bfg` will return an error to +matched up with the request, :mod:`pyramid` will return an error to the user's browser, representing a "not found" (404) page. See :ref:`changing_the_notfound_view` for more information about changing the default notfound view. diff --git a/docs/narr/webob.rst b/docs/narr/webob.rst index 7241b4ebc..82416a44d 100644 --- a/docs/narr/webob.rst +++ b/docs/narr/webob.rst @@ -10,17 +10,17 @@ Request and Response Objects .. note:: This chapter is adapted from a portion of the :term:`WebOb` documentation, originally written by Ian Bicking. -:mod:`repoze.bfg` uses the :term:`WebOb` package to supply +:mod:`pyramid` uses the :term:`WebOb` package to supply :term:`request` and :term:`response` object implementations. The -:term:`request` object that is passed to a :mod:`repoze.bfg` -:term:`view` is an instance of the :class:`repoze.bfg.request.Request` +:term:`request` object that is passed to a :mod:`pyramid` +:term:`view` is an instance of the :class:`pyramid.request.Request` class, which is a subclass of :class:`webob.Request`. The -:term:`response` returned from a :mod:`repoze.bfg` :term:`view` +:term:`response` returned from a :mod:`pyramid` :term:`view` :term:`renderer` is an instance of the :mod:`webob.Response` class. Users can also return an instance of :mod:`webob.Response` directly from a view as necessary. -WebOb is a project separate from :mod:`repoze.bfg` with a separate set +WebOb is a project separate from :mod:`pyramid` with a separate set of authors and a fully separate `set of documentation `_. @@ -31,7 +31,7 @@ environment and response status/headers/app_iter (body). WebOb request and response objects provide many conveniences for parsing WSGI requests and forming WSGI responses. WebOb is a nice way to represent "raw" WSGI requests and responses; however, we won't -cover that use case in this document, as users of :mod:`repoze.bfg` +cover that use case in this document, as users of :mod:`pyramid` don't typically need to use the WSGI-related features of WebOb directly. The `reference documentation `_ shows many examples of @@ -98,7 +98,7 @@ instance, ``req.if_modified_since`` returns a `datetime `_ object (or None if the header is was not provided). -.. note:: Full API documentation for the :mod:`repoze.bfg` request +.. note:: Full API documentation for the :mod:`pyramid` request object is available in :ref:`request_module`. .. index:: @@ -106,15 +106,15 @@ instance, ``req.if_modified_since`` returns a `datetime .. _special_request_attributes: -Special Attributes Added to the Request by :mod:`repoze.bfg` +Special Attributes Added to the Request by :mod:`pyramid` ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ In addition to the standard :term:`WebOb` attributes, -:mod:`repoze.bfg` adds special attributes to every request: +:mod:`pyramid` adds special attributes to every request: ``context``, ``registry``, ``root``, ``subpath``, ``traversed``, ``view_name``, ``virtual_root`` , and ``virtual_root_path``. These attributes are documented further within the -:class:`repoze.bfg.request.Request` API documentation. +:class:`pyramid.request.Request` API documentation. .. index:: single: request URLs @@ -194,12 +194,12 @@ More Details More detail about the request object API is available in: -- The :class:`repoze.bfg.request.Request` API documentation. +- The :class:`pyramid.request.Request` API documentation. - The `WebOb documentation `_ . All methods and attributes of a ``webob.Request`` documented within the WebOb documentation will work against request objects created by - :mod:`repoze.bfg`. + :mod:`pyramid`. Response ~~~~~~~~ @@ -360,7 +360,7 @@ More details about the response object API are available in the `WebOb documentation `_ . All methods and attributes of a ``webob.Response`` documented within the WebOb documentation will work against response objects created by -:mod:`repoze.bfg`. :mod:`repoze.bfg` does not use a Webob Response +:mod:`pyramid`. :mod:`pyramid` does not use a Webob Response object subclass to represent a response, it uses WebOb's Response class directly. diff --git a/docs/narr/zca.rst b/docs/narr/zca.rst index 11b7eabad..b558580b5 100644 --- a/docs/narr/zca.rst +++ b/docs/narr/zca.rst @@ -8,10 +8,10 @@ .. _zca_chapter: -Using the Zope Component Architecture in :mod:`repoze.bfg` +Using the Zope Component Architecture in :mod:`pyramid` ========================================================== -Under the hood, :mod:`repoze.bfg` uses a :term:`Zope Component +Under the hood, :mod:`pyramid` uses a :term:`Zope Component Architecture` component registry as its :term:`application registry`. The Zope Component Architecture is referred to colloquially as the "ZCA." @@ -25,7 +25,7 @@ as it might appear in a traditional Zope application: .. code-block:: python :linenos: - from repoze.bfg.interfaces import ISettings + from pyramid.interfaces import ISettings from zope.component import getUtility settings = getUtility(ISettings) @@ -36,16 +36,16 @@ API is used by a developer, the conceptual load on a casual reader of code is high. While the ZCA is an excellent tool with which to build a *framework* -such as :mod:`repoze.bfg`, it is not always the best tool with which +such as :mod:`pyramid`, it is not always the best tool with which to build an *application* due to the opacity of the ``zope.component`` -APIs. Accordingly, :mod:`repoze.bfg` tends to hide the the presence +APIs. Accordingly, :mod:`pyramid` tends to hide the the presence of the ZCA from application developers. You needn't understand the -ZCA to create a :mod:`repoze.bfg` application; its use is effectively +ZCA to create a :mod:`pyramid` application; its use is effectively only a framework implementation detail. However, developers who are already used to writing :term:`Zope` applications often still wish to use the ZCA while building a -:mod:`repoze.bfg` application; :mod:`repoze.bfg` makes this possible. +:mod:`pyramid` application; :mod:`pyramid` makes this possible. .. index:: single: get_current_registry @@ -53,7 +53,7 @@ applications often still wish to use the ZCA while building a single: getSiteManager single: ZCA global API -Using the ZCA Global API in a :mod:`repoze.bfg` Application +Using the ZCA Global API in a :mod:`pyramid` Application ----------------------------------------------------------- :term:`Zope` uses a single ZCA registry -- the "global" ZCA registry @@ -72,28 +72,28 @@ process. Most production Zope applications are relatively large, making it impractical due to memory constraints to run more than one Zope -application per Python process. However, a :mod:`repoze.bfg` +application per Python process. However, a :mod:`pyramid` application may be very small and consume very little memory, so it's a reasonable goal to be able to run more than one BFG application per process. -In order to make it possible to run more than one :mod:`repoze.bfg` -application in a single process, :mod:`repoze.bfg` defaults to using a +In order to make it possible to run more than one :mod:`pyramid` +application in a single process, :mod:`pyramid` defaults to using a separate ZCA registry *per application*. While this services a reasonable goal, it causes some issues when trying to use patterns which you might use to build a typical -:term:`Zope` application to build a :mod:`repoze.bfg` application. +:term:`Zope` application to build a :mod:`pyramid` application. Without special help, ZCA "global" APIs such as ``zope.component.getUtility`` and ``zope.component.getSiteManager`` will use the ZCA "global" registry. Therefore, these APIs -will appear to fail when used in a :mod:`repoze.bfg` application, +will appear to fail when used in a :mod:`pyramid` application, because they'll be consulting the ZCA global registry rather than the -component registry associated with your :mod:`repoze.bfg` application. +component registry associated with your :mod:`pyramid` application. There are three ways to fix this: by disusing the ZCA global API entirely, by using -:meth:`repoze.bfg.configuration.Configurator.hook_zca` or by passing +:meth:`pyramid.configuration.Configurator.hook_zca` or by passing the ZCA global registry to the :term:`Configurator` constructor at startup time. We'll describe all three methods in this section. @@ -123,21 +123,21 @@ but it largely mirrors the "global" API almost exactly. If you are willing to disuse the "global" ZCA APIs and use the method interface of a registry instead, you need only know how to obtain the -:mod:`repoze.bfg` component registry. +:mod:`pyramid` component registry. There are two ways of doing so: -- use the :func:`repoze.bfg.threadlocal.get_current_registry` - function within :mod:`repoze.bfg` view or model code. This will - always return the "current" :mod:`repoze.bfg` application registry. +- use the :func:`pyramid.threadlocal.get_current_registry` + function within :mod:`pyramid` view or model code. This will + always return the "current" :mod:`pyramid` application registry. - use the attribute of the :term:`request` object named ``registry`` - in your :mod:`repoze.bfg` view code, eg. ``request.registry``. This + in your :mod:`pyramid` view code, eg. ``request.registry``. This is the ZCA component registry related to the running - :mod:`repoze.bfg` application. + :mod:`pyramid` application. See :ref:`threadlocals_chapter` for more information about -:func:`repoze.bfg.threadlocal.get_current_registry`. +:func:`pyramid.threadlocal.get_current_registry`. .. index:: single: hook_zca (configurator method) @@ -147,13 +147,13 @@ See :ref:`threadlocals_chapter` for more information about Enabling the ZCA Global API by Using ``hook_zca`` +++++++++++++++++++++++++++++++++++++++++++++++++ -Consider the following bit of idiomatic :mod:`repoze.bfg` startup code: +Consider the following bit of idiomatic :mod:`pyramid` startup code: .. code-block:: python :linenos: from zope.component import getGlobalSiteManager - from repoze.bfg.configuration import Configurator + from pyramid.configuration import Configurator def app(global_settings, **settings): config = Configurator(settings=settings) @@ -172,7 +172,7 @@ when a :term:`Configurator` constructor is called, or when a During a request, the application registry created by the Configurator is "made current". This means calls to -:func:`repoze.bfg.threadlocal.get_current_registry` in the thread +:func:`pyramid.threadlocal.get_current_registry` in the thread handling the request will return the component registry associated with the application. @@ -185,14 +185,14 @@ always return the global ZCA registry (the one in To "fix" this and make the ZCA global APIs use the "current" BFG registry, you need to call -:meth:`repoze.bfg.configuration.Configurator.hook_zca` within your +:meth:`pyramid.configuration.Configurator.hook_zca` within your setup code. For example: .. code-block:: python :linenos: from zope.component import getGlobalSiteManager - from repoze.bfg.configuration import Configurator + from pyramid.configuration import Configurator def app(global_settings, **settings): config = Configurator(settings=settings) @@ -210,17 +210,17 @@ is that an analogue of the following code is executed: :linenos: from zope.component import getSiteManager - from repoze.bfg.threadlocal import get_current_registry + from pyramid.threadlocal import get_current_registry getSiteManager.sethook(get_current_registry) -This causes the ZCA global API to start using the :mod:`repoze.bfg` -application registry in threads which are running a :mod:`repoze.bfg` +This causes the ZCA global API to start using the :mod:`pyramid` +application registry in threads which are running a :mod:`pyramid` request. Calling ``hook_zca`` is usually sufficient to "fix" the problem of -being able to use the global ZCA API within a :mod:`repoze.bfg` +being able to use the global ZCA API within a :mod:`pyramid` application. However, it also means that a Zope application that is -running in the same process may start using the :mod:`repoze.bfg` +running in the same process may start using the :mod:`pyramid` global registry instead of the Zope global registry, effectively inverting the original problem. In such a case, follow the steps in the next section, :ref:`using_the_zca_global_registry`. @@ -235,14 +235,14 @@ the next section, :ref:`using_the_zca_global_registry`. Enabling the ZCA Global API by Using The ZCA Global Registry ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -You can tell your :mod:`repoze.bfg` application to use the ZCA global +You can tell your :mod:`pyramid` application to use the ZCA global registry at startup time instead of constructing a new one: .. code-block:: python :linenos: from zope.component import getGlobalSiteManager - from repoze.bfg.configuration import Configurator + from pyramid.configuration import Configurator def app(global_settings, **settings): globalreg = getGlobalSiteManager() @@ -262,7 +262,7 @@ registry with BFG-specific registrations; this is code that is normally executed when a registry is constructed rather than created, but we must call it "by hand" when we pass an explicit registry. -At this point, :mod:`repoze.bfg` will use the ZCA global registry +At this point, :mod:`pyramid` will use the ZCA global registry rather than creating a new application-specific registry; since by default the ZCA global API will use this registry, things will work as you might expect a Zope app to when you use the global ZCA API. @@ -280,15 +280,15 @@ Some :term:`Zope` and third-party :term:`ZCML` directives use the they should actually be calling ``zope.component.getSiteManager``. ``zope.component.getSiteManager`` can be overridden by -:mod:`repoze.bfg` via -:meth:`repoze.bfg.configuration.Configurator.hook_zca`, while +:mod:`pyramid` via +:meth:`pyramid.configuration.Configurator.hook_zca`, while ``zope.component.getGlobalSiteManager`` cannot. Directives that use ``zope.component.getGlobalSiteManager`` are effectively broken; no ZCML directive should be using this function to find a registry to populate. You cannot use ZCML directives which use -``zope.component.getGlobalSiteManager`` within a :mod:`repoze.bfg` +``zope.component.getGlobalSiteManager`` within a :mod:`pyramid` application without passing the ZCA global registry to the :term:`Configurator` constructor at application startup, as per :ref:`using_the_zca_global_registry`. -- cgit v1.2.3

`${project}`, a `repoze.bfg` application

`${project}`, a `Pyramid` application

Welcome to `${project}`, an application generated by the repoze.bfg web + href="http://pylonshq.com/pyramid">Pyramid web application framework.

Search
`repoze.bfg` Documentation

Search
`Pyramid` Documentation

`repoze.bfg` links

`Pyramid` links

Welcome to `${project}`, an application generated by the repoze.bfg web + href="http://pylonshq.com/pyramid">pyramid web application framework.

${project}, a repoze.bfg application

${project}, a Pyramid application

Welcome to ${project}, an application generated by the repoze.bfg web + href="http://pylonshq.com/pyramid">Pyramid web application framework.

Search repoze.bfg Documentation

Search Pyramid Documentation

repoze.bfg links

Pyramid links

Welcome to ${project}, an application generated by the repoze.bfg web + href="http://pylonshq.com/pyramid">pyramid web application framework.

`${project}`, a `repoze.bfg` application

`${project}`, a `Pyramid` application

Welcome to `${project}`, an application generated by the repoze.bfg web + href="http://pylonshq.com/pyramid">Pyramid web application framework.

Search
`repoze.bfg` Documentation

Search
`Pyramid` Documentation

`repoze.bfg` links

`Pyramid` links

Welcome to `${project}`, an application generated by the repoze.bfg web + href="http://pylonshq.com/pyramid">pyramid web application framework.