Collector #685: Improved documentation explaining how, where and

       why security assertions should be placed

doc/CHANGES.txt

@@ -24,6 +24,11 @@ Zope Changes
 
     Bugs Fixed
 
+     - Collector #685: Improved documentation explaining how, where and 
+       why security assertions should be placed in:
+       lib/python/Products/PythonScripts/README.txt
+       lib/python/Products/PythonScripts/module_access_examples.py
+
      - The ZEO unit tests and wo_pcgi.py didn't run on Windows if the path 
        to the python executable included a space.
 

lib/python/Products/PythonScripts/README.txt

@@ -56,4 +56,20 @@ Python Scripts
       o Restart your Zope server. After restarting, the modules you enabled
         in your custom product will be available to Python scripts.
 
+    NB --  Placing security assestions within the package/module you are trying 
+           to import will not work unless that package/module is located in
+           your Products directory.
+ 
+           This is because that package/module would have to be imported for its
+           included security assertions to take effect, but to do
+	   that would require importing a module without any security
+           declarations, which defeats the point of the restricted
+           python environment.
+
+           Products work differently as they are imported at Zope startup.
+           By placing a package/module in your Products directory, you are
+           asserting, among other things, that it is safe for Zope to check 
+           that package/module for security assertions. As a result, please 
+           be careful when place packages or modules that are not Zope Products 
+	   in the Products directory.
         

lib/python/Products/PythonScripts/module_access_examples.py

@@ -13,6 +13,23 @@ make available for import by Scripts.
 You can, of course, add your own code to your "__init__.py" for
 modules that are not listed below.  The list is not comprehensive,
 but is provided as a decent cross-section of modules.
+
+NB:  Placing security assestions within the package/module you are trying 
+     to import will not work unless that package/module is located in
+     your Products directory.
+ 
+     This is because that package/module would have to be imported for its
+     included security assertions to take effect, but to do
+     that would require importing a module without any security
+     declarations, which defeats the point of the restricted
+     python environment.
+
+     Products work differently as they are imported at Zope startup.
+     By placing a package/module in your Products directory, you are
+     asserting, among other things, that it is safe for Zope to check 
+     that package/module for security assertions. As a result, please 
+     be careful when place packages or modules that are not Zope Products 
+     in the Products directory.
 '''
 
 from AccessControl import allow_module, allow_class, allow_type