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 the yagot.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)

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 and code 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

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()

Returns the singleton garbage tracker object.

The object is created when accessed through this method for the first time.

enabled

Boolean indicating the enablement status of the garbage tracker.

Type:bool

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 and code 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)

Enable the garbage tracker and control what objects it checks for.

Parameters:leaks_only (bool) – Boolean limiting the checks to uncollectable objects (=leaks) only.

disable()

Disable the garbage tracker.

ignore()

Ignore the current tracking period for this garbage tracker, if it is enabled. This causes ignored to be set.

ignore_types(type_list)

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()

Start the tracking period for this garbage tracker.

Must be called before the code to be tracked is run.

stop()

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)

Return a formatted multi-line string for the assertion message for the collected objects or uncollectable objects detected during the tracking period.

Parameters:

• location (string) – Location of the function that created the objects, e.g. in the notation “module::function”.
• max (int) – Maximum number of objects to be included in the returned string.

Returns:

Formatted multi-line string.

Return type:

unicode string

static format_obj(obj)

Return a formatted string for a single object.

Parameters:obj (object) – The object. Returns:Formatted string for the object. Return type:unicode string

4.3. yagot.__version__

The version of the yagot package can be accessed by programs using the yagot.__version__ variable:

yagot._version.__version__ = '0.5.0'

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