oops, re-clarify that tweens should not have mutable state

1 files changed, 4 insertions, 5 deletions

diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst
index fe7749cac..4da36e730 100644
--- a/docs/narr/hooks.rst
+++ b/docs/narr/hooks.rst
@@ -995,11 +995,6 @@ A tween is called with a single argument, ``request``, which is the
 A tween should return a :term:`response`, usually the one generated by the
 downstream Pyramid application.
 
-The tween factory will be shared between requests and is used to create one
-tween per-request. Shared mutable state on the factory itself needs to be
-carefully handled, and should be avoided unless you are willing to handle
-the race conditions that may arise.
-
 You can write the tween factory as a simple closure-returning function:
 
 .. code-block:: python
@@ -1045,6 +1040,10 @@ method:
 
             return response
 
+You should avoid mutating any state on the tween instance. The tween is
+invoked once per request and any shared mutable state needs to be carefully
+handled to avoid any race conditions.
+
 The closure style performs slightly better and enables you to conditionally
 omit the tween from the request processing pipeline (see the following timing
 tween example), whereas the class style makes it easier to have shared mutable