A sane scheme for raising deprecation warnings.

branches/tim-simpler_connection/NEWS.txt

@@ -5,11 +5,30 @@ Release date: DD-MMM-2004
 DB
 --
 
-- The following optional arguments to ``DB.open()`` are deprecated:
+- There is no longer a hard limit on the number of connections that
+  ``DB.open()`` will create.  In other words, ``DB.open()`` never blocks
+  anymore waiting for an earlier connection to close, and ``DB.open()``
+  always returns a connection now (while it wasn't documented, it was
+  possible for ``DB.open()`` to return ``None`` before).
+
+  ``pool_size`` continues to default to 7, but its meaning has changed:
+  if more than ``pool_size`` connections are obtained from ``DB.open()``
+  and not closed, a warning is logged; if more than twice ``pool_size``, a
+  critical problem is logged.  ``pool_size`` should be set to the maximum
+  number of connections from the ``DB`` instance you expect to have open
+  simultaneously.
+
+  In addition, if a connection obtained from ``DB.open()`` becomes
+  unreachable without having been explicitly closed, when Python's garbage
+  collection reclaims that connection it no longer counts against the
+  ``pool_size`` thresholds for logging messages.
+
+  The following optional arguments to ``DB.open()`` are deprecated:
   ``transaction``, ``waitflag``, ``force`` and ``temporary``.  If one
   is specified, its value is ignored, and ``DeprecationWarning`` is
-  raised.  In a future release, these optional arguments will be
-  removed.
+  raised.  In ZODB 3.6, these optional arguments will be removed.
+
+
 
 Tools
 -----

branches/tim-simpler_connection/src/ZODB/Connection.py

@@ -36,6 +36,8 @@ from ZODB.TmpStore import TmpStore
 from ZODB.utils import oid_repr, z64, positive_id
 from ZODB.serialize import ObjectWriter, ConnectionObjectReader, myhasattr
 from ZODB.interfaces import IConnection
+from ZODB.utils import DEPRECATED_ARGUMENT, deprecated36
+
 from zope.interface import implements
 
 global_reset_counter = 0
@@ -264,9 +266,8 @@ class Connection(ExportImport, object):
         method.  You can pass a transaction manager (TM) to DB.open()
         to control which TM the Connection uses.
         """
-        warnings.warn("getTransaction() is deprecated. "
-                      "Use the txn_mgr argument to DB.open() instead.",
-                      DeprecationWarning)
+        deprecated36("getTransaction() is deprecated. "
+                     "Use the txn_mgr argument to DB.open() instead.")
         return self._txn_mgr.get()
 
     def setLocalTransaction(self):
@@ -278,9 +279,8 @@ class Connection(ExportImport, object):
         can pass a transaction manager (TM) to DB.open() to control
         which TM the Connection uses.
         """
-        warnings.warn("setLocalTransaction() is deprecated. "
-                      "Use the txn_mgr argument to DB.open() instead.",
-                      DeprecationWarning)
+        deprecated36("setLocalTransaction() is deprecated. "
+                     "Use the txn_mgr argument to DB.open() instead.")
         if self._txn_mgr is transaction.manager:
             if self._synch:
                 self._txn_mgr.unregisterSynch(self)
@@ -488,14 +488,14 @@ class Connection(ExportImport, object):
 
     def cacheFullSweep(self, dt=None):
         # XXX needs doc string
-        warnings.warn("cacheFullSweep is deprecated. "
-                      "Use cacheMinimize instead.", DeprecationWarning)
+        deprecated36("cacheFullSweep is deprecated. "
+                     "Use cacheMinimize instead.")
         if dt is None:
             self._cache.full_sweep()
         else:
             self._cache.full_sweep(dt)
 
-    def cacheMinimize(self, dt=None):
+    def cacheMinimize(self, dt=DEPRECATED_ARGUMENT):
         """Deactivate all unmodified objects in the cache.
 
         Call _p_deactivate() on each cached object, attempting to turn
@@ -505,9 +505,8 @@ class Connection(ExportImport, object):
         :Parameters:
           - `dt`: ignored.  It is provided only for backwards compatibility.
         """
-        if dt is not None:
-            warnings.warn("The dt argument to cacheMinimize is ignored.",
-                          DeprecationWarning)
+        if dt is not DEPRECATED_ARGUMENT:
+            deprecated36("cacheMinimize() dt= is ignored.")
         self._cache.minimize()
 
     def cacheGC(self):
