Hide navigation sidebar
Hide table of contents sidebar
Skip to content
Back to top
Toggle table of contents sidebar

# `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.