From 21f2b61272f83de110087344e68f32953cd7b42f Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sat, 24 Sep 2016 20:39:45 -0700 Subject: Why use venv/bin/pip instead of source bin/activate then pip? - Closes #2610 --- docs/narr/install.rst | 21 +++++++++++++++++++++ docs/quick_tour.rst | 4 +++- docs/quick_tutorial/requirements.rst | 3 +++ 3 files changed, 27 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/narr/install.rst b/docs/narr/install.rst index 677c27e4a..7b5d8361b 100644 --- a/docs/narr/install.rst +++ b/docs/narr/install.rst @@ -191,6 +191,24 @@ After installing Python as described previously in :ref:`for-mac-os-x-users` or $ $VENV/bin/pip install "pyramid==\ |release|\ " +.. index:: + single: $VENV/bin/pip vs. source bin/activate + +.. _venv-bin-pip-vs-source-bin-activate: + +.. note:: Why use ``$VENV/bin/pip`` instead of ``source bin/activate``, then + ``pip``? + + Although the latter method requires fewer key strokes to issue commands once + invoked, there are numerous reasons why one should avoid using ``activate`` + within a virtual environment. Michael F. Lamb (datagrok) presents a summary + in `Virtualenv's bin/activate is Doing It Wrong + `_, and proposes alternatives, + followed by comments from other developers. + + However, we prefer to keep things simple. ``$VENV/bin/pip`` is already + UNIX-y. The few extra key strokes are worth avoiding the mess altogether. + .. index:: single: installing on Windows @@ -227,6 +245,9 @@ After installing Python as described previously in c:\\> %VENV%\\Scripts\\pip install "pyramid==\ |release|\ " +.. note:: See the note above for :ref:`Why use $VENV/bin/pip instead of source + bin/activate, then pip `. + What Gets Installed ------------------- diff --git a/docs/quick_tour.rst b/docs/quick_tour.rst index b2dec77e9..39b4cafb3 100644 --- a/docs/quick_tour.rst +++ b/docs/quick_tour.rst @@ -59,7 +59,9 @@ show only UNIX commands. .. seealso:: See also: :ref:`Quick Tutorial section on Requirements `, - :ref:`installing_unix`, :ref:`Before You Install `, and + :ref:`installing_unix`, :ref:`Before You Install `, + :ref:`Why use $VENV/bin/pip instead of source bin/activate, then pip + `, and :ref:`Installing Pyramid on a Windows System `. diff --git a/docs/quick_tutorial/requirements.rst b/docs/quick_tutorial/requirements.rst index 1de9a8acf..afa8ed104 100644 --- a/docs/quick_tutorial/requirements.rst +++ b/docs/quick_tutorial/requirements.rst @@ -179,6 +179,9 @@ time of its release. # Windows c:\> %VENV%\Scripts\pip install --upgrade pip setuptools +.. seealso:: See also :ref:`Why use $VENV/bin/pip instead of source + bin/activate, then pip `. + .. _install-pyramid: -- cgit v1.2.3 From 781cf1a5d685daf21ab7b885fda4ab21b05ce940 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 26 Sep 2016 00:18:34 -0700 Subject: Revise Why use venv/bin/pip instead of source bin/activate then pip? - Closes #2610 --- docs/narr/install.rst | 23 ++++++++++++++--------- 1 file changed, 14 insertions(+), 9 deletions(-) (limited to 'docs') diff --git a/docs/narr/install.rst b/docs/narr/install.rst index 7b5d8361b..570cb2285 100644 --- a/docs/narr/install.rst +++ b/docs/narr/install.rst @@ -199,15 +199,20 @@ After installing Python as described previously in :ref:`for-mac-os-x-users` or .. note:: Why use ``$VENV/bin/pip`` instead of ``source bin/activate``, then ``pip``? - Although the latter method requires fewer key strokes to issue commands once - invoked, there are numerous reasons why one should avoid using ``activate`` - within a virtual environment. Michael F. Lamb (datagrok) presents a summary - in `Virtualenv's bin/activate is Doing It Wrong - `_, and proposes alternatives, - followed by comments from other developers. - - However, we prefer to keep things simple. ``$VENV/bin/pip`` is already - UNIX-y. The few extra key strokes are worth avoiding the mess altogether. + ``$VENV/bin/pip`` clearly specifies that ``pip`` is run from within the + virtual environment and not at the system level. + + ``activate`` drops turds into the user's shell environment, leaving them + vulnerable to executing commands in the wrong context. ``deactivate`` might + not correctly restore previous shell environment variables. + + Although using ``source bin/activate``, then ``pip``, requires fewer key + strokes to issue commands once invoked, there are other things to consider. + Michael F. Lamb (datagrok) presents a summary in `Virtualenv's bin/activate + is Doing It Wrong `_. + + Ultimately we prefer to keep things clear and simple, so we use + ``$VENV/bin/pip``. .. index:: -- cgit v1.2.3 From e8c66a339e9f7d83bd2408952de53ef30dba0794 Mon Sep 17 00:00:00 2001 From: Michael Merickel Date: Mon, 19 Sep 2016 23:52:05 -0500 Subject: derive exception views separately from normal views - previously the multiview was shared for both exception and hot-route, but now that we allow some exception-only views this needed to be separated - add ViewDeriverInfo.exception_only to detect exception views - do not prevent http_cache on exception views - optimize secured_view and csrf_view derivers to remove themselves from the view pipeline for exception views --- docs/narr/hooks.rst | 23 +++++++++++++++++++++-- docs/narr/viewconfig.rst | 19 ++++++++++++++++++- docs/narr/views.rst | 40 ++++++++++++++++++++++++++-------------- 3 files changed, 65 insertions(+), 17 deletions(-) (limited to 'docs') diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst index 49ef29d3f..7fbac2080 100644 --- a/docs/narr/hooks.rst +++ b/docs/narr/hooks.rst @@ -1639,7 +1639,8 @@ the user-defined :term:`view callable`: Enforce the ``permission`` defined on the view. This element is a no-op if no permission is defined. Note there will always be a permission defined if a default permission was assigned via - :meth:`pyramid.config.Configurator.set_default_permission`. + :meth:`pyramid.config.Configurator.set_default_permission` unless the + view is an :term:`exception view`. This element will also output useful debugging information when ``pyramid.debug_authorization`` is enabled. @@ -1649,7 +1650,8 @@ the user-defined :term:`view callable`: Used to check the CSRF token provided in the request. This element is a no-op if ``require_csrf`` view option is not ``True``. Note there will always be a ``require_csrf`` option if a default value was assigned via - :meth:`pyramid.config.Configurator.set_default_csrf_options`. + :meth:`pyramid.config.Configurator.set_default_csrf_options` unless + the view is an :term:`exception view`. ``owrapped_view`` @@ -1695,6 +1697,8 @@ around monitoring and security. In order to register a custom :term:`view deriver`, you should create a callable that conforms to the :class:`pyramid.interfaces.IViewDeriver` interface, and then register it with your application using :meth:`pyramid.config.Configurator.add_view_deriver`. +The callable should accept the ``view`` to be wrapped and the ``info`` object +which is an instance of :class:`pyramid.interfaces.IViewDeriverInfo`. For example, below is a callable that can provide timing information for the view pipeline: @@ -1745,6 +1749,21 @@ View derivers are unique in that they have access to most of the options passed to :meth:`pyramid.config.Configurator.add_view` in order to decide what to do, and they have a chance to affect every view in the application. +.. _exception_view_derivers: + +Exception Views and View Derivers +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +A :term:`view deriver` has the opportunity to wrap any view, including +an :term:`exception view`. In general this is fine, but certain view derivers +may wish to avoid doing certain things when handling exceptions. For example, +the ``csrf_view`` and ``secured_view`` built-in view derivers will not perform +security checks on exception views unless explicitly told to do so. + +You can check for ``info.exception_only`` on the +:class:`pyramid.interfaces.IViewDeriverInfo` object when wrapping the view +to determine whether you are wrapping an exception view or a normal view. + Ordering View Derivers ~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/narr/viewconfig.rst b/docs/narr/viewconfig.rst index cd5b8feb0..76eaf3cc5 100644 --- a/docs/narr/viewconfig.rst +++ b/docs/narr/viewconfig.rst @@ -34,7 +34,7 @@ determine the set of circumstances which must be true for the view callable to be invoked. A view configuration statement is made about information present in the -:term:`context` resource and the :term:`request`. +:term:`context` resource (or exception) and the :term:`request`. View configuration is performed in one of two ways: @@ -306,9 +306,26 @@ configured view. represented class or if the :term:`context` resource provides the represented interface; it is otherwise false. + It is possible to pass an exception class as the context if your context may + subclass an exception. In this case **two** views will be registered. One + will match normal incoming requests and the other will match as an + :term:`exception view` which only occurs when an exception is raised during + the normal request processing pipeline. + If ``context`` is not supplied, the value ``None``, which matches any resource, is used. +``exception_only`` + + When this value is ``True`` the ``context`` argument must be a subclass of + ``Exception``. This flag indicates that only an :term:`exception view` should + be created and that this view should not match if the traversal + :term:`context` matches the ``context`` argument. If the ``context`` is a + subclass of ``Exception`` and this value is ``False`` (the default) then a + view will be registered to match the traversal :term:`context` as well. + + .. versionadded:: 1.8 + ``route_name`` If ``route_name`` is supplied, the view callable will be invoked only when the named route has matched. diff --git a/docs/narr/views.rst b/docs/narr/views.rst index 770d27919..465062651 100644 --- a/docs/narr/views.rst +++ b/docs/narr/views.rst @@ -262,10 +262,16 @@ specialized views as described in :ref:`special_exceptions_in_callables` can also be used by application developers to convert arbitrary exceptions to responses. -To register a view that should be called whenever a particular exception is -raised from within :app:`Pyramid` view code, use the exception class (or one of -its superclasses) as the :term:`context` of a view configuration which points -at a view callable for which you'd like to generate a response. +To register a :term:`exception view` that should be called whenever a +particular exception is raised from within :app:`Pyramid` view code, use +:meth:`pyramid.config.Configurator.add_exception_view` to register a view +configuration which matches the exception (or a subclass of the exception) and +points at a view callable for which you'd like to generate a response. The +exception will be passed as the ``context`` argument to any +:term:`view predicate` registered with the view as well as to the view itself. +For convenience a new decorator exists, +:class:`pyramid.views.exception_view_config`, which may be used to easily +register exception views. For example, given the following exception class in a module named ``helloworld.exceptions``: @@ -277,17 +283,16 @@ For example, given the following exception class in a module named def __init__(self, msg): self.msg = msg - You can wire a view callable to be called whenever any of your *other* code raises a ``helloworld.exceptions.ValidationFailure`` exception: .. code-block:: python :linenos: - from pyramid.view import view_config + from pyramid.view import exception_view_config from helloworld.exceptions import ValidationFailure - @view_config(context=ValidationFailure) + @exception_view_config(ValidationFailure) def failed_validation(exc, request): response = Response('Failed validation: %s' % exc.msg) response.status_int = 500 @@ -308,7 +313,7 @@ view registration: from pyramid.view import view_config from helloworld.exceptions import ValidationFailure - @view_config(context=ValidationFailure, route_name='home') + @exception_view_config(ValidationFailure, route_name='home') def failed_validation(exc, request): response = Response('Failed validation: %s' % exc.msg) response.status_int = 500 @@ -327,14 +332,21 @@ which have a name will be ignored. .. note:: - Normal (i.e., non-exception) views registered against a context resource type - which inherits from :exc:`Exception` will work normally. When an exception - view configuration is processed, *two* views are registered. One as a - "normal" view, the other as an "exception" view. This means that you can use - an exception as ``context`` for a normal view. + In most cases, you should register an :term:`exception view` by using + :meth:`pyramid.config.Configurator.add_exception_view`. However, it is + possible to register 'normal' (i.e., non-exception) views against a context + resource type which inherits from :exc:`Exception` (i.e., + ``config.add_view(context=Exception)``). When the view configuration is + processed, *two* views are registered. One as a "normal" view, the other + as an :term:`exception view`. This means that you can use an exception as + ``context`` for a normal view. + + The view derivers that wrap these two views may behave differently. + See :ref:`exception_view_derivers` for more information about this. Exception views can be configured with any view registration mechanism: -``@view_config`` decorator or imperative ``add_view`` styles. +``@exception_view_config`` decorator or imperative ``add_exception_view`` +styles. .. note:: -- cgit v1.2.3 From 160aabb3798b4f613c89054ce4a60cba7374ddae Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 29 Sep 2016 00:04:01 -0700 Subject: Clean up docstrings/narr docs from PR #2660 - Closes #2768 --- docs/narr/viewconfig.rst | 10 +++++----- docs/narr/views.rst | 6 +++--- 2 files changed, 8 insertions(+), 8 deletions(-) (limited to 'docs') diff --git a/docs/narr/viewconfig.rst b/docs/narr/viewconfig.rst index 76eaf3cc5..7cb8e0306 100644 --- a/docs/narr/viewconfig.rst +++ b/docs/narr/viewconfig.rst @@ -307,8 +307,8 @@ configured view. interface; it is otherwise false. It is possible to pass an exception class as the context if your context may - subclass an exception. In this case **two** views will be registered. One - will match normal incoming requests and the other will match as an + subclass an exception. In this case *two* views will be registered. One + will match normal incoming requests, and the other will match as an :term:`exception view` which only occurs when an exception is raised during the normal request processing pipeline. @@ -317,11 +317,11 @@ configured view. ``exception_only`` - When this value is ``True`` the ``context`` argument must be a subclass of + When this value is ``True``, the ``context`` argument must be a subclass of ``Exception``. This flag indicates that only an :term:`exception view` should - be created and that this view should not match if the traversal + be created, and that this view should not match if the traversal :term:`context` matches the ``context`` argument. If the ``context`` is a - subclass of ``Exception`` and this value is ``False`` (the default) then a + subclass of ``Exception`` and this value is ``False`` (the default), then a view will be registered to match the traversal :term:`context` as well. .. versionadded:: 1.8 diff --git a/docs/narr/views.rst b/docs/narr/views.rst index 465062651..ab139ea19 100644 --- a/docs/narr/views.rst +++ b/docs/narr/views.rst @@ -262,13 +262,13 @@ specialized views as described in :ref:`special_exceptions_in_callables` can also be used by application developers to convert arbitrary exceptions to responses. -To register a :term:`exception view` that should be called whenever a +To register an :term:`exception view` that should be called whenever a particular exception is raised from within :app:`Pyramid` view code, use :meth:`pyramid.config.Configurator.add_exception_view` to register a view configuration which matches the exception (or a subclass of the exception) and points at a view callable for which you'd like to generate a response. The exception will be passed as the ``context`` argument to any -:term:`view predicate` registered with the view as well as to the view itself. +:term:`view predicate` registered with the view, as well as to the view itself. For convenience a new decorator exists, :class:`pyramid.views.exception_view_config`, which may be used to easily register exception views. @@ -334,7 +334,7 @@ which have a name will be ignored. In most cases, you should register an :term:`exception view` by using :meth:`pyramid.config.Configurator.add_exception_view`. However, it is - possible to register 'normal' (i.e., non-exception) views against a context + possible to register "normal" (i.e., non-exception) views against a context resource type which inherits from :exc:`Exception` (i.e., ``config.add_view(context=Exception)``). When the view configuration is processed, *two* views are registered. One as a "normal" view, the other -- cgit v1.2.3 From bf22edc86d0f8dc9b072b974cfd5b4604688efa6 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 6 Oct 2016 11:43:22 -0700 Subject: Add pyramid_nacl_session to session factories - closes #2791 --- docs/narr/sessions.rst | 9 +++++++++ 1 file changed, 9 insertions(+) (limited to 'docs') diff --git a/docs/narr/sessions.rst b/docs/narr/sessions.rst index a1319e45f..5b24201a9 100644 --- a/docs/narr/sessions.rst +++ b/docs/narr/sessions.rst @@ -157,6 +157,12 @@ The following session factories exist at the time of this writing. ======================= ======= ============================= Session Factory Backend Description ======================= ======= ============================= +pyramid_nacl_session_ PyNaCl_ Defines an encrypting, + pickle-based cookie + serializer, using PyNaCl to + generate the symmetric + encryption for the cookie + state. pyramid_redis_sessions_ Redis_ Server-side session library for Pyramid, using Redis for storage. @@ -165,6 +171,9 @@ pyramid_beaker_ Beaker_ Session factory for Pyramid sessioning system. ======================= ======= ============================= +.. _pyramid_nacl_session: https://pypi.python.org/pypi/pyramid_nacl_session +.. _PyNaCl: https://pynacl.readthedocs.io/en/latest/secret/ + .. _pyramid_redis_sessions: https://pypi.python.org/pypi/pyramid_redis_sessions .. _Redis: http://redis.io/ -- cgit v1.2.3