eventlet package

Subpackages

Submodules

eventlet.asyncio module

Asyncio compatibility functions.

eventlet.asyncio.spawn_for_awaitable(coroutine)

Take a coroutine or some other object that can be awaited (asyncio.Future, asyncio.Task), and turn it into a GreenThread.

Known limitations:

  • The coroutine/future/etc. don’t run in their own greenlet/GreenThread.

  • As a result, things like eventlet.Lock won’t work correctly inside async functions, thread ids aren’t meaningful, and so on.

eventlet.backdoor module

class eventlet.backdoor.FileProxy(f)

Bases: object

flush()
isatty()
readline(*a)
write(data, *a, **kw)
class eventlet.backdoor.SocketConsole(desc, hostport, locals)

Bases: greenlet

finalize()
run()
switch(*args, **kwargs)

Switch execution to this greenlet.

If this greenlet has never been run, then this greenlet will be switched to using the body of self.run(*args, **kwargs).

If the greenlet is active (has been run, but was switch()’ed out before leaving its run function), then this greenlet will be resumed and the return value to its switch call will be None if no arguments are given, the given argument if one argument is given, or the args tuple and keyword args dict if multiple arguments are given.

If the greenlet is dead, or is the current greenlet then this function will simply return the arguments using the same rules as above.

switch_out()
eventlet.backdoor.backdoor(conn_info, locals=None)

Sets up an interactive console on a socket with a single connected client. This does not block the caller, as it spawns a new greenlet to handle the console. This is meant to be called from within an accept loop (such as backdoor_server).

eventlet.backdoor.backdoor_server(sock, locals=None)

Blocking function that runs a backdoor server on the socket sock, accepting connections and running backdoor consoles for each client that connects.

The locals argument is a dictionary that will be included in the locals() of the interpreters. It can be convenient to stick important application variables in here.

eventlet.convenience module

exception eventlet.convenience.ReusePortUnavailableWarning

Bases: Warning

exception eventlet.convenience.ReuseRandomPortWarning

Bases: Warning

exception eventlet.convenience.StopServe

Bases: Exception

Exception class used for quitting serve() gracefully.

eventlet.convenience.connect(addr, family=AddressFamily.AF_INET, bind=None)

Convenience function for opening client sockets.

Parameters:

  • addr – Address of the server to connect to. For TCP sockets, this is a (host, port) tuple.

  • family – Socket family, optional. See socket documentation for available families.

  • bind – Local address to bind to, optional.

Returns:

The connected green socket object.

eventlet.convenience.listen(addr, family=AddressFamily.AF_INET, backlog=50, reuse_addr=True, reuse_port=None)

Convenience function for opening server sockets. This socket can be used in serve() or a custom accept() loop.

Sets SO_REUSEADDR on the socket to save on annoyance.

Parameters:

  • addr – Address to listen on. For TCP sockets, this is a (host, port) tuple.

  • family – Socket family, optional. See socket documentation for available families.

  • backlog – The maximum number of queued connections. Should be at least 1; the maximum value is system-dependent.

Returns:

The listening green socket object.

eventlet.convenience.serve(sock, handle, concurrency=1000)

Runs a server on the supplied socket. Calls the function handle in a separate greenthread for every incoming client connection. handle takes two arguments: the client socket object, and the client address:

def myhandle(client_sock, client_addr):
    print("client connected", client_addr)

eventlet.serve(eventlet.listen(('127.0.0.1', 9999)), myhandle)

Returning from handle closes the client socket.

serve() blocks the calling greenthread; it won’t return until the server completes. If you desire an immediate return, spawn a new greenthread for serve().

Any uncaught exceptions raised in handle are raised as exceptions from serve(), terminating the server, so be sure to be aware of the exceptions your application can raise. The return value of handle is ignored.

Raise a StopServe exception to gracefully terminate the server – that’s the only way to get the server() function to return rather than raise.

The value in concurrency controls the maximum number of greenthreads that will be open at any time handling requests. When the server hits the concurrency limit, it stops accepting new connections until the existing ones complete.

eventlet.convenience.wrap_ssl(sock, *a, **kw)

Convenience function for converting a regular socket into an SSL socket. Has the same interface as ssl.wrap_socket(), but can also use PyOpenSSL. Though, note that it ignores the cert_reqs, ssl_version, ca_certs, do_handshake_on_connect, and suppress_ragged_eofs arguments when using PyOpenSSL.

The preferred idiom is to call wrap_ssl directly on the creation method, e.g., wrap_ssl(connect(addr)) or wrap_ssl(listen(addr), server_side=True). This way there is no “naked” socket sitting around to accidentally corrupt the SSL session.

:return Green SSL object.

eventlet.corolocal module

eventlet.corolocal.get_ident()

Returns id() of current greenlet. Useful for debugging.

class eventlet.corolocal.local(*args, **kw)

Bases: _localbase

eventlet.coros module

class eventlet.coros.metaphore

Bases: object

This is sort of an inverse semaphore: a counter that starts at 0 and waits only if nonzero. It’s used to implement a “wait for all” scenario.

>>> from eventlet import coros, spawn_n
>>> count = coros.metaphore()
>>> count.wait()
>>> def decrementer(count, id):
...     print("{0} decrementing".format(id))
...     count.dec()
...
>>> _ = spawn_n(decrementer, count, 'A')
>>> _ = spawn_n(decrementer, count, 'B')
>>> count.inc(2)
>>> count.wait()
A decrementing
B decrementing
dec(by=1)

Decrement our counter. If this transitions the counter from nonzero to zero, a current or subsequent wait() call need no longer wait.

inc(by=1)

Increment our counter. If this transitions the counter from zero to nonzero, make any subsequent wait() call wait.

wait()

Suspend the caller only if our count is nonzero. In that case, resume the caller once the count decrements to zero again.

eventlet.dagpool module

exception eventlet.dagpool.Collision

Bases: Exception

DAGPool raises Collision when you try to launch two greenthreads with the same key, or post() a result for a key corresponding to a greenthread, or post() twice for the same key. As with KeyError, str(collision) names the key in question.

class eventlet.dagpool.DAGPool(preload={})

Bases: object

A DAGPool is a pool that constrains greenthreads, not by max concurrency, but by data dependencies.

This is a way to implement general DAG dependencies. A simple dependency tree (flowing in either direction) can straightforwardly be implemented using recursion and (e.g.) GreenThread.imap(). What gets complicated is when a given node depends on several other nodes as well as contributing to several other nodes.

With DAGPool, you concurrently launch all applicable greenthreads; each will proceed as soon as it has all required inputs. The DAG is implicit in which items are required by each greenthread.

Each greenthread is launched in a DAGPool with a key: any value that can serve as a Python dict key. The caller also specifies an iterable of other keys on which this greenthread depends. This iterable may be empty.

The greenthread callable must accept (key, results), where:

key

