gevent.util – Low-level utilities

Low-level utilities.

class GreenletTree(greenlet)

Bases: object

Represents a tree of greenlets.

In gevent, the parent of a greenlet is usually the hub, so this tree is primarily arganized along the spawning_greenlet dimension.

This object has a small str form showing this hierarchy. The format method can output more details. The exact output is unspecified but is intended to be human readable.

Use the forest method to get the root greenlet trees for all threads, and the current_tree to get the root greenlet tree for the current thread.

classmethod current_tree() → GreenletTree

Returns the GreenletTree for the current thread.

classmethod forest() → sequence

Return a sequence of GreenletTree, one for each running native thread.

format(details=True)

Like format_lines but returns a string.

format_lines(details=True)

Return a sequence of lines for the greenlet tree.

Parameters:

details (bool) – If true (the default), then include more informative details in the output.

greenlet = None

The greenlet this tree represents.

is_current_tree = False

Is this tree the root for the current thread?

class assert_switches(max_blocking_time=None, hub_only=False)

Bases: object

A context manager for ensuring a block of code switches greenlets.

This performs a similar function as the monitoring thread, but the scope is limited to the body of the with statement. If the code within the body doesn’t yield to the hub (and doesn’t raise an exception), then upon exiting the context manager an AssertionError will be raised.

This is useful in unit tests and for debugging purposes.

Parameters:

• max_blocking_time (float) – If given, the body is allowed to block for up to this many fractional seconds before an error is raised.

• hub_only (bool) – If True, then max_blocking_time only refers to the amount of time spent between switches into the hub. If False, then it refers to the maximum time between any switches. If max_blocking_time is not given, has no effect.

Example:

# This will always raise an exception: nothing switched
with assert_switches():
    pass

# This will never raise an exception; nothing switched,
# but it happened very fast
with assert_switches(max_blocking_time=1.0):
    pass

Added in version 1.3.

Changed in version 1.4: If an exception is raised, it now includes information about the duration of blocking and the parameters of this object.

class wrap_errors(errors, func)

Bases: object

Helper to make function return an exception, rather than raise it.

Because every exception that is unhandled by greenlet will be logged, it is desirable to prevent non-error exceptions from leaving a greenlet. This can done with a simple try/except construct:

def wrapped_func(*args, **kwargs):
    try:
        return func(*args, **kwargs)
    except (TypeError, ValueError, AttributeError) as ex:
        return ex

This class provides a shortcut to write that in one line:

wrapped_func = wrap_errors((TypeError, ValueError, AttributeError), func)

It also preserves __str__ and __repr__ of the original function.

Calling this makes a new function from func, such that it catches errors (an BaseException subclass, or a tuple of BaseException subclasses) and return it as a value.

format_run_info(thread_stacks=True, greenlet_stacks=True, limit=None) → [str]

Request information about the running threads of the current process.

This is a debugging utility. Its output has no guarantees other than being intended for human consumption.

Parameters:

• thread_stacks (bool) – If true, then include the stacks for running threads.

• greenlet_stacks (bool) – If true, then include the stacks for running greenlets. (Spawning stacks will always be printed.) Setting this to False can reduce the output volume considerably without reducing the overall information if thread_stacks is true and you can associate a greenlet to a thread (using thread_ident printed values).

• limit (int) – If given, passed directly to traceback.format_stack. If not given, this defaults to the whole stack under CPython, and a smaller stack under PyPy.

Returns:

A sequence of text lines detailing the stacks of running threads and greenlets. (One greenlet will duplicate one thread, the current thread and greenlet. If there are multiple running threads, the stack for the current greenlet may be incorrectly duplicated in multiple greenlets.) Extra information about gevent.Greenlet object will also be returned.

Added in version 1.3a1.

Changed in version 1.3a2: Renamed from dump_stacks to reflect the fact that this prints additional information about greenlets, including their spawning stack, parent, locals, and any spawn tree locals.

Changed in version 1.3b1: Added the thread_stacks, greenlet_stacks, and limit params.

print_run_info(thread_stacks=True, greenlet_stacks=True, limit=<default value>, file=None)

Call format_run_info and print the results to file.

If file is not given, sys.stderr will be used.

Added in version 1.3b1.