From f54cae02910f27e2ef7df224aa8fb7b9e1df5f99 Mon Sep 17 00:00:00 2001 From: Theron Luhn Date: Sun, 23 Jun 2019 11:27:27 -0700 Subject: Add a whatsnew-2.0 doc. --- docs/index.rst | 1 + docs/upgrading-2.0.rst | 74 --------------------------------------- docs/whatsnew-2.0.rst | 95 ++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 96 insertions(+), 74 deletions(-) delete mode 100644 docs/upgrading-2.0.rst create mode 100644 docs/whatsnew-2.0.rst diff --git a/docs/index.rst b/docs/index.rst index 4b413c16d..13ece925a 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -174,6 +174,7 @@ Change History .. toctree:: :maxdepth: 1 + whatsnew-2.0 whatsnew-1.10 whatsnew-1.9 whatsnew-1.8 diff --git a/docs/upgrading-2.0.rst b/docs/upgrading-2.0.rst deleted file mode 100644 index 506d9cf3c..000000000 --- a/docs/upgrading-2.0.rst +++ /dev/null @@ -1,74 +0,0 @@ -Upgrading to Pyramid 2.0 -======================== - -Pyramid 2.0 is largely backwards compatible with the 1.x series, so minimal -changes should be necessary. However, some 1.x functionality has been -deprecated and it is recommended to upgrade from the legacy systems. - -.. _upgrading_auth: - -Upgrading Authentication/Authorization --------------------------------------- - -The authentication and authorization policies of Pyramid 1.x have been merged -into a single :term:`security policy` in Pyramid 2.0. Authentication and -authorization policies can still be used and will continue to function -normally, however they have been deprecated and support may be removed in -upcoming versions. - -The new security policy should implement -:interface:`pyramid.interfaces.ISecurityPolicy` and can be set via the -``security_policy`` argument of :class:`pyramid.config.Configurator` or -:meth:`pyramid.config.Configurator.set_security_policy`. - -The new security policy merges ``unauthenticated_userid`` and -``authenticated_userid`` into an :term:`identity` object. This object can be -of any shape, such as a simple ID string or an ORM object, but should The -identity can be accessed via -:prop:`pyramid.request.Request.authenticated_identity`. - -The concept of :term:`principals ` has been removed; the -``permits`` method is passed an identity object. This change gives much more -flexibility in authorization implementations, especially those that do not -match the ACL pattern. If you were previously using -:class:`pyramid.authorization.ACLAuthorizationPolicy`, you can achieve the same -results by writing your own ``permits`` method using -:class:`pyraid.authorization.ACLHelper`. For more details on implementing an -ACL, see :ref:`assigning_acls`. - -Pyramid does not provide any built-in security policies. Similiar -functionality of the authentication and authorization policies is now provided -by helpers, which can be utilized to easily implement your own security policy. -The functionality of the legacy authencation policies roughly correspond to the -following helpers - -* :class:`pyramid.authentication.SessionAuthenticationPolicy`: - :class:`pyramid.authentication.SessionAuthenticationHelper` -* :class:`pyramid.authentication.AuthTktAuthenticationPolicy`: - :class:`pyramid.authentication.AuthTktCookieHelper` -* :class:`pyramid.authentication.BasicAuthAuthenticationPolicy`: - Use :func:`pyramid.authentication.extract_http_basic_credentials` to retrieve - credentials. -* :class:`pyramid.authentication.RemoteUserAuthenticationPolicy`: - ``REMOTE_USER`` can be accessed with ``request.environ.get('REMOTE_USER')``. -* :class:`pyramid.authentication.RepozeWho1AuthenticationPolicy`: - No equivalent. - -For further documentation on implementing security policies, see -:ref:`writing_security_policy`. - -Behavior of the Legacy System -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Legacy authentication and authorization policies will continue to function as -normal, as well as all related :class:`pyramid.request.Request` properties. -The new :prop:`pyramid.request.Request.authenticated_identity` property will -output the same result as :prop:`pyramid.request.Request.authenticated_userid`. - -If using a security policy, -:prop:`pyramid.request.Request.unauthenticated_userid` and -:prop:`pyramid.request.Request.authenticated_userid` will both return the -string representation of the :term:`identity`. -:prop:`pyramid.request.Request.effective_principals` will always return a -one-element list containing the :data:`pyramid.security.Everyone` principal, as -there is no equivalent in the new security policy. diff --git a/docs/whatsnew-2.0.rst b/docs/whatsnew-2.0.rst new file mode 100644 index 000000000..c33f40206 --- /dev/null +++ b/docs/whatsnew-2.0.rst @@ -0,0 +1,95 @@ +What's New in Pyramid 2.0 +========================= + +This article explains the new features in :app:`Pyramid` version 2.0 as +compared to its predecessor, :app:`Pyramid` 1.10. It also documents backwards +incompatibilities between the two versions and deprecations added to +:app:`Pyramid` 2.0, as well as software dependency changes and notable +documentation additions. + +Feature Additions +----------------- + +The feature additions in Pyramid 2.0 are as follows: + +- The authentication and authorization policies of Pyramid 1.x have been merged + into a single :term:`security policy` in Pyramid 2.0. For details on how to + migrate to the new security policy, see :ref:`upgrading_auth`. + Authentication and authorization policies can still be used and will continue + to function normally for the time being. + +Deprecations +------------ + +- Authentication and authorization policies have been deprecated in favor of + the new :term:`security policy`. + +.. _upgrading_auth: + +Upgrading Authentication/Authorization +-------------------------------------- + +The authentication and authorization policies of Pyramid 1.x have been merged +into a single :term:`security policy` in Pyramid 2.0. Authentication and +authorization policies can still be used and will continue to function +normally, however they have been deprecated and support may be removed in +upcoming versions. + +The new security policy should implement +:class:`pyramid.interfaces.ISecurityPolicy` and can be set via the +``security_policy`` argument of :class:`pyramid.config.Configurator` or +:meth:`pyramid.config.Configurator.set_security_policy`. + +The new security policy merges ``unauthenticated_userid`` and +``authenticated_userid`` into an :term:`identity` object. This object can be +of any shape, such as a simple ID string or an ORM object, but should The +identity can be accessed via +:attr:`pyramid.request.Request.authenticated_identity`. + +The concept of :term:`principals ` has been removed; the +``permits`` method is passed an identity object. This change gives much more +flexibility in authorization implementations, especially those that do not +match the ACL pattern. If you were previously using +:class:`pyramid.authorization.ACLAuthorizationPolicy`, you can achieve the same +results by writing your own ``permits`` method using +:class:`pyraid.authorization.ACLHelper`. For more details on implementing an +ACL, see :ref:`assigning_acls`. + +Pyramid does not provide any built-in security policies. Similiar +functionality of the authentication and authorization policies is now provided +by helpers, which can be utilized to easily implement your own security policy. +The functionality of the legacy authencation policies roughly correspond to the +following helpers + +* :class:`pyramid.authentication.SessionAuthenticationPolicy`: + :class:`pyramid.authentication.SessionAuthenticationHelper` +* :class:`pyramid.authentication.AuthTktAuthenticationPolicy`: + :class:`pyramid.authentication.AuthTktCookieHelper` +* :class:`pyramid.authentication.BasicAuthAuthenticationPolicy`: + Use :func:`pyramid.authentication.extract_http_basic_credentials` to retrieve + credentials. +* :class:`pyramid.authentication.RemoteUserAuthenticationPolicy`: + ``REMOTE_USER`` can be accessed with ``request.environ.get('REMOTE_USER')``. +* :class:`pyramid.authentication.RepozeWho1AuthenticationPolicy`: + No equivalent. + +For further documentation on implementing security policies, see +:ref:`writing_security_policy`. + +.. _behavior_of_legacy_auth: + +Behavior of the Legacy System +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Legacy authentication and authorization policies will continue to function as +normal, as well as all related :class:`pyramid.request.Request` properties. +The new :attr:`pyramid.request.Request.authenticated_identity` property will +output the same result as :attr:`pyramid.request.Request.authenticated_userid`. + +If using a security policy, +:attr:`pyramid.request.Request.unauthenticated_userid` and +:attr:`pyramid.request.Request.authenticated_userid` will both return the +string representation of the :term:`identity`. +:attr:`pyramid.request.Request.effective_principals` will always return a +one-element list containing the :data:`pyramid.security.Everyone` principal, as +there is no equivalent in the new security policy. -- cgit v1.2.3