@@ -783,8 +782,8 @@ class Connection(ExportImport, object):
             # an oid is being registered.  I can't think of any way to
             # achieve that without assignment to _p_jar.  If there is
             # a way, this will be a very confusing warning.
-            warnings.warn("Assigning to _p_jar is deprecated",
-                          DeprecationWarning)
+            deprecated36("Assigning to _p_jar is deprecated, and will be "
+                         "changed to raise an exception.")
         elif obj._p_oid in self._added:
             # It was registered before it was added to _added.
             return

branches/tim-simpler_connection/src/ZODB/DB.py

@@ -25,15 +25,12 @@ from ZODB.broken import find_global
 from ZODB.Connection import Connection
 from ZODB.serialize import referencesf
 from ZODB.utils import WeakSet
+from ZODB.utils import DEPRECATED_ARGUMENT, deprecated36
 
 import transaction
 
 logger = logging.getLogger('ZODB.DB')
 
-# A unique marker for detecting use of deprecated arguments.
-_deprecated = object()
-
-
 class _ConnectionPool(object):
     """Manage a pool of connections.
 
@@ -189,10 +186,10 @@ class DB(object):
     def __init__(self, storage,
                  pool_size=7,
                  cache_size=400,
-                 cache_deactivate_after=None,
+                 cache_deactivate_after=DEPRECATED_ARGUMENT,
                  version_pool_size=3,
                  version_cache_size=100,
-                 version_cache_deactivate_after=None,
+                 version_cache_deactivate_after=DEPRECATED_ARGUMENT,
                  ):
         """Create an object database.
 
@@ -221,10 +218,10 @@ class DB(object):
         self._version_cache_size = version_cache_size
 
         # warn about use of deprecated arguments
-        if (cache_deactivate_after is not None or
-            version_cache_deactivate_after is not None):
-            warnings.warn("cache_deactivate_after has no effect",
-                          DeprecationWarning)
+        if cache_deactivate_after is not DEPRECATED_ARGUMENT:
+            deprecated36("cache_deactivate_after has no effect")
+        if version_cache_deactivate_after is not DEPRECATED_ARGUMENT:
+            deprecated36("version_cache_deactivate_after has no effect")
 
         self._miv_cache = {}
 
@@ -483,8 +480,8 @@ class DB(object):
         return len(self._storage)
 
     def open(self, version='',
-             transaction=_deprecated, temporary=_deprecated,
-             force=_deprecated, waitflag=_deprecated,
+             transaction=DEPRECATED_ARGUMENT, temporary=DEPRECATED_ARGUMENT,
+             force=DEPRECATED_ARGUMENT, waitflag=DEPRECATED_ARGUMENT,
              mvcc=True, txn_mgr=None, synch=True):
         """Return a database Connection for use by application code.
 
@@ -505,21 +502,20 @@ class DB(object):
              register for afterCompletion() calls.
         """
 
-        if temporary is not _deprecated:
-            warnings.warn("DB.open() temporary= has no effect",
-                          DeprecationWarning)
+        if temporary is not DEPRECATED_ARGUMENT:
+            deprecated36("DB.open() temporary= ignored. "
+                         "open() no longer blocks.")
 
-        if force is not _deprecated:
-            warnings.warn("DB.open() force= has no effect",
-                          DeprecationWarning)
+        if force is not DEPRECATED_ARGUMENT:
+            deprecated36("DB.open() force= ignored. "
+                         "open() no longer blocks.")
 
-        if waitflag is not _deprecated:
-            warnings.warn("DB.open() waitflag= has no effect",
-                          DeprecationWarning)
+        if waitflag is not DEPRECATED_ARGUMENT:
+            deprecated36("DB.open() waitflag= ignored. "
+                         "open() no longer blocks.")
 
-        if transaction is not _deprecated:
-            warnings.warn("DB.open() transaction= has no effect",
-                          DeprecationWarning)
+        if transaction is not DEPRECATED_ARGUMENT:
+            deprecated36("DB.open() transaction= ignored.")
 
         self._a()
         try:
@@ -686,23 +682,19 @@ class DB(object):
 
     def getCacheDeactivateAfter(self):
         """Deprecated"""
-        warnings.warn("cache_deactivate_after has no effect",
-                      DeprecationWarning)
+        deprecated36("getCacheDeactivateAfter has no effect")
 
     def getVersionCacheDeactivateAfter(self):
         """Deprecated"""
