From ffffac27f9a1f493df94b9b8d4fb3d77cd047664 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jurko=20Gospodneti=C4=87?= Date: Thu, 23 Jan 2014 09:46:36 +0100 Subject: [PATCH 1/2] document explicitly clearing local references to pytest.raises() results pytest.raises() returns an ExceptionInfo object which, if a local reference is made to it, forms a reference cycle: ExceptionInfo --> exception --> stack frame raising the exception --> current stack frame --> current local variables --> Exception Info Such a reference cycle would then prevent any local variables in the current stack frame, or any of its child stack frames involved in the same reference cycle, from being garbage collected until the next reference cycle garbage collection phase. This unnecessarily increases the program's memory footprint and potentially slows it down. This situation is based on a similar one described in the official 'try' statement Python documentation for locally stored exception references. --HG-- branch : document_ExceptionInfo_ref_cycle --- _pytest/python.py | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/_pytest/python.py b/_pytest/python.py index 4ef5e9849..5c063b041 100644 --- a/_pytest/python.py +++ b/_pytest/python.py @@ -938,6 +938,12 @@ def raises(ExpectedException, *args, **kwargs): This helper produces a ``py.code.ExceptionInfo()`` object. + Note that any local references made to such returned + ``py.code.ExceptionInfo()`` objects should be explicitly cleared, as they + are part of a reference cycle similar to local references to caught Python + exception objects. See the official Python ``try`` statement documentation + for more detailed information. + If using Python 2.5 or above, you may use this function as a context manager:: From 75c124ea170d21160714f5c0264d8b4d1b594e8e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jurko=20Gospodneti=C4=87?= Date: Thu, 23 Jan 2014 11:36:04 +0100 Subject: [PATCH 2/2] reword note on explicitly clearing local references to pytest.raises() results Made it clearer that clearing such references is not mandatory and is only an optional step which may help the Python interpreter speed up its garbage collection. --HG-- branch : document_ExceptionInfo_ref_cycle --- _pytest/python.py | 22 ++++++++++++++++------ 1 file changed, 16 insertions(+), 6 deletions(-) diff --git a/_pytest/python.py b/_pytest/python.py index 5c063b041..91369fedb 100644 --- a/_pytest/python.py +++ b/_pytest/python.py @@ -938,12 +938,6 @@ def raises(ExpectedException, *args, **kwargs): This helper produces a ``py.code.ExceptionInfo()`` object. - Note that any local references made to such returned - ``py.code.ExceptionInfo()`` objects should be explicitly cleared, as they - are part of a reference cycle similar to local references to caught Python - exception objects. See the official Python ``try`` statement documentation - for more detailed information. - If using Python 2.5 or above, you may use this function as a context manager:: @@ -968,6 +962,22 @@ def raises(ExpectedException, *args, **kwargs): >>> raises(ZeroDivisionError, "f(0)") + + Performance note: + ----------------- + + Similar to caught exception objects in Python, explicitly clearing local + references to returned ``py.code.ExceptionInfo`` objects can help the Python + interpreter speed up its garbage collection. + + Clearing those references breaks a reference cycle (``ExceptionInfo`` --> + caught exception --> frame stack raising the exception --> current frame + stack --> local variables --> ``ExceptionInfo``) which makes Python keep all + objects referenced from that cycle (including all local variables in the + current frame) alive until the next cyclic garbage collection run. See the + official Python ``try`` statement documentation for more detailed + information. + """ __tracebackhide__ = True if ExpectedException is AssertionError: