From 2033eeb3602f330930585678aac926749b9c22f7 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 10 Feb 2014 03:22:33 -0600 Subject: [PATCH] - Garden PR #1121 --- docs/api/registry.rst | 5 +- docs/api/request.rst | 13 +++-- docs/designdefense.rst | 6 ++- docs/glossary.rst | 66 +++++++++++++++++------ docs/narr/advconfig.rst | 8 ++- docs/narr/environment.rst | 38 ++++++++++--- docs/narr/events.rst | 6 ++- docs/narr/hellotraversal.rst | 10 ++-- docs/narr/introduction.rst | 29 +++++++--- docs/narr/project.rst | 19 ++++--- docs/narr/resources.rst | 7 ++- docs/narr/security.rst | 18 +++++-- docs/narr/templates.rst | 6 ++- docs/narr/testing.rst | 6 ++- docs/narr/urldispatch.rst | 5 +- docs/narr/viewconfig.rst | 5 +- docs/quick_tour.rst | 38 ++++++------- docs/quick_tutorial/authentication.rst | 4 +- docs/quick_tutorial/debugtoolbar.rst | 2 +- docs/quick_tutorial/logging.rst | 2 +- docs/quick_tutorial/requirements.rst | 2 +- docs/quick_tutorial/tutorial_approach.rst | 6 +-- docs/quick_tutorial/unit_testing.rst | 2 +- docs/whatsnew-1.0.rst | 7 ++- docs/whatsnew-1.1.rst | 19 ++++--- pyramid/config/__init__.py | 7 ++- pyramid/config/factories.py | 6 +-- pyramid/config/routes.py | 31 ++++++----- pyramid/config/security.py | 4 +- pyramid/config/views.py | 30 ++++++----- pyramid/events.py | 4 +- pyramid/i18n.py | 25 +++++---- pyramid/interfaces.py | 10 ++-- pyramid/renderers.py | 4 +- pyramid/request.py | 8 ++- pyramid/router.py | 36 ++----------- pyramid/security.py | 16 +++--- pyramid/session.py | 10 ++-- pyramid/url.py | 7 ++- pyramid/view.py | 18 ++++--- 40 files changed, 338 insertions(+), 207 deletions(-) diff --git a/docs/api/registry.rst b/docs/api/registry.rst index 7736cf0751..bab3e26ba6 100644 --- a/docs/api/registry.rst +++ b/docs/api/registry.rst @@ -21,7 +21,10 @@ When a registry is set up (or created) by a :term:`Configurator`, the registry will be decorated with an instance named ``introspector`` implementing the :class:`pyramid.interfaces.IIntrospector` interface. - See also :attr:`pyramid.config.Configurator.introspector`. + + .. seealso:: + + See also :attr:`pyramid.config.Configurator.introspector`. When a registry is created "by hand", however, this attribute will not exist until set up by a configurator. diff --git a/docs/api/request.rst b/docs/api/request.rst index b7604020ea..343d0c0227 100644 --- a/docs/api/request.rst +++ b/docs/api/request.rst @@ -250,8 +250,11 @@ ``invoke_subrequest`` isn't *actually* a method of the Request object; it's a callable added when the Pyramid router is invoked, or when a subrequest is invoked. This means that it's not available for use on a - request provided by e.g. the ``pshell`` environment. For more - information, see :ref:`subrequest_chapter`. + request provided by e.g. the ``pshell`` environment. + + .. seealso:: + + See also :ref:`subrequest_chapter`. .. automethod:: has_permission @@ -280,7 +283,11 @@ This property will return the JSON-decoded variant of the request body. If the request body is not well-formed JSON, or there is no body associated with this request, this property will raise an - exception. See also :ref:`request_json_body`. + exception. + + .. seealso:: + + See also :ref:`request_json_body`. .. method:: set_property(callable, name=None, reify=False) diff --git a/docs/designdefense.rst b/docs/designdefense.rst index 418ceb08f0..1ed4f65a42 100644 --- a/docs/designdefense.rst +++ b/docs/designdefense.rst @@ -537,7 +537,11 @@ text indexing. It does not dictate how you arrange your code. Such opinionated functionality exists in applications and frameworks built *on top* of :app:`Pyramid`. It's intended that higher-level systems emerge -built using :app:`Pyramid` as a base. See also :ref:`apps_are_extensible`. +built using :app:`Pyramid` as a base. + +.. seealso:: + + See also :ref:`apps_are_extensible`. Pyramid Provides Too Many "Rails" --------------------------------- diff --git a/docs/glossary.rst b/docs/glossary.rst index 406b817782..0e340491bd 100644 --- a/docs/glossary.rst +++ b/docs/glossary.rst @@ -54,8 +54,12 @@ Glossary provides an API for addressing "asset files" within a Python :term:`package`. Asset files are static files, template files, etc; basically anything non-Python-source that lives in a Python package can - be considered a asset file. See also `PkgResources - `_ + be considered a asset file. + + .. seealso:: + + See also `PkgResources + `_. asset Any file contained within a Python :term:`package` which is *not* @@ -242,7 +246,11 @@ Glossary be effectively amended with a ``permission`` argument that will require that the executing user possess the default permission in order to successfully execute the associated :term:`view - callable` See also :ref:`setting_a_default_permission`. + callable`. + + .. seealso:: + + See also :ref:`setting_a_default_permission`. ACE An *access control entry*. An access control entry is one element @@ -380,7 +388,11 @@ Glossary route A single pattern matched by the :term:`url dispatch` subsystem, which generally resolves to a :term:`root factory` (and then - ultimately a :term:`view`). See also :term:`url dispatch`. + ultimately a :term:`view`). + + .. seealso:: + + See also :term:`url dispatch`. route configuration Route configuration is the act of associating request parameters with a @@ -580,8 +592,11 @@ Glossary A wrapper around a Python function or class which accepts the function or class as its first argument and which returns an arbitrary object. :app:`Pyramid` provides several decorators, - used for configuration and return value modification purposes. See - also `PEP 318 `_. + used for configuration and return value modification purposes. + + .. seealso:: + + See also `PEP 318 `_. configuration declaration An individual method call made to a :term:`configuration directive`, @@ -646,8 +661,11 @@ Glossary HTTP Exception The set of exception classes defined in :mod:`pyramid.httpexceptions`. These can be used to generate responses with various status codes when - raised or returned from a :term:`view callable`. See also - :ref:`http_exceptions`. + raised or returned from a :term:`view callable`. + + .. seealso:: + + See also :ref:`http_exceptions`. thread local A thread-local variable is one which is essentially a global variable @@ -656,8 +674,11 @@ Glossary application may have a different value for this same "global" variable. :app:`Pyramid` uses a small number of thread local variables, as described in :ref:`threadlocals_chapter`. - See also the :class:`stdlib documentation ` - for more information. + + .. seealso:: + + See also the :class:`stdlib documentation ` + for more information. multidict An ordered dictionary that can have multiple values for each key. Adds @@ -671,7 +692,11 @@ Glossary Agendaless Consulting A consulting organization formed by Paul Everitt, Tres Seaver, - and Chris McDonough. See also http://agendaless.com . + and Chris McDonough. + + .. seealso:: + + See also `Agendaless Consulting `_. Jython A `Python implementation `_ written for @@ -792,15 +817,21 @@ Glossary The act of creating software with a user interface that can potentially be displayed in more than one language or cultural context. Often shortened to "i18n" (because the word - "internationalization" is I, 18 letters, then N). See also: - :term:`Localization`. + "internationalization" is I, 18 letters, then N). + + .. seealso:: + + See also :term:`Localization`. Localization The process of displaying the user interface of an internationalized application in a particular language or cultural context. Often shortened to "l10" (because the word - "localization" is L, 10 letters, then N). See also: - :term:`Internationalization`. + "localization" is L, 10 letters, then N). + + .. seealso:: + + See also :term:`Internationalization`. renderer globals Values injected as names into a renderer by a @@ -809,7 +840,10 @@ Glossary response callback A user-defined callback executed by the :term:`router` at a point after a :term:`response` object is successfully created. - See :ref:`using_response_callbacks`. + + .. seealso:: + + See also :ref:`using_response_callbacks`. finished callback A user-defined callback executed by the :term:`router` diff --git a/docs/narr/advconfig.rst b/docs/narr/advconfig.rst index d3431e39e7..9ceaaa4957 100644 --- a/docs/narr/advconfig.rst +++ b/docs/narr/advconfig.rst @@ -158,8 +158,12 @@ use :meth:`pyramid.config.Configurator.include`: Using :meth:`~pyramid.config.Configurator.include` instead of calling the function directly provides a modicum of automated conflict resolution, with the configuration statements you define in the calling code overriding those -of the included function. See also :ref:`automatic_conflict_resolution` and -:ref:`including_configuration`. +of the included function. + +.. seealso:: + + See also :ref:`automatic_conflict_resolution` and + :ref:`including_configuration`. Using ``config.commit()`` +++++++++++++++++++++++++ diff --git a/docs/narr/environment.rst b/docs/narr/environment.rst index f0c0c18fee..412635f08a 100644 --- a/docs/narr/environment.rst +++ b/docs/narr/environment.rst @@ -59,8 +59,11 @@ third-party template rendering extensions. Reloading Assets ---------------- -Don't cache any asset file data when this value is true. See -also :ref:`overriding_assets_section`. +Don't cache any asset file data when this value is true. + +.. seealso:: + + See also :ref:`overriding_assets_section`. +---------------------------------+-----------------------------+ | Environment Variable Name | Config File Setting Name | @@ -79,7 +82,11 @@ Debugging Authorization ----------------------- Print view authorization failure and success information to stderr -when this value is true. See also :ref:`debug_authorization_section`. +when this value is true. + +.. seealso:: + + See also :ref:`debug_authorization_section`. +---------------------------------+-----------------------------------+ | Environment Variable Name | Config File Setting Name | @@ -94,7 +101,11 @@ Debugging Not Found Errors -------------------------- Print view-related ``NotFound`` debug messages to stderr -when this value is true. See also :ref:`debug_notfound_section`. +when this value is true. + +.. seealso:: + + See also :ref:`debug_notfound_section`. +---------------------------------+------------------------------+ | Environment Variable Name | Config File Setting Name | @@ -109,7 +120,11 @@ Debugging Route Matching ------------------------ Print debugging messages related to :term:`url dispatch` route matching when -this value is true. See also :ref:`debug_routematch_section`. +this value is true. + +.. seealso:: + + See also :ref:`debug_routematch_section`. +---------------------------------+--------------------------------+ | Environment Variable Name | Config File Setting Name | @@ -128,7 +143,11 @@ Preventing HTTP Caching Prevent the ``http_cache`` view configuration argument from having any effect globally in this process when this value is true. No http caching-related response headers will be set by the Pyramid ``http_cache`` view configuration -feature when this is true. See also :ref:`influencing_http_caching`. +feature when this is true. + +.. seealso:: + + See also :ref:`influencing_http_caching`. +---------------------------------+----------------------------------+ | Environment Variable Name | Config File Setting Name | @@ -173,8 +192,11 @@ Default Locale Name -------------------- The value supplied here is used as the default locale name when a -:term:`locale negotiator` is not registered. See also -:ref:`localization_deployment_settings`. +:term:`locale negotiator` is not registered. + +.. seealso:: + + See also :ref:`localization_deployment_settings`. +---------------------------------+-----------------------------------+ | Environment Variable Name | Config File Setting Name | diff --git a/docs/narr/events.rst b/docs/narr/events.rst index 50484761d8..09caac898f 100644 --- a/docs/narr/events.rst +++ b/docs/narr/events.rst @@ -44,7 +44,7 @@ Configuring an Event Listener Imperatively You can imperatively configure a subscriber function to be called for some event type via the :meth:`~pyramid.config.Configurator.add_subscriber` -method (see also :term:`Configurator`): +method: .. code-block:: python :linenos: @@ -63,6 +63,10 @@ The first argument to subscriber function (or a :term:`dotted Python name` which refers to a subscriber callable); the second argument is the event type. +.. seealso:: + + See also :term:`Configurator`. + Configuring an Event Listener Using a Decorator ----------------------------------------------- diff --git a/docs/narr/hellotraversal.rst b/docs/narr/hellotraversal.rst index 142c24f54f..0a93b8f166 100644 --- a/docs/narr/hellotraversal.rst +++ b/docs/narr/hellotraversal.rst @@ -60,10 +60,10 @@ A more complicated application could have many types of resources, with different view callables defined for each type, and even multiple views for each type. -See Also ---------- +.. seealso:: -Full technical details may be found in :doc:`traversal`. - -For more about *why* you might use traversal, see :doc:`muchadoabouttraversal`. + Full technical details may be found in :doc:`traversal`. + + For more about *why* you might use traversal, see + :doc:`muchadoabouttraversal`. diff --git a/docs/narr/introduction.rst b/docs/narr/introduction.rst index 8acbab3a05..a37d74c9b5 100644 --- a/docs/narr/introduction.rst +++ b/docs/narr/introduction.rst @@ -121,7 +121,9 @@ ways. .. literalinclude:: helloworld.py -See also :ref:`firstapp_chapter`. +.. seealso:: + + See also :ref:`firstapp_chapter`. Decorator-based configuration ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -271,7 +273,9 @@ Here's a few views defined as methods of a class instead: def view_two(self): return Response('two') -See also :ref:`view_config_placement`. +.. seealso:: + + See also :ref:`view_config_placement`. .. _intro_asset_specs: @@ -572,7 +576,10 @@ For example: config.include('pyramid_exclog') config.include('some.other.guys.package', route_prefix='/someotherguy') -See also :ref:`including_configuration` and :ref:`building_an_extensible_app` +.. seealso:: + + See also :ref:`including_configuration` and + :ref:`building_an_extensible_app`. Flexible authentication and authorization ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -730,7 +737,9 @@ Pyramid defaults to explicit behavior, because it's the most generally useful, but provides hooks that allow you to adapt the framework to localized aesthetic desires. -See also :ref:`using_iresponse`. +.. seealso:: + + See also :ref:`using_iresponse`. "Global" response object ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -748,7 +757,9 @@ section," you say. Fine. Be that way: response.content_type = 'text/plain' return response -See also :ref:`request_response_attr`. +.. seealso:: + + See also :ref:`request_response_attr`. Automating repetitive configuration ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -811,7 +822,9 @@ it up and calling :meth:`~pyramid.config.Configurator.add_directive` from within a function called when another user uses the :meth:`~pyramid.config.Configurator.include` method against your code. -See also :ref:`add_directive`. +.. seealso:: + + See also :ref:`add_directive`. Programmatic Introspection ~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -839,7 +852,9 @@ callable: route_intr = introspector.get('routes', route_name) return Response(str(route_intr['pattern'])) -See also :ref:`using_introspection`. +.. seealso:: + + See also :ref:`using_introspection`. Python 3 Compatibility ~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/narr/project.rst b/docs/narr/project.rst index eb12f67ef5..62b91de0ef 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -898,15 +898,22 @@ returns the HTML in a :term:`response`. a server restart to reload them. Production applications should use ``pyramid.reload_templates = False``. -.. seealso:: See also :ref:`views_which_use_a_renderer` for more information +.. seealso:: + + See also :ref:`views_which_use_a_renderer` for more information about how views, renderers, and templates relate and cooperate. -.. seealso:: Pyramid can also dynamically reload changed Python files. For - more on this see :ref:`reloading_code`. +.. seealso:: + + Pyramid can also dynamically reload changed Python files. See also + :ref:`reloading_code`. + +.. seealso:: -.. seealso:: The :ref:`debug_toolbar` provides interactive access to your - application's internals and, should an exception occur, allows interactive - access to traceback execution stack frames from the Python interpreter. + See also the :ref:`debug_toolbar`, which provides interactive access to + your application's internals and, should an exception occur, allows + interactive access to traceback execution stack frames from the Python + interpreter. .. index:: single: static directory diff --git a/docs/narr/resources.rst b/docs/narr/resources.rst index f3ff1dc4cb..6139154ff7 100644 --- a/docs/narr/resources.rst +++ b/docs/narr/resources.rst @@ -673,8 +673,11 @@ Calling ``find_interface(b, Thing2)`` will return the ``b`` resource. The second argument to find_interface may also be a :term:`interface` instead of a class. If it is an interface, each resource in the lineage is checked to see if the resource implements the specificed interface (instead of seeing -if the resource is of a class). See also -:ref:`resources_which_implement_interfaces`. +if the resource is of a class). + +.. seealso:: + + See also :ref:`resources_which_implement_interfaces`. .. index:: single: resource API functions diff --git a/docs/narr/security.rst b/docs/narr/security.rst index 9e6fb6c829..8db23a33ba 100644 --- a/docs/narr/security.rst +++ b/docs/narr/security.rst @@ -113,9 +113,11 @@ authorization policies, it is an error to configure a Pyramid application with an authentication policy but without the authorization policy or vice versa. If you do this, you'll receive an error at application startup time. -See also the :mod:`pyramid.authorization` and -:mod:`pyramid.authentication` modules for alternate implementations -of authorization and authentication policies. +.. seealso:: + + See also the :mod:`pyramid.authorization` and + :mod:`pyramid.authentication` modules for alternate implementations of + authorization and authentication policies. .. index:: single: permissions @@ -495,8 +497,14 @@ is said to be *location-aware*. Location-aware objects define an ``__parent__`` attribute which points at their parent object. The root object's ``__parent__`` is ``None``. -See :ref:`location_module` for documentations of functions which use -location-awareness. See also :ref:`location_aware`. +.. seealso:: + + See also :ref:`location_module` for documentations of functions which use + location-awareness. + +.. seealso:: + + See also :ref:`location_aware`. .. index:: single: forbidden view diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst index 00fc216341..038dd2594f 100644 --- a/docs/narr/templates.rst +++ b/docs/narr/templates.rst @@ -320,7 +320,11 @@ template renderer: in Chameleon, not in Mako templates. Similar renderer configuration can be done imperatively. See -:ref:`views_which_use_a_renderer`. See also :ref:`built_in_renderers`. +:ref:`views_which_use_a_renderer`. + +.. seealso:: + + See also :ref:`built_in_renderers`. Although a renderer path is usually just a simple relative pathname, a path named as a renderer can be absolute, starting with a slash on UNIX or a drive diff --git a/docs/narr/testing.rst b/docs/narr/testing.rst index 5a5bf8fade..e001ad81c5 100644 --- a/docs/narr/testing.rst +++ b/docs/narr/testing.rst @@ -319,8 +319,10 @@ registering resources at paths, registering event listeners, registering views and view permissions, and classes representing "dummy" implementations of a request and a resource. -See also the various methods of the :term:`Configurator` documented in -:ref:`configuration_module` that begin with the ``testing_`` prefix. +.. seealso:: + + See also the various methods of the :term:`Configurator` documented in + :ref:`configuration_module` that begin with the ``testing_`` prefix. .. index:: single: integration tests diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst index 96ee5758ed..87a962a9a6 100644 --- a/docs/narr/urldispatch.rst +++ b/docs/narr/urldispatch.rst @@ -1183,9 +1183,10 @@ still easily do it by wrapping it in classmethod call. Same will work with staticmethod, just use ``staticmethod`` instead of ``classmethod``. +.. seealso:: -See also :class:`pyramid.interfaces.IRoute` for more API documentation about -route objects. + See also :class:`pyramid.interfaces.IRoute` for more API documentation + about route objects. .. index:: single: route factory diff --git a/docs/narr/viewconfig.rst b/docs/narr/viewconfig.rst index 84fde3f01b..adc53bd11b 100644 --- a/docs/narr/viewconfig.rst +++ b/docs/narr/viewconfig.rst @@ -118,8 +118,9 @@ Non-Predicate Arguments ``renderer`` Denotes the :term:`renderer` implementation which will be used to construct - a :term:`response` from the associated view callable's return value. (see - also :ref:`renderers_chapter`). + a :term:`response` from the associated view callable's return value. + + .. seealso:: See also :ref:`renderers_chapter`. This is either a single string term (e.g. ``json``) or a string implying a path or :term:`asset specification` (e.g. ``templates/views.pt``) naming a diff --git a/docs/quick_tour.rst b/docs/quick_tour.rst index 65fd002d5a..2d4e679f87 100644 --- a/docs/quick_tour.rst +++ b/docs/quick_tour.rst @@ -49,7 +49,7 @@ production support in October 2011.) some optional C extensions for performance. With ``easy_install``, Windows users can get these extensions without needing a C compiler. -.. seealso:: See Also: +.. seealso:: See also: :ref:`Quick Tutorial section on Requirements `, :ref:`installing_unix`, :ref:`Before You Install `, and @@ -92,7 +92,7 @@ in Pyramid development. Building an application from loosely-coupled parts via :doc:`../narr/configuration` is a central idea in Pyramid, one that we will revisit regurlarly in this *Quick Tour*. -.. seealso:: See Also: +.. seealso:: See also: :ref:`Quick Tutorial Hello World `, :ref:`firstapp_chapter`, and :ref:`Single File Tasks tutorial ` @@ -125,7 +125,7 @@ the name is included in the body of the response:: Finally, we set the response's content type and return the Response. -.. seealso:: See Also: +.. seealso:: See also: :ref:`Quick Tutorial Request and Response ` and :ref:`webob_chapter` @@ -178,7 +178,7 @@ configuration`, in which a Python :term:`decorator` is placed on the line above the view. Both approaches result in the same final configuration, thus usually, it is simply a matter of taste. -.. seealso:: See Also: +.. seealso:: See also: :ref:`Quick Tutorial Views `, :doc:`../narr/views`, :doc:`../narr/viewconfig`, and @@ -226,7 +226,7 @@ view: "replacement patterns" (the curly braces) in the route declaration. This information can then be used in your view. -.. seealso:: See Also: +.. seealso:: See also: :ref:`Quick Tutorial Routing `, :doc:`../narr/urldispatch`, :ref:`debug_routematch_section`, and @@ -277,7 +277,7 @@ Since our view returned ``dict(name=request.matchdict['name'])``, we can use ``name`` as a variable in our template via ``${name}``. -.. seealso:: See Also: +.. seealso:: See also: :ref:`Quick Tutorial Templating `, :doc:`../narr/templates`, :ref:`debugging_templates`, and @@ -320,7 +320,7 @@ filename extensions. In this case, changing the extension from ``.pt`` to ``.jinja2`` passed the view response through the ``pyramid_jinja2`` renderer. -.. seealso:: See Also: +.. seealso:: See also: :ref:`Quick Tutorial Jinja2 `, `Jinja2 homepage `_, and :ref:`pyramid_jinja2 Overview ` @@ -368,7 +368,7 @@ By using ``request.static_url`` to generate the full URL to the static assets, you both ensure you stay in sync with the configuration and gain refactoring flexibility later. -.. seealso:: See Also: +.. seealso:: See also: :ref:`Quick Tutorial Static Assets `, :doc:`../narr/assets`, :ref:`preventing_http_caching`, and @@ -389,7 +389,7 @@ This wires up a view that returns some data through the JSON :term:`renderer`, which calls Python's JSON support to serialize the data into JSON and set the appropriate HTTP headers. -.. seealso:: See Also: +.. seealso:: See also: :ref:`Quick Tutorial JSON `, :ref:`views_which_use_a_renderer`, :ref:`json_renderer`, and @@ -446,7 +446,7 @@ have much more to offer: ``accept``, ``header``, ``xhr``, ``containment``, and ``custom_predicates`` -.. seealso:: See Also: +.. seealso:: See also: :ref:`Quick Tutorial View Classes `, :ref:`Quick Tutorial More View Classes `, and :ref:`class_as_view` @@ -497,7 +497,7 @@ configuration. This includes a new way of running your application: Let's look at ``pserve`` and configuration in more depth. -.. seealso:: See Also: +.. seealso:: See also: :ref:`Quick Tutorial Scaffolds `, :ref:`project_narr`, and :doc:`../narr/scaffolding` @@ -528,7 +528,7 @@ Most of the work, though, comes from your project's wiring, as expressed in the configuration file you supply to ``pserve``. Let's take a look at this configuration file. -.. seealso:: See Also: +.. seealso:: See also: :ref:`what_is_this_pserve_thing` Configuration with ``.ini`` Files @@ -576,7 +576,7 @@ Additionally, the ``development.ini`` generated by this scaffold wired up Python's standard logging. We'll now see in the console, for example, a log on every request that comes in, as well traceback information. -.. seealso:: See Also: +.. seealso:: See also: :ref:`Quick Tutorial Application Configuration `, :ref:`environment_chapter` and :doc:`../narr/paste` @@ -631,7 +631,7 @@ you want to disable this toolbar, no need to change code: you can remove it from ``pyramid.includes`` in the relevant ``.ini`` configuration file. -.. seealso:: See Also: +.. seealso:: See also: :ref:`Quick Tutorial pyramid_debugtoolbar ` and :ref:`pyramid_debugtoolbar ` @@ -685,7 +685,7 @@ Pyramid supplies helpers for test writing, which we use in the test setup and teardown. Our one test imports the view, makes a dummy request, and sees if the view returns what we expected. -.. seealso:: See Also: +.. seealso:: See also: :ref:`Quick Tutorial Unit Testing `, :ref:`Quick Tutorial Functional Testing `, and @@ -732,7 +732,7 @@ visit ``http://localhost:6543`` your console will now show:: 2013-08-09 10:42:42,968 DEBUG [hello_world.views][MainThread] Some Message -.. seealso:: See Also: +.. seealso:: See also: :ref:`Quick Tutorial Logging ` and :ref:`logging_chapter` @@ -780,7 +780,7 @@ Jinja2 template: :start-after: Start Sphinx Include 1 :end-before: End Sphinx Include 1 -.. seealso:: See Also: +.. seealso:: See also: :ref:`Quick Tutorial Sessions `, :ref:`sessions_chapter`, :ref:`flash_messages`, :ref:`session_module`, and :term:`pyramid_redis_sessions`. @@ -828,7 +828,7 @@ of the system, can then easily get at the data thanks to SQLAlchemy: :start-after: Start Sphinx Include :end-before: End Sphinx Include -.. seealso:: See Also: +.. seealso:: See also: :ref:`Quick Tutorial Databases `, `SQLAlchemy `_, :ref:`making_a_console_script`, @@ -891,7 +891,7 @@ Also, the ``deform_bootstrap`` Pyramid add-on restyles the stock Deform widgets using attractive CSS from Bootstrap and more powerful widgets from Chosen. -.. seealso:: See Also: +.. seealso:: See also: :ref:`Quick Tutorial Forms `, :ref:`Deform `, :ref:`Colander `, and diff --git a/docs/quick_tutorial/authentication.rst b/docs/quick_tutorial/authentication.rst index 8380a75ed9..4b4eb1ba31 100644 --- a/docs/quick_tutorial/authentication.rst +++ b/docs/quick_tutorial/authentication.rst @@ -130,5 +130,5 @@ Extra Credit onto each request? Use ``import pdb; pdb.set_trace()`` to answer this. -.. seealso:: :ref:`security_chapter`, - :ref:`AuthTktAuthenticationPolicy ` +.. seealso:: See also :ref:`security_chapter`, + :ref:`AuthTktAuthenticationPolicy `. diff --git a/docs/quick_tutorial/debugtoolbar.rst b/docs/quick_tutorial/debugtoolbar.rst index d25588c498..9a37c5f0ee 100644 --- a/docs/quick_tutorial/debugtoolbar.rst +++ b/docs/quick_tutorial/debugtoolbar.rst @@ -86,4 +86,4 @@ start to experience otherwise inexplicable client-side weirdness, you can shut it off by commenting out the ``pyramid_debugtoolbar`` line in ``pyramid.includes`` temporarily. -.. seealso:: See Also: :ref:`pyramid_debugtoolbar ` +.. seealso:: See also :ref:`pyramid_debugtoolbar `. diff --git a/docs/quick_tutorial/logging.rst b/docs/quick_tutorial/logging.rst index 0167e52495..855ded59f1 100644 --- a/docs/quick_tutorial/logging.rst +++ b/docs/quick_tutorial/logging.rst @@ -76,4 +76,4 @@ visit http://localhost:6543 your console will now show:: Also, if you have configured your Pyramid application to use the ``pyramid_debugtoolbar``, logging statements appear in one of its menus. -.. seealso:: See Also: :ref:`logging_chapter` +.. seealso:: See also :ref:`logging_chapter`. diff --git a/docs/quick_tutorial/requirements.rst b/docs/quick_tutorial/requirements.rst index 234e4aa0da..df920ea39a 100644 --- a/docs/quick_tutorial/requirements.rst +++ b/docs/quick_tutorial/requirements.rst @@ -240,7 +240,7 @@ during this tutorial: some optional C extensions for performance. With ``easy_install``, Windows users can get these extensions without needing a C compiler. -.. seealso:: See Also: :ref:`installing_unix`. For instructions to set up your +.. seealso:: See also :ref:`installing_unix`. For instructions to set up your Python environment for development using Windows or Python 2, see Pyramid's :ref:`Before You Install `. diff --git a/docs/quick_tutorial/tutorial_approach.rst b/docs/quick_tutorial/tutorial_approach.rst index 52d7683065..204d388b04 100644 --- a/docs/quick_tutorial/tutorial_approach.rst +++ b/docs/quick_tutorial/tutorial_approach.rst @@ -4,9 +4,9 @@ Tutorial Approach This tutorial uses conventions to keep the introduction focused and concise. Details, references, and deeper discussions are mentioned in -"See Also" notes. +"See also" notes. -.. seealso:: This is an example "See Also" note. +.. seealso:: This is an example "See also" note. This "Getting Started" tutorial is broken into independent steps, starting with the smallest possible "single file WSGI app" example. @@ -42,4 +42,4 @@ Each of the first-level directories (e.g. ``request_response``) is a *Python project* (except, as noted, the ``hello_world`` step.) The ``tutorial`` directory is a *Python package*. At the end of each step, we copy a previous directory into a new directory to use as a starting -point. \ No newline at end of file +point. diff --git a/docs/quick_tutorial/unit_testing.rst b/docs/quick_tutorial/unit_testing.rst index ed33f62d7a..f8a33b39d0 100644 --- a/docs/quick_tutorial/unit_testing.rst +++ b/docs/quick_tutorial/unit_testing.rst @@ -116,4 +116,4 @@ Extra Credit #. Why do we import the ``hello_world`` view function *inside* the ``test_hello_world`` method instead of at the top of the module? -.. seealso:: See Also: :ref:`testing_chapter` +.. seealso:: See also :ref:`testing_chapter` diff --git a/docs/whatsnew-1.0.rst b/docs/whatsnew-1.0.rst index 8750863e79..9541f0a28b 100644 --- a/docs/whatsnew-1.0.rst +++ b/docs/whatsnew-1.0.rst @@ -114,8 +114,11 @@ Scaffold Improvements scaffolds now use a default "commit veto" hook when configuring the ``repoze.tm2`` transaction manager in ``development.ini``. This prevents a transaction from being committed when the response status code is within - the 400 or 500 ranges. See also - http://docs.repoze.org/tm2/#using-a-commit-veto. + the 400 or 500 ranges. + + .. seealso:: + + See also http://docs.repoze.org/tm2/#using-a-commit-veto. Terminology Changes ~~~~~~~~~~~~~~~~~~~ diff --git a/docs/whatsnew-1.1.rst b/docs/whatsnew-1.1.rst index 086c12ca25..99737b6d82 100644 --- a/docs/whatsnew-1.1.rst +++ b/docs/whatsnew-1.1.rst @@ -454,10 +454,13 @@ Deprecations and Behavior Differences renderer='some/renderer.pt') This deprecation was done to reduce confusion observed in IRC, as well as - to (eventually) reduce documentation burden (see also - https://github.com/Pylons/pyramid/issues/164). A deprecation warning is - now issued when any view-related parameter is passed to - ``add_route``. + to (eventually) reduce documentation burden. A deprecation warning is + now issued when any view-related parameter is passed to ``add_route``. + + .. seealso:: + + See also `issue #164 on GitHub + `_. - Passing an ``environ`` dictionary to the ``__call__`` method of a "traverser" (e.g. an object that implements @@ -537,8 +540,12 @@ Deprecations and Behavior Differences subdirectory, the ``index.html`` of that subdirectory would not be served properly. Instead, a redirect to ``/subdir`` would be issued. This has been fixed, and now visiting a subdirectory that contains an ``index.html`` - within a static view returns the index.html properly. See also - https://github.com/Pylons/pyramid/issues/67. + within a static view returns the index.html properly. + + .. seealso:: + + See also `issue #67 on GitHub + `_. - Deprecated the ``pyramid.config.Configurator.set_renderer_globals_factory`` method and the ``renderer_globals`` Configurator constructor parameter. diff --git a/pyramid/config/__init__.py b/pyramid/config/__init__.py index 19c47cbd95..32cf82fba2 100644 --- a/pyramid/config/__init__.py +++ b/pyramid/config/__init__.py @@ -181,8 +181,11 @@ class Configurator( By default, ``default_permission`` is ``None``, meaning that view configurations which do not explicitly declare a permission will always be executable by entirely anonymous users (any - authorization policy in effect is ignored). See also - :ref:`setting_a_default_permission`. + authorization policy in effect is ignored). + + .. seealso:: + + See also :ref:`setting_a_default_permission`. If ``session_factory`` is passed, it should be an object which implements the :term:`session factory` interface. If a nondefault diff --git a/pyramid/config/factories.py b/pyramid/config/factories.py index 7741258219..1990c377a6 100644 --- a/pyramid/config/factories.py +++ b/pyramid/config/factories.py @@ -186,9 +186,9 @@ def set_request_property(self, callable, name=None, reify=False): """ Add a property to the request object. .. deprecated:: 1.5 - :meth:`pyramid.config.Configurator.add_request_method` should be - used instead. (This method was docs-deprecated in 1.4 and - issues a real deprecation warning in 1.5). + :meth:`pyramid.config.Configurator.add_request_method` should be + used instead. (This method was docs-deprecated in 1.4 and + issues a real deprecation warning in 1.5). .. versionadded:: 1.3 """ diff --git a/pyramid/config/routes.py b/pyramid/config/routes.py index 4fd207600e..f1463b50b0 100644 --- a/pyramid/config/routes.py +++ b/pyramid/config/routes.py @@ -249,22 +249,21 @@ def add_route(self, custom_predicates .. deprecated:: 1.5 - - This value should be a sequence of references to custom - predicate callables. Use custom predicates when no set of - predefined predicates does what you need. Custom predicates - can be combined with predefined predicates as necessary. - Each custom predicate callable should accept two arguments: - ``info`` and ``request`` and should return either ``True`` - or ``False`` after doing arbitrary evaluation of the info - and/or the request. If all custom and non-custom predicate - callables return ``True`` the associated route will be - considered viable for a given request. If any predicate - callable returns ``False``, route matching continues. Note - that the value ``info`` passed to a custom route predicate - is a dictionary containing matching information; see - :ref:`custom_route_predicates` for more information about - ``info``. + This value should be a sequence of references to custom + predicate callables. Use custom predicates when no set of + predefined predicates does what you need. Custom predicates + can be combined with predefined predicates as necessary. + Each custom predicate callable should accept two arguments: + ``info`` and ``request`` and should return either ``True`` + or ``False`` after doing arbitrary evaluation of the info + and/or the request. If all custom and non-custom predicate + callables return ``True`` the associated route will be + considered viable for a given request. If any predicate + callable returns ``False``, route matching continues. Note + that the value ``info`` passed to a custom route predicate + is a dictionary containing matching information; see + :ref:`custom_route_predicates` for more information about + ``info``. predicates diff --git a/pyramid/config/security.py b/pyramid/config/security.py index 6a1257b6ad..81549cbfc9 100644 --- a/pyramid/config/security.py +++ b/pyramid/config/security.py @@ -112,7 +112,9 @@ def set_default_permission(self, permission): permission is ignored, and the view is registered, making it available to all callers regardless of their credentials. - See also :ref:`setting_a_default_permission`. + .. seealso:: + + See also :ref:`setting_a_default_permission`. .. note:: diff --git a/pyramid/config/views.py b/pyramid/config/views.py index cdad7e85e1..1ef4efdb36 100644 --- a/pyramid/config/views.py +++ b/pyramid/config/views.py @@ -1035,18 +1035,20 @@ def myview(request): custom_predicates - .. deprecated:: 1.5 - - This value should be a sequence of references to custom predicate - callables. Use custom predicates when no set of predefined - predicates do what you need. Custom predicates can be combined with - predefined predicates as necessary. Each custom predicate callable - should accept two arguments: ``context`` and ``request`` and should - return either ``True`` or ``False`` after doing arbitrary evaluation - of the context and/or the request. The ``predicates`` argument to - this method and the ability to register third-party view predicates - via :meth:`pyramid.config.Configurator.add_view_predicate` obsoletes - this argument, but it is kept around for backwards compatibility. + .. deprecated:: 1.5 + This value should be a sequence of references to custom + predicate callables. Use custom predicates when no set of + predefined predicates do what you need. Custom predicates + can be combined with predefined predicates as necessary. + Each custom predicate callable should accept two arguments: + ``context`` and ``request`` and should return either + ``True`` or ``False`` after doing arbitrary evaluation of + the context and/or the request. The ``predicates`` argument + to this method and the ability to register third-party view + predicates via + :meth:`pyramid.config.Configurator.add_view_predicate` + obsoletes this argument, but it is kept around for backwards + compatibility. predicates @@ -1744,7 +1746,9 @@ def set_view_mapper(self, mapper): the default view mapper to be used by all subsequent :term:`view configuration` registrations. - See also :ref:`using_a_view_mapper`. + .. seealso:: + + See also :ref:`using_a_view_mapper`. .. note:: diff --git a/pyramid/events.py b/pyramid/events.py index 5179ab08a5..97375638ee 100644 --- a/pyramid/events.py +++ b/pyramid/events.py @@ -235,7 +235,9 @@ def read_return(event): For a description of the values present in the renderer globals dictionary, see :ref:`renderer_system_values`. - See also :class:`pyramid.interfaces.IBeforeRender`. + .. seealso:: + + See also :class:`pyramid.interfaces.IBeforeRender`. """ def __init__(self, system, rendering_val=None): dict.__init__(self, system) diff --git a/pyramid/i18n.py b/pyramid/i18n.py index aaba769c69..4c8f4b55da 100644 --- a/pyramid/i18n.py +++ b/pyramid/i18n.py @@ -25,10 +25,10 @@ class Localizer(object): """ An object providing translation and pluralizations related to - the current request's locale name. A - :class:`pyramid.i18n.Localizer` object is created using the - :func:`pyramid.i18n.get_localizer` function. - """ + the current request's locale name. A + :class:`pyramid.i18n.Localizer` object is created using the + :func:`pyramid.i18n.get_localizer` function. + """ def __init__(self, locale_name, translations): self.locale_name = locale_name self.translations = translations @@ -158,9 +158,11 @@ def negotiate_locale_name(request): return locale_name def get_locale_name(request): - """ Return the :term:`locale name` associated with the current - request. Deprecated in favor of using request.locale_name directly as of - Pyramid 1.5.""" + """ + .. deprecated:: 1.5 + Use :attr:`pyramid.request.Request.locale_name` directly instead. + Return the :term:`locale name` associated with the current request. + """ return request.locale_name def make_localizer(current_locale_name, translation_directories): @@ -207,9 +209,12 @@ def make_localizer(current_locale_name, translation_directories): translations=translations) def get_localizer(request): - """ Retrieve a :class:`pyramid.i18n.Localizer` object - corresponding to the current request's locale name. Deprecated in favor - of using the ``request.localizer`` attribute directly as of Pyramid 1.5""" + """ + .. deprecated:: 1.5 + Use the :attr:`pyramid.request.Request.localizer` attribute directly + instead. Retrieve a :class:`pyramid.i18n.Localizer` object + corresponding to the current request's locale name. + """ return request.localizer class Translations(gettext.GNUTranslations, object): diff --git a/pyramid/interfaces.py b/pyramid/interfaces.py index cf651cf1ed..75b9b1cb96 100644 --- a/pyramid/interfaces.py +++ b/pyramid/interfaces.py @@ -361,7 +361,9 @@ class IBeforeRender(IDict): def add_global(event): event['mykey'] = 'foo' - See also :ref:`beforerender_event`. + .. seealso:: + + See also :ref:`beforerender_event`. """ rendering_val = Attribute('The value returned by a view or passed to a ' '``render`` method for this rendering. ' @@ -767,10 +769,10 @@ class IResourceURL(Interface): ) class IContextURL(IResourceURL): - """ An adapter which deals with URLs related to a context. - + """ .. deprecated:: 1.3 - use IResourceURL instead. + An adapter which deals with URLs related to a context. Use + :class:`pyramid.interfaces.IResourceURL` instead. """ # this class subclasses IResourceURL because request.resource_url looks # for IResourceURL via queryAdapter. queryAdapter will find a deprecated diff --git a/pyramid/renderers.py b/pyramid/renderers.py index 88ef285a0d..108255ee47 100644 --- a/pyramid/renderers.py +++ b/pyramid/renderers.py @@ -341,7 +341,9 @@ def myview(request): .. versionadded:: 1.1 - See also: :ref:`jsonp_renderer`. + .. seealso:: + + See also :ref:`jsonp_renderer`. """ def __init__(self, param_name='callback', **kw): diff --git a/pyramid/request.py b/pyramid/request.py index 188e968ac9..f8514066e4 100644 --- a/pyramid/request.py +++ b/pyramid/request.py @@ -66,7 +66,9 @@ def cache_callback(request, response): will be propagated to the caller of the :app:`Pyramid` router application. - See also: :ref:`using_response_callbacks`. + .. seealso:: + + See also :ref:`using_response_callbacks`. """ callbacks = self.response_callbacks @@ -124,7 +126,9 @@ def commit_callback(request): They will be propagated to the caller of the :app:`Pyramid` router application. - See also: :ref:`using_finished_callbacks`. + .. seealso:: + + See also :ref:`using_finished_callbacks`. """ callbacks = self.finished_callbacks diff --git a/pyramid/router.py b/pyramid/router.py index 6239f39802..ba4f85b180 100644 --- a/pyramid/router.py +++ b/pyramid/router.py @@ -183,46 +183,16 @@ def handle_request(self, request): return response def invoke_subrequest(self, request, use_tweens=False): - """ - Obtain a response object from the Pyramid application based on + """Obtain a response object from the Pyramid application based on information in the ``request`` object provided. The ``request`` object must be an object that implements the Pyramid request interface (such as a :class:`pyramid.request.Request` instance). If ``use_tweens`` is ``True``, the request will be sent to the :term:`tween` in the tween stack closest to the request ingress. If ``use_tweens`` is ``False``, the request will be sent to the main - router handler, and no tweens will be invoked. This function also: + router handler, and no tweens will be invoked. - - manages the threadlocal stack (so that - :func:`~pyramid.threadlocal.get_current_request` and - :func:`~pyramid.threadlocal.get_current_registry` work during a - request) - - - Adds a ``registry`` attribute and a ``invoke_subrequest`` attribute - (a callable) to the request object it's handed. - - - sets request extensions (such as those added via - :meth:`~pyramid.config.Configurator.add_request_method` or - :meth:`~pyramid.config.Configurator.set_request_property`) on the - request it's passed. - - - causes a :class:`~pyramid.event.NewRequest` event to be sent at the - beginning of request processing. - - - causes a :class:`~pyramid.event.ContextFound` event to be sent - when a context resource is found. - - - Calls any :term:`response callback` functions defined within the - request's lifetime if a response is obtained from the Pyramid - application. - - - causes a :class:`~pyramid.event.NewResponse` event to be sent if a - response is obtained. - - - Calls any :term:`finished callback` functions defined within the - request's lifetime. - - See also :ref:`subrequest_chapter`. + See the API for pyramid.request for complete documentation. """ registry = self.registry has_listeners = self.registry.has_listeners diff --git a/pyramid/security.py b/pyramid/security.py index 58fa9332aa..8485742339 100644 --- a/pyramid/security.py +++ b/pyramid/security.py @@ -44,15 +44,15 @@ def _get_authentication_policy(request): def has_permission(permission, context, request): """ - A function that calls - :meth:`pyramid.request.Request.has_permission` and returns its result. + A function that calls :meth:`pyramid.request.Request.has_permission` + and returns its result. .. deprecated:: 1.5 - Use :meth:`pyramid.request.Request.has_permission` instead. + Use :meth:`pyramid.request.Request.has_permission` instead. .. versionchanged:: 1.5a3 - If context is None, then attempt to use the context attribute - of self, if not set then the AttributeError is propergated. + If context is None, then attempt to use the context attribute of self; + if not set, then the AttributeError is propagated. """ return request.has_permission(permission, context) @@ -87,7 +87,7 @@ def unauthenticated_userid(request): :attr:`pyramid.request.Request.unauthenticated_userid`. .. deprecated:: 1.5 - Use :attr:`pyramid.request.Request.unauthenticated_userid` instead. + Use :attr:`pyramid.request.Request.unauthenticated_userid` instead. """ return request.unauthenticated_userid @@ -104,7 +104,7 @@ def effective_principals(request): :attr:`pyramid.request.Request.effective_principals`. .. deprecated:: 1.5 - Use :attr:`pyramid.request.Request.effective_principals` instead. + Use :attr:`pyramid.request.Request.effective_principals` instead. """ return request.effective_principals @@ -162,7 +162,7 @@ def forget(request): always return an empty sequence. .. deprecated:: 1.5 - Use :meth:`pyramid.request.Request.get_logout_headers` instead. + Use :meth:`pyramid.request.Request.get_logout_headers` instead. """ policy = _get_authentication_policy(request) if policy is None: diff --git a/pyramid/session.py b/pyramid/session.py index e3ce4a0909..3a045b91bc 100644 --- a/pyramid/session.py +++ b/pyramid/session.py @@ -381,11 +381,11 @@ def UnencryptedCookieSessionFactoryConfig( ): """ .. deprecated:: 1.5 - Use :func:`pyramid.session.SignedCookieSessionFactory` instead. - Caveat: Cookies generated using ``SignedCookieSessionFactory`` are not - compatible with cookies generated using - ``UnencryptedCookieSessionFactory``, so existing user session data will - be destroyed if you switch to it. + Use :func:`pyramid.session.SignedCookieSessionFactory` instead. + Caveat: Cookies generated using ``SignedCookieSessionFactory`` are not + compatible with cookies generated using + ``UnencryptedCookieSessionFactory``, so existing user session data + will be destroyed if you switch to it. Configure a :term:`session factory` which will provide unencrypted (but signed) cookie-based sessions. The return value of this diff --git a/pyramid/url.py b/pyramid/url.py index 78dd297d5c..bf4d4ff486 100644 --- a/pyramid/url.py +++ b/pyramid/url.py @@ -442,8 +442,11 @@ def resource_url(self, resource, *elements, **kw): If the ``resource`` passed in has a ``__resource_url__`` method, it will be used to generate the URL (scheme, host, port, path) for the - base resource which is operated upon by this function. See also - :ref:`overriding_resource_url_generation`. + base resource which is operated upon by this function. + + .. seealso:: + + See also :ref:`overriding_resource_url_generation`. .. versionadded:: 1.5 ``route_name``, ``route_kw``, and ``route_remainder_name`` diff --git a/pyramid/view.py b/pyramid/view.py index 55ab388718..02ac8849f5 100644 --- a/pyramid/view.py +++ b/pyramid/view.py @@ -162,12 +162,16 @@ def my_view(context, request): in a class or module context. It's not often used, but it can be useful in this circumstance. See the ``attach`` function in Venusian for more information. + + .. seealso:: + + See also :ref:`mapping_views_using_a_decorator_section` for + details about using :class:`pyramid.view.view_config`. - See :ref:`mapping_views_using_a_decorator_section` for details about - using :class:`pyramid.view.view_config`. - - ATTENTION: ``view_config`` will work ONLY on module top level members - because of the limitation of ``venusian.Scanner.scan``. + .. warning:: + + ``view_config`` will work ONLY on module top level members + because of the limitation of ``venusian.Scanner.scan``. """ venusian = venusian # for testing injection @@ -245,6 +249,8 @@ def notfound_view(context, request): return HTTPNotFound('nope') view callable calling convention of ``(context, request)`` (``context`` will be the exception object). + .. deprecated:: 1.3 + """ def __init__(self, notfound_view=None): if notfound_view is None: @@ -286,7 +292,7 @@ def __call__(self, context, request): from pyramid.view import append_slash_notfound_view config.add_view(append_slash_notfound_view, context=HTTPNotFound) -See also :ref:`changing_the_notfound_view`. +.. deprecated:: 1.3 """