Misc. doc additions: callback exception handling, and an assortment of

tips and techniques for using easy_install.

--HG--
branch : setuptools
extra : convert_revision : svn%3A6015fed2-1504-0410-9fe1-9d1591cc4771/sandbox/trunk/setuptools%4042336

1 files changed, 7 insertions, 0 deletions

diff --git a/pkg_resources.txt b/pkg_resources.txt
index 6fd1af82..ada2de3f 100755
--- a/pkg_resources.txt
+++ b/pkg_resources.txt
@@ -349,6 +349,13 @@ function are for.
     yourself to deal with the existing items; just register the callback and
     be prepared for the fact that it will be called immediately by this method.
 
+    Note that callbacks *must not* allow exceptions to propagate, or they will
+    interfere with the operation of other callbacks and possibly result in an
+    inconsistent working set state.  Callbacks should use a try/except block
+    to ignore, log, or otherwise process any errors, especially since the code
+    that caused the callback to be invoked is unlikely to be able to handle
+    the errors any better than the callback itself.
+
 ``pkg_resources.add_activation_listener()`` is an alternate spelling of
 ``pkg_resources.working_set.subscribe()``.