diff options
Diffstat (limited to 'docs/api')
| -rw-r--r-- | docs/api/authentication.rst | 5 | ||||
| -rw-r--r-- | docs/api/config.rst | 14 | ||||
| -rw-r--r-- | docs/api/csrf.rst | 23 | ||||
| -rw-r--r-- | docs/api/events.rst | 2 | ||||
| -rw-r--r-- | docs/api/exceptions.rst | 14 | ||||
| -rw-r--r-- | docs/api/httpexceptions.rst | 96 | ||||
| -rw-r--r-- | docs/api/i18n.rst | 1 | ||||
| -rw-r--r-- | docs/api/index.rst | 12 | ||||
| -rw-r--r-- | docs/api/interfaces.rst | 23 | ||||
| -rw-r--r-- | docs/api/paster.rst | 6 | ||||
| -rw-r--r-- | docs/api/registry.rst | 12 | ||||
| -rw-r--r-- | docs/api/request.rst | 90 | ||||
| -rw-r--r-- | docs/api/scaffolds.rst | 13 | ||||
| -rw-r--r-- | docs/api/security.rst | 32 | ||||
| -rw-r--r-- | docs/api/session.rst | 11 | ||||
| -rw-r--r-- | docs/api/static.rst | 8 | ||||
| -rw-r--r-- | docs/api/url.rst | 2 | ||||
| -rw-r--r-- | docs/api/view.rst | 2 | ||||
| -rw-r--r-- | docs/api/viewderivers.rst | 17 |
19 files changed, 246 insertions, 137 deletions
diff --git a/docs/api/authentication.rst b/docs/api/authentication.rst index 19d08618b..57f32327a 100644 --- a/docs/api/authentication.rst +++ b/docs/api/authentication.rst @@ -34,5 +34,10 @@ Helper Classes .. autoclass:: AuthTktCookieHelper :members: + .. autoclass:: HTTPBasicCredentials + :members: +Helper Functions +~~~~~~~~~~~~~~~~ + .. autofunction:: extract_http_basic_credentials diff --git a/docs/api/config.rst b/docs/api/config.rst index 48dd2f0b9..4fe0e855d 100644 --- a/docs/api/config.rst +++ b/docs/api/config.rst @@ -17,6 +17,7 @@ .. automethod:: end .. automethod:: include .. automethod:: make_wsgi_app() + .. automethod:: route_prefix_context .. automethod:: scan :methodcategory:`Adding Routes and Views` @@ -26,6 +27,7 @@ .. automethod:: add_view .. automethod:: add_notfound_view .. automethod:: add_forbidden_view + .. automethod:: add_exception_view :methodcategory:`Adding an Event Subscriber` @@ -35,13 +37,14 @@ .. automethod:: set_authentication_policy .. automethod:: set_authorization_policy + .. automethod:: set_default_csrf_options + .. automethod:: set_csrf_storage_policy .. automethod:: set_default_permission .. automethod:: add_permission :methodcategory:`Extending the Request Object` .. automethod:: add_request_method - .. automethod:: set_request_property :methodcategory:`Using I18N` @@ -59,13 +62,17 @@ :methodcategory:`Hooking Pyramid Behavior` + .. automethod:: add_accept_view_order .. automethod:: add_renderer .. automethod:: add_resource_url_adapter .. automethod:: add_response_adapter .. automethod:: add_traverser .. automethod:: add_tween .. automethod:: add_route_predicate + .. automethod:: add_subscriber_predicate .. automethod:: add_view_predicate + .. automethod:: add_view_deriver + .. automethod:: set_execution_policy .. automethod:: set_request_factory .. automethod:: set_root_factory .. automethod:: set_session_factory @@ -132,3 +139,8 @@ are being used. .. autoclass:: not_ + +.. attribute:: PHASE0_CONFIG +.. attribute:: PHASE1_CONFIG +.. attribute:: PHASE2_CONFIG +.. attribute:: PHASE3_CONFIG diff --git a/docs/api/csrf.rst b/docs/api/csrf.rst new file mode 100644 index 000000000..38501546e --- /dev/null +++ b/docs/api/csrf.rst @@ -0,0 +1,23 @@ +.. _csrf_module: + +:mod:`pyramid.csrf` +------------------- + +.. automodule:: pyramid.csrf + + .. autoclass:: LegacySessionCSRFStoragePolicy + :members: + + .. autoclass:: SessionCSRFStoragePolicy + :members: + + .. autoclass:: CookieCSRFStoragePolicy + :members: + + .. autofunction:: get_csrf_token + + .. autofunction:: new_csrf_token + + .. autofunction:: check_csrf_origin + + .. autofunction:: check_csrf_token diff --git a/docs/api/events.rst b/docs/api/events.rst index 31a0e22c1..0a8463740 100644 --- a/docs/api/events.rst +++ b/docs/api/events.rst @@ -21,6 +21,8 @@ Event Types .. autoclass:: ContextFound +.. autoclass:: BeforeTraversal + .. autoclass:: NewResponse .. autoclass:: BeforeRender diff --git a/docs/api/exceptions.rst b/docs/api/exceptions.rst index 0c630571f..cb411458d 100644 --- a/docs/api/exceptions.rst +++ b/docs/api/exceptions.rst @@ -5,14 +5,16 @@ .. automodule:: pyramid.exceptions - .. autoclass:: BadCSRFToken + .. autoexception:: BadCSRFOrigin - .. autoclass:: PredicateMismatch + .. autoexception:: BadCSRFToken - .. autoclass:: Forbidden + .. autoexception:: PredicateMismatch - .. autoclass:: NotFound + .. autoexception:: Forbidden - .. autoclass:: ConfigurationError + .. autoexception:: NotFound - .. autoclass:: URLDecodeError + .. autoexception:: ConfigurationError + + .. autoexception:: URLDecodeError diff --git a/docs/api/httpexceptions.rst b/docs/api/httpexceptions.rst index b50f10beb..e25a07cd5 100644 --- a/docs/api/httpexceptions.rst +++ b/docs/api/httpexceptions.rst @@ -13,96 +13,98 @@ .. autofunction:: exception_response - .. autoclass:: HTTPException + .. autoexception:: HTTPException - .. autoclass:: HTTPOk + .. autoexception:: HTTPOk - .. autoclass:: HTTPRedirection + .. autoexception:: HTTPRedirection - .. autoclass:: HTTPError + .. autoexception:: HTTPError - .. autoclass:: HTTPClientError + .. autoexception:: HTTPClientError - .. autoclass:: HTTPServerError + .. autoexception:: HTTPServerError - .. autoclass:: HTTPCreated + .. autoexception:: HTTPCreated - .. autoclass:: HTTPAccepted + .. autoexception:: HTTPAccepted - .. autoclass:: HTTPNonAuthoritativeInformation + .. autoexception:: HTTPNonAuthoritativeInformation - .. autoclass:: HTTPNoContent + .. autoexception:: HTTPNoContent - .. autoclass:: HTTPResetContent + .. autoexception:: HTTPResetContent - .. autoclass:: HTTPPartialContent + .. autoexception:: HTTPPartialContent - .. autoclass:: HTTPMultipleChoices + .. autoexception:: HTTPMultipleChoices - .. autoclass:: HTTPMovedPermanently + .. autoexception:: HTTPMovedPermanently - .. autoclass:: HTTPFound + .. autoexception:: HTTPFound - .. autoclass:: HTTPSeeOther + .. autoexception:: HTTPSeeOther - .. autoclass:: HTTPNotModified + .. autoexception:: HTTPNotModified - .. autoclass:: HTTPUseProxy + .. autoexception:: HTTPUseProxy - .. autoclass:: HTTPTemporaryRedirect + .. autoexception:: HTTPTemporaryRedirect - .. autoclass:: HTTPBadRequest + .. autoexception:: HTTPPermanentRedirect - .. 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:: HTTPUnprocessableEntity + .. autoexception:: HTTPExpectationFailed - .. autoclass:: HTTPLocked + .. autoexception:: HTTPUnprocessableEntity - .. autoclass:: HTTPFailedDependency + .. autoexception:: HTTPLocked - .. autoclass:: HTTPInternalServerError + .. autoexception:: HTTPFailedDependency - .. autoclass:: HTTPNotImplemented + .. autoexception:: HTTPInternalServerError - .. autoclass:: HTTPBadGateway + .. autoexception:: HTTPNotImplemented - .. autoclass:: HTTPServiceUnavailable + .. autoexception:: HTTPBadGateway - .. autoclass:: HTTPGatewayTimeout + .. autoexception:: HTTPServiceUnavailable - .. autoclass:: HTTPVersionNotSupported + .. autoexception:: HTTPGatewayTimeout - .. autoclass:: HTTPInsufficientStorage + .. autoexception:: HTTPVersionNotSupported + + .. autoexception:: HTTPInsufficientStorage diff --git a/docs/api/i18n.rst b/docs/api/i18n.rst index 3b9abbc1d..7a61246df 100644 --- a/docs/api/i18n.rst +++ b/docs/api/i18n.rst @@ -6,6 +6,7 @@ .. automodule:: pyramid.i18n .. autoclass:: TranslationString + :noindex: .. autofunction:: TranslationStringFactory diff --git a/docs/api/index.rst b/docs/api/index.rst new file mode 100644 index 000000000..4b912e2bd --- /dev/null +++ b/docs/api/index.rst @@ -0,0 +1,12 @@ +.. _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 d8d935afd..e542a6be0 100644 --- a/docs/api/interfaces.rst +++ b/docs/api/interfaces.rst @@ -17,6 +17,9 @@ Event-Related Interfaces .. autointerface:: IContextFound :members: + .. autointerface:: IBeforeTraversal + :members: + .. autointerface:: INewResponse :members: @@ -41,6 +44,9 @@ Other Interfaces .. autointerface:: IRoutePregenerator :members: + .. autointerface:: ICSRFStoragePolicy + :members: + .. autointerface:: ISession :members: @@ -56,6 +62,15 @@ Other Interfaces .. autointerface:: IRenderer :members: + .. autointerface:: IRequestFactory + :members: + + .. autointerface:: IResponseFactory + :members: + + .. autointerface:: IRouter + :members: + .. autointerface:: IViewMapperFactory :members: @@ -86,3 +101,11 @@ Other Interfaces .. 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 edc3738fc..f0784d0f8 100644 --- a/docs/api/paster.rst +++ b/docs/api/paster.rst @@ -7,8 +7,8 @@ .. autofunction:: bootstrap - .. autofunction:: get_app(config_uri, name=None, options=None) + .. autofunction:: get_app - .. autofunction:: get_appsettings(config_uri, name=None, options=None) + .. autofunction:: get_appsettings - .. autofunction:: setup_logging(config_uri) + .. autofunction:: setup_logging diff --git a/docs/api/registry.rst b/docs/api/registry.rst index bab3e26ba..57a80b3f5 100644 --- a/docs/api/registry.rst +++ b/docs/api/registry.rst @@ -14,6 +14,18 @@ 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 diff --git a/docs/api/request.rst b/docs/api/request.rst index 77d80f6d6..0c169adaf 100644 --- a/docs/api/request.rst +++ b/docs/api/request.rst @@ -11,9 +11,10 @@ :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, set_property, + model_url, resource_url, resource_path, set_property, effective_principals, authenticated_userid, - unauthenticated_userid, has_permission + unauthenticated_userid, has_permission, + invoke_exception_view .. attribute:: context @@ -167,37 +168,40 @@ .. versionadded:: 1.5 - A property which returns the 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 userid exists in persistent storage; if it has - not, this value will be ``None``. + 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) user id 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 userid exists in persistent storage. Even if the userid - does not exist in persistent storage, this value will be the value - of the userid *claimed* by the request data. + 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 will include the userid of the - currently authenticated user if a user is currently authenticated. If no - :term:`authentication policy` is in effect, this will return a sequence - containing only the :attr:`pyramid.security.Everyone` 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) @@ -224,8 +228,7 @@ 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 + :meth:`~pyramid.config.Configurator.add_request_method`) on the request it's passed. - causes a :class:`~pyramid.events.NewRequest` event to be sent at the @@ -256,6 +259,8 @@ See also :ref:`subrequest_chapter`. + .. automethod:: invoke_exception_view + .. automethod:: has_permission .. automethod:: add_response_callback @@ -315,25 +320,25 @@ 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) + :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 @@ -366,3 +371,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/scaffolds.rst b/docs/api/scaffolds.rst deleted file mode 100644 index 827962e19..000000000 --- a/docs/api/scaffolds.rst +++ /dev/null @@ -1,13 +0,0 @@ -.. _scaffolds_module: - -:mod:`pyramid.scaffolds` ------------------------- - -.. automodule:: pyramid.scaffolds - - .. autoclass:: pyramid.scaffolds.Template - :members: - - .. autoclass:: pyramid.scaffolds.PyramidTemplate - :members: - diff --git a/docs/api/security.rst b/docs/api/security.rst index 814b68e5a..edb66472e 100644 --- a/docs/api/security.rst +++ b/docs/api/security.rst @@ -8,21 +8,13 @@ Authentication API Functions ---------------------------- -.. autofunction:: authenticated_userid - -.. autofunction:: unauthenticated_userid - -.. autofunction:: effective_principals - .. autofunction:: forget -.. autofunction:: remember +.. autofunction:: remember(request, userid, **kwargs) Authorization API Functions --------------------------- -.. autofunction:: has_permission - .. autofunction:: principals_allowed_by_permission .. autofunction:: view_execution_permitted @@ -80,15 +72,23 @@ Return Values 'george', 'read')`` that means deny access. A sequence of ACEs makes up an ACL. It is a string, and its actual value is "Deny". +.. autoclass:: Denied + :members: msg + + .. automethod:: __new__ + +.. autoclass:: Allowed + :members: msg + + .. automethod:: __new__ + .. autoclass:: ACLDenied - :members: + :members: msg -.. autoclass:: ACLAllowed - :members: + .. automethod:: __new__ -.. autoclass:: Denied - :members: +.. autoclass:: ACLAllowed + :members: msg -.. autoclass:: Allowed - :members: + .. automethod:: __new__ diff --git a/docs/api/session.rst b/docs/api/session.rst index dde9d20e9..60b3cc22f 100644 --- a/docs/api/session.rst +++ b/docs/api/session.rst @@ -5,16 +5,11 @@ .. automodule:: pyramid.session - .. autofunction:: signed_serialize - - .. autofunction:: signed_deserialize - - .. autofunction:: check_csrf_token - .. autofunction:: SignedCookieSessionFactory - .. autofunction:: UnencryptedCookieSessionFactoryConfig - .. autofunction:: BaseCookieSessionFactory + .. autoclass:: JSONSerializer + + .. autoclass:: PickleSerializer diff --git a/docs/api/static.rst b/docs/api/static.rst index c28473584..f3727e197 100644 --- a/docs/api/static.rst +++ b/docs/api/static.rst @@ -9,3 +9,11 @@ :members: :inherited-members: + .. autoclass:: ManifestCacheBuster + :members: + + .. autoclass:: QueryStringCacheBuster + :members: + + .. autoclass:: QueryStringConstantCacheBuster + :members: diff --git a/docs/api/url.rst b/docs/api/url.rst index 131d85806..8aaabc352 100644 --- a/docs/api/url.rst +++ b/docs/api/url.rst @@ -5,7 +5,7 @@ .. automodule:: pyramid.url - .. autofunction:: pyramid.url.resource_url(context, request, *elements, query=None, anchor=None) + .. autofunction:: resource_url .. autofunction:: route_url diff --git a/docs/api/view.rst b/docs/api/view.rst index d8e429552..e41212012 100644 --- a/docs/api/view.rst +++ b/docs/api/view.rst @@ -23,4 +23,6 @@ .. autoclass:: forbidden_view_config :members: + .. autoclass:: exception_view_config + :members: 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`. |