From: Mike Bayer Date: Sat, 23 Oct 2010 21:09:53 +0000 (-0400) Subject: - make a futile attempt to combat the needless usage of clear_mappers() in the wild, X-Git-Tag: rel_0_6_5~4 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=6f4f497f00d55008e4ee612f43b91c3767e0eebe;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git - make a futile attempt to combat the needless usage of clear_mappers() in the wild, [ticket:1861] --- diff --git a/lib/sqlalchemy/orm/__init__.py b/lib/sqlalchemy/orm/__init__.py index d4e436b3b1..18031e15ff 100644 --- a/lib/sqlalchemy/orm/__init__.py +++ b/lib/sqlalchemy/orm/__init__.py @@ -963,11 +963,24 @@ def compile_mappers(): m.compile() def clear_mappers(): - """Remove all mappers that have been created thus far. - - The mapped classes will return to their initial "unmapped" state and can - be re-mapped with new mappers. - + """Remove all mappers from all classes. + + This function removes all instrumentation from classes and disposes + of their associated mappers. Once called, the classes are unmapped + and can be later re-mapped with new mappers. + + :func:`.clear_mappers` is *not* for normal use, as there is literally no + valid usage for it outside of very specific testing scenarios. Normally, + mappers are permanent structural components of user-defined classes, and + are never discarded independently of their class. If a mapped class itself + is garbage collected, its mapper is automatically disposed of as well. As + such, :func:`.clear_mappers` is only for usage in test suites that re-use + the same classes with different mappings, which is itself an extremely rare + use case - the only such use case is in fact SQLAlchemy's own test suite, + and possibly the test suites of other ORM extension libraries which + intend to test various combinations of mapper construction upon a fixed + set of classes. + """ mapperlib._COMPILE_MUTEX.acquire() try: