Skip to content
Back to top
View this page

# Python API Reference

## Exceptions

exception greenlet.GreenletExit

  Bases: `BaseException`

exception greenlet.error

  Bases: `Exception`

## Greenlets

greenlet.getcurrent() → greenlet

  Returns the current greenlet (i.e. the one which called this function).

class greenlet.greenlet(run=None, parent=None) → greenlet

  Bases: `object`

  Creates a new greenlet object (without running it).

  > - run – The callable to invoke.

  > - parent – The parent greenlet. The default is the current greenlet.

  Greenlets support boolean tests: `bool(g)` is true if `g` is active and false if it is dead or not yet started.

  switch(*args, **kwargs)

    Switches execution to this greenlet. See Switching Between Greenlets: Passing Objects and Control.

  throw()

    Switches execution to this greenlet, but immediately raises the given exception in this greenlet. If no argument is provided, the exception defaults to `greenlet.GreenletExit`. The normal exception propagation rules apply, as described for `switch`. Note that calling this method is almost equivalent to the following:

        def raiser():
            raise typ, val, tb
        g_raiser = greenlet(raiser, parent=g)
        g_raiser.switch()

    except that this trick does not work for the `greenlet.GreenletExit` exception, which would not propagate from `g_raiser` to `g`.

  dead

    True if this greenlet is dead (i.e., it finished its execution).

  gr_context

    The `contextvars.Context` in which `g` will run. Writable; defaults to `None`, reflecting that a greenlet starts execution in an empty context unless told otherwise. Generally, this should only be set once, before a greenlet begins running. Accessing or modifying this attribute raises `AttributeError` on Python versions 3.6 and earlier (which don’t natively support the `contextvars` module) or if `greenlet` was built without contextvars support.

    For more information, see Context Variables (asyncio).

    Added in version 1.0.0.

  gr_frame

    The frame that was active in this greenlet when it most recently called `some_other_greenlet.switch()`, and that will resume execution when `this_greenlet.switch()` is next called. The remainder of the greenlet’s stack can be accessed by following the frame object’s `f_back` attributes. `gr_frame` is non-None only for suspended greenlets; it is None if the greenlet is dead, not yet started, or currently executing.

    Note

    Greenlet stack introspection is fragile on CPython 3.12 and later. The frame objects of a suspended greenlet are not safe to access as-is, but must be adjusted by the greenlet package in order to make traversing `f_back` links not crash the interpreter, and restored to their original state when resuming the greenlet. The intent is to handle this transparently, but it does introduce additional overhead to switching greenlets, and there may be obscure usage patterns that can still crash the interpreter; if you find one of these, please report it to the maintainer.

  parent

    The parent greenlet. This is writable, but it is not allowed to create cycles of parents.

    A greenlet without a parent is the main greenlet of its thread.

    Cannot be set to anything except a greenlet.

  run

    The callable that this greenlet will run when it starts. After it is started, this attribute no longer exists.

    Subclasses can define this as a method on the type.

## Tracing

For details on tracing, see Tracing And Profiling.

greenlet.gettrace() → object

  Returns the currently set tracing function, or None.

greenlet.settrace(callback) → object

  Sets a new tracing function and returns the previous one.

  Parameters:

    callback – A callable object with the signature `callback(event, args)`.