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

[Tres Seaver]

-----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.


Tres.
- --
===================================================================
Tres Seaver          +1 202-558-7113          tseaver at palladion.com
Palladion Software   "Excellence by Design"    http://palladion.com
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.1 (GNU/Linux)
Comment: Using GnuPG with Thunderbird - http://enigmail.mozdev.org

iD8DBQFDVkeT+gerLs4ltQ4RAnoDAJ9wFMH6huX+KJblNTVEWRWEGWwxXACbBMOZ
hustAs1BdEXE927fGclWmWE=
=KlRX
-----END PGP SIGNATURE-----