From ecfd8b79c9cc68eb7462cf6e4534c300c489b50e Mon Sep 17 00:00:00 2001 From: Theron Luhn Date: Sat, 8 Jun 2019 10:50:21 -0700 Subject: Beginnings of upgrade docs. --- docs/upgrading-2.0.rst | 42 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) create mode 100644 docs/upgrading-2.0.rst (limited to 'docs') diff --git a/docs/upgrading-2.0.rst b/docs/upgrading-2.0.rst new file mode 100644 index 000000000..e896633e5 --- /dev/null +++ b/docs/upgrading-2.0.rst @@ -0,0 +1,42 @@ +Upgrading to Pyramid 2.0 +======================== + +Pyramid 2.0 was built to be backwards compatible with the 1.x series, so no +changes to your application should be necessary. However, some functionality +has been deprecated and it is recommended to upgrade from the legacy systems. + +.. _upgrade_auth: + +Upgrading to a Security Policy +------------------------------ + +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 will continue to function normally, however they have +been deprecated and may be removed in upcoming versions. + +A security policy should implement +:interface:`pyramid.interfaces.ISecurityPolicy`. You can set the security +policy for your application via the ``security_policy`` parameter in +:class:`pyramid.config.Configurator` or by calling +:meth:`pyramid.config.Configurator.set_security_policy`. If you set a security +policy, you cannot set a authentication or authorization policy. + +``unauthenticated_userid`` and ``authenticated_userid`` have been replaced with +the ``identify`` method. This method should return an :term:`identity`, which +can be an object of any shape, such as a dictionary or an ORM object. (It can +also be a simple user ID, as in the legacy authentication policy.) The +identity can be accessed via +:meth:`pyramid.request.Request.authenticated_identity`. If you're +using a legacy authentication policy, +:meth:`pyramid.request.Request.authenticated_identity` will return the result +of ``authenticated_userid``. + +:prop:`pyramid.request.Request.unauthenticated_userid` and +:prop:`pyramid.request.Request.authenticated_userid` are deprecated but will +continue to work as normal with legacy policies. If using a new security +policy, both properties will return the string representation of the +:term:`identity`. :prop:`pyramid.request.Request.effective_principals` is +also deprecated and will work with legacy policies, but always return a +one-element list containing the :data:`pyramid.security.Everyone` principal +when using a security policy, as there is no equivalent in the new -- cgit v1.2.3