is its own key

results

is an iterable of (key, value) pairs.

A newly-launched DAGPool greenthread is entered immediately, and can perform any necessary setup work. At some point it will iterate over the (key, value) pairs from the passed ‘results’ iterable. Doing so blocks the greenthread until a value is available for each of the keys specified in its initial dependencies iterable. These (key, value) pairs are delivered in chronological order, not the order in which they are initially specified: each value will be delivered as soon as it becomes available.

The value returned by a DAGPool greenthread becomes the value for its key, which unblocks any other greenthreads waiting on that key.

If a DAGPool greenthread terminates with an exception instead of returning a value, attempting to retrieve the value raises PropagateError, which binds the key of the original greenthread and the original exception. Unless the greenthread attempting to retrieve the value handles PropagateError, that exception will in turn be wrapped in a PropagateError of its own, and so forth. The code that ultimately handles PropagateError can follow the chain of PropagateError.exc attributes to discover the flow of that exception through the DAG of greenthreads.

External greenthreads may also interact with a DAGPool. See wait_each(), waitall(), post().

It is not recommended to constrain external DAGPool producer greenthreads in a GreenPool: it may be hard to provably avoid deadlock.

__init__(preload={})

DAGPool can be prepopulated with an initial dict or iterable of (key, value) pairs. These (key, value) pairs are of course immediately available for any greenthread that depends on any of those keys.

__getitem__(key)

__getitem__(key) (aka dagpool[key]) blocks until key has a value, then delivers that value.

get(key, default=None)

get() returns the value for key. If key does not yet have a value, get() returns default.

items()

Return a snapshot tuple of currently-available (key, value) pairs.

keys()

Return a snapshot tuple of keys for which we currently have values.

kill(key)

Kill the greenthread that was spawned with the specified key.

If no such greenthread was spawned, raise KeyError.

post(key, value, replace=False)

post(key, value) stores the passed value for the passed key. It then causes each greenthread blocked on its results iterable, or on wait_each(keys), to check for new values. A waiting greenthread might not literally resume on every single post() of a relevant key, but the first post() of a relevant key ensures that it will resume eventually, and when it does it will catch up with all relevant post() calls.

Calling post(key, value) when there is a running greenthread with that same key raises Collision. If you must post(key, value) instead of letting the greenthread run to completion, you must first call kill(key).

The DAGPool implicitly post()s the return value from each of its greenthreads. But a greenthread may explicitly post() a value for its own key, which will cause its return value to be discarded.

Calling post(key, value, replace=False) (the default replace) when a value for that key has already been posted, by any means, raises Collision.

Calling post(key, value, replace=True) when a value for that key has already been posted, by any means, replaces the previously-stored value. However, that may make it complicated to reason about the behavior of greenthreads waiting on that key.

After a post(key, value1) followed by post(key, value2, replace=True), it is unspecified which pending wait_each([key...]) calls (or greenthreads iterating over results involving that key) will observe value1 versus value2. It is guaranteed that subsequent wait_each([key…]) calls (or greenthreads spawned after that point) will observe value2.

A successful call to post(key, PropagateError(key, ExceptionSubclass)) ensures that any subsequent attempt to retrieve that key’s value will raise that PropagateError instance.

running()

Return number of running DAGPool greenthreads. This includes greenthreads blocked while iterating through their results iterable, that is, greenthreads waiting on values from other keys.

running_keys()

Return keys for running DAGPool greenthreads. This includes greenthreads blocked while iterating through their results iterable, that is, greenthreads waiting on values from other keys.

spawn(key, depends, function, *args, **kwds)

Launch the passed function(key, results, …) as a greenthread, passing it:

  • the specified key

  • an iterable of (key, value) pairs

  • whatever other positional args or keywords you specify.

Iterating over the results iterable behaves like calling wait_each(depends).

Returning from function() behaves like post(key, return_value).

If function() terminates with an exception, that exception is wrapped in PropagateError with the greenthread’s key and (effectively) posted as the value for that key. Attempting to retrieve that value will raise that PropagateError.

Thus, if the greenthread with key ‘a’ terminates with an exception, and greenthread ‘b’ depends on ‘a’, when greenthread ‘b’ attempts to iterate through its results argument, it will encounter PropagateError. So by default, an uncaught exception will propagate through all the downstream dependencies.

If you pass spawn() a key already passed to spawn() or post(), spawn() raises Collision.

spawn_many(depends, function, *args, **kwds)

spawn_many() accepts a single function whose parameters are the same as for spawn().

The difference is that spawn_many() accepts a dependency dict depends. A new greenthread is spawned for each key in the dict. That dict key’s value should be an iterable of other keys on which this greenthread depends.

If the depends dict contains any key already passed to spawn() or post(), spawn_many() raises Collision. It is indeterminate how many of the other keys in depends will have successfully spawned greenthreads.

wait(keys=<object object>)

keys is an optional iterable of keys. If you omit the argument, it waits for all the keys from preload data, from post() calls and from spawn() calls: in other words, all the keys of which this DAGPool is aware.

wait() blocks the calling greenthread until all of the relevant keys have values. wait() returns a dict whose keys are the relevant keys, and whose values come from the preload data, from values returned by DAGPool greenthreads or from post() calls.

If a DAGPool greenthread terminates with an exception, wait() will raise PropagateError wrapping that exception. If more than one greenthread terminates with an exception, it is indeterminate which one wait() will raise.

If an external greenthread posts a PropagateError instance, wait() will raise that PropagateError. If more than one greenthread posts PropagateError, it is indeterminate which one wait() will raise.

See also wait_each_success(), wait_each_exception().

wait_each(keys=<object object>)

keys is an optional iterable of keys. If you omit the argument, it waits for all the keys from preload data, from post() calls and from spawn() calls: in other words, all the keys of which this DAGPool is aware.

wait_each() is a generator producing (key, value) pairs as a value becomes available for each requested key. wait_each() blocks the calling greenthread until the next value becomes available. If the DAGPool was prepopulated with values for any of the relevant keys, of course those can be delivered immediately without waiting.

Delivery order is intentionally decoupled from the initial sequence of keys: each value is delivered as soon as it becomes available. If multiple keys are available at the same time, wait_each() delivers each of the ready ones in arbitrary order before blocking again.

The DAGPool does not distinguish between a value returned by one of its own greenthreads and one provided by a post() call or preload data.

The wait_each() generator terminates (raises StopIteration) when all specified keys have been delivered. Thus, typical usage might be:

for key, value in dagpool.wait_each(keys):
    # process this ready key and value
# continue processing now that we've gotten values for all keys

By implication, if you pass wait_each() an empty iterable of keys, it returns immediately without yielding anything.

If the value to be delivered is a PropagateError exception object, the generator raises that PropagateError instead of yielding it.

See also wait_each_success(), wait_each_exception().

wait_each_exception(keys=<object object>)

