disallow adding a tween factory which is an instance without passing its globally importable name

2 files changed, 15 insertions, 16 deletions

diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst
index b1a646aec..97004d2b8 100644
--- a/docs/narr/commandline.rst
+++ b/docs/narr/commandline.rst
@@ -311,11 +311,9 @@ application request handler and the WSGI application which calls it.  A user
 can get a representation of both the implicit tween ordering (the ordering
 specified by calls to :meth:`pyramid.config.Configurator.add_tween`) and the
 explicit tween ordering (specified by the ``pyramid.tweens`` configuration
-setting) orderings using the ``paster ptweens`` command.  Handler factories
-which are functions or classes will show up as a standard Python dotted name
-in the ``paster ptweens`` output.  Tween factories which are *instances* will
-show their module and class name; the Python object id of the instance will
-be appended.
+setting) orderings using the ``paster ptweens`` command.  Tween factories
+will show up represented by their standard Python dotted name in the
+``paster ptweens`` output.
 
 For example, here's the ``paster pwteens`` command run against a system
 configured without any explicit tweens:
diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst
index c8efc057c..97bee479b 100644
--- a/docs/narr/hooks.rst
+++ b/docs/narr/hooks.rst
@@ -847,12 +847,12 @@ running in a context in which they have access to the Pyramid
 :term:`application registry` as well as the Pyramid rendering machinery.
 
 To make use of tweens, you must construct a "tween factory".  A tween factory
-must be a callable (or a :term:`dotted Python name` to such a callable) which
-accepts two arguments: ``handler`` and ``registry``.  ``handler`` will be the
-either the main Pyramid request handling function or another tween (if more
-than one tween is configured into the request handling chain).  ``registry``
-will be the Pyramid :term:`application registry` represented by this
-Configurator.  A tween factory must return a tween when it is called.
+must be a globally importable callable (or a :term:`dotted Python name` to
+such a callable) which accepts two arguments: ``handler`` and ``registry``.
+``handler`` will be the either the main Pyramid request handling function or
+another tween.  ``registry`` will be the Pyramid :term:`application registry`
+represented by this Configurator.  A tween factory must return a tween when
+it is called.
 
 A tween is a callable which accepts a :term:`request` object and returns a
 two-tuple a :term:`response` object.
@@ -1089,11 +1089,12 @@ Tween Conflicts and Ordering Cycles
 Pyramid will prevent the same tween factory from being added to the tween
 chain more than once using configuration conflict detection.  If you wish to
 add the same tween factory more than once in a configuration, you should
-either: a) use a tween factory that is an instance rather than a function or
-class, b) use a function or class as a tween factory with the same logic as
-the other tween factory it conflicts with but with a different ``__name__``
-attribute or c) call :meth:`pyramid.config.Configurator.commit` between calls
-to :meth:`pyramid.config.Configurator.add_tween`.
+either: a) use a tween factory that is a separate globally importable
+instance object from the factory that it conflicts with b) use a function or
+class as a tween factory with the same logic as the other tween factory it
+conflicts with but with a different ``__name__`` attribute or c) call
+:meth:`pyramid.config.Configurator.commit` between calls to
+:meth:`pyramid.config.Configurator.add_tween`.
 
 If a cycle is detected in implicit tween ordering when ``over`` and ``under``
 are used in any call to "add_tween", an exception will be raised at startup