4. API reference¶
This section describes the API of Yagot.
There are two main elements of the API:
yagot.garbage_checked()
: A decorator that checks for uncollectable objects and optionally for collected objects caused by the decorated function or method and raises AssertionError if detected.yagot.GarbageTracker
: A class that checks for uncollectable objects and optionally for collected objects caused during a tracking period. This is a plumbing class theyagot.garbage_checked()
decorator and the pytest plugin of Yagot use, and that other packages building on Yagot can also use.
4.1. yagot.garbage_checked¶
-
yagot.
garbage_checked
(leaks_only=False, ignore_types=None)[source]¶ Decorator that checks for uncollectable objects and optionally for collected objects caused by the decorated function or method, and raises AssertionError if such objects are detected.
The decorated function or method needs to make sure that any objects it creates are deleted again, either implicitly (e.g. by a local variable going out of scope upon return) or explicitly. Ideally, no garbage is created that way, but whether that is actually the case is exactly what the decorator tests for. Also, it is possible that your code is clean but other modules your code uses are not clean, and that will surface this way.
Note that this decorator has arguments, so it must be specified with parenthesis, even when relying on the default argument values:
@yagot.garbage_checked() test_something(): # do some tests
Parameters: - leaks_only (bool) – Boolean to limit the checks to only uncollectable objects. By default, collected objects and uncollectable objects are checked for.
- ignore_types (iterable) –
None or iterable of Python types or type names that are set as additional garbage types to ignore, in addition to
frame
andcode
that are always ignored.If any detected object has one of the types to be ignored, the entire set of objects caused by the decorated function or method is ignored.
Each type can be specified as a type object or as a string with the type name as represented by the
str(type)
function (for example, “int” or “mymodule.MyClass”).None or an empty iterable means not to ignore any types.
4.2. yagot.GarbageTracker¶
-
class
yagot.
GarbageTracker
[source]¶ The GarbageTracker class provides a singleton garbage tracker that can track uncollectable objects and optionally collected objects that emerged during a tracking period.
Methods
assert_message
Return a formatted multi-line string for the assertion message for the collected objects or uncollectable objects detected during the tracking period. disable
Disable the garbage tracker. enable
Enable the garbage tracker and control what objects it checks for. format_obj
Return a formatted string for a single object. get_tracker
Returns the singleton garbage tracker object. ignore
Ignore the current tracking period for this garbage tracker, if it is enabled. ignore_types
Set additional Python types to be ignored as collected objects or uncollectable objects. start
Start the tracking period for this garbage tracker. stop
Stop the tracking period for this garbage tracker. Attributes
enabled
Boolean indicating the enablement status of the garbage tracker. garbage
List of new collected objects or uncollectable objects that emerged during the last tracking period. ignored
Boolean indicating whether the current tracking period should be ignored. ignored_type_names
Return the Python type names to be ignored as collected objects or uncollectable objects. leaks_only
Boolean indicating whether the tracker limits the checks to uncollectable objects (= leaks) only. Details
-
static
get_tracker
()[source]¶ Returns the singleton garbage tracker object.
The object is created when accessed through this method for the first time.
-
ignored
¶ Boolean indicating whether the current tracking period should be ignored.
This flag is set via
ignore()
.Type: bool
-
leaks_only
¶ Boolean indicating whether the tracker limits the checks to uncollectable objects (= leaks) only.
This flag can be set via
enable()
.Type: bool
-
garbage
¶ List of new collected objects or uncollectable objects that emerged during the last tracking period.
Type: list
-
ignored_type_names
¶ Return the Python type names to be ignored as collected objects or uncollectable objects.
The types
frame
andcode
that are always ignored are included in the returned list.Returns: - List of Python type names to be ignored as represented by
- the
str(type)
function (for example “int” or “mymodule.MyClass”).
Return type: list
-
enable
(leaks_only=False)[source]¶ Enable the garbage tracker and control what objects it checks for.
Parameters: leaks_only (bool) – Boolean limiting the checks to uncollectable objects (=leaks) only.
-
ignore
()[source]¶ Ignore the current tracking period for this garbage tracker, if it is enabled. This causes
ignored
to be set.
-
ignore_types
(type_list)[source]¶ Set additional Python types to be ignored as collected objects or uncollectable objects.
The specified types are in addition to the following list of types that are aways ignored because they often appear as collectable objects when catching exceptions (e.g. when using
pytest.raises()
):frame
code
If the list of collected or uncollectable objects detected during the tracking period contains an object with a type that is to be ignored, the entire tracking period is ignored.
Parameters: type_list (iterable) – Iterable of Python types, or None.
Each type can be specified as a type object or as a string with the type name as represented by the
str(type)
function (for example, “int” or “mymodule.MyClass”).None or an empty iterable means not to set additional types.
-
start
()[source]¶ Start the tracking period for this garbage tracker.
Must be called before the code to be tracked is run.
-
stop
()[source]¶ Stop the tracking period for this garbage tracker.
Must be called after the code to be tracked is run.
-
assert_message
(location=None, max=10)[source]¶ Return a formatted multi-line string for the assertion message for the collected objects or uncollectable objects detected during the tracking period.
Parameters: Returns: Formatted multi-line string.
Return type:
-
static
format_obj
(obj)[source]¶ Return a formatted string for a single object.
Parameters: obj (object) – The object. Returns: Formatted string for the object. Return type: unicode string
-
static
4.3. yagot.__version__¶
The version of the yagot package can be accessed by
programs using the yagot.__version__
variable:
-
yagot._version.
__version__
= '0.6.0.dev1'¶ The full version of this package including any development levels, as a string.
Possible formats for this version string are:
- “M.N.P.dev1”: Development level 1 of a not yet released version M.N.P
- “M.N.P”: A released version M.N.P
Note: For tooling reasons, the variable is shown as
yagot._version.__version__
, but it should be used as
yagot.__version__
.