wait_each_exception() filters results so that only exceptions are yielded. Not every provided (or defaulted) key will necessarily be represented, though naturally the generator will not finish until all have completed.

Unlike other DAGPool methods, wait_each_exception() simply yields PropagateError instances as values rather than raising them.

In all other respects, wait_each_exception() behaves like wait_each().

wait_each_success(keys=<object object>)

wait_each_success() filters results so that only success values are yielded. In other words, unlike wait_each(), wait_each_success() will not raise PropagateError. Not every provided (or defaulted) key will necessarily be represented, though naturally the generator will not finish until all have completed.

In all other respects, wait_each_success() behaves like wait_each().

waitall()

waitall() blocks the calling greenthread until there is a value for every DAGPool greenthread launched by spawn(). It returns a dict containing all preload data, all data from post() and all values returned by spawned greenthreads.

See also wait().

waiting()

Return number of waiting DAGPool greenthreads, that is, greenthreads still waiting on values from other keys. This explicitly does not include external greenthreads waiting on wait(), waitall(), wait_each().

waiting_for(key=<object object>)

waiting_for(key) returns a set() of the keys for which the DAGPool greenthread spawned with that key is still waiting. If you pass a key for which no greenthread was spawned, waiting_for() raises KeyError.

waiting_for() without argument returns a dict. Its keys are the keys of DAGPool greenthreads still waiting on one or more values. In the returned dict, the value of each such key is the set of other keys for which that greenthread is still waiting.

This method allows diagnosing a “hung” DAGPool. If certain greenthreads are making no progress, it’s possible that they are waiting on keys for which there is no greenthread and no post() data.

exception eventlet.dagpool.PropagateError(key, exc)

Bases: Exception

When a DAGPool greenthread terminates with an exception instead of returning a result, attempting to retrieve its value raises PropagateError.

Attributes:

key

the key of the greenthread which raised the exception

exc

the exception object raised by the greenthread

eventlet.db_pool module

class eventlet.db_pool.BaseConnectionPool(db_module, min_size=0, max_size=4, max_idle=10, max_age=30, connect_timeout=5, cleanup=<function cleanup_rollback>, *args, **kwargs)

Bases: Pool

clear()

Close all connections that this pool still holds a reference to, and removes all references to them.

get()

Return an item from the pool, when one is available. This may cause the calling greenthread to block.

item(cleanup=<object object>)

Get an object out of the pool, for use with with statement.

>>> from eventlet import pools
>>> pool = pools.TokenPool(max_size=4)
>>> with pool.item() as obj:
...     print("got token")
...
got token
>>> pool.free()
4
put(conn, cleanup=<object object>)

Put an item back into the pool, when done. This may cause the putting greenthread to block.

exception eventlet.db_pool.ConnectTimeout

Bases: Exception

eventlet.db_pool.ConnectionPool

alias of TpooledConnectionPool

class eventlet.db_pool.DatabaseConnector(module, credentials, conn_pool=None, *args, **kwargs)

Bases: object

This is an object which will maintain a collection of database connection pools on a per-host basis.

credentials_for(host)
get(host, dbname)

Returns a ConnectionPool to the target host and schema.

class eventlet.db_pool.GenericConnectionWrapper(baseconn)

Bases: object

affected_rows(*args, **kwargs)
autocommit(*args, **kwargs)
begin(*args, **kwargs)
change_user(*args, **kwargs)
character_set_name(*args, **kwargs)
close(*args, **kwargs)
commit(*args, **kwargs)
cursor(*args, **kwargs)
dump_debug_info(*args, **kwargs)
errno(*args, **kwargs)
error(*args, **kwargs)
errorhandler(*args, **kwargs)
get_server_info(*args, **kwargs)
insert_id(*args, **kwargs)
literal(*args, **kwargs)
ping(*args, **kwargs)
query(*args, **kwargs)
rollback(*args, **kwargs)
select_db(*args, **kwargs)
server_capabilities(*args, **kwargs)
set_character_set(*args, **kwargs)
set_isolation_level(*args, **kwargs)
set_server_option(*args, **kwargs)
set_sql_mode(*args, **kwargs)
show_warnings(*args, **kwargs)
shutdown(*args, **kwargs)
sqlstate(*args, **kwargs)
stat(*args, **kwargs)
store_result(*args, **kwargs)
string_literal(*args, **kwargs)
thread_id(*args, **kwargs)
use_result(*args, **kwargs)
warning_count(*args, **kwargs)
class eventlet.db_pool.PooledConnectionWrapper(baseconn, pool)

Bases: GenericConnectionWrapper

A connection wrapper where: - the close method returns the connection to the pool instead of closing it directly - bool(conn) returns a reasonable value - returns itself to the pool if it gets garbage collected

close()

Return the connection to the pool, and remove the reference to it so that you can’t use it again through this wrapper object.

class eventlet.db_pool.RawConnectionPool(db_module, min_size=0, max_size=4, max_idle=10, max_age=30, connect_timeout=5, cleanup=<function cleanup_rollback>, *args, **kwargs)

Bases: BaseConnectionPool

A pool which gives out plain database connections.

classmethod connect(db_module, connect_timeout, *args, **kw)
create()

Generate a new pool item. In order for the pool to function, either this method must be overriden in a subclass or the pool must be constructed with the create argument. It accepts no arguments and returns a single instance of whatever thing the pool is supposed to contain.

In general, create() is called whenever the pool exceeds its previous high-water mark of concurrently-checked-out-items. In other words, in a new pool with min_size of 0, the very first call to get() will result in a call to create(). If the first caller calls put() before some other caller calls get(), then the first item will be returned, and create() will not be called a second time.

class eventlet.db_pool.TpooledConnectionPool(db_module, min_size=0, max_size=4, max_idle=10, max_age=30, connect_timeout=5, cleanup=<function cleanup_rollback>, *args, **kwargs)

Bases: BaseConnectionPool

A pool which gives out Proxy-based database connections.

classmethod connect(db_module, connect_timeout, *args, **kw)
create()

Generate a new pool item. In order for the pool to function, either this method must be overriden in a subclass or the pool must be constructed with the create argument. It accepts no arguments and returns a single instance of whatever thing the pool is supposed to contain.

In general, create() is called whenever the pool exceeds its previous high-water mark of concurrently-checked-out-items. In other words, in a new pool with min_size of 0, the very first call to get() will result in a call to create(). If the first caller calls put() before some other caller calls get(), then the first item will be returned, and create() will not be called a second time.

eventlet.db_pool.cleanup_rollback(conn)

eventlet.debug module

The debug module contains utilities and functions for better debugging Eventlet-powered applications.

eventlet.debug.format_asyncio_info()

Returns a formatted string of the asyncio info. This can be useful in determining what’s going on in the asyncio event loop system, especially when used in conjunction with the asyncio hub.

eventlet.debug.format_hub_listeners()

Returns a formatted string of the current listeners on the current hub. This can be useful in determining what’s going on in the event system, especially when used in conjunction with hub_listener_stacks().

eventlet.debug.format_hub_timers()

Returns a formatted string of the current timers on the current hub. This can be useful in determining what’s going on in the event system, especially when used in conjunction with hub_timer_stacks().

eventlet.debug.format_threads_info()

Returns a formatted string of the threads info. This can be useful in determining what’s going on with created threads, especially when used in conjunction with greenlet

eventlet.debug.hub_blocking_detection(state=False, resolution=1)

Toggles whether Eventlet makes an effort to detect blocking behavior in an application.

It does this by telling the kernel to raise a SIGALARM after a short timeout, and clearing the timeout every time the hub greenlet is resumed. Therefore, any code that runs for a long time without yielding to the hub will get interrupted by the blocking detector (don’t use it in production!).

The resolution argument governs how long the SIGALARM timeout waits in seconds. The implementation uses signal.setitimer() and can be specified as a floating-point value. The shorter the resolution, the greater the chance of false positives.

eventlet.debug.hub_exceptions(state=True)

Toggles whether the hub prints exceptions that are raised from its timers. This can be useful to see how greenthreads are terminating.

eventlet.debug.hub_listener_stacks(state=False)

Toggles whether or not the hub records the stack when clients register listeners on file descriptors. This can be useful when trying to figure out what the hub is up to at any given moment. To inspect the stacks of the current listeners, call format_hub_listeners() at critical junctures in the application logic.

eventlet.debug.hub_prevent_multiple_readers(state=True)

Toggle prevention of multiple greenlets reading from a socket

When multiple greenlets read from the same socket it is often hard to predict which greenlet will receive what data. To achieve resource sharing consider using eventlet.pools.Pool instead.

But if you really know what you are doing you can change the state to False to stop the hub from protecting against this mistake.

eventlet.debug.hub_timer_stacks(state=False)

Toggles whether or not the hub records the stack when timers are set. To inspect the stacks of the current timers, call format_hub_timers() at critical junctures in the application logic.

eventlet.debug.spew(trace_names=None, show_values=False)

Install a trace hook which writes incredibly detailed logs about what code is being executed to stdout.

eventlet.debug.tpool_exceptions(state=False)

Toggles whether tpool itself prints exceptions that are raised from functions that are executed in it, in addition to raising them like it normally does.

eventlet.debug.unspew()

Remove the trace hook installed by spew.

eventlet.event module

class eventlet.event.Event

Bases: object

An abstraction where an arbitrary number of coroutines can wait for one event from another.

Events are similar to a Queue that can only hold one item, but differ in two important ways:

  1. calling send() never unschedules the current greenthread

  2. send() can only be called once; create a new event to send again.

They are good for communicating results between coroutines, and are the basis for how GreenThread.wait() is implemented.

>>> from eventlet import event
>>> import eventlet
>>> evt = event.Event()
>>> def baz(b):
...     evt.send(b + 1)
...
>>> _ = eventlet.spawn_n(baz, 3)
>>> evt.wait()
4
has_exception()
has_result()
poll(notready=None)
poll_exception(notready=None)
poll_result(notready=None)
ready()

Return true if the wait() call will return immediately. Used to avoid waiting for things that might take a while to time out. For example, you can put a bunch of events into a list, and then visit them all repeatedly, calling ready() until one returns True, and then you can wait() on that one.

reset()
send(result=None, exc=None)

Makes arrangements for the waiters to be woken with the result and then returns immediately to the parent.

>>> from eventlet import event
>>> import eventlet
>>> evt = event.Event()
>>> def waiter():
...     print('about to wait')
...     result = evt.wait()
...     print('waited for {0}'.format(result))
>>> _ = eventlet.spawn(waiter)
>>> eventlet.sleep(0)
about to wait
>>> evt.send('a')
>>> eventlet.sleep(0)
waited for a

It is an error to call send() multiple times on the same event.

>>> evt.send('whoops') 
Traceback (most recent call last):
AssertionError: Trying to re-send() an already-triggered event.

Use reset() between send() s to reuse an event object.

send_exception(*args)

Same as send(), but sends an exception to waiters.

The arguments to send_exception are the same as the arguments to raise. If a single exception object is passed in, it will be re-raised when wait() is called, generating a new stacktrace.

>>> from eventlet import event
>>> evt = event.Event()
>>> evt.send_exception(RuntimeError())
>>> evt.wait()
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "eventlet/event.py", line 120, in wait
    current.throw(*self._exc)
RuntimeError

If it’s important to preserve the entire original stack trace, you must pass in the entire sys.exc_info() tuple.

>>> import sys
>>> evt = event.Event()
>>> try:
...     raise RuntimeError()
... except RuntimeError:
...     evt.send_exception(*sys.exc_info())
...
>>> evt.wait()
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "eventlet/event.py", line 120, in wait
    current.throw(*self._exc)
  File "<stdin>", line 2, in <module>
RuntimeError

Note that doing so stores a traceback object directly on the Event object, which may cause reference cycles. See the sys.exc_info() documentation.

wait(timeout=None)

Wait until another coroutine calls send(). Returns the value the other coroutine passed to send().

>>> import eventlet
>>> evt = eventlet.Event()
>>> def wait_on():
...    retval = evt.wait()
...    print("waited for {0}".format(retval))
>>> _ = eventlet.spawn(wait_on)
>>> evt.send('result')
>>> eventlet.sleep(0)
waited for result

Returns immediately if the event has already occurred.

>>> evt.wait()
'result'

When the timeout argument is present and not None, it should be a floating point number specifying a timeout for the operation in seconds (or fractions thereof).

eventlet.greenpool module

class eventlet.greenpool.GreenPile(size_or_pool=1000)

Bases: object

GreenPile is an abstraction representing a bunch of I/O-related tasks.

Construct a GreenPile with an existing GreenPool object. The GreenPile will then use that pool’s concurrency as it processes its jobs. There can be many GreenPiles associated with a single GreenPool.

A GreenPile can also be constructed standalone, not associated with any GreenPool. To do this, construct it with an integer size parameter instead of a GreenPool.

It is not advisable to iterate over a GreenPile in a different greenthread than the one which is calling spawn. The iterator will exit early in that situation.

next()

Wait for the next result, suspending the current greenthread until it is available. Raises StopIteration when there are no more results.

spawn(func, *args, **kw)

Runs func in its own green thread, with the result available by iterating over the GreenPile object.

class eventlet.greenpool.GreenPool(size=1000)

Bases: object

The GreenPool class is a pool of green threads.

free()

Returns the number of greenthreads available for use.

If zero or less, the next call to spawn() or spawn_n() will block the calling greenthread until a slot becomes available.

imap(function, *iterables)

This is the same as itertools.imap(), and has the same concurrency and memory behavior as starmap().

It’s quite convenient for, e.g., farming out jobs from a file:

def worker(line):
    return do_something(line)
pool = GreenPool()
for result in pool.imap(worker, open("filename", 'r')):
    print(result)
resize(new_size)

Change the max number of greenthreads doing work at any given time.

If resize is called when there are more than new_size greenthreads already working on tasks, they will be allowed to complete but no new tasks will be allowed to get launched until enough greenthreads finish their tasks to drop the overall quantity below new_size. Until then, the return value of free() will be negative.

running()

Returns the number of greenthreads that are currently executing functions in the GreenPool.

spawn(function, *args, **kwargs)

Run the function with its arguments in its own green thread. Returns the GreenThread object that is running the function, which can be used to retrieve the results.

If the pool is currently at capacity, spawn will block until one of the running greenthreads completes its task and frees up a slot.

This function is reentrant; function can call spawn on the same pool without risk of deadlocking the whole thing.

spawn_n(function, *args, **kwargs)

Create a greenthread to run the function, the same as spawn(). The difference is that spawn_n() returns None; the results of function are not retrievable.

starmap(function, iterable)

This is the same as itertools.starmap(), except that func is executed in a separate green thread for each item, with the concurrency limited by the pool’s size. In operation, starmap consumes a constant amount of memory, proportional to the size of the pool, and is thus suited for iterating over extremely long input lists.

waitall()

Waits until all greenthreads in the pool are finished working.

waiting()

Return the number of greenthreads waiting to spawn.

eventlet.greenthread module

class eventlet.greenthread.GreenThread(parent)

Bases: greenlet

The GreenThread class is a type of Greenlet which has the additional property of being able to retrieve the return value of the main function. Do not construct GreenThread objects directly; call spawn() to get one.

cancel(*throw_args)

Kills the greenthread using kill(), but only if it hasn’t already started running. After being canceled, all calls to wait() will raise throw_args (which default to greenlet.GreenletExit).

kill(*throw_args)

Kills the greenthread using kill(). After being killed all calls to wait() will raise throw_args (which default to greenlet.GreenletExit).

Set up a function to be called with the results of the GreenThread.

The function must have the following signature:

def func(gt, [curried args/kwargs]):

When the GreenThread finishes its run, it calls func with itself and with the curried arguments supplied at link-time. If the function wants to retrieve the result of the GreenThread, it should call wait() on its first argument.

Note that func is called within execution context of the GreenThread, so it is possible to interfere with other linked functions by doing things like switching explicitly to another greenthread.

main(function, args, kwargs)

remove linked function set by link()

Remove successfully return True, otherwise False

wait()

Returns the result of the main function of this GreenThread. If the result is a normal return value, wait() returns it. If it raised an exception, wait() will raise the same exception (though the stack trace will unavoidably contain some frames from within the greenthread module).

eventlet.greenthread.getcurrent() → greenlet

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

eventlet.greenthread.kill(g, *throw_args)

Terminates the target greenthread by raising an exception into it. Whatever that greenthread might be doing; be it waiting for I/O or another primitive, it sees an exception right away.

By default, this exception is GreenletExit, but a specific exception may be specified. throw_args should be the same as the arguments to raise; either an exception instance or an exc_info tuple.

Calling kill() causes the calling greenthread to cooperatively yield.

eventlet.greenthread.sleep(seconds=0)

Yield control to another eligible coroutine until at least seconds have elapsed.

seconds may be specified as an integer, or a float if fractional seconds are desired. Calling sleep() with seconds of 0 is the canonical way of expressing a cooperative yield. For example, if one is looping over a large list performing an expensive calculation without calling any socket methods, it’s a good idea to call sleep(0) occasionally; otherwise nothing else will run.

eventlet.greenthread.spawn(func, *args, **kwargs)

Create a greenthread to run func(*args, **kwargs). Returns a GreenThread object which you can use to get the results of the call.

Execution control returns immediately to the caller; the created greenthread is merely scheduled to be run at the next available opportunity. Use spawn_after() to arrange for greenthreads to be spawned after a finite delay.

eventlet.greenthread.spawn_after(seconds, func, *args, **kwargs)

Spawns func after seconds have elapsed. It runs as scheduled even if the current greenthread has completed.

seconds may be specified as an integer, or a float if fractional seconds are desired. The func will be called with the given args and keyword arguments kwargs, and will be executed within its own greenthread.

The return value of spawn_after() is a GreenThread object, which can be used to retrieve the results of the call.

To cancel the spawn and prevent func from being called, call GreenThread.cancel() on the return value of spawn_after(). This will not abort the function if it’s already started running, which is generally the desired behavior. If terminating func regardless of whether it’s started or not is the desired behavior, call GreenThread.kill().

eventlet.greenthread.spawn_after_local(seconds, func, *args, **kwargs)

Spawns func after seconds have elapsed. The function will NOT be called if the current greenthread has exited.

seconds may be specified as an integer, or a float if fractional seconds are desired. The func will be called with the given args and keyword arguments kwargs, and will be executed within its own greenthread.

The return value of spawn_after() is a GreenThread object, which can be used to retrieve the results of the call.

To cancel the spawn and prevent func from being called, call GreenThread.cancel() on the return value. This will not abort the function if it’s already started running. If terminating func regardless of whether it’s started or not is the desired behavior, call GreenThread.kill().

eventlet.greenthread.spawn_n(func, *args, **kwargs)

Same as spawn(), but returns a greenlet object from which it is not possible to retrieve either a return value or whether it raised any exceptions. This is faster than spawn(); it is fastest if there are no keyword arguments.

If an exception is raised in the function, spawn_n prints a stack trace; the print can be disabled by calling eventlet.debug.hub_exceptions() with False.

eventlet.lock module

class eventlet.lock.Lock(value=1)

Bases: Semaphore

A lock. This is API-compatible with threading.Lock.

It is a context manager, and thus can be used in a with block:

lock = Lock()
with lock:
  do_some_stuff()
release(blocking=True)

Modify behaviour vs Semaphore to raise a RuntimeError exception if the value is greater than zero. This corrects behaviour to realign with threading.Lock.

eventlet.patcher module

eventlet.patcher.import_patched(module_name, *additional_modules, **kw_additional_modules)

Imports a module in a way that ensures that the module uses “green” versions of the standard library modules, so that everything works nonblockingly.

The only required argument is the name of the module to be imported.

eventlet.patcher.inject(module_name, new_globals, *additional_modules)

Base method for “injecting” greened modules into an imported module. It imports the module specified in module_name, arranging things so that the already-imported modules in additional_modules are used when module_name makes its imports.

Note: This function does not create or change any sys.modules item, so if your greened module use code like ‘sys.modules[“your_module_name”]’, you need to update sys.modules by yourself.

new_globals is either None or a globals dictionary that gets populated with the contents of the module_name module. This is useful when creating a “green” version of some other module.

