diff options
Diffstat (limited to 'docs/api')
| -rw-r--r-- | docs/api/authentication.rst | 16 | ||||
| -rw-r--r-- | docs/api/chameleon_text.rst | 31 | ||||
| -rw-r--r-- | docs/api/chameleon_zpt.rst | 28 | ||||
| -rw-r--r-- | docs/api/compat.rst | 156 | ||||
| -rw-r--r-- | docs/api/config.rst | 134 | ||||
| -rw-r--r-- | docs/api/decorator.rst | 9 | ||||
| -rw-r--r-- | docs/api/events.rst | 11 | ||||
| -rw-r--r-- | docs/api/exceptions.rst | 14 | ||||
| -rw-r--r-- | docs/api/httpexceptions.rst | 102 | ||||
| -rw-r--r-- | docs/api/i18n.rst | 2 | ||||
| -rw-r--r-- | docs/api/index.rst | 12 | ||||
| -rw-r--r-- | docs/api/interfaces.rst | 44 | ||||
| -rw-r--r-- | docs/api/paster.rst | 11 | ||||
| -rw-r--r-- | docs/api/path.rst | 19 | ||||
| -rw-r--r-- | docs/api/registry.rst | 59 | ||||
| -rw-r--r-- | docs/api/renderers.rst | 17 | ||||
| -rw-r--r-- | docs/api/request.rst | 232 | ||||
| -rw-r--r-- | docs/api/response.rst | 11 | ||||
| -rw-r--r-- | docs/api/scaffolds.rst | 13 | ||||
| -rw-r--r-- | docs/api/scripting.rst | 2 | ||||
| -rw-r--r-- | docs/api/security.rst | 14 | ||||
| -rw-r--r-- | docs/api/session.rst | 13 | ||||
| -rw-r--r-- | docs/api/settings.rst | 4 | ||||
| -rw-r--r-- | docs/api/static.rst | 19 | ||||
| -rw-r--r-- | docs/api/testing.rst | 2 | ||||
| -rw-r--r-- | docs/api/tweens.rst | 25 | ||||
| -rw-r--r-- | docs/api/url.rst | 4 | ||||
| -rw-r--r-- | docs/api/view.rst | 12 | ||||
| -rw-r--r-- | docs/api/viewderivers.rst | 17 |
29 files changed, 841 insertions, 192 deletions
diff --git a/docs/api/authentication.rst b/docs/api/authentication.rst index 5d4dbd9e3..19d08618b 100644 --- a/docs/api/authentication.rst +++ b/docs/api/authentication.rst @@ -9,12 +9,24 @@ Authentication Policies .. automodule:: pyramid.authentication .. autoclass:: AuthTktAuthenticationPolicy - - .. autoclass:: RepozeWho1AuthenticationPolicy + :members: + :inherited-members: .. autoclass:: RemoteUserAuthenticationPolicy + :members: + :inherited-members: .. autoclass:: SessionAuthenticationPolicy + :members: + :inherited-members: + + .. autoclass:: BasicAuthAuthenticationPolicy + :members: + :inherited-members: + + .. autoclass:: RepozeWho1AuthenticationPolicy + :members: + :inherited-members: Helper Classes ~~~~~~~~~~~~~~ diff --git a/docs/api/chameleon_text.rst b/docs/api/chameleon_text.rst deleted file mode 100644 index 494f5b464..000000000 --- a/docs/api/chameleon_text.rst +++ /dev/null @@ -1,31 +0,0 @@ -.. _chameleon_text_module: - -:mod:`pyramid.chameleon_text` ----------------------------------- - -.. automodule:: pyramid.chameleon_text - - .. autofunction:: get_template - - .. autofunction:: render_template - - .. autofunction:: render_template_to_response - -These APIs will will work against template files which contain simple -``${Genshi}`` - style replacement markers. - -The API of :mod:`pyramid.chameleon_text` is identical to that of -:mod:`pyramid.chameleon_zpt`; only its import location is -different. If you need to import an API functions from this module as -well as the :mod:`pyramid.chameleon_zpt` module within the same -view file, use the ``as`` feature of the Python import statement, -e.g.: - -.. code-block:: python - :linenos: - - from pyramid.chameleon_zpt import render_template as zpt_render - from pyramid.chameleon_text import render_template as text_render - - - diff --git a/docs/api/chameleon_zpt.rst b/docs/api/chameleon_zpt.rst deleted file mode 100644 index df9a36a56..000000000 --- a/docs/api/chameleon_zpt.rst +++ /dev/null @@ -1,28 +0,0 @@ -.. _chameleon_zpt_module: - -:mod:`pyramid.chameleon_zpt` -------------------------------- - -.. automodule:: pyramid.chameleon_zpt - - .. autofunction:: get_template - - .. autofunction:: render_template - - .. autofunction:: render_template_to_response - -These APIs will work against files which supply template text which -matches the :term:`ZPT` specification. - -The API of :mod:`pyramid.chameleon_zpt` is identical to that of -:mod:`pyramid.chameleon_text`; only its import location is -different. If you need to import an API functions from this module as -well as the :mod:`pyramid.chameleon_text` module within the same -view file, use the ``as`` feature of the Python import statement, -e.g.: - -.. code-block:: python - :linenos: - - from pyramid.chameleon_zpt import render_template as zpt_render - from pyramid.chameleon_text import render_template as text_render diff --git a/docs/api/compat.rst b/docs/api/compat.rst new file mode 100644 index 000000000..bb34f38e4 --- /dev/null +++ b/docs/api/compat.rst @@ -0,0 +1,156 @@ +.. _compat_module: + +:mod:`pyramid.compat` +---------------------- + +The ``pyramid.compat`` module provides platform and version compatibility for +Pyramid and its add-ons across Python platform and version differences. APIs +will be removed from this module over time as Pyramid ceases to support +systems which require compatibility imports. + +.. automodule:: pyramid.compat + + .. autofunction:: ascii_native_ + + .. attribute:: binary_type + + Binary type for this platform. For Python 3, it's ``bytes``. For + Python 2, it's ``str``. + + .. autofunction:: bytes_ + + .. attribute:: class_types + + Sequence of class types for this platform. For Python 3, it's + ``(type,)``. For Python 2, it's ``(type, types.ClassType)``. + + .. attribute:: configparser + + On Python 2, the ``ConfigParser`` module, on Python 3, the + ``configparser`` module. + + .. function:: escape(v) + + On Python 2, the ``cgi.escape`` function, on Python 3, the + ``html.escape`` function. + + .. function:: exec_(code, globs=None, locs=None) + + Exec code in a compatible way on both Python 2 and 3. + + .. attribute:: im_func + + On Python 2, the string value ``im_func``, on Python 3, the string + value ``__func__``. + + .. function:: input_(v) + + On Python 2, the ``raw_input`` function, on Python 3, the + ``input`` function. + + .. attribute:: integer_types + + Sequence of integer types for this platform. For Python 3, it's + ``(int,)``. For Python 2, it's ``(int, long)``. + + .. function:: is_nonstr_iter(v) + + Return ``True`` if ``v`` is a non-``str`` iterable on both Python 2 and + Python 3. + + .. function:: iteritems_(d) + + Return ``d.items()`` on Python 3, ``d.iteritems()`` on Python 2. + + .. function:: itervalues_(d) + + Return ``d.values()`` on Python 3, ``d.itervalues()`` on Python 2. + + .. function:: iterkeys_(d) + + Return ``d.keys()`` on Python 3, ``d.iterkeys()`` on Python 2. + + .. attribute:: long + + Long type for this platform. For Python 3, it's ``int``. For + Python 2, it's ``long``. + + .. function:: map_(v) + + Return ``list(map(v))`` on Python 3, ``map(v)`` on Python 2. + + .. attribute:: pickle + + ``cPickle`` module if it exists, ``pickle`` module otherwise. + + .. attribute:: PY3 + + ``True`` if running on Python 3, ``False`` otherwise. + + .. attribute:: PYPY + + ``True`` if running on PyPy, ``False`` otherwise. + + .. function:: reraise(tp, value, tb=None) + + Reraise an exception in a compatible way on both Python 2 and Python 3, + e.g. ``reraise(*sys.exc_info())``. + + .. attribute:: string_types + + Sequence of string types for this platform. For Python 3, it's + ``(str,)``. For Python 2, it's ``(basestring,)``. + + .. attribute:: SimpleCookie + + On Python 2, the ``Cookie.SimpleCookie`` class, on Python 3, the + ``http.cookies.SimpleCookie`` module. + + .. autofunction:: text_ + + .. attribute:: text_type + + Text type for this platform. For Python 3, it's ``str``. For Python + 2, it's ``unicode``. + + .. autofunction:: native_ + + .. attribute:: urlparse + + ``urlparse`` module on Python 2, ``urllib.parse`` module on Python 3. + + .. attribute:: url_quote + + ``urllib.quote`` function on Python 2, ``urllib.parse.quote`` function + on Python 3. + + .. attribute:: url_quote_plus + + ``urllib.quote_plus`` function on Python 2, ``urllib.parse.quote_plus`` + function on Python 3. + + .. attribute:: url_unquote + + ``urllib.unquote`` function on Python 2, ``urllib.parse.unquote`` + function on Python 3. + + .. attribute:: url_encode + + ``urllib.urlencode`` function on Python 2, ``urllib.parse.urlencode`` + function on Python 3. + + .. attribute:: url_open + + ``urllib2.urlopen`` function on Python 2, ``urllib.request.urlopen`` + function on Python 3. + + .. function:: url_unquote_text(v, encoding='utf-8', errors='replace') + + On Python 2, return ``url_unquote(v).decode(encoding(encoding, errors))``; + on Python 3, return the result of ``urllib.parse.unquote``. + + .. function:: url_unquote_native(v, encoding='utf-8', errors='replace') + + On Python 2, return ``native_(url_unquote_text_v, encoding, errors))``; + on Python 3, return the result of ``urllib.parse.unquote``. + diff --git a/docs/api/config.rst b/docs/api/config.rst index 2b9d7bcef..e083dbc68 100644 --- a/docs/api/config.rst +++ b/docs/api/config.rst @@ -1,86 +1,140 @@ .. _configuration_module: +.. role:: methodcategory + :class: methodcategory + :mod:`pyramid.config` --------------------- .. automodule:: pyramid.config - .. autoclass:: Configurator(registry=None, package=None, settings=None, root_factory=None, authentication_policy=None, authorization_policy=None, renderers=DEFAULT_RENDERERS, debug_logger=None, locale_negotiator=None, request_factory=None, renderer_globals_factory=None, default_permission=None, session_factory=None, autocommit=False) +.. autoclass:: Configurator - .. attribute:: registry + :methodcategory:`Controlling Configuration State` - The :term:`application registry` which holds the configuration - associated with this configurator. + .. automethod:: commit + .. automethod:: begin + .. automethod:: end + .. automethod:: include + .. automethod:: make_wsgi_app() + .. automethod:: scan - .. automethod:: begin + :methodcategory:`Adding Routes and Views` - .. automethod:: end + .. automethod:: add_route + .. automethod:: add_static_view(name, path, cache_max_age=3600, permission=NO_PERMISSION_REQUIRED) + .. automethod:: add_view + .. automethod:: add_notfound_view + .. automethod:: add_forbidden_view - .. automethod:: hook_zca + :methodcategory:`Adding an Event Subscriber` - .. automethod:: unhook_zca + .. automethod:: add_subscriber - .. automethod:: get_settings + :methodcategory:`Using Security` - .. automethod:: commit + .. automethod:: set_authentication_policy + .. automethod:: set_authorization_policy + .. automethod:: set_default_permission + .. automethod:: add_permission - .. automethod:: action + :methodcategory:`Extending the Request Object` - .. automethod:: include + .. automethod:: add_request_method + .. automethod:: set_request_property - .. automethod:: add_directive + :methodcategory:`Using I18N` - .. automethod:: with_package + .. automethod:: add_translation_dirs + .. automethod:: set_locale_negotiator - .. automethod:: maybe_dotted + :methodcategory:`Overriding Assets` - .. automethod:: absolute_asset_spec + .. automethod:: override_asset(to_override, override_with) - .. automethod:: setup_registry(settings=None, root_factory=None, authentication_policy=None, renderers=DEFAULT_RENDERERS, debug_logger=None, locale_negotiator=None, request_factory=None, renderer_globals_factory=None) + :methodcategory:`Getting and Adding Settings` + + .. automethod:: add_settings + .. automethod:: get_settings - .. automethod:: add_renderer(name, factory) + :methodcategory:`Hooking Pyramid Behavior` - .. automethod:: add_route + .. automethod:: add_renderer + .. automethod:: add_resource_url_adapter + .. automethod:: add_response_adapter + .. automethod:: add_traverser + .. automethod:: add_tween + .. automethod:: add_route_predicate + .. automethod:: add_view_predicate + .. automethod:: add_view_deriver + .. automethod:: set_request_factory + .. automethod:: set_root_factory + .. automethod:: set_session_factory + .. automethod:: set_view_mapper - .. automethod:: add_static_view(name, path, cache_max_age=3600, permission='__no_permission_required__') + :methodcategory:`Extension Author APIs` - .. automethod:: add_settings + .. automethod:: action + .. automethod:: add_directive + .. automethod:: with_package + .. automethod:: derive_view - .. automethod:: add_subscriber + :methodcategory:`Utility Methods` - .. automethod:: add_translation_dirs + .. automethod:: absolute_asset_spec + .. automethod:: maybe_dotted - .. automethod:: add_view + :methodcategory:`ZCA-Related APIs` - .. automethod:: derive_view + .. automethod:: hook_zca + .. automethod:: unhook_zca + .. automethod:: setup_registry - .. automethod:: make_wsgi_app() + :methodcategory:`Testing Helper APIs` - .. automethod:: override_asset(to_override, override_with) + .. automethod:: testing_add_renderer + .. automethod:: testing_add_subscriber + .. automethod:: testing_resources + .. automethod:: testing_securitypolicy - .. automethod:: scan + :methodcategory:`Attributes` - .. automethod:: set_forbidden_view + .. attribute:: introspectable - .. automethod:: set_notfound_view + A shortcut attribute which points to the + :class:`pyramid.registry.Introspectable` class (used during + directives to provide introspection to actions). - .. automethod:: set_locale_negotiator + .. versionadded:: 1.3 - .. automethod:: set_default_permission + .. attribute:: introspector - .. automethod:: set_session_factory + The :term:`introspector` related to this configuration. It is an + instance implementing the :class:`pyramid.interfaces.IIntrospector` + interface. - .. automethod:: set_request_factory + .. versionadded:: 1.3 - .. automethod:: set_renderer_globals_factory + .. attribute:: registry - .. automethod:: set_view_mapper + The :term:`application registry` which holds the configuration + associated with this configurator. - .. automethod:: testing_securitypolicy +.. attribute:: global_registries - .. automethod:: testing_resources + The set of registries that have been created for :app:`Pyramid` + applications, one for each call to + :meth:`pyramid.config.Configurator.make_wsgi_app` in the current + process. The object itself supports iteration and has a ``last`` property + containing the last registry loaded. - .. automethod:: testing_add_subscriber + The registries contained in this object are stored as weakrefs, thus they + will only exist for the lifetime of the actual applications for which they + are being used. - .. automethod:: testing_add_renderer +.. autoclass:: not_ +.. attribute:: PHASE0_CONFIG +.. attribute:: PHASE1_CONFIG +.. attribute:: PHASE2_CONFIG +.. attribute:: PHASE3_CONFIG diff --git a/docs/api/decorator.rst b/docs/api/decorator.rst new file mode 100644 index 000000000..35d9131df --- /dev/null +++ b/docs/api/decorator.rst @@ -0,0 +1,9 @@ +.. _decorator_module: + +:mod:`pyramid.decorator` +-------------------------- + +.. automodule:: pyramid.decorator + +.. autofunction:: reify + diff --git a/docs/api/events.rst b/docs/api/events.rst index 59657a820..0a8463740 100644 --- a/docs/api/events.rst +++ b/docs/api/events.rst @@ -21,10 +21,21 @@ Event Types .. autoclass:: ContextFound +.. autoclass:: BeforeTraversal + .. autoclass:: NewResponse .. autoclass:: BeforeRender :members: + :inherited-members: + :exclude-members: update + + .. method:: update(E, **F) + + Update D from dict/iterable E and F. If E has a .keys() method, does: + for k in E: D[k] = E[k] If E lacks .keys() method, does: for (k, v) in + E: D[k] = v. In either case, this is followed by: for k in F: D[k] = + F[k]. See :ref:`events_chapter` for more information about how to register code which subscribes to these events. diff --git a/docs/api/exceptions.rst b/docs/api/exceptions.rst index 1dfbf46fd..cb411458d 100644 --- a/docs/api/exceptions.rst +++ b/docs/api/exceptions.rst @@ -5,10 +5,16 @@ .. automodule:: pyramid.exceptions - .. autoclass:: Forbidden + .. autoexception:: BadCSRFOrigin - .. autoclass:: NotFound + .. autoexception:: BadCSRFToken - .. autoclass:: ConfigurationError + .. autoexception:: PredicateMismatch - .. autoclass:: URLDecodeError + .. autoexception:: Forbidden + + .. autoexception:: NotFound + + .. autoexception:: ConfigurationError + + .. autoexception:: URLDecodeError diff --git a/docs/api/httpexceptions.rst b/docs/api/httpexceptions.rst index 57ca8092c..d4cf97f1d 100644 --- a/docs/api/httpexceptions.rst +++ b/docs/api/httpexceptions.rst @@ -7,92 +7,102 @@ .. attribute:: status_map - A mapping of integer status code to exception class (eg. the - integer "401" maps to - :class:`pyramid.httpexceptions.HTTPUnauthorized`). + A mapping of integer status code to HTTP exception class (eg. the integer + "401" maps to :class:`pyramid.httpexceptions.HTTPUnauthorized`). All + mapped exception classes are children of :class:`pyramid.httpexceptions`, - .. autoclass:: HTTPException + .. autofunction:: exception_response - .. autoclass:: HTTPOk + .. autoexception:: HTTPException - .. autoclass:: HTTPRedirection + .. autoexception:: HTTPOk - .. autoclass:: HTTPError + .. autoexception:: HTTPRedirection - .. autoclass:: HTTPClientError + .. autoexception:: HTTPError - .. autoclass:: HTTPServerError + .. autoexception:: HTTPClientError - .. autoclass:: HTTPCreated + .. autoexception:: HTTPServerError - .. autoclass:: HTTPAccepted + .. autoexception:: HTTPCreated - .. autoclass:: HTTPNonAuthoritativeInformation + .. autoexception:: HTTPAccepted - .. autoclass:: HTTPNoContent + .. autoexception:: HTTPNonAuthoritativeInformation - .. autoclass:: HTTPResetContent + .. autoexception:: HTTPNoContent - .. autoclass:: HTTPPartialContent + .. autoexception:: HTTPResetContent - .. autoclass:: HTTPMultipleChoices + .. autoexception:: HTTPPartialContent - .. autoclass:: HTTPMovedPermanently + .. autoexception:: HTTPMultipleChoices - .. autoclass:: HTTPFound + .. autoexception:: HTTPMovedPermanently - .. autoclass:: HTTPSeeOther + .. autoexception:: HTTPFound - .. autoclass:: HTTPNotModified + .. autoexception:: HTTPSeeOther - .. autoclass:: HTTPUseProxy + .. autoexception:: HTTPNotModified - .. autoclass:: HTTPTemporaryRedirect + .. autoexception:: HTTPUseProxy - .. autoclass:: HTTPBadRequest + .. autoexception:: HTTPTemporaryRedirect - .. autoclass:: HTTPUnauthorized + .. autoexception:: HTTPBadRequest - .. autoclass:: HTTPPaymentRequired + .. autoexception:: HTTPUnauthorized - .. autoclass:: HTTPForbidden + .. autoexception:: HTTPPaymentRequired - .. autoclass:: HTTPNotFound + .. autoexception:: HTTPForbidden - .. autoclass:: HTTPMethodNotAllowed + .. autoexception:: HTTPNotFound - .. autoclass:: HTTPNotAcceptable + .. autoexception:: HTTPMethodNotAllowed - .. autoclass:: HTTPProxyAuthenticationRequired + .. autoexception:: HTTPNotAcceptable - .. autoclass:: HTTPRequestTimeout + .. autoexception:: HTTPProxyAuthenticationRequired - .. autoclass:: HTTPConflict + .. autoexception:: HTTPRequestTimeout - .. autoclass:: HTTPGone + .. autoexception:: HTTPConflict - .. autoclass:: HTTPLengthRequired + .. autoexception:: HTTPGone - .. autoclass:: HTTPPreconditionFailed + .. autoexception:: HTTPLengthRequired - .. autoclass:: HTTPRequestEntityTooLarge + .. autoexception:: HTTPPreconditionFailed - .. autoclass:: HTTPRequestURITooLong + .. autoexception:: HTTPRequestEntityTooLarge - .. autoclass:: HTTPUnsupportedMediaType + .. autoexception:: HTTPRequestURITooLong - .. autoclass:: HTTPRequestRangeNotSatisfiable + .. autoexception:: HTTPUnsupportedMediaType - .. autoclass:: HTTPExpectationFailed + .. autoexception:: HTTPRequestRangeNotSatisfiable - .. autoclass:: HTTPInternalServerError + .. autoexception:: HTTPExpectationFailed - .. autoclass:: HTTPNotImplemented + .. autoexception:: HTTPUnprocessableEntity - .. autoclass:: HTTPBadGateway + .. autoexception:: HTTPLocked - .. autoclass:: HTTPServiceUnavailable + .. autoexception:: HTTPFailedDependency - .. autoclass:: HTTPGatewayTimeout + .. autoexception:: HTTPInternalServerError - .. autoclass:: HTTPVersionNotSupported + .. autoexception:: HTTPNotImplemented + + .. autoexception:: HTTPBadGateway + + .. autoexception:: HTTPServiceUnavailable + + .. autoexception:: HTTPGatewayTimeout + + .. autoexception:: HTTPVersionNotSupported + + .. autoexception:: HTTPInsufficientStorage diff --git a/docs/api/i18n.rst b/docs/api/i18n.rst index 53e8c8a9b..3b9abbc1d 100644 --- a/docs/api/i18n.rst +++ b/docs/api/i18n.rst @@ -7,7 +7,7 @@ .. autoclass:: TranslationString - .. autoclass:: TranslationStringFactory + .. autofunction:: TranslationStringFactory .. autoclass:: Localizer :members: diff --git a/docs/api/index.rst b/docs/api/index.rst new file mode 100644 index 000000000..cb38aa0b2 --- /dev/null +++ b/docs/api/index.rst @@ -0,0 +1,12 @@ +.. _html_api_documentation: + +API Documentation +================= + +Comprehensive reference material for every public API exposed by :app:`Pyramid`: + +.. toctree:: + :maxdepth: 1 + :glob: + + * diff --git a/docs/api/interfaces.rst b/docs/api/interfaces.rst index ac282fbcc..272820a91 100644 --- a/docs/api/interfaces.rst +++ b/docs/api/interfaces.rst @@ -9,14 +9,22 @@ Event-Related Interfaces ++++++++++++++++++++++++ .. autointerface:: IApplicationCreated + :members: .. autointerface:: INewRequest + :members: .. autointerface:: IContextFound + :members: + + .. autointerface:: IBeforeTraversal + :members: .. autointerface:: INewResponse + :members: .. autointerface:: IBeforeRender + :members: Other Interfaces ++++++++++++++++ @@ -45,7 +53,13 @@ Other Interfaces .. autointerface:: IRendererInfo :members: - .. autointerface:: ITemplateRenderer + .. autointerface:: IRendererFactory + :members: + + .. autointerface:: IRenderer + :members: + + .. autointerface:: IResponseFactory :members: .. autointerface:: IViewMapperFactory @@ -54,7 +68,35 @@ Other Interfaces .. autointerface:: IViewMapper :members: + .. autointerface:: IDict + :members: + .. autointerface:: IMultiDict :members: + .. autointerface:: IResponse + :members: + .. autointerface:: IIntrospectable + :members: + + .. autointerface:: IIntrospector + :members: + + .. autointerface:: IActionInfo + :members: + + .. autointerface:: IAssetDescriptor + :members: + + .. autointerface:: IResourceURL + :members: + + .. autointerface:: ICacheBuster + :members: + + .. autointerface:: IViewDeriver + :members: + + .. autointerface:: IViewDeriverInfo + :members: diff --git a/docs/api/paster.rst b/docs/api/paster.rst index 9ecfa3d9c..27bc81a1f 100644 --- a/docs/api/paster.rst +++ b/docs/api/paster.rst @@ -3,11 +3,12 @@ :mod:`pyramid.paster` --------------------------- -.. module:: pyramid.paster +.. automodule:: pyramid.paster -.. function:: get_app(config_file, name) + .. autofunction:: bootstrap - Return the WSGI application named ``name`` in the PasteDeploy - config file ``config_file``. + .. autofunction:: get_app(config_uri, name=None, options=None) - + .. autofunction:: get_appsettings(config_uri, name=None, options=None) + + .. autofunction:: setup_logging(config_uri, global_conf=None) diff --git a/docs/api/path.rst b/docs/api/path.rst new file mode 100644 index 000000000..814fc47d5 --- /dev/null +++ b/docs/api/path.rst @@ -0,0 +1,19 @@ +.. _path_module: + +:mod:`pyramid.path` +--------------------------- + +.. automodule:: pyramid.path + + .. attribute:: CALLER_PACKAGE + + A constant used by the constructor of + :class:`pyramid.path.DottedNameResolver` and + :class:`pyramid.path.AssetResolver`. + + .. autoclass:: DottedNameResolver + :members: + + .. autoclass:: AssetResolver + :members: + diff --git a/docs/api/registry.rst b/docs/api/registry.rst index 4d327370a..57a80b3f5 100644 --- a/docs/api/registry.rst +++ b/docs/api/registry.rst @@ -14,3 +14,62 @@ accessed as ``request.registry.settings`` or ``config.registry.settings`` in a typical Pyramid application. + .. attribute:: package_name + + .. versionadded:: 1.6 + + When a registry is set up (or created) by a :term:`Configurator`, this + attribute will be the shortcut for + :attr:`pyramid.config.Configurator.package_name`. + + This attribute is often accessed as ``request.registry.package_name`` or + ``config.registry.package_name`` or ``config.package_name`` + in a typical Pyramid application. + + .. attribute:: introspector + + .. versionadded:: 1.3 + + 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. + + .. 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. + + This attribute is often accessed as ``request.registry.introspector`` in + a typical Pyramid application. + + .. method:: notify(*events) + + Fire one or more events. All event subscribers to the event(s) + will be notified. The subscribers will be called synchronously. + This method is often accessed as ``request.registry.notify`` + in Pyramid applications to fire custom events. See + :ref:`custom_events` for more information. + + +.. class:: Introspectable + + .. versionadded:: 1.3 + + The default implementation of the interface + :class:`pyramid.interfaces.IIntrospectable` used by framework exenders. + An instance of this class is created when + :attr:`pyramid.config.Configurator.introspectable` is called. + +.. autoclass:: Deferred + + .. versionadded:: 1.4 + +.. autofunction:: undefer + + .. versionadded:: 1.4 + +.. autoclass:: predvalseq + + .. versionadded:: 1.4 diff --git a/docs/api/renderers.rst b/docs/api/renderers.rst index 459639a46..0caca02b4 100644 --- a/docs/api/renderers.rst +++ b/docs/api/renderers.rst @@ -11,3 +11,20 @@ .. autofunction:: render_to_response +.. autoclass:: JSON + + .. automethod:: add_adapter + +.. autoclass:: JSONP + + .. automethod:: add_adapter + +.. attribute:: null_renderer + + An object that can be used in advanced integration cases as input to the + view configuration ``renderer=`` argument. When the null renderer is used + as a view renderer argument, Pyramid avoids converting the view callable + result into a Response object. This is useful if you want to reuse the + view configuration and lookup machinery outside the context of its use by + the Pyramid router. + diff --git a/docs/api/request.rst b/docs/api/request.rst index 8cb424658..52bf50078 100644 --- a/docs/api/request.rst +++ b/docs/api/request.rst @@ -8,6 +8,13 @@ .. autoclass:: Request :members: :inherited-members: + :exclude-members: add_response_callback, add_finished_callback, + route_url, route_path, current_route_url, + current_route_path, static_url, static_path, + model_url, resource_url, resource_path, set_property, + effective_principals, authenticated_userid, + unauthenticated_userid, has_permission, + invoke_exception_view .. attribute:: context @@ -85,6 +92,17 @@ of ``request.exception`` will be ``None`` within response and finished callbacks. + .. attribute:: exc_info + + If an exception was raised by a :term:`root factory` or a :term:`view + callable`, or at various other points where :app:`Pyramid` executes + user-defined code during the processing of a request, result of + ``sys.exc_info()`` will be available as the ``exc_info`` attribute of + the request within a :term:`exception view`, a :term:`response callback` + or a :term:`finished callback`. If no exception occurred, the value of + ``request.exc_info`` will be ``None`` within response and finished + callbacks. + .. attribute:: response This attribute is actually a "reified" property which returns an @@ -107,7 +125,9 @@ return {'text':'Value that will be used by the renderer'} Mutations to this response object will be preserved in the response sent - to the client after rendering. + to the client after rendering. For more information about using + ``request.response`` in conjunction with a renderer, see + :ref:`request_response_attr`. Non-renderer code can also make use of request.response instead of creating a response "by hand". For example, in view code:: @@ -128,10 +148,6 @@ ``request.session`` attribute will cause a :class:`pyramid.exceptions.ConfigurationError` to be raised. - .. attribute:: tmpl_context - - The template context for Pylons-style applications. - .. attribute:: matchdict If a :term:`route` has matched during this request, this attribute will @@ -143,11 +159,111 @@ .. attribute:: matched_route If a :term:`route` has matched during this request, this attribute will - be an obect representing the route matched by the URL pattern + be an object representing the route matched by the URL pattern associated with the route. If a route has not matched during this request, the value of this attribute will be ``None``. See :ref:`matched_route`. + .. attribute:: authenticated_userid + + .. versionadded:: 1.5 + + A property which returns the :term:`userid` of the currently + authenticated user or ``None`` if there is no :term:`authentication + policy` in effect or there is no currently authenticated user. This + differs from :attr:`~pyramid.request.Request.unauthenticated_userid`, + because the effective authentication policy will have ensured that a + record associated with the :term:`userid` exists in persistent storage; + if it has not, this value will be ``None``. + + .. attribute:: unauthenticated_userid + + .. versionadded:: 1.5 + + A property which returns a value which represents the *claimed* (not + verified) :term:`userid` of the credentials present in the + request. ``None`` if there is no :term:`authentication policy` in effect + or there is no user data associated with the current request. This + differs from :attr:`~pyramid.request.Request.authenticated_userid`, + because the effective authentication policy will not ensure that a + record associated with the :term:`userid` exists in persistent storage. + Even if the :term:`userid` does not exist in persistent storage, this + value will be the value of the :term:`userid` *claimed* by the request + data. + + .. attribute:: effective_principals + + .. versionadded:: 1.5 + + A property which returns the list of 'effective' :term:`principal` + identifiers for this request. This list typically includes the + :term:`userid` of the currently authenticated user if a user is + currently authenticated, but this depends on the + :term:`authentication policy` in effect. If no :term:`authentication + policy` is in effect, this will return a sequence containing only the + :attr:`pyramid.security.Everyone` principal. + + .. method:: invoke_subrequest(request, use_tweens=False) + + .. versionadded:: 1.4a1 + + 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: + + - 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 (the current Pyramid registry) 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.events.NewRequest` event to be sent at the + beginning of request processing. + + - causes a :class:`~pyramid.events.ContextFound` event to be sent + when a context resource is found. + + - Ensures that the user implied by the request passed has the necessary + authorization to invoke view callable before calling it. + + - 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.events.NewResponse` event to be sent if a + response is obtained. + + - Calls any :term:`finished callback` functions defined within the + request's lifetime. + + ``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. + + .. seealso:: + + See also :ref:`subrequest_chapter`. + + .. automethod:: invoke_exception_view + + .. automethod:: has_permission + .. automethod:: add_response_callback .. automethod:: add_finished_callback @@ -156,26 +272,99 @@ .. automethod:: route_path - .. automethod:: resource_url + .. automethod:: current_route_url + + .. automethod:: current_route_path .. automethod:: static_url - .. attribute:: response_* + .. automethod:: static_path + + .. automethod:: resource_url + + .. automethod:: resource_path + + .. attribute:: json_body + + 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. + + .. seealso:: + + See also :ref:`request_json_body`. + + .. method:: set_property(callable, name=None, reify=False) + + Add a callable or a property descriptor to the request instance. + + Properties, unlike attributes, are lazily evaluated by executing + an underlying callable when accessed. They can be useful for + adding features to an object without any cost if those features + go unused. + + A property may also be reified via the + :class:`pyramid.decorator.reify` decorator by setting + ``reify=True``, allowing the result of the evaluation to be + cached. Thus the value of the property is only computed once for + the lifetime of the object. + + ``callable`` can either be a callable that accepts the request as + its single positional parameter, or it can be a property + descriptor. + + If the ``callable`` is a property descriptor a ``ValueError`` + will be raised if ``name`` is ``None`` or ``reify`` is ``True``. + + If ``name`` is None, the name of the property will be computed + from the name of the ``callable``. + + .. code-block:: python + :linenos: + + def _connect(request): + conn = request.registry.dbsession() + def cleanup(request): + # since version 1.5, request.exception is no + # longer eagerly cleared + if request.exception is not None: + conn.rollback() + else: + conn.commit() + conn.close() + request.add_finished_callback(cleanup) + return conn + + @subscriber(NewRequest) + def new_request(event): + request = event.request + request.set_property(_connect, 'db', reify=True) + + The subscriber doesn't actually connect to the database, it just + provides the API which, when accessed via ``request.db``, will + create the connection. Thanks to reify, only one connection is + made per-request even if ``request.db`` is accessed many times. + + This pattern provides a way to augment the ``request`` object + without having to subclass it, which can be useful for extension + authors. + + .. versionadded:: 1.3 + + .. attribute:: localizer + + A :term:`localizer` which will use the current locale name to + translate values. + + .. versionadded:: 1.5 + + .. attribute:: locale_name - .. warning:: As of Pyramid 1.1, assignment to ``response_*`` attrs are - deprecated. Assigning to one will cause a deprecation warning to be - emitted. Instead of assigning ``response_*`` attributes to the - request, use API of the the :attr:`pyramid.request.Request.response` - object (exposed to view code as ``request.response``) to influence - response behavior. + The locale name of the current request as computed by the + :term:`locale negotiator`. - You can set attributes on a :class:`pyramid.request.Request` which will - influence the behavor of *rendered* responses (views which use a - :term:`renderer` and which don't directly return a response). These - attributes begin with ``response_``, such as ``response_headerlist``. If - you need to influence response values from a view that uses a renderer - (such as the status code, a header, the content type, etc) see, - :ref:`response_prefixed_attrs`. + .. versionadded:: 1.5 .. note:: @@ -183,3 +372,4 @@ that used as ``request.GET``, ``request.POST``, and ``request.params``), see :class:`pyramid.interfaces.IMultiDict`. +.. autofunction:: apply_request_extensions(request) diff --git a/docs/api/response.rst b/docs/api/response.rst index c545b4977..52978a126 100644 --- a/docs/api/response.rst +++ b/docs/api/response.rst @@ -8,3 +8,14 @@ .. autoclass:: Response :members: :inherited-members: + +.. autoclass:: FileResponse + :members: + +.. autoclass:: FileIter + +Functions +~~~~~~~~~ + +.. autofunction:: response_adapter + diff --git a/docs/api/scaffolds.rst b/docs/api/scaffolds.rst new file mode 100644 index 000000000..827962e19 --- /dev/null +++ b/docs/api/scaffolds.rst @@ -0,0 +1,13 @@ +.. _scaffolds_module: + +:mod:`pyramid.scaffolds` +------------------------ + +.. automodule:: pyramid.scaffolds + + .. autoclass:: pyramid.scaffolds.Template + :members: + + .. autoclass:: pyramid.scaffolds.PyramidTemplate + :members: + diff --git a/docs/api/scripting.rst b/docs/api/scripting.rst index 9d5bc2e58..51bd3c7a0 100644 --- a/docs/api/scripting.rst +++ b/docs/api/scripting.rst @@ -7,3 +7,5 @@ .. autofunction:: get_root + .. autofunction:: prepare + diff --git a/docs/api/security.rst b/docs/api/security.rst index de249355d..88086dbbf 100644 --- a/docs/api/security.rst +++ b/docs/api/security.rst @@ -16,7 +16,7 @@ Authentication API Functions .. autofunction:: forget -.. autofunction:: remember +.. autofunction:: remember(request, userid, **kwargs) Authorization API Functions --------------------------- @@ -57,6 +57,14 @@ Constants last ACE in an ACL in systems that use an "inheriting" security policy, representing the concept "don't inherit any other ACEs". +.. attribute:: NO_PERMISSION_REQUIRED + + A special permission which indicates that the view should always + be executable by entirely anonymous users, regardless of the + default permission, bypassing any :term:`authorization policy` + that may be in effect. Its actual value is the string + '__no_permission_required__'. + Return Values ------------- @@ -64,13 +72,13 @@ Return Values The ACE "action" (the first element in an ACE e.g. ``(Allow, Everyone, 'read')`` that means allow access. A sequence of ACEs makes up an - ACL. It is a string, and it's actual value is "Allow". + ACL. It is a string, and its actual value is "Allow". .. attribute:: Deny The ACE "action" (the first element in an ACE e.g. ``(Deny, 'george', 'read')`` that means deny access. A sequence of ACEs - makes up an ACL. It is a string, and it's actual value is "Deny". + makes up an ACL. It is a string, and its actual value is "Deny". .. autoclass:: ACLDenied :members: diff --git a/docs/api/session.rst b/docs/api/session.rst index 44b4bd860..56c4f52d7 100644 --- a/docs/api/session.rst +++ b/docs/api/session.rst @@ -5,10 +5,19 @@ .. automodule:: pyramid.session - .. autofunction:: UnencryptedCookieSessionFactoryConfig - .. autofunction:: signed_serialize .. autofunction:: signed_deserialize + .. autofunction:: check_csrf_origin + + .. autofunction:: check_csrf_token + + .. autofunction:: SignedCookieSessionFactory + + .. autofunction:: UnencryptedCookieSessionFactoryConfig + + .. autofunction:: BaseCookieSessionFactory + + .. autoclass:: PickleSerializer diff --git a/docs/api/settings.rst b/docs/api/settings.rst index ac1cd3f9c..cd802e138 100644 --- a/docs/api/settings.rst +++ b/docs/api/settings.rst @@ -5,8 +5,8 @@ .. automodule:: pyramid.settings - .. autofunction:: get_settings - .. autofunction:: asbool + .. autofunction:: aslist + diff --git a/docs/api/static.rst b/docs/api/static.rst new file mode 100644 index 000000000..f3727e197 --- /dev/null +++ b/docs/api/static.rst @@ -0,0 +1,19 @@ +.. _static_module: + +:mod:`pyramid.static` +--------------------- + +.. automodule:: pyramid.static + + .. autoclass:: static_view + :members: + :inherited-members: + + .. autoclass:: ManifestCacheBuster + :members: + + .. autoclass:: QueryStringCacheBuster + :members: + + .. autoclass:: QueryStringConstantCacheBuster + :members: diff --git a/docs/api/testing.rst b/docs/api/testing.rst index f388dc263..1366a1795 100644 --- a/docs/api/testing.rst +++ b/docs/api/testing.rst @@ -9,6 +9,8 @@ .. autofunction:: tearDown + .. autofunction:: testConfig(registry=None, request=None, hook_zca=True, autocommit=True, settings=None) + .. autofunction:: cleanUp .. autoclass:: DummyResource diff --git a/docs/api/tweens.rst b/docs/api/tweens.rst new file mode 100644 index 000000000..ddacd2cde --- /dev/null +++ b/docs/api/tweens.rst @@ -0,0 +1,25 @@ +.. _tweens_module: + +:mod:`pyramid.tweens` +--------------------- + +.. automodule:: pyramid.tweens + + .. autofunction:: excview_tween_factory + + .. attribute:: MAIN + + Constant representing the main Pyramid handling function, for use in + ``under`` and ``over`` arguments to + :meth:`pyramid.config.Configurator.add_tween`. + + .. attribute:: INGRESS + + Constant representing the request ingress, for use in ``under`` and + ``over`` arguments to :meth:`pyramid.config.Configurator.add_tween`. + + .. attribute:: EXCVIEW + + Constant representing the exception view tween, for use in ``under`` + and ``over`` arguments to + :meth:`pyramid.config.Configurator.add_tween`. diff --git a/docs/api/url.rst b/docs/api/url.rst index 01be76283..131d85806 100644 --- a/docs/api/url.rst +++ b/docs/api/url.rst @@ -13,7 +13,11 @@ .. autofunction:: route_path + .. autofunction:: current_route_path + .. autofunction:: static_url + .. autofunction:: static_path + .. autofunction:: urlencode diff --git a/docs/api/view.rst b/docs/api/view.rst index 4dddea25f..d8e429552 100644 --- a/docs/api/view.rst +++ b/docs/api/view.rst @@ -11,16 +11,16 @@ .. autofunction:: render_view - .. autofunction:: is_response - .. autoclass:: view_config :members: - .. autoclass:: static + .. autoclass:: view_defaults + :members: + + .. autoclass:: notfound_view_config :members: - :inherited-members: - .. autofunction:: append_slash_notfound_view(context, request) + .. autoclass:: forbidden_view_config + :members: - .. autoclass:: AppendSlashNotFoundViewFactory diff --git a/docs/api/viewderivers.rst b/docs/api/viewderivers.rst new file mode 100644 index 000000000..2a141501e --- /dev/null +++ b/docs/api/viewderivers.rst @@ -0,0 +1,17 @@ +.. _viewderivers_module: + +:mod:`pyramid.viewderivers` +--------------------------- + +.. automodule:: pyramid.viewderivers + + .. attribute:: INGRESS + + Constant representing the request ingress, for use in ``under`` + arguments to :meth:`pyramid.config.Configurator.add_view_deriver`. + + .. attribute:: VIEW + + Constant representing the :term:`view callable` at the end of the view + pipeline, for use in ``over`` arguments to + :meth:`pyramid.config.Configurator.add_view_deriver`. |