diff options
Diffstat (limited to 'docs')
| m--------- | docs/_themes | 0 | ||||
| -rw-r--r-- | docs/glossary.rst | 4 | ||||
| -rw-r--r-- | docs/narr/commandline.rst | 56 | ||||
| -rw-r--r-- | docs/narr/hooks.rst | 48 | ||||
| -rw-r--r-- | docs/narr/hybrid.rst | 2 | ||||
| -rw-r--r-- | docs/narr/introspector.rst | 16 | ||||
| -rw-r--r-- | docs/narr/logging.rst | 18 | ||||
| -rw-r--r-- | docs/narr/sessions.rst | 4 |
8 files changed, 117 insertions, 31 deletions
diff --git a/docs/_themes b/docs/_themes -Subproject 3bec9280a6cedb15e97e5899021aa8d723c2538 +Subproject b14bf8c2a0d95ae8e3d38d07ad3721370ae6f3f diff --git a/docs/glossary.rst b/docs/glossary.rst index 01300a0be..911c22075 100644 --- a/docs/glossary.rst +++ b/docs/glossary.rst @@ -16,6 +16,10 @@ Glossary An object which, provided a :term:`WSGI` environment as a single positional argument, returns a Pyramid-compatible request. + response factory + An object which, provided a :term:`request` as a single positional + argument, returns a Pyramid-compatible response. + response An object returned by a :term:`view callable` that represents response data returned to the requesting user agent. It must implement the diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst index 4f16617c4..1fe2d9278 100644 --- a/docs/narr/commandline.rst +++ b/docs/narr/commandline.rst @@ -312,24 +312,60 @@ For example: :linenos: $ $VENV/bin/proutes development.ini - Name Pattern View - ---- ------- ---- - home / <function my_view> - home2 / <function my_view> - another /another None - static/ static/*subpath <static_view object> - catchall /*subpath <function static_view> - -``proutes`` generates a table with three columns: *Name*, *Pattern*, + Name Pattern View + ---- ------- ---- + debugtoolbar /_debug_toolbar/*subpath <wsgiapp> * + __static/ /static/*subpath dummy_starter:static/ * + __static2/ /static2/*subpath /var/www/static/ * + __pdt_images/ /pdt_images/*subpath pyramid_debugtoolbar:static/img/ * + a / <unknown> * + no_view_attached / <unknown> * + route_and_view_attached / app1.standard_views.route_and_view_attached * + method_conflicts /conflicts app1.standard_conflicts <route mismatch> + multiview /multiview app1.standard_views.multiview GET,PATCH + not_post /not_post app1.standard_views.multview !POST,* + +``proutes`` generates a table with four columns: *Name*, *Pattern*, *Method*, and *View*. The items listed in the Name column are route names, the items listed in the Pattern column are route patterns, and the items listed in the View column are representations of the view callable that will be invoked when a request matches the associated -route pattern. The view column may show ``None`` if no associated view +route pattern. The view column may show ``<unknown>`` if no associated view callable could be found. If no routes are configured within your application, nothing will be printed to the console when ``proutes`` is executed. +It is convenient when using the ``proutes`` often to configure which columns +and the order you would like to view them. To facilitate this, ``proutes`` will +look for a special ``[proutes]`` section in your INI file and use those as +defaults. + +For example you may remove request method and place the view first: + +.. code-block:: text + :linenos: + + [proutes] + format = view + name + pattern + +You can also separate the formats with commas or spaces: + +.. code-block:: text + :linenos: + + [proutes] + format = view name pattern + + [proutes] + format = view, name, pattern + +If you want to temporarily configure the columns and order there is the +``--format`` which is a comma separated list of columns you want to include. The +current available formats are ``name``, ``pattern``, ``view``, and ``method``. + + .. index:: pair: tweens; printing single: ptweens diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst index 4da36e730..17cae2c67 100644 --- a/docs/narr/hooks.rst +++ b/docs/narr/hooks.rst @@ -349,6 +349,52 @@ We attach and cache an object named ``extra`` to the ``request`` object. the property .. index:: + single: response factory + +.. _changing_the_response_factory: + +Changing the Response Factory +------------------------------- + +.. versionadded:: 1.6 + +Whenever :app:`Pyramid` returns a response from a view it creates a +:term:`response` object. By default, an instance of the +:class:`pyramid.response.Response` class is created to represent the response +object. + +The factory that :app:`Pyramid` uses to create a response object instance can be +changed by passing a ``response_factory`` argument to the constructor of the +:term:`configurator`. This argument can be either a callable or a +:term:`dotted Python name` representing a callable. + +.. code-block:: python + :linenos: + + from pyramid.response import Response + + class MyResponse(Response): + pass + + config = Configurator(response_factory=lambda r: MyResponse()) + +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:`pyramid.config.Configurator.set_response_factory` method: + +.. code-block:: python + :linenos: + + from pyramid.config import Configurator + from pyramid.response import Response + + class MyResponse(Response): + pass + + config = Configurator() + config.set_response_factory(lambda r: MyResponse()) + +.. index:: single: before render event single: adding renderer globals @@ -730,7 +776,7 @@ If you want to implement your own Response object instead of using the :class:`pyramid.response.Response` object in any capacity at all, you'll have to make sure the object implements every attribute and method outlined in :class:`pyramid.interfaces.IResponse` and you'll have to ensure that it uses -``zope.interface.implementer(IResponse)`` as a class decoratoror. +``zope.interface.implementer(IResponse)`` as a class decorator. .. code-block:: python :linenos: diff --git a/docs/narr/hybrid.rst b/docs/narr/hybrid.rst index 4a3258d35..1c324d22b 100644 --- a/docs/narr/hybrid.rst +++ b/docs/narr/hybrid.rst @@ -453,7 +453,7 @@ commonly in route declarations that look like this: .. code-block:: python :linenos: - from pryamid.static import static_view + from pyramid.static import static_view www = static_view('mypackage:static', use_subpath=True) diff --git a/docs/narr/introspector.rst b/docs/narr/introspector.rst index a7bde4cf7..8caba522c 100644 --- a/docs/narr/introspector.rst +++ b/docs/narr/introspector.rst @@ -121,7 +121,7 @@ introspectables in categories not described here. ``subscriber`` The subscriber callable object (the resolution of the ``subscriber`` - argument passed to ``add_susbcriber``). + argument passed to ``add_subscriber``). ``interfaces`` @@ -137,12 +137,12 @@ introspectables in categories not described here. ``predicates`` The predicate objects created as the result of passing predicate arguments - to ``add_susbcriber`` + to ``add_subscriber`` ``derived_predicates`` Wrappers around the predicate objects created as the result of passing - predicate arguments to ``add_susbcriber`` (to be used when predicates take + predicate arguments to ``add_subscriber`` (to be used when predicates take only one value but must be passed more than one). ``response adapters`` @@ -450,9 +450,9 @@ introspectables in categories not described here. The :class:`pyramid.interfaces.IRendererInfo` object which represents this template's renderer. -``view mapper`` +``view mappers`` - Each introspectable in the ``permissions`` category represents a call to + Each introspectable in the ``view mappers`` category represents a call to :meth:`pyramid.config.Configurator.add_view` that has an explicit ``mapper`` argument to *or* a call to :meth:`pyramid.config.Configurator.set_view_mapper`; each will have @@ -481,8 +481,8 @@ introspectables in categories not described here. ``translation directories`` - Each introspectable in the ``asset overrides`` category represents an - individual element in a ``specs`` argument passed to + Each introspectable in the ``translation directories`` category represents + an individual element in a ``specs`` argument passed to :meth:`pyramid.config.Configurator.add_translation_dirs`; each will have the following data. @@ -511,7 +511,7 @@ introspectables in categories not described here. ``type`` - ``implict`` or ``explicit`` as a string. + ``implicit`` or ``explicit`` as a string. ``under`` diff --git a/docs/narr/logging.rst b/docs/narr/logging.rst index c16673ae6..921883091 100644 --- a/docs/narr/logging.rst +++ b/docs/narr/logging.rst @@ -254,16 +254,15 @@ level unless they're explicitly set differently. Meaning the ``myapp.views``, ``myapp.models`` (and all your app's modules') loggers by default have an effective level of ``DEBUG`` too. -For more advanced filtering, the logging module provides a `Filter -<http://docs.python.org/lib/node423.html>`_ object; however it cannot be used -directly from the configuration file. +For more advanced filtering, the logging module provides a +:class:`logging.Filter` object; however it cannot be used directly from the +configuration file. -Advanced Configuration +Advanced Configuration ---------------------- -To capture log output to a separate file, use a `FileHandler -<http://docs.python.org/lib/node412.html>`_ (or a `RotatingFileHandler -<http://docs.python.org/lib/node413.html>`_): +To capture log output to a separate file, use :class:`logging.FileHandler` (or +:class:`logging.handlers.RotatingFileHandler`): .. code-block:: ini @@ -317,8 +316,9 @@ output, etc., but not web traffic. For web traffic logging Paste provides the :term:`middleware`. TransLogger produces logs in the `Apache Combined Log Format <http://httpd.apache.org/docs/2.2/logs.html#combined>`_. But TransLogger does not write to files, the Python logging system must be -configured to do this. The Python FileHandler_ logging handler can be used -alongside TransLogger to create an ``access.log`` file similar to Apache's. +configured to do this. The Python :class:`logging.FileHandler` logging +handler can be used alongside TransLogger to create an ``access.log`` file +similar to Apache's. Like any standard :term:`middleware` with a Paste entry point, TransLogger can be configured to wrap your application using ``.ini`` file syntax. First, diff --git a/docs/narr/sessions.rst b/docs/narr/sessions.rst index 8da743a01..5c103405a 100644 --- a/docs/narr/sessions.rst +++ b/docs/narr/sessions.rst @@ -44,7 +44,7 @@ It is digitally signed, however, and thus its data cannot easily be tampered with. You can configure this session factory in your :app:`Pyramid` application -by using the :meth:`pyramid.config.Configurator.set_session_factory`` method. +by using the :meth:`pyramid.config.Configurator.set_session_factory` method. .. code-block:: python :linenos: @@ -380,7 +380,7 @@ Checking CSRF Tokens Manually ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ In request handling code, you can check the presence and validity of a CSRF -token with :func:`pyramid.session.check_csrf_token(request)``. If the token is +token with :func:`pyramid.session.check_csrf_token`. If the token is valid, it will return ``True``, otherwise it will raise ``HTTPBadRequest``. Optionally, you can specify ``raises=False`` to have the check return ``False`` instead of raising an exception. |