[Zope-CMF] Better DeprecationWarnings (was Re: SVN: CMF/trunk/CMFDefault/Portal.py - reverted Portal.py change of r39125 to fix BBB temporarily)

[Sidnei da Silva]

On Wed, Oct 19, 2005 at 09:18:12AM -0400, Tres Seaver wrote:
| -----BEGIN PGP SIGNED MESSAGE-----
| Hash: SHA1
| 
| Yvo Schubbe wrote:
| > Log message for revision 39508:
| >   - reverted Portal.py change of r39125 to fix BBB temporarily
| >   
| >   Note: PortalGenerator will soon be removed completely from the trunk.
| 
| 
| Sounds fine.  I'd like to add a DeprecationWarning in manage_addCMFSite,
| which is the entry point which drives PortalGenerator.  I plan to write
| it as::
| 
|  def manage_addCMFSite(self, id, title='Portal', description='',
|                        create_userfolder=1,
|                        email_from_address='postmaster at localhost',
|                        email_from_name='Portal Administrator',
|                        validate_email=0, default_charset='',
|                        RESPONSE=None):
|      """ Adds a portal instance.
|      """
|      from warnings import warn
| 
|      warn("manage_addCMFSite is a deprecated way to create a CMF site; "
|           "in the "
|           "future, please use CMFSetup's 'Configured CMF Site' (from "
|           "the ZMI "
|           "add menu) or 'CMFSetup.factory.addConfiguredSite' (from "
|           "Python).  "
|          "manage_addCMFSite will be removed in CMF 2.0.",
|          DeprecationWarning, 2)
|      ...
| 
| Note that I have just figured out that we can make DeprecationWarnings
| more useful by passing the 'stacklevel' argument to 'warnings.warn';
| passing a value of 2 for that argument causes the warning to be reported
| against the *caller* of the code issuing the warning, which makes it
| possible to find and remove the deprecated use.
| 
| On another note:  we should probably avoid all attempts to muck with the
| 'warnings.filters' data structure in tests.  Getting that wrong causes
| non-local breakage.
| 
|   - Test cases which just want to suppress warnings, should use
|     'Products.CMFCore.tests.base.testcase.WarningInterceptor' as a base
|     class, and call its '_trap_warning_output' / '_free_warning_output'
|     methods as appropriate ('_free_warning_output' should be in
|    'tearDown').
| 
|   - Test cases which actually want to check that warnings are emitted
|     should examine either their own '__warningregistry__' (for
|     stacklevel=2 warnings) or the '__warningregistry__' of the
|     module-under-test, rather than trying to test the output stream.

As a side note, Zope 3 has a excellent way of dealing with warnings
and specially deprecation warnings that should IMHO be used in CMF.

There was also a 'WarningsHook' that has been backported to
ZopeTestCase about one year ago (!) by me.

http://svn.plone.org/svn/collective/ZopeTestCase/trunk/zopedoctest/WarningsTest.txt

-- 
Sidnei da Silva
Enfold Systems, LLC.
http://enfoldsystems.com