-        warnings.warn("cache_deactivate_after has no effect",
-                      DeprecationWarning)
+        deprecated36("getVersionCacheDeactivateAfter has no effect")
 
     def setCacheDeactivateAfter(self, v):
         """Deprecated"""
-        warnings.warn("cache_deactivate_after has no effect",
-                      DeprecationWarning)
+        deprecated36("setCacheDeactivateAfter has no effect")
 
     def setVersionCacheDeactivateAfter(self, v):
         """Deprecated"""
-        warnings.warn("cache_deactivate_after has no effect",
-                      DeprecationWarning)
+        deprecated36("setVersionCacheDeactivateAfter has no effect")
 
 class ResourceManager(object):
     """Transaction participation for a version or undo resource."""

branches/tim-simpler_connection/src/ZODB/tests/testConnection.py

@@ -414,8 +414,9 @@ class UserMethodTests(unittest.TestCase):
         >>> len(hook.warnings)
         1
         >>> message, category, filename, lineno = hook.warnings[0]
-        >>> message
-        'The dt argument to cacheMinimize is ignored.'
+        >>> print message
+        This will be removed in ZODB 3.6:
+        cacheMinimize() dt= is ignored.
         >>> category.__name__
         'DeprecationWarning'
         >>> hook.clear()
@@ -434,8 +435,9 @@ class UserMethodTests(unittest.TestCase):
         >>> len(hook.warnings)
         2
         >>> message, category, filename, lineno = hook.warnings[0]
-        >>> message
-        'cacheFullSweep is deprecated. Use cacheMinimize instead.'
+        >>> print message
+        This will be removed in ZODB 3.6:
+        cacheFullSweep is deprecated. Use cacheMinimize instead.
         >>> category.__name__
         'DeprecationWarning'
         >>> message, category, filename, lineno = hook.warnings[1]

branches/tim-simpler_connection/src/ZODB/tests/testZODB.py

@@ -243,9 +243,13 @@ class ZODBTests(unittest.TestCase):
             self.assertEqual(r1['item'], 2)
             self.assertEqual(r2['item'], 2)
             for msg, obj, filename, lineno in hook.warnings:
-                self.assert_(
-                    msg.startswith("setLocalTransaction() is deprecated.") or
-                    msg.startswith("getTransaction() is deprecated."))
+                self.assert_(msg in [
+                    "This will be removed in ZODB 3.6:\n"
+                        "setLocalTransaction() is deprecated. "
+                        "Use the txn_mgr argument to DB.open() instead.",
+                    "This will be removed in ZODB 3.6:\n"
+                        "getTransaction() is deprecated. "
+                        "Use the txn_mgr argument to DB.open() instead."])
         finally:
             conn1.close()
             conn2.close()

branches/tim-simpler_connection/src/ZODB/utils.py

@@ -19,6 +19,7 @@ from binascii import hexlify
 import cPickle
 import cStringIO
 import weakref
+import warnings
 
 from persistent.TimeStamp import TimeStamp
 
@@ -36,8 +37,26 @@ __all__ = ['z64',
            'get_refs',
            'readable_tid_repr',
            'WeakSet',
+           'DEPRECATED_ARGUMENT',
+           'deprecated36',
           ]
 
+# A unique marker to give as the default value for a deprecated argument.
+# The method should then do a
+#
+#     if that_arg is not DEPRECATED_ARGUMENT:
+#         complain
+#
+# dance.
+DEPRECATED_ARGUMENT = object()
+
+# Raise DeprecationWarning, noting that the deprecated thing will go
+# away in ZODB 3.6.  Point to the caller of our caller (i.e., at the
+# code using the deprecated thing).
+def deprecated36(msg):
+    warnings.warn("This will be removed in ZODB 3.6:\n%s" % msg,
+                  DeprecationWarning, stacklevel=3)
+
 z64 = '\0'*8
 
 # TODO The purpose of t32 is unclear.  Code that uses it is usually

branches/tim-simpler_connection/src/transaction/_transaction.py

@@ -261,9 +261,10 @@ class Transaction(object):
                 self._resources.append(adapter)
 
     def begin(self):
-        warnings.warn("Transaction.begin() should no longer be used; use "
-                      "the begin() method of a transaction manager.",
-                      DeprecationWarning, stacklevel=2)
+        from ZODB.utils import deprecated36
+
+        deprecated36("Transaction.begin() should no longer be used; use "
+                      "the begin() method of a transaction manager.")
         if (self._resources or
               self._sub or
               self._nonsub or