additional_modules should be a collection of two-element tuples, of the form (<name>, <module>). If it’s not specified, a default selection of name/module pairs is used, which should cover all use cases but may be slower because there are inevitably redundant or unnecessary imports.

eventlet.patcher.is_monkey_patched(module)

Returns True if the given module is monkeypatched currently, False if not. module can be either the module itself or its name.

Based entirely off the name of the module, so if you import a module some other way than with the import keyword (including import_patched), this might not be correct about that particular module.

eventlet.patcher.monkey_patch(**on)

Globally patches certain system modules to be greenthread-friendly.

The keyword arguments afford some control over which modules are patched. If no keyword arguments are supplied, all possible modules are patched. If keywords are set to True, only the specified modules are patched. E.g., monkey_patch(socket=True, select=True) patches only the select and socket modules. Most arguments patch the single module of the same name (os, time, select). The exceptions are socket, which also patches the ssl module if present; and thread, which patches thread, threading, and Queue.

It’s safe to call monkey_patch multiple times.

eventlet.pools module

class eventlet.pools.Pool(min_size=0, max_size=4, order_as_stack=False, create=None)

Bases: object

Pool class implements resource limitation and construction.

There are two ways of using Pool: passing a create argument or subclassing. In either case you must provide a way to create the resource.

When using create argument, pass a function with no arguments:

http_pool = pools.Pool(create=httplib2.Http)

If you need to pass arguments, build a nullary function with either lambda expression:

http_pool = pools.Pool(create=lambda: httplib2.Http(timeout=90))

or functools.partial():

from functools import partial
http_pool = pools.Pool(create=partial(httplib2.Http, timeout=90))

When subclassing, define only the create() method to implement the desired resource:

class MyPool(pools.Pool):
    def create(self):
        return MyObject()

If using 2.5 or greater, the item() method acts as a context manager; that’s the best way to use it:

with mypool.item() as thing:
    thing.dostuff()

The maximum size of the pool can be modified at runtime via the resize() method.

Specifying a non-zero min-size argument pre-populates the pool with min_size items. max-size sets a hard limit to the size of the pool – it cannot contain any more items than max_size, and if there are already max_size items ‘checked out’ of the pool, the pool will cause any greenthread calling get() to cooperatively yield until an item is put() in.

create()

Generate a new pool item. In order for the pool to function, either this method must be overriden in a subclass or the pool must be constructed with the create argument. It accepts no arguments and returns a single instance of whatever thing the pool is supposed to contain.

In general, create() is called whenever the pool exceeds its previous high-water mark of concurrently-checked-out-items. In other words, in a new pool with min_size of 0, the very first call to get() will result in a call to create(). If the first caller calls put() before some other caller calls get(), then the first item will be returned, and create() will not be called a second time.

free()

Return the number of free items in the pool. This corresponds to the number of get() calls needed to empty the pool.

get()

Return an item from the pool, when one is available. This may cause the calling greenthread to block.

item()

Get an object out of the pool, for use with with statement.

>>> from eventlet import pools
>>> pool = pools.TokenPool(max_size=4)
>>> with pool.item() as obj:
...     print("got token")
...
got token
>>> pool.free()
4
put(item)

Put an item back into the pool, when done. This may cause the putting greenthread to block.

resize(new_size)

Resize the pool to new_size.

Adjusting this number does not affect existing items checked out of the pool, nor on any greenthreads who are waiting for an item to free up. Some indeterminate number of get()/put() cycles will be necessary before the new maximum size truly matches the actual operation of the pool.

waiting()

Return the number of routines waiting for a pool item.

class eventlet.pools.TokenPool(min_size=0, max_size=4, order_as_stack=False, create=None)

Bases: Pool

A pool which gives out tokens (opaque unique objects), which indicate that the coroutine which holds the token has a right to consume some limited resource.

create()

Generate a new pool item. In order for the pool to function, either this method must be overriden in a subclass or the pool must be constructed with the create argument. It accepts no arguments and returns a single instance of whatever thing the pool is supposed to contain.

In general, create() is called whenever the pool exceeds its previous high-water mark of concurrently-checked-out-items. In other words, in a new pool with min_size of 0, the very first call to get() will result in a call to create(). If the first caller calls put() before some other caller calls get(), then the first item will be returned, and create() will not be called a second time.

eventlet.queue module

Synchronized queues.

The eventlet.queue module implements multi-producer, multi-consumer queues that work across greenlets, with the API similar to the classes found in the standard Queue and multiprocessing modules.

A major difference is that queues in this module operate as channels when initialized with maxsize of zero. In such case, both Queue.empty() and Queue.full() return True and Queue.put() always blocks until a call to Queue.get() retrieves the item.

An interesting difference, made possible because of greenthreads, is that Queue.qsize(), Queue.empty(), and Queue.full() can be used as indicators of whether the subsequent Queue.get() or Queue.put() will not block. The new methods Queue.getting() and Queue.putting() report on the number of greenthreads blocking in put or get respectively.

exception eventlet.queue.Empty

Bases: Exception

Exception raised by Queue.get(block=0)/get_nowait().

exception eventlet.queue.Full

Bases: Exception

Exception raised by Queue.put(block=0)/put_nowait().

class eventlet.queue.LifoQueue(maxsize=None)

Bases: Queue

A subclass of Queue that retrieves most recently added entries first.

class eventlet.queue.LightQueue(maxsize=None)

Bases: object

This is a variant of Queue that behaves mostly like the standard Stdlib_Queue. It differs by not supporting the task_done or join methods, and is a little faster for not having that overhead.

empty()

Return True if the queue is empty, False otherwise.

full()

Return True if the queue is full, False otherwise.

Queue(None) is never full.

get(block=True, timeout=None)

Remove and return an item from the queue.

If optional args block is true and timeout is None (the default), block if necessary until an item is available. If timeout is a positive number, it blocks at most timeout seconds and raises the Empty exception if no item was available within that time. Otherwise (block is false), return an item if one is immediately available, else raise the Empty exception (timeout is ignored in that case).

get_nowait()

Remove and return an item from the queue without blocking.

Only get an item if one is immediately available. Otherwise raise the Empty exception.

getting()

Returns the number of greenthreads that are blocked waiting on an empty queue.

put(item, block=True, timeout=None)

Put an item into the queue.

If optional arg block is true and timeout is None (the default), block if necessary until a free slot is available. If timeout is a positive number, it blocks at most timeout seconds and raises the Full exception if no free slot was available within that time. Otherwise (block is false), put an item on the queue if a free slot is immediately available, else raise the Full exception (timeout is ignored in that case).

put_nowait(item)

Put an item into the queue without blocking.

Only enqueue the item if a free slot is immediately available. Otherwise raise the Full exception.

putting()

Returns the number of greenthreads that are blocked waiting to put items into the queue.

qsize()

Return the size of the queue.

resize(size)

Resizes the queue’s maximum size.

If the size is increased, and there are putters waiting, they may be woken up.

class eventlet.queue.PriorityQueue(maxsize=None)

Bases: Queue

A subclass of Queue that retrieves entries in priority order (lowest first).

Entries are typically tuples of the form: (priority number, data).

class eventlet.queue.Queue(maxsize=None)

Bases: LightQueue

Create a queue object with a given maximum size.

If maxsize is less than zero or None, the queue size is infinite.

Queue(0) is a channel, that is, its put() method always blocks until the item is delivered. (This is unlike the standard Stdlib_Queue, where 0 means infinite size).

In all other respects, this Queue class resembles the standard library, Stdlib_Queue.

join()

Block until all items in the queue have been gotten and processed.

The count of unfinished tasks goes up whenever an item is added to the queue. The count goes down whenever a consumer thread calls task_done() to indicate that the item was retrieved and all work on it is complete. When the count of unfinished tasks drops to zero, join() unblocks.

task_done()

Indicate that a formerly enqueued task is complete. Used by queue consumer threads. For each get used to fetch a task, a subsequent call to task_done() tells the queue that the processing on the task is complete.

If a join() is currently blocking, it will resume when all items have been processed (meaning that a task_done() call was received for every item that had been put into the queue).

Raises a ValueError if called more times than there were items placed in the queue.

eventlet.semaphore module

class eventlet.semaphore.BoundedSemaphore(value=1)

Bases: Semaphore

A bounded semaphore checks to make sure its current value doesn’t exceed its initial value. If it does, ValueError is raised. In most situations semaphores are used to guard resources with limited capacity. If the semaphore is released too many times it’s a sign of a bug. If not given, value defaults to 1.

release(blocking=True)

Release a semaphore, incrementing the internal counter by one. If the counter would exceed the initial value, raises ValueError. When it was zero on entry and another thread is waiting for it to become larger than zero again, wake up that thread.

The blocking argument is for consistency with CappedSemaphore and is ignored

class eventlet.semaphore.CappedSemaphore(count, limit)

Bases: object

A blockingly bounded semaphore.

Optionally initialize with a resource count, then acquire() and release() resources as needed. Attempting to acquire() when count is zero suspends the calling greenthread until count becomes nonzero again. Attempting to release() after count has reached limit suspends the calling greenthread until count becomes less than limit again.

This has the same API as threading.Semaphore, though its semantics and behavior differ subtly due to the upper limit on calls to release(). It is not compatible with threading.BoundedSemaphore because it blocks when reaching limit instead of raising a ValueError.

It is a context manager, and thus can be used in a with block:

sem = CappedSemaphore(2)
with sem:
  do_some_stuff()
acquire(blocking=True)

Acquire a semaphore.

When invoked without arguments: if the internal counter is larger than zero on entry, decrement it by one and return immediately. If it is zero on entry, block, waiting until some other thread has called release() to make it larger than zero. This is done with proper interlocking so that if multiple acquire() calls are blocked, release() will wake exactly one of them up. The implementation may pick one at random, so the order in which blocked threads are awakened should not be relied on. There is no return value in this case.

When invoked with blocking set to true, do the same thing as when called without arguments, and return true.

When invoked with blocking set to false, do not block. If a call without an argument would block, return false immediately; otherwise, do the same thing as when called without arguments, and return true.

property balance

An integer value that represents how many new calls to acquire() or release() would be needed to get the counter to 0. If it is positive, then its value is the number of acquires that can happen before the next acquire would block. If it is negative, it is the negative of the number of releases that would be required in order to make the counter 0 again (one more release would push the counter to 1 and unblock acquirers). It takes into account how many greenthreads are currently blocking in acquire() and release().

bounded()

Returns true if a call to release would block.

locked()

Returns true if a call to acquire would block.

release(blocking=True)

Release a semaphore. In this class, this behaves very much like an acquire() but in the opposite direction.

Imagine the docs of acquire() here, but with every direction reversed. When calling this method, it will block if the internal counter is greater than or equal to limit.

class eventlet.semaphore.Semaphore(value=1)

Bases: object

An unbounded semaphore. Optionally initialize with a resource count, then acquire() and release() resources as needed. Attempting to acquire() when count is zero suspends the calling greenthread until count becomes nonzero again.

This is API-compatible with threading.Semaphore.

It is a context manager, and thus can be used in a with block:

sem = Semaphore(2)
with sem:
  do_some_stuff()

If not specified, value defaults to 1.

It is possible to limit acquire time:

sem = Semaphore()
ok = sem.acquire(timeout=0.1)
# True if acquired, False if timed out.
acquire(blocking=True, timeout=None)

Acquire a semaphore.

When invoked without arguments: if the internal counter is larger than zero on entry, decrement it by one and return immediately. If it is zero on entry, block, waiting until some other thread has called release() to make it larger than zero. This is done with proper interlocking so that if multiple acquire() calls are blocked, release() will wake exactly one of them up. The implementation may pick one at random, so the order in which blocked threads are awakened should not be relied on. There is no return value in this case.

When invoked with blocking set to true, do the same thing as when called without arguments, and return true.

When invoked with blocking set to false, do not block. If a call without an argument would block, return false immediately; otherwise, do the same thing as when called without arguments, and return true.

Timeout value must be strictly positive.

property balance

An integer value that represents how many new calls to acquire() or release() would be needed to get the counter to 0. If it is positive, then its value is the number of acquires that can happen before the next acquire would block. If it is negative, it is the negative of the number of releases that would be required in order to make the counter 0 again (one more release would push the counter to 1 and unblock acquirers). It takes into account how many greenthreads are currently blocking in acquire().

bounded()

Returns False; for consistency with CappedSemaphore.

locked()

Returns true if a call to acquire would block.

release(blocking=True)

Release a semaphore, incrementing the internal counter by one. When it was zero on entry and another thread is waiting for it to become larger than zero again, wake up that thread.

The blocking argument is for consistency with CappedSemaphore and is ignored

eventlet.timeout module

exception eventlet.timeout.Timeout(seconds=None, exception=None)

Bases: BaseException

Raises exception in the current greenthread after timeout seconds.

When exception is omitted or None, the Timeout instance itself is raised. If seconds is None, the timer is not scheduled, and is only useful if you’re planning to raise it directly.

Timeout objects are context managers, and so can be used in with statements. When used in a with statement, if exception is False, the timeout is still raised, but the context manager suppresses it, so the code outside the with-block won’t see it.

cancel()

If the timeout is pending, cancel it. If not using Timeouts in with statements, always call cancel() in a finally after the block of code that is getting timed out. If not canceled, the timeout will be raised later on, in some unexpected section of the application.

property is_timeout
property pending

True if the timeout is scheduled to be raised.

start()

Schedule the timeout. This is called on construction, so it should not be called explicitly, unless the timer has been canceled.

eventlet.timeout.is_timeout(obj)
eventlet.timeout.with_timeout(seconds, function, *args, **kwds)

Wrap a call to some (yielding) function with a timeout; if the called function fails to return before the timeout, cancel it and return a flag value.

eventlet.timeout.wrap_is_timeout(base)

Adds .is_timeout=True attribute to objects returned by base().

When base is class, attribute is added as read-only property. Returns base. Otherwise, it returns a function that sets attribute on result of base() call.

Wrappers make best effort to be transparent.

eventlet.tpool module

class eventlet.tpool.Proxy(obj, autowrap=(), autowrap_names=())

Bases: object

a simple proxy-wrapper of any object that comes with a methods-only interface, in order to forward every method invocation onto a thread in the native-thread pool. A key restriction is that the object’s methods should not switch greenlets or use Eventlet primitives, since they are in a different thread from the main hub, and therefore might behave unexpectedly. This is for running native-threaded code only.

It’s common to want to have some of the attributes or return values also wrapped in Proxy objects (for example, database connection objects produce cursor objects which also should be wrapped in Proxy objects to remain nonblocking). autowrap, if supplied, is a collection of types; if an attribute or return value matches one of those types (via isinstance), it will be wrapped in a Proxy. autowrap_names is a collection of strings, which represent the names of attributes that should be wrapped in Proxy objects when accessed.

next()
eventlet.tpool.execute(meth, *args, **kwargs)

Execute meth in a Python thread, blocking the current coroutine/ greenthread until the method completes.

The primary use case for this is to wrap an object or module that is not amenable to monkeypatching or any of the other tricks that Eventlet uses to achieve cooperative yielding. With tpool, you can force such objects to cooperate with green threads by sticking them in native threads, at the cost of some overhead.

eventlet.tpool.killall()
eventlet.tpool.set_num_threads(nthreads)

eventlet.websocket module

class eventlet.websocket.WebSocket(sock, environ, version=76)

Bases: object

A websocket object that handles the details of serialization/deserialization to the socket.

The primary way to interact with a WebSocket object is to call send() and wait() in order to pass messages back and forth with the browser. Also available are the following properties:

path

The path value of the request. This is the same as the WSGI PATH_INFO variable, but more convenient.

protocol

The value of the Websocket-Protocol header.

origin

The value of the ‘Origin’ header.

environ

The full WSGI environment for this request.

close()

Forcibly close the websocket; generally it is preferable to return from the handler method.

send(message)

Send a message to the browser.

message should be convertable to a string; unicode objects should be encodable as utf-8. Raises socket.error with errno of 32 (broken pipe) if the socket has already been closed by the client.

wait()

Waits for and deserializes messages.

Returns a single message; the oldest not yet processed. If the client has already closed the connection, returns None. This is different from normal socket behavior because the empty string is a valid websocket message.

class eventlet.websocket.WebSocketWSGI(handler, max_frame_length=8388608)

Bases: object

Wraps a websocket handler function in a WSGI application.

Use it like this:

@websocket.WebSocketWSGI
def my_handler(ws):
    from_browser = ws.wait()
    ws.send("from server")

The single argument to the function will be an instance of WebSocket. To close the socket, simply return from the function. Note that the server will log the websocket request at the time of closure.

An optional argument max_frame_length can be given, which will set the maximum incoming uncompressed payload length of a frame. By default, this is set to 8MiB. Note that excessive values here might create a DOS attack vector.

classmethod configured(handler=None, supported_protocols=None, origin_checker=None, support_legacy_versions=False)

eventlet.wsgi module

eventlet.wsgi.format_date_time(timestamp)

Formats a unix timestamp into an HTTP standard string.

eventlet.wsgi.server(sock, site, log=None, environ=None, max_size=None, max_http_version='HTTP/1.1', protocol=<class 'eventlet.wsgi.HttpProtocol'>, server_event=None, minimum_chunk_size=None, log_x_forwarded_for=True, custom_pool=None, keepalive=True, log_output=True, log_format='%(client_ip)s - - [%(date_time)s] "%(request_line)s" %(status_code)s %(body_length)s %(wall_seconds).6f', url_length_limit=8192, debug=True, socket_timeout=None, capitalize_response_headers=True)

Start up a WSGI server handling requests from the supplied server socket. This function loops forever. The sock object will be closed after server exits, but the underlying file descriptor will remain open, so if you have a dup() of sock, it will remain usable.

Warning

At the moment server() will always wait for active connections to finish before exiting, even if there’s an exception raised inside it (all exceptions are handled the same way, including greenlet.GreenletExit and those inheriting from BaseException).

While this may not be an issue normally, when it comes to long running HTTP connections (like eventlet.websocket) it will become problematic and calling wait() on a thread that runs the server may hang, even after using kill(), as long as there are active connections.

Parameters:

  • sock – Server socket, must be already bound to a port and listening.

  • site – WSGI application function.

  • log – logging.Logger instance or file-like object that logs should be written to. If a Logger instance is supplied, messages are sent to the INFO log level. If not specified, sys.stderr is used.

  • environ – Additional parameters that go into the environ dictionary of every request.

  • max_size – Maximum number of client connections opened at any time by this server. Default is 1024.

  • max_http_version – Set to “HTTP/1.0” to make the server pretend it only supports HTTP 1.0. This can help with applications or clients that don’t behave properly using HTTP 1.1.

  • protocol – Protocol class. Deprecated.

  • server_event – Used to collect the Server object. Deprecated.

  • minimum_chunk_size – Minimum size in bytes for http chunks. This can be used to improve performance of applications which yield many small strings, though using it technically violates the WSGI spec. This can be overridden on a per request basis by setting environ[‘eventlet.minimum_write_chunk_size’].

  • log_x_forwarded_for – If True (the default), logs the contents of the x-forwarded-for header in addition to the actual client ip address in the ‘client_ip’ field of the log line.

  • custom_pool – A custom GreenPool instance which is used to spawn client green threads. If this is supplied, max_size is ignored.

  • keepalive – If set to False or zero, disables keepalives on the server; all connections will be closed after serving one request. If numeric, it will be the timeout used when reading the next request.

  • log_output – A Boolean indicating if the server will log data or not.

  • log_format – A python format string that is used as the template to generate log lines. The following values can be formatted into it: client_ip, date_time, request_line, status_code, body_length, wall_seconds. The default is a good example of how to use it.

  • url_length_limit – A maximum allowed length of the request url. If exceeded, 414 error is returned.

  • debug – True if the server should send exception tracebacks to the clients on 500 errors. If False, the server will respond with empty bodies.

  • socket_timeout – Timeout for client connections’ socket operations. Default None means wait forever.

  • capitalize_response_headers – Normalize response headers’ names to Foo-Bar. Default is True.

Module contents