💾 Archived View for tris.fyi › pydoc › asyncio captured on 2022-07-16 at 14:53:14. Gemini links have been rewritten to link to archived content
⬅️ Previous capture (2022-04-28)
-=-=-=-=-=-=-
The asyncio package, tracking PEP 3156.
Abstract base class for monitoring child processes.
Objects derived from this class monitor a collection of subprocesses and
report their termination or interruption by a signal.
New callbacks are registered with .add_child_handler(). Starting a new
process must be done within a 'with' block to allow the watcher to suspend
its activity until the new process if fully registered (this is needed to
prevent a race condition in some implementations).
Example:
with watcher:
proc = subprocess.Popen("sleep 1")
watcher.add_child_handler(proc.pid, callback)
Notes:
Implementations of this class must be thread-safe.
Since child watcher objects may catch the SIGCHLD signal and call
waitpid(-1), there should be only one active object per process.
add_child_handler(self, pid, callback, *args)
Register a new child handler.
Arrange for callback(pid, returncode, *args) to be called when
process 'pid' terminates. Specifying another callback for the same
process replaces the previous handler.
Note: callback() must be thread-safe.
attach_loop(self, loop)
Attach the watcher to an event loop.
If the watcher was previously attached to an event loop, then it is
first detached before attaching to the new loop.
Note: loop may be None.
close(self)
Close the watcher.
This must be called to make sure that any underlying resource is freed.
is_active(self)
Return ``True`` if the watcher is active and is used by the event loop.
Return True if the watcher is installed and ready to handle process exit
notifications.
remove_child_handler(self, pid)
Removes the handler for process 'pid'.
The function returns True if the handler was successfully removed,
False if there was nothing to remove.
Abstract event loop.
add_reader(self, fd, callback, *args)
add_signal_handler(self, sig, callback, *args)
add_writer(self, fd, callback, *args)
call_at(self, when, callback, *args, context=None)
call_exception_handler(self, context)
call_later(self, delay, callback, *args, context=None)
call_soon(self, callback, *args, context=None)
call_soon_threadsafe(self, callback, *args, context=None)
close(self)
Close the loop.
The loop should not be running.
This is idempotent and irreversible.
No other methods should be called after this one.
connect_read_pipe(self, protocol_factory, pipe)
Register read pipe in event loop. Set the pipe to non-blocking mode.
protocol_factory should instantiate object with Protocol interface.
pipe is a file-like object.
Return pair (transport, protocol), where transport supports the
ReadTransport interface.
connect_write_pipe(self, protocol_factory, pipe)
Register write pipe in event loop.
protocol_factory should instantiate object with BaseProtocol interface.
Pipe is file-like object already switched to nonblocking.
Return pair (transport, protocol), where transport support
WriteTransport interface.
create_connection(self, protocol_factory, host=None, port=None, *, ssl=None, family=0, proto=0, flags=0, sock=None, local_addr=None, server_hostname=None, ssl_handshake_timeout=None, happy_eyeballs_delay=None, interleave=None)
create_datagram_endpoint(self, protocol_factory, local_addr=None, remote_addr=None, *, family=0, proto=0, flags=0, reuse_address=None, reuse_port=None, allow_broadcast=None, sock=None)
A coroutine which creates a datagram endpoint.
This method will try to establish the endpoint in the background.
When successful, the coroutine returns a (transport, protocol) pair.
protocol_factory must be a callable returning a protocol instance.
socket family AF_INET, socket.AF_INET6 or socket.AF_UNIX depending on
host (or family if specified), socket type SOCK_DGRAM.
reuse_address tells the kernel to reuse a local socket in
TIME_WAIT state, without waiting for its natural timeout to
expire. If not specified it will automatically be set to True on
UNIX.
reuse_port tells the kernel to allow this endpoint to be bound to
the same port as other existing endpoints are bound to, so long as
they all set this flag when being created. This option is not
supported on Windows and some UNIX's. If the
:py:data:`~socket.SO_REUSEPORT` constant is not defined then this
capability is unsupported.
allow_broadcast tells the kernel to allow this endpoint to send
messages to the broadcast address.
sock can optionally be specified in order to use a preexisting
socket object.
create_future(self)
create_server(self, protocol_factory, host=None, port=None, *, family=<AddressFamily.AF_UNSPEC: 0>, flags=<AddressInfo.AI_PASSIVE: 1>, sock=None, backlog=100, ssl=None, reuse_address=None, reuse_port=None, ssl_handshake_timeout=None, start_serving=True)
A coroutine which creates a TCP server bound to host and port.
The return value is a Server object which can be used to stop
the service.
If host is an empty string or None all interfaces are assumed
and a list of multiple sockets will be returned (most likely
one for IPv4 and another one for IPv6). The host parameter can also be
a sequence (e.g. list) of hosts to bind to.
family can be set to either AF_INET or AF_INET6 to force the
socket to use IPv4 or IPv6. If not set it will be determined
from host (defaults to AF_UNSPEC).
flags is a bitmask for getaddrinfo().
sock can optionally be specified in order to use a preexisting
socket object.
backlog is the maximum number of queued connections passed to
listen() (defaults to 100).
ssl can be set to an SSLContext to enable SSL over the
accepted connections.
reuse_address tells the kernel to reuse a local socket in
TIME_WAIT state, without waiting for its natural timeout to
expire. If not specified will automatically be set to True on
UNIX.
reuse_port tells the kernel to allow this endpoint to be bound to
the same port as other existing endpoints are bound to, so long as
they all set this flag when being created. This option is not
supported on Windows.
ssl_handshake_timeout is the time in seconds that an SSL server
will wait for completion of the SSL handshake before aborting the
connection. Default is 60s.
start_serving set to True (default) causes the created server
to start accepting connections immediately. When set to False,
the user should await Server.start_serving() or Server.serve_forever()
to make the server to start accepting connections.
create_task(self, coro, *, name=None)
create_unix_connection(self, protocol_factory, path=None, *, ssl=None, sock=None, server_hostname=None, ssl_handshake_timeout=None)
create_unix_server(self, protocol_factory, path=None, *, sock=None, backlog=100, ssl=None, ssl_handshake_timeout=None, start_serving=True)
A coroutine which creates a UNIX Domain Socket server.
The return value is a Server object, which can be used to stop
the service.
path is a str, representing a file system path to bind the
server socket to.
sock can optionally be specified in order to use a preexisting
socket object.
backlog is the maximum number of queued connections passed to
listen() (defaults to 100).
ssl can be set to an SSLContext to enable SSL over the
accepted connections.
ssl_handshake_timeout is the time in seconds that an SSL server
will wait for the SSL handshake to complete (defaults to 60s).
start_serving set to True (default) causes the created server
to start accepting connections immediately. When set to False,
the user should await Server.start_serving() or Server.serve_forever()
to make the server to start accepting connections.
default_exception_handler(self, context)
get_debug(self)
get_exception_handler(self)
get_task_factory(self)
getaddrinfo(self, host, port, *, family=0, type=0, proto=0, flags=0)
getnameinfo(self, sockaddr, flags=0)
is_closed(self) Returns True if the event loop was closed.
is_running(self) Return whether the event loop is currently running.
remove_reader(self, fd)
remove_signal_handler(self, sig)
remove_writer(self, fd)
run_forever(self) Run the event loop until stop() is called.
run_in_executor(self, executor, func, *args)
run_until_complete(self, future)
Run the event loop until a Future is done.
Return the Future's result, or raise its exception.
sendfile(self, transport, file, offset=0, count=None, *, fallback=True)
Send a file through a transport.
Return an amount of sent bytes.
set_debug(self, enabled)
set_default_executor(self, executor)
set_exception_handler(self, handler)
set_task_factory(self, factory)
shutdown_asyncgens(self) Shutdown all active asynchronous generators.
shutdown_default_executor(self) Schedule the shutdown of the default executor.
sock_accept(self, sock)
sock_connect(self, sock, address)
sock_recv(self, sock, nbytes)
sock_recv_into(self, sock, buf)
sock_sendall(self, sock, data)
sock_sendfile(self, sock, file, offset=0, count=None, *, fallback=None)
start_tls(self, transport, protocol, sslcontext, *, server_side=False, server_hostname=None, ssl_handshake_timeout=None)
Upgrade a transport to TLS.
Return a new transport that *protocol* should start using
immediately.
stop(self)
Stop the event loop as soon as reasonable.
Exactly how soon that is may depend on the implementation, but
no more I/O callbacks should be scheduled.
subprocess_exec(self, protocol_factory, *args, stdin=-1, stdout=-1, stderr=-1, **kwargs)
subprocess_shell(self, protocol_factory, cmd, *, stdin=-1, stdout=-1, stderr=-1, **kwargs)
time(self)
Abstract policy for accessing the event loop.
get_child_watcher(self) Get the watcher for child processes.
get_event_loop(self)
Get the event loop for the current context.
Returns an event loop object implementing the BaseEventLoop interface,
or raises an exception in case no event loop has been set for the
current context and the current policy does not specify to create one.
It should never return None.
new_event_loop(self)
Create and return a new event loop object according to this
policy's rules. If there's need to set this loop as the event loop for
the current context, set_event_loop must be called explicitly.
set_child_watcher(self, watcher) Set the watcher for child processes.
set_event_loop(self, loop) Set the event loop for the current context to loop.
Abstract server returned by create_server().
close(self) Stop serving. This leaves existing connections open.
get_loop(self) Get the event loop the Server object is attached to.
is_serving(self) Return True if the server is accepting connections.
serve_forever(self)
Start accepting connections until the coroutine is cancelled.
The server is closed when the coroutine is cancelled.
start_serving(self)
Start accepting connections.
This method is idempotent, so it can be called when
the server is already being serving.
wait_closed(self) Coroutine to wait until service is closed.
add_reader(self, fd, callback, *args)
add_signal_handler(self, sig, callback, *args)
add_writer(self, fd, callback, *args)
call_at(self, when, callback, *args, context=None)
Like call_later(), but uses an absolute time.
Absolute time corresponds to the event loop's time() method.
call_exception_handler(self, context)
Call the current event loop's exception handler.
The context argument is a dict containing the following keys:
- 'message': Error message;
- 'exception' (optional): Exception object;
- 'future' (optional): Future instance;
- 'task' (optional): Task instance;
- 'handle' (optional): Handle instance;
- 'protocol' (optional): Protocol instance;
- 'transport' (optional): Transport instance;
- 'socket' (optional): Socket instance;
- 'asyncgen' (optional): Asynchronous generator that caused
the exception.
New keys maybe introduced in the future.
Note: do not overload this method in an event loop subclass.
For custom exception handling, use the
`set_exception_handler()` method.
call_later(self, delay, callback, *args, context=None)
Arrange for a callback to be called at a given time.
Return a Handle: an opaque object with a cancel() method that
can be used to cancel the call.
The delay can be an int or float, expressed in seconds. It is
always relative to the current time.
Each callback will be called exactly once. If two callbacks
are scheduled for exactly the same time, it undefined which
will be called first.
Any positional arguments after the callback will be passed to
the callback when it is called.
call_soon(self, callback, *args, context=None)
Arrange for a callback to be called as soon as possible.
This operates as a FIFO queue: callbacks are called in the
order in which they are registered. Each callback will be
called exactly once.
Any positional arguments after the callback will be passed to
the callback when it is called.
call_soon_threadsafe(self, callback, *args, context=None) Like call_soon(), but thread-safe.
close(self)
Close the event loop.
This clears the queues and shuts down the executor,
but does not wait for the executor to finish.
The event loop must not be running.
connect_accepted_socket(self, protocol_factory, sock, *, ssl=None, ssl_handshake_timeout=None)
Handle an accepted connection.
This is used by servers that accept connections outside of
asyncio but that use asyncio to handle connections.
This method is a coroutine. When completed, the coroutine
returns a (transport, protocol) pair.
connect_read_pipe(self, protocol_factory, pipe)
connect_write_pipe(self, protocol_factory, pipe)
create_connection(self, protocol_factory, host=None, port=None, *, ssl=None, family=0, proto=0, flags=0, sock=None, local_addr=None, server_hostname=None, ssl_handshake_timeout=None, happy_eyeballs_delay=None, interleave=None)
Connect to a TCP server.
Create a streaming transport connection to a given Internet host and
port: socket family AF_INET or socket.AF_INET6 depending on host (or
family if specified), socket type SOCK_STREAM. protocol_factory must be
a callable returning a protocol instance.
This method is a coroutine which will try to establish the connection
in the background. When successful, the coroutine returns a
(transport, protocol) pair.
create_datagram_endpoint(self, protocol_factory, local_addr=None, remote_addr=None, *, family=0, proto=0, flags=0, reuse_address=<object object at 0x7f92bfcfeb40>, reuse_port=None, allow_broadcast=None, sock=None) Create datagram connection.
create_future(self) Create a Future object attached to the loop.
create_server(self, protocol_factory, host=None, port=None, *, family=<AddressFamily.AF_UNSPEC: 0>, flags=<AddressInfo.AI_PASSIVE: 1>, sock=None, backlog=100, ssl=None, reuse_address=None, reuse_port=None, ssl_handshake_timeout=None, start_serving=True)
Create a TCP server.
The host parameter can be a string, in that case the TCP server is
bound to host and port.
The host parameter can also be a sequence of strings and in that case
the TCP server is bound to all hosts of the sequence. If a host
appears multiple times (possibly indirectly e.g. when hostnames
resolve to the same IP address), the server is only bound once to that
host.
Return a Server object which can be used to stop the service.
This method is a coroutine.
create_task(self, coro, *, name=None)
Schedule a coroutine object.
Return a task object.
create_unix_connection(self, protocol_factory, path=None, *, ssl=None, sock=None, server_hostname=None, ssl_handshake_timeout=None)
create_unix_server(self, protocol_factory, path=None, *, sock=None, backlog=100, ssl=None, ssl_handshake_timeout=None, start_serving=True)
A coroutine which creates a UNIX Domain Socket server.
The return value is a Server object, which can be used to stop
the service.
path is a str, representing a file system path to bind the
server socket to.
sock can optionally be specified in order to use a preexisting
socket object.
backlog is the maximum number of queued connections passed to
listen() (defaults to 100).
ssl can be set to an SSLContext to enable SSL over the
accepted connections.
ssl_handshake_timeout is the time in seconds that an SSL server
will wait for the SSL handshake to complete (defaults to 60s).
start_serving set to True (default) causes the created server
to start accepting connections immediately. When set to False,
the user should await Server.start_serving() or Server.serve_forever()
to make the server to start accepting connections.
default_exception_handler(self, context)
Default exception handler.
This is called when an exception occurs and no exception
handler is set, and can be called by a custom exception
handler that wants to defer to the default behavior.
This default handler logs the error message and other
context-dependent information. In debug mode, a truncated
stack trace is also appended showing where the given object
(e.g. a handle or future or task) was created, if any.
The context parameter has the same meaning as in
`call_exception_handler()`.
get_debug(self)
get_exception_handler(self)
Return an exception handler, or None if the default one is in use.
get_task_factory(self) Return a task factory, or None if the default one is in use.
getaddrinfo(self, host, port, *, family=0, type=0, proto=0, flags=0)
getnameinfo(self, sockaddr, flags=0)
is_closed(self) Returns True if the event loop was closed.
is_running(self) Returns True if the event loop is running.
remove_reader(self, fd)
remove_signal_handler(self, sig)
remove_writer(self, fd)
run_forever(self) Run until stop() is called.
run_in_executor(self, executor, func, *args)
run_until_complete(self, future)
Run until the Future is done.
If the argument is a coroutine, it is wrapped in a Task.
WARNING: It would be disastrous to call run_until_complete()
with the same coroutine twice -- it would wrap it in two
different Tasks and that can't be good.
Return the Future's result, or raise its exception.
sendfile(self, transport, file, offset=0, count=None, *, fallback=True)
Send a file to transport.
Return the total number of bytes which were sent.
The method uses high-performance os.sendfile if available.
file must be a regular file object opened in binary mode.
offset tells from where to start reading the file. If specified,
count is the total number of bytes to transmit as opposed to
sending the file until EOF is reached. File position is updated on
return or also in case of error in which case file.tell()
can be used to figure out the number of bytes
which were sent.
fallback set to True makes asyncio to manually read and send
the file when the platform does not support the sendfile syscall
(e.g. Windows or SSL socket on Unix).
Raise SendfileNotAvailableError if the system does not support
sendfile syscall and fallback is False.
set_debug(self, enabled)
set_default_executor(self, executor)
set_exception_handler(self, handler)
Set handler as the new event loop exception handler.
If handler is None, the default exception handler will
be set.
If handler is a callable object, it should have a
signature matching '(loop, context)', where 'loop'
will be a reference to the active event loop, 'context'
will be a dict object (see `call_exception_handler()`
documentation for details about context).
set_task_factory(self, factory)
Set a task factory that will be used by loop.create_task().
If factory is None the default task factory will be set.
If factory is a callable, it should have a signature matching
'(loop, coro)', where 'loop' will be a reference to the active
event loop, 'coro' will be a coroutine object. The callable
must return a Future.
shutdown_asyncgens(self) Shutdown all active asynchronous generators.
shutdown_default_executor(self) Schedule the shutdown of the default executor.
sock_accept(self, sock)
sock_connect(self, sock, address)
sock_recv(self, sock, nbytes)
sock_recv_into(self, sock, buf)
sock_sendall(self, sock, data)
sock_sendfile(self, sock, file, offset=0, count=None, *, fallback=True)
start_tls(self, transport, protocol, sslcontext, *, server_side=False, server_hostname=None, ssl_handshake_timeout=None)
Upgrade transport to TLS.
Return a new transport that *protocol* should start using
immediately.
stop(self)
Stop running the event loop.
Every callback already scheduled will still run. This simply informs
run_forever to stop looping after a complete iteration.
subprocess_exec(self, protocol_factory, program, *args, stdin=-1, stdout=-1, stderr=-1, universal_newlines=False, shell=False, bufsize=0, encoding=None, errors=None, text=None, **kwargs)
subprocess_shell(self, protocol_factory, cmd, *, stdin=-1, stdout=-1, stderr=-1, universal_newlines=False, shell=True, bufsize=0, encoding=None, errors=None, text=None, **kwargs)
time(self)
Return the time according to the event loop's clock.
This is a float expressed in seconds since an epoch, but the
epoch, precision, accuracy and drift are unspecified and may
differ per event loop.
Common base class for protocol interfaces.
Usually user implements protocols that derived from BaseProtocol
like Protocol or ProcessProtocol.
The only case when BaseProtocol should be implemented directly is
write-only transport like write pipe
connection_lost(self, exc)
Called when the connection is lost or closed.
The argument is an exception object or None (the latter
meaning a regular EOF is received or the connection was
aborted or closed).
connection_made(self, transport)
Called when a connection is made.
The argument is the transport representing the pipe connection.
To receive data, wait for data_received() calls.
When the connection is closed, connection_lost() is called.
pause_writing(self)
Called when the transport's buffer goes over the high-water mark.
Pause and resume calls are paired -- pause_writing() is called
once when the buffer goes strictly over the high-water mark
(even if subsequent writes increases the buffer size even
more), and eventually resume_writing() is called once when the
buffer size reaches the low-water mark.
Note that if the buffer size equals the high-water mark,
pause_writing() is not called -- it must go strictly over.
Conversely, resume_writing() is called when the buffer size is
equal or lower than the low-water mark. These end conditions
are important to ensure that things go as expected when either
mark is zero.
NOTE: This is the only Protocol callback that is not called
through EventLoop.call_soon() -- if it were, it would have no
effect when it's most needed (when the app keeps writing
without yielding until pause_writing() is called).
resume_writing(self)
Called when the transport's buffer drains below the low-water mark.
See pause_writing() for details.
Base class for transports.
close(self)
Close the transport.
Buffered data will be flushed asynchronously. No more data
will be received. After all buffered data is flushed, the
protocol's connection_lost() method will (eventually) be
called with None as its argument.
get_extra_info(self, name, default=None) Get optional transport information.
get_protocol(self) Return the current protocol.
is_closing(self) Return True if the transport is closing or closed.
set_protocol(self, protocol) Set a new protocol.
A bounded semaphore implementation.
This raises ValueError in release() if it would increase the value
above the initial value.
acquire(self)
Acquire a semaphore.
If the internal counter is larger than zero on entry,
decrement it by one and return True immediately. If it is
zero on entry, block, waiting until some other coroutine has
called release() to make it larger than 0, and then return
True.
locked(self) Returns True if semaphore can not be acquired immediately.
release(self)
Interface for stream protocol with manual buffer control.
Event methods, such as `create_server` and `create_connection`,
accept factories that return protocols that implement this interface.
The idea of BufferedProtocol is that it allows to manually allocate
and control the receive buffer. Event loops can then use the buffer
provided by the protocol to avoid unnecessary data copies. This
can result in noticeable performance improvement for protocols that
receive big amounts of data. Sophisticated protocols can allocate
the buffer only once at creation time.
State machine of calls:
start -> CM [-> GB [-> BU?]]* [-> ER?] -> CL -> end
* CM: connection_made()
* GB: get_buffer()
* BU: buffer_updated()
* ER: eof_received()
* CL: connection_lost()
buffer_updated(self, nbytes)
Called when the buffer was updated with the received data.
*nbytes* is the total number of bytes that were written to
the buffer.
connection_lost(self, exc)
Called when the connection is lost or closed.
The argument is an exception object or None (the latter
meaning a regular EOF is received or the connection was
aborted or closed).
connection_made(self, transport)
Called when a connection is made.
The argument is the transport representing the pipe connection.
To receive data, wait for data_received() calls.
When the connection is closed, connection_lost() is called.
eof_received(self)
Called when the other end calls write_eof() or equivalent.
If this returns a false value (including None), the transport
will close itself. If it returns a true value, closing the
transport is up to the protocol.
get_buffer(self, sizehint)
Called to allocate a new receive buffer.
*sizehint* is a recommended minimal size for the returned
buffer. When set to -1, the buffer size can be arbitrary.
Must return an object that implements the
:ref:`buffer protocol <bufferobjects>`.
It is an error to return a zero-sized buffer.
pause_writing(self)
Called when the transport's buffer goes over the high-water mark.
Pause and resume calls are paired -- pause_writing() is called
once when the buffer goes strictly over the high-water mark
(even if subsequent writes increases the buffer size even
more), and eventually resume_writing() is called once when the
buffer size reaches the low-water mark.
Note that if the buffer size equals the high-water mark,
pause_writing() is not called -- it must go strictly over.
Conversely, resume_writing() is called when the buffer size is
equal or lower than the low-water mark. These end conditions
are important to ensure that things go as expected when either
mark is zero.
NOTE: This is the only Protocol callback that is not called
through EventLoop.call_soon() -- if it were, it would have no
effect when it's most needed (when the app keeps writing
without yielding until pause_writing() is called).
resume_writing(self)
Called when the transport's buffer drains below the low-water mark.
See pause_writing() for details.
The Future or Task was cancelled.
with_traceback(...)
Exception.with_traceback(tb) --
set self.__traceback__ to tb and return self.
args = <attribute 'args' of 'BaseException' objects>
Asynchronous equivalent to threading.Condition.
This class implements condition variable objects. A condition variable
allows one or more coroutines to wait until they are notified by another
coroutine.
A new Lock object is created and used as the underlying lock.
notify(self, n=1)
By default, wake up one coroutine waiting on this condition, if any.
If the calling coroutine has not acquired the lock when this method
is called, a RuntimeError is raised.
This method wakes up at most n of the coroutines waiting for the
condition variable; it is a no-op if no coroutines are waiting.
Note: an awakened coroutine does not actually return from its
wait() call until it can reacquire the lock. Since notify() does
not release the lock, its caller should.
notify_all(self)
Wake up all threads waiting on this condition. This method acts
like notify(), but wakes up all waiting threads instead of one. If the
calling thread has not acquired the lock when this method is called,
a RuntimeError is raised.
wait(self)
Wait until notified.
If the calling coroutine has not acquired the lock when this
method is called, a RuntimeError is raised.
This method releases the underlying lock, and then blocks
until it is awakened by a notify() or notify_all() call for
the same condition variable in another coroutine. Once
awakened, it re-acquires the lock and returns True.
wait_for(self, predicate)
Wait until a predicate becomes true.
The predicate should be a callable which result will be
interpreted as a boolean value. The final predicate value is
the return value.
Interface for datagram protocol.
connection_lost(self, exc)
Called when the connection is lost or closed.
The argument is an exception object or None (the latter
meaning a regular EOF is received or the connection was
aborted or closed).
connection_made(self, transport)
Called when a connection is made.
The argument is the transport representing the pipe connection.
To receive data, wait for data_received() calls.
When the connection is closed, connection_lost() is called.
datagram_received(self, data, addr) Called when some datagram is received.
error_received(self, exc)
Called when a send or receive operation raises an OSError.
(Other than BlockingIOError or InterruptedError.)
pause_writing(self)
Called when the transport's buffer goes over the high-water mark.
Pause and resume calls are paired -- pause_writing() is called
once when the buffer goes strictly over the high-water mark
(even if subsequent writes increases the buffer size even
more), and eventually resume_writing() is called once when the
buffer size reaches the low-water mark.
Note that if the buffer size equals the high-water mark,
pause_writing() is not called -- it must go strictly over.
Conversely, resume_writing() is called when the buffer size is
equal or lower than the low-water mark. These end conditions
are important to ensure that things go as expected when either
mark is zero.
NOTE: This is the only Protocol callback that is not called
through EventLoop.call_soon() -- if it were, it would have no
effect when it's most needed (when the app keeps writing
without yielding until pause_writing() is called).
resume_writing(self)
Called when the transport's buffer drains below the low-water mark.
See pause_writing() for details.
Interface for datagram (UDP) transports.
abort(self)
Close the transport immediately.
Buffered data will be lost. No more data will be received.
The protocol's connection_lost() method will (eventually) be
called with None as its argument.
close(self)
Close the transport.
Buffered data will be flushed asynchronously. No more data
will be received. After all buffered data is flushed, the
protocol's connection_lost() method will (eventually) be
called with None as its argument.
get_extra_info(self, name, default=None) Get optional transport information.
get_protocol(self) Return the current protocol.
is_closing(self) Return True if the transport is closing or closed.
sendto(self, data, addr=None)
Send data to the transport.
This does not block; it buffers the data and arranges for it
to be sent out asynchronously.
addr is target socket address.
If addr is None use target address pointed on transport creation.
set_protocol(self, protocol) Set a new protocol.
UNIX event loop policy with a watcher for child processes.
get_child_watcher(self)
Get the watcher for child processes.
If not yet set, a ThreadedChildWatcher object is automatically created.
get_event_loop(self)
Get the event loop for the current context.
Returns an instance of EventLoop or raises an exception.
new_event_loop(self)
Create a new event loop.
You must call set_event_loop() to make this the current event
loop.
set_child_watcher(self, watcher) Set the watcher for child processes.
set_event_loop(self, loop)
Set the event loop.
As a side effect, if a child watcher was set before, then calling
.set_event_loop() from the main thread will call .attach_loop(loop) on
the child watcher.
Asynchronous equivalent to threading.Event.
Class implementing event objects. An event manages a flag that can be set
to true with the set() method and reset to false with the clear() method.
The wait() method blocks until the flag is true. The flag is initially
false.
clear(self)
Reset the internal flag to false. Subsequently, coroutines calling
wait() will block until set() is called to set the internal flag
to true again.
is_set(self) Return True if and only if the internal flag is true.
set(self)
Set the internal flag to true. All coroutines waiting for it to
become true are awakened. Coroutine that call wait() once the flag is
true will not block at all.
wait(self)
Block until the internal flag is true.
If the internal flag is true on entry, return True
immediately. Otherwise, block until another coroutine calls
set() to set the flag to true, then return True.
'Fast' child watcher implementation.
This implementation reaps every terminated processes by calling
os.waitpid(-1) directly, possibly breaking other code spawning processes
and waiting for their termination.
There is no noticeable overhead when handling a big number of children
(O(1) each time a child terminates).
add_child_handler(self, pid, callback, *args)
attach_loop(self, loop)
close(self)
is_active(self)
remove_child_handler(self, pid)
This class is *almost* compatible with concurrent.futures.Future.
Differences:
- result() and exception() do not take a timeout argument and
raise an exception when the future isn't done yet.
- Callbacks registered with add_done_callback() are always called
via the event loop's call_soon_threadsafe().
- This class is not compatible with the wait() and as_completed()
methods in the concurrent.futures package.
add_done_callback(...) Add a callback to be run when the future becomes done. The callback is called with a single argument - the future object. If the future is already done when this is called, the callback is scheduled with call_soon.
cancel(self, /, msg=None) Cancel the future and schedule callbacks. If the future is already done or cancelled, return False. Otherwise, change the future's state to cancelled, schedule the callbacks and return True.
cancelled(self, /) Return True if the future was cancelled.
done(self, /) Return True if the future is done. Done means either that a result / exception are available, or that the future was cancelled.
exception(self, /) Return the exception that was set on this future. The exception (or None if no exception was set) is returned only if the future is done. If the future has been cancelled, raises CancelledError. If the future isn't done yet, raises InvalidStateError.
get_loop(self, /) Return the event loop the Future is bound to.
remove_done_callback(self, fn, /) Remove all instances of a callback from the "call when done" list. Returns the number of callbacks removed.
result(self, /) Return the result this future represents. If the future has been cancelled, raises CancelledError. If the future's result isn't yet available, raises InvalidStateError. If the future is done and has an exception set, this exception is raised.
set_exception(self, exception, /) Mark the future done and set an exception. If the future is already done when this method is called, raises InvalidStateError.
set_result(self, result, /) Mark the future done and set its result. If the future is already done when this method is called, raises InvalidStateError.
Object returned by callback registration methods.
cancel(self)
cancelled(self)
Incomplete read error. Attributes:
- partial: read bytes string before the end of stream was reached
- expected: total number of expected bytes (or None if unknown)
with_traceback(...)
Exception.with_traceback(tb) --
set self.__traceback__ to tb and return self.
args = <attribute 'args' of 'BaseException' objects>
The operation is not allowed in this state.
with_traceback(...)
Exception.with_traceback(tb) --
set self.__traceback__ to tb and return self.
args = <attribute 'args' of 'BaseException' objects>
A subclass of Queue that retrieves most recently added entries first.
empty(self) Return True if the queue is empty, False otherwise.
full(self)
Return True if there are maxsize items in the queue.
Note: if the Queue was initialized with maxsize=0 (the default),
then full() is never True.
get(self)
Remove and return an item from the queue.
If queue is empty, wait until an item is available.
get_nowait(self)
Remove and return an item from the queue.
Return an item if one is immediately available, else raise QueueEmpty.
join(self)
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 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.
put(self, item)
Put an item into the queue.
Put an item into the queue. If the queue is full, wait until a free
slot is available before adding item.
put_nowait(self, item)
Put an item into the queue without blocking.
If no free slot is immediately available, raise QueueFull.
qsize(self) Number of items in the queue.
task_done(self)
Indicate that a formerly enqueued task is complete.
Used by queue consumers. 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 ValueError if called more times than there were items placed in
the queue.
maxsize = <property object at 0x7f92bf3d6cc0> Number of items allowed in the queue.
Reached the buffer limit while looking for a separator.
Attributes:
- consumed: total number of to be consumed bytes.
with_traceback(...)
Exception.with_traceback(tb) --
set self.__traceback__ to tb and return self.
args = <attribute 'args' of 'BaseException' objects>
Primitive lock objects.
A primitive lock is a synchronization primitive that is not owned
by a particular coroutine when locked. A primitive lock is in one
of two states, 'locked' or 'unlocked'.
It is created in the unlocked state. It has two basic methods,
acquire() and release(). When the state is unlocked, acquire()
changes the state to locked and returns immediately. When the
state is locked, acquire() blocks until a call to release() in
another coroutine changes it to unlocked, then the acquire() call
resets it to locked and returns. The release() method should only
be called in the locked state; it changes the state to unlocked
and returns immediately. If an attempt is made to release an
unlocked lock, a RuntimeError will be raised.
When more than one coroutine is blocked in acquire() waiting for
the state to turn to unlocked, only one coroutine proceeds when a
release() call resets the state to unlocked; first coroutine which
is blocked in acquire() is being processed.
acquire() is a coroutine and should be called with 'await'.
Locks also support the asynchronous context management protocol.
'async with lock' statement should be used.
Usage:
lock = Lock()
...
await lock.acquire()
try:
...
finally:
lock.release()
Context manager usage:
lock = Lock()
...
async with lock:
...
Lock objects can be tested for locking state:
if not lock.locked():
await lock.acquire()
else:
# lock is acquired
...
acquire(self)
Acquire a lock.
This method blocks until the lock is unlocked, then sets it to
locked and returns True.
locked(self) Return True if lock is acquired.
release(self)
Release a lock.
When the lock is locked, reset it to unlocked, and return.
If any other coroutines are blocked waiting for the lock to become
unlocked, allow exactly one of them to proceed.
When invoked on an unlocked lock, a RuntimeError is raised.
There is no return value.
A watcher that doesn't require running loop in the main thread.
This implementation registers a SIGCHLD signal handler on
instantiation (which may conflict with other code that
install own handler for this signal).
The solution is safe but it has a significant overhead when
handling a big number of processes (*O(n)* each time a
SIGCHLD is received).
add_child_handler(self, pid, callback, *args)
attach_loop(self, loop)
close(self)
is_active(self)
remove_child_handler(self, pid)
Child watcher implementation using Linux's pid file descriptors.
This child watcher polls process file descriptors (pidfds) to await child
process termination. In some respects, PidfdChildWatcher is a "Goldilocks"
child watcher implementation. It doesn't require signals or threads, doesn't
interfere with any processes launched outside the event loop, and scales
linearly with the number of subprocesses launched by the event loop. The
main disadvantage is that pidfds are specific to Linux, and only work on
recent (5.3+) kernels.
add_child_handler(self, pid, callback, *args)
attach_loop(self, loop)
close(self)
is_active(self)
remove_child_handler(self, pid)
A subclass of Queue; retrieves entries in priority order (lowest first).
Entries are typically tuples of the form: (priority number, data).
empty(self) Return True if the queue is empty, False otherwise.
full(self)
Return True if there are maxsize items in the queue.
Note: if the Queue was initialized with maxsize=0 (the default),
then full() is never True.
get(self)
Remove and return an item from the queue.
If queue is empty, wait until an item is available.
get_nowait(self)
Remove and return an item from the queue.
Return an item if one is immediately available, else raise QueueEmpty.
join(self)
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 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.
put(self, item)
Put an item into the queue.
Put an item into the queue. If the queue is full, wait until a free
slot is available before adding item.
put_nowait(self, item)
Put an item into the queue without blocking.
If no free slot is immediately available, raise QueueFull.
qsize(self) Number of items in the queue.
task_done(self)
Indicate that a formerly enqueued task is complete.
Used by queue consumers. 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 ValueError if called more times than there were items placed in
the queue.
maxsize = <property object at 0x7f92bf3d6cc0> Number of items allowed in the queue.
Interface for stream protocol.
The user should implement this interface. They can inherit from
this class but don't need to. The implementations here do
nothing (they don't raise exceptions).
When the user wants to requests a transport, they pass a protocol
factory to a utility function (e.g., EventLoop.create_connection()).
When the connection is made successfully, connection_made() is
called with a suitable transport object. Then data_received()
will be called 0 or more times with data (bytes) received from the
transport; finally, connection_lost() will be called exactly once
with either an exception object or None as an argument.
State machine of calls:
start -> CM [-> DR*] [-> ER?] -> CL -> end
* CM: connection_made()
* DR: data_received()
* ER: eof_received()
* CL: connection_lost()
connection_lost(self, exc)
Called when the connection is lost or closed.
The argument is an exception object or None (the latter
meaning a regular EOF is received or the connection was
aborted or closed).
connection_made(self, transport)
Called when a connection is made.
The argument is the transport representing the pipe connection.
To receive data, wait for data_received() calls.
When the connection is closed, connection_lost() is called.
data_received(self, data)
Called when some data is received.
The argument is a bytes object.
eof_received(self)
Called when the other end calls write_eof() or equivalent.
If this returns a false value (including None), the transport
will close itself. If it returns a true value, closing the
transport is up to the protocol.
pause_writing(self)
Called when the transport's buffer goes over the high-water mark.
Pause and resume calls are paired -- pause_writing() is called
once when the buffer goes strictly over the high-water mark
(even if subsequent writes increases the buffer size even
more), and eventually resume_writing() is called once when the
buffer size reaches the low-water mark.
Note that if the buffer size equals the high-water mark,
pause_writing() is not called -- it must go strictly over.
Conversely, resume_writing() is called when the buffer size is
equal or lower than the low-water mark. These end conditions
are important to ensure that things go as expected when either
mark is zero.
NOTE: This is the only Protocol callback that is not called
through EventLoop.call_soon() -- if it were, it would have no
effect when it's most needed (when the app keeps writing
without yielding until pause_writing() is called).
resume_writing(self)
Called when the transport's buffer drains below the low-water mark.
See pause_writing() for details.
A queue, useful for coordinating producer and consumer coroutines.
If maxsize is less than or equal to zero, the queue size is infinite. If it
is an integer greater than 0, then "await put()" will block when the
queue reaches maxsize, until an item is removed by get().
Unlike the standard library Queue, you can reliably know this Queue's size
with qsize(), since your single-threaded asyncio application won't be
interrupted between calling qsize() and doing an operation on the Queue.
empty(self) Return True if the queue is empty, False otherwise.
full(self)
Return True if there are maxsize items in the queue.
Note: if the Queue was initialized with maxsize=0 (the default),
then full() is never True.
get(self)
Remove and return an item from the queue.
If queue is empty, wait until an item is available.
get_nowait(self)
Remove and return an item from the queue.
Return an item if one is immediately available, else raise QueueEmpty.
join(self)
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 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.
put(self, item)
Put an item into the queue.
Put an item into the queue. If the queue is full, wait until a free
slot is available before adding item.
put_nowait(self, item)
Put an item into the queue without blocking.
If no free slot is immediately available, raise QueueFull.
qsize(self) Number of items in the queue.
task_done(self)
Indicate that a formerly enqueued task is complete.
Used by queue consumers. 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 ValueError if called more times than there were items placed in
the queue.
maxsize = <property object at 0x7f92bf3d6cc0> Number of items allowed in the queue.
Raised when Queue.get_nowait() is called on an empty Queue.
with_traceback(...)
Exception.with_traceback(tb) --
set self.__traceback__ to tb and return self.
args = <attribute 'args' of 'BaseException' objects>
Raised when the Queue.put_nowait() method is called on a full Queue.
with_traceback(...)
Exception.with_traceback(tb) --
set self.__traceback__ to tb and return self.
args = <attribute 'args' of 'BaseException' objects>
Interface for read-only transports.
close(self)
Close the transport.
Buffered data will be flushed asynchronously. No more data
will be received. After all buffered data is flushed, the
protocol's connection_lost() method will (eventually) be
called with None as its argument.
get_extra_info(self, name, default=None) Get optional transport information.
get_protocol(self) Return the current protocol.
is_closing(self) Return True if the transport is closing or closed.
is_reading(self) Return True if the transport is receiving.
pause_reading(self)
Pause the receiving end.
No data will be passed to the protocol's data_received()
method until resume_reading() is called.
resume_reading(self)
Resume the receiving end.
Data received will once again be passed to the protocol's
data_received() method.
set_protocol(self, protocol) Set a new protocol.
'Safe' child watcher implementation.
This implementation avoids disrupting other code spawning processes by
polling explicitly each process in the SIGCHLD handler instead of calling
os.waitpid(-1).
This is a safe solution but it has a significant overhead when handling a
big number of children (O(n) each time SIGCHLD is raised)
add_child_handler(self, pid, callback, *args)
attach_loop(self, loop)
close(self)
is_active(self)
remove_child_handler(self, pid)
Unix event loop.
Adds signal handling and UNIX Domain Socket support to SelectorEventLoop.
add_reader(self, fd, callback, *args) Add a reader callback.
add_signal_handler(self, sig, callback, *args)
Add a handler for a signal. UNIX only.
Raise ValueError if the signal number is invalid or uncatchable.
Raise RuntimeError if there is a problem setting up the handler.
add_writer(self, fd, callback, *args) Add a writer callback..
call_at(self, when, callback, *args, context=None)
Like call_later(), but uses an absolute time.
Absolute time corresponds to the event loop's time() method.
call_exception_handler(self, context)
Call the current event loop's exception handler.
The context argument is a dict containing the following keys:
- 'message': Error message;
- 'exception' (optional): Exception object;
- 'future' (optional): Future instance;
- 'task' (optional): Task instance;
- 'handle' (optional): Handle instance;
- 'protocol' (optional): Protocol instance;
- 'transport' (optional): Transport instance;
- 'socket' (optional): Socket instance;
- 'asyncgen' (optional): Asynchronous generator that caused
the exception.
New keys maybe introduced in the future.
Note: do not overload this method in an event loop subclass.
For custom exception handling, use the
`set_exception_handler()` method.
call_later(self, delay, callback, *args, context=None)
Arrange for a callback to be called at a given time.
Return a Handle: an opaque object with a cancel() method that
can be used to cancel the call.
The delay can be an int or float, expressed in seconds. It is
always relative to the current time.
Each callback will be called exactly once. If two callbacks
are scheduled for exactly the same time, it undefined which
will be called first.
Any positional arguments after the callback will be passed to
the callback when it is called.
call_soon(self, callback, *args, context=None)
Arrange for a callback to be called as soon as possible.
This operates as a FIFO queue: callbacks are called in the
order in which they are registered. Each callback will be
called exactly once.
Any positional arguments after the callback will be passed to
the callback when it is called.
call_soon_threadsafe(self, callback, *args, context=None) Like call_soon(), but thread-safe.
close(self)
connect_accepted_socket(self, protocol_factory, sock, *, ssl=None, ssl_handshake_timeout=None)
Handle an accepted connection.
This is used by servers that accept connections outside of
asyncio but that use asyncio to handle connections.
This method is a coroutine. When completed, the coroutine
returns a (transport, protocol) pair.
connect_read_pipe(self, protocol_factory, pipe)
connect_write_pipe(self, protocol_factory, pipe)
create_connection(self, protocol_factory, host=None, port=None, *, ssl=None, family=0, proto=0, flags=0, sock=None, local_addr=None, server_hostname=None, ssl_handshake_timeout=None, happy_eyeballs_delay=None, interleave=None)
Connect to a TCP server.
Create a streaming transport connection to a given Internet host and
port: socket family AF_INET or socket.AF_INET6 depending on host (or
family if specified), socket type SOCK_STREAM. protocol_factory must be
a callable returning a protocol instance.
This method is a coroutine which will try to establish the connection
in the background. When successful, the coroutine returns a
(transport, protocol) pair.
create_datagram_endpoint(self, protocol_factory, local_addr=None, remote_addr=None, *, family=0, proto=0, flags=0, reuse_address=<object object at 0x7f92bfcfeb40>, reuse_port=None, allow_broadcast=None, sock=None) Create datagram connection.
create_future(self) Create a Future object attached to the loop.
create_server(self, protocol_factory, host=None, port=None, *, family=<AddressFamily.AF_UNSPEC: 0>, flags=<AddressInfo.AI_PASSIVE: 1>, sock=None, backlog=100, ssl=None, reuse_address=None, reuse_port=None, ssl_handshake_timeout=None, start_serving=True)
Create a TCP server.
The host parameter can be a string, in that case the TCP server is
bound to host and port.
The host parameter can also be a sequence of strings and in that case
the TCP server is bound to all hosts of the sequence. If a host
appears multiple times (possibly indirectly e.g. when hostnames
resolve to the same IP address), the server is only bound once to that
host.
Return a Server object which can be used to stop the service.
This method is a coroutine.
create_task(self, coro, *, name=None)
Schedule a coroutine object.
Return a task object.
create_unix_connection(self, protocol_factory, path=None, *, ssl=None, sock=None, server_hostname=None, ssl_handshake_timeout=None)
create_unix_server(self, protocol_factory, path=None, *, sock=None, backlog=100, ssl=None, ssl_handshake_timeout=None, start_serving=True)
default_exception_handler(self, context)
Default exception handler.
This is called when an exception occurs and no exception
handler is set, and can be called by a custom exception
handler that wants to defer to the default behavior.
This default handler logs the error message and other
context-dependent information. In debug mode, a truncated
stack trace is also appended showing where the given object
(e.g. a handle or future or task) was created, if any.
The context parameter has the same meaning as in
`call_exception_handler()`.
get_debug(self)
get_exception_handler(self)
Return an exception handler, or None if the default one is in use.
get_task_factory(self) Return a task factory, or None if the default one is in use.
getaddrinfo(self, host, port, *, family=0, type=0, proto=0, flags=0)
getnameinfo(self, sockaddr, flags=0)
is_closed(self) Returns True if the event loop was closed.
is_running(self) Returns True if the event loop is running.
remove_reader(self, fd) Remove a reader callback.
remove_signal_handler(self, sig)
Remove a handler for a signal. UNIX only.
Return True if a signal handler was removed, False if not.
remove_writer(self, fd) Remove a writer callback.
run_forever(self) Run until stop() is called.
run_in_executor(self, executor, func, *args)
run_until_complete(self, future)
Run until the Future is done.
If the argument is a coroutine, it is wrapped in a Task.
WARNING: It would be disastrous to call run_until_complete()
with the same coroutine twice -- it would wrap it in two
different Tasks and that can't be good.
Return the Future's result, or raise its exception.
sendfile(self, transport, file, offset=0, count=None, *, fallback=True)
Send a file to transport.
Return the total number of bytes which were sent.
The method uses high-performance os.sendfile if available.
file must be a regular file object opened in binary mode.
offset tells from where to start reading the file. If specified,
count is the total number of bytes to transmit as opposed to
sending the file until EOF is reached. File position is updated on
return or also in case of error in which case file.tell()
can be used to figure out the number of bytes
which were sent.
fallback set to True makes asyncio to manually read and send
the file when the platform does not support the sendfile syscall
(e.g. Windows or SSL socket on Unix).
Raise SendfileNotAvailableError if the system does not support
sendfile syscall and fallback is False.
set_debug(self, enabled)
set_default_executor(self, executor)
set_exception_handler(self, handler)
Set handler as the new event loop exception handler.
If handler is None, the default exception handler will
be set.
If handler is a callable object, it should have a
signature matching '(loop, context)', where 'loop'
will be a reference to the active event loop, 'context'
will be a dict object (see `call_exception_handler()`
documentation for details about context).
set_task_factory(self, factory)
Set a task factory that will be used by loop.create_task().
If factory is None the default task factory will be set.
If factory is a callable, it should have a signature matching
'(loop, coro)', where 'loop' will be a reference to the active
event loop, 'coro' will be a coroutine object. The callable
must return a Future.
shutdown_asyncgens(self) Shutdown all active asynchronous generators.
shutdown_default_executor(self) Schedule the shutdown of the default executor.
sock_accept(self, sock)
Accept a connection.
The socket must be bound to an address and listening for connections.
The return value is a pair (conn, address) where conn is a new socket
object usable to send and receive data on the connection, and address
is the address bound to the socket on the other end of the connection.
sock_connect(self, sock, address)
Connect to a remote socket at address.
This method is a coroutine.
sock_recv(self, sock, n)
Receive data from the socket.
The return value is a bytes object representing the data received.
The maximum amount of data to be received at once is specified by
nbytes.
sock_recv_into(self, sock, buf)
Receive data from the socket.
The received data is written into *buf* (a writable buffer).
The return value is the number of bytes written.
sock_sendall(self, sock, data)
Send data to the socket.
The socket must be connected to a remote socket. This method continues
to send data from data until either all data has been sent or an
error occurs. None is returned on success. On error, an exception is
raised, and there is no way to determine how much data, if any, was
successfully processed by the receiving end of the connection.
sock_sendfile(self, sock, file, offset=0, count=None, *, fallback=True)
start_tls(self, transport, protocol, sslcontext, *, server_side=False, server_hostname=None, ssl_handshake_timeout=None)
Upgrade transport to TLS.
Return a new transport that *protocol* should start using
immediately.
stop(self)
Stop running the event loop.
Every callback already scheduled will still run. This simply informs
run_forever to stop looping after a complete iteration.
subprocess_exec(self, protocol_factory, program, *args, stdin=-1, stdout=-1, stderr=-1, universal_newlines=False, shell=False, bufsize=0, encoding=None, errors=None, text=None, **kwargs)
subprocess_shell(self, protocol_factory, cmd, *, stdin=-1, stdout=-1, stderr=-1, universal_newlines=False, shell=True, bufsize=0, encoding=None, errors=None, text=None, **kwargs)
time(self)
Return the time according to the event loop's clock.
This is a float expressed in seconds since an epoch, but the
epoch, precision, accuracy and drift are unspecified and may
differ per event loop.
A Semaphore implementation.
A semaphore manages an internal counter which is decremented by each
acquire() call and incremented by each release() call. The counter
can never go below zero; when acquire() finds that it is zero, it blocks,
waiting until some other thread calls release().
Semaphores also support the context management protocol.
The optional argument gives the initial value for the internal
counter; it defaults to 1. If the value given is less than 0,
ValueError is raised.
acquire(self)
Acquire a semaphore.
If the internal counter is larger than zero on entry,
decrement it by one and return True immediately. If it is
zero on entry, block, waiting until some other coroutine has
called release() to make it larger than 0, and then return
True.
locked(self) Returns True if semaphore can not be acquired immediately.
release(self)
Release a semaphore, incrementing the internal counter by one.
When it was zero on entry and another coroutine is waiting for it to
become larger than zero again, wake up that coroutine.
Sendfile syscall is not available.
Raised if OS does not support sendfile syscall for given socket or
file type.
with_traceback(...)
Exception.with_traceback(tb) --
set self.__traceback__ to tb and return self.
args = <attribute 'args' of 'BaseException' objects>
close(self)
get_loop(self)
is_serving(self)
serve_forever(self)
start_serving(self)
wait_closed(self)
sockets = <property object at 0x7f92bf3a1cc0>
at_eof(self) Return True if the buffer is empty and 'feed_eof' was called.
exception(self)
feed_data(self, data)
feed_eof(self)
read(self, n=-1)
Read up to `n` bytes from the stream.
If n is not provided, or set to -1, read until EOF and return all read
bytes. If the EOF was received and the internal buffer is empty, return
an empty bytes object.
If n is zero, return empty bytes object immediately.
If n is positive, this function try to read `n` bytes, and may return
less or equal bytes than requested, but at least one byte. If EOF was
received before any byte is read, this function returns empty byte
object.
Returned value is not limited with limit, configured at stream
creation.
If stream was paused, this function will automatically resume it if
needed.
readexactly(self, n)
Read exactly `n` bytes.
Raise an IncompleteReadError if EOF is reached before `n` bytes can be
read. The IncompleteReadError.partial attribute of the exception will
contain the partial read bytes.
if n is zero, return empty bytes object.
Returned value is not limited with limit, configured at stream
creation.
If stream was paused, this function will automatically resume it if
needed.
readline(self)
Read chunk of data from the stream until newline (b'
') is found.
On success, return chunk that ends with newline. If only partial
line can be read due to EOF, return incomplete line without
terminating newline. When EOF was reached while no bytes read, empty
bytes object is returned.
If limit is reached, ValueError will be raised. In that case, if
newline was found, complete line including newline will be removed
from internal buffer. Else, internal buffer will be cleared. Limit is
compared against part of the line without newline.
If stream was paused, this function will automatically resume it if
needed.
readuntil(self, separator=b'\n')
Read data from the stream until ``separator`` is found.
On success, the data and separator will be removed from the
internal buffer (consumed). Returned data will include the
separator at the end.
Configured stream limit is used to check result. Limit sets the
maximal length of data that can be returned, not counting the
separator.
If an EOF occurs and the complete separator is still not found,
an IncompleteReadError exception will be raised, and the internal
buffer will be reset. The IncompleteReadError.partial attribute
may contain the separator partially.
If the data cannot be read because of over limit, a
LimitOverrunError exception will be raised, and the data
will be left in the internal buffer, so it can be read again.
set_exception(self, exc)
set_transport(self, transport)
Helper class to adapt between Protocol and StreamReader.
(This is a helper class instead of making StreamReader itself a
Protocol subclass, because the StreamReader has other potential
uses, and to prevent the user of the StreamReader to accidentally
call inappropriate methods of the protocol.)
connection_lost(self, exc)
connection_made(self, transport)
data_received(self, data)
eof_received(self)
pause_writing(self)
resume_writing(self)
Wraps a Transport.
This exposes write(), writelines(), [can_]write_eof(),
get_extra_info() and close(). It adds drain() which returns an
optional Future on which you can wait for flow control. It also
adds a transport property which references the Transport
directly.
can_write_eof(self)
close(self)
drain(self)
Flush the write buffer.
The intended use is to write
w.write(data)
await w.drain()
get_extra_info(self, name, default=None)
is_closing(self)
wait_closed(self)
write(self, data)
write_eof(self)
writelines(self, data)
transport = <property object at 0x7f92bf36a900>
Interface for protocol for subprocess calls.
connection_lost(self, exc)
Called when the connection is lost or closed.
The argument is an exception object or None (the latter
meaning a regular EOF is received or the connection was
aborted or closed).
connection_made(self, transport)
Called when a connection is made.
The argument is the transport representing the pipe connection.
To receive data, wait for data_received() calls.
When the connection is closed, connection_lost() is called.
pause_writing(self)
Called when the transport's buffer goes over the high-water mark.
Pause and resume calls are paired -- pause_writing() is called
once when the buffer goes strictly over the high-water mark
(even if subsequent writes increases the buffer size even
more), and eventually resume_writing() is called once when the
buffer size reaches the low-water mark.
Note that if the buffer size equals the high-water mark,
pause_writing() is not called -- it must go strictly over.
Conversely, resume_writing() is called when the buffer size is
equal or lower than the low-water mark. These end conditions
are important to ensure that things go as expected when either
mark is zero.
NOTE: This is the only Protocol callback that is not called
through EventLoop.call_soon() -- if it were, it would have no
effect when it's most needed (when the app keeps writing
without yielding until pause_writing() is called).
pipe_connection_lost(self, fd, exc)
Called when a file descriptor associated with the child process is
closed.
fd is the int file descriptor that was closed.
pipe_data_received(self, fd, data)
Called when the subprocess writes data into stdout/stderr pipe.
fd is int file descriptor.
data is bytes object.
process_exited(self) Called when subprocess has exited.
resume_writing(self)
Called when the transport's buffer drains below the low-water mark.
See pause_writing() for details.
close(self)
Close the transport.
Buffered data will be flushed asynchronously. No more data
will be received. After all buffered data is flushed, the
protocol's connection_lost() method will (eventually) be
called with None as its argument.
get_extra_info(self, name, default=None) Get optional transport information.
get_pid(self) Get subprocess id.
get_pipe_transport(self, fd) Get transport for pipe with number fd.
get_protocol(self) Return the current protocol.
get_returncode(self)
Get subprocess returncode.
See also
http://docs.python.org/3/library/subprocess#subprocess.Popen.returncode
is_closing(self) Return True if the transport is closing or closed.
kill(self)
Kill the subprocess.
On Posix OSs the function sends SIGKILL to the subprocess.
On Windows kill() is an alias for terminate().
See also:
http://docs.python.org/3/library/subprocess#subprocess.Popen.kill
send_signal(self, signal)
Send signal to subprocess.
See also:
docs.python.org/3/library/subprocess#subprocess.Popen.send_signal
set_protocol(self, protocol) Set a new protocol.
terminate(self)
Stop the subprocess.
Alias for close() method.
On Posix OSs the method sends SIGTERM to the subprocess.
On Windows the Win32 API function TerminateProcess()
is called to stop the subprocess.
See also:
http://docs.python.org/3/library/subprocess#subprocess.Popen.terminate
A coroutine wrapped in a Future.
add_done_callback(...) Add a callback to be run when the future becomes done. The callback is called with a single argument - the future object. If the future is already done when this is called, the callback is scheduled with call_soon.
cancel(self, /, msg=None) Request that this task cancel itself. This arranges for a CancelledError to be thrown into the wrapped coroutine on the next cycle through the event loop. The coroutine then has a chance to clean up or even deny the request using try/except/finally. Unlike Future.cancel, this does not guarantee that the task will be cancelled: the exception might be caught and acted upon, delaying cancellation of the task or preventing cancellation completely. The task may also return a value or raise a different exception. Immediately after this method is called, Task.cancelled() will not return True (unless the task was already cancelled). A task will be marked as cancelled when the wrapped coroutine terminates with a CancelledError exception (even if cancel() was not called).
cancelled(self, /) Return True if the future was cancelled.
done(self, /) Return True if the future is done. Done means either that a result / exception are available, or that the future was cancelled.
exception(self, /) Return the exception that was set on this future. The exception (or None if no exception was set) is returned only if the future is done. If the future has been cancelled, raises CancelledError. If the future isn't done yet, raises InvalidStateError.
get_coro(self, /)
get_loop(self, /) Return the event loop the Future is bound to.
get_name(self, /)
get_stack(self, /, *, limit=None) Return the list of stack frames for this task's coroutine. If the coroutine is not done, this returns the stack where it is suspended. If the coroutine has completed successfully or was cancelled, this returns an empty list. If the coroutine was terminated by an exception, this returns the list of traceback frames. The frames are always ordered from oldest to newest. The optional limit gives the maximum number of frames to return; by default all available frames are returned. Its meaning differs depending on whether a stack or a traceback is returned: the newest frames of a stack are returned, but the oldest frames of a traceback are returned. (This matches the behavior of the traceback module.) For reasons beyond our control, only one stack frame is returned for a suspended coroutine.
print_stack(self, /, *, limit=None, file=None) Print the stack or traceback for this task's coroutine. This produces output similar to that of the traceback module, for the frames retrieved by get_stack(). The limit argument is passed to get_stack(). The file argument is an I/O stream to which the output is written; by default output is written to sys.stderr.
remove_done_callback(self, fn, /) Remove all instances of a callback from the "call when done" list. Returns the number of callbacks removed.
result(self, /) Return the result this future represents. If the future has been cancelled, raises CancelledError. If the future's result isn't yet available, raises InvalidStateError. If the future is done and has an exception set, this exception is raised.
set_exception(self, exception, /)
set_name(self, value, /)
set_result(self, result, /)
Threaded child watcher implementation.
The watcher uses a thread per process
for waiting for the process finish.
It doesn't require subscription on POSIX signal
but a thread creation is not free.
The watcher has O(1) complexity, its performance doesn't depend
on amount of spawn processes.
add_child_handler(self, pid, callback, *args)
attach_loop(self, loop)
close(self)
is_active(self)
remove_child_handler(self, pid)
The operation exceeded the given deadline.
with_traceback(...)
Exception.with_traceback(tb) --
set self.__traceback__ to tb and return self.
args = <attribute 'args' of 'BaseException' objects>
Object returned by timed callback registration methods.
cancel(self)
cancelled(self)
when(self)
Return a scheduled callback time.
The time is an absolute timestamp, using the same time
reference as loop.time().
Interface representing a bidirectional transport.
There may be several implementations, but typically, the user does
not implement new transports; rather, the platform provides some
useful transports that are implemented using the platform's best
practices.
The user never instantiates a transport directly; they call a
utility function, passing it a protocol factory and other
information necessary to create the transport and protocol. (E.g.
EventLoop.create_connection() or EventLoop.create_server().)
The utility function will asynchronously create a transport and a
protocol and hook them up by calling the protocol's
connection_made() method, passing it the transport.
The implementation here raises NotImplemented for every method
except writelines(), which calls write() in a loop.
abort(self)
Close the transport immediately.
Buffered data will be lost. No more data will be received.
The protocol's connection_lost() method will (eventually) be
called with None as its argument.
can_write_eof(self) Return True if this transport supports write_eof(), False if not.
close(self)
Close the transport.
Buffered data will be flushed asynchronously. No more data
will be received. After all buffered data is flushed, the
protocol's connection_lost() method will (eventually) be
called with None as its argument.
get_extra_info(self, name, default=None) Get optional transport information.
get_protocol(self) Return the current protocol.
get_write_buffer_limits(self)
Get the high and low watermarks for write flow control.
Return a tuple (low, high) where low and high are
positive number of bytes.
get_write_buffer_size(self) Return the current size of the write buffer.
is_closing(self) Return True if the transport is closing or closed.
is_reading(self) Return True if the transport is receiving.
pause_reading(self)
Pause the receiving end.
No data will be passed to the protocol's data_received()
method until resume_reading() is called.
resume_reading(self)
Resume the receiving end.
Data received will once again be passed to the protocol's
data_received() method.
set_protocol(self, protocol) Set a new protocol.
set_write_buffer_limits(self, high=None, low=None)
Set the high- and low-water limits for write flow control.
These two values control when to call the protocol's
pause_writing() and resume_writing() methods. If specified,
the low-water limit must be less than or equal to the
high-water limit. Neither value can be negative.
The defaults are implementation-specific. If only the
high-water limit is given, the low-water limit defaults to an
implementation-specific value less than or equal to the
high-water limit. Setting high to zero forces low to zero as
well, and causes pause_writing() to be called whenever the
buffer becomes non-empty. Setting low to zero causes
resume_writing() to be called only once the buffer is empty.
Use of zero for either limit is generally sub-optimal as it
reduces opportunities for doing I/O and computation
concurrently.
write(self, data)
Write some data bytes to the transport.
This does not block; it buffers the data and arranges for it
to be sent out asynchronously.
write_eof(self)
Close the write end after flushing buffered data.
(This is like typing ^D into a UNIX program reading from stdin.)
Data may still be received.
writelines(self, list_of_data)
Write a list (or any iterable) of data bytes to the transport.
The default implementation concatenates the arguments and
calls write() on the result.
Interface for write-only transports.
abort(self)
Close the transport immediately.
Buffered data will be lost. No more data will be received.
The protocol's connection_lost() method will (eventually) be
called with None as its argument.
can_write_eof(self) Return True if this transport supports write_eof(), False if not.
close(self)
Close the transport.
Buffered data will be flushed asynchronously. No more data
will be received. After all buffered data is flushed, the
protocol's connection_lost() method will (eventually) be
called with None as its argument.
get_extra_info(self, name, default=None) Get optional transport information.
get_protocol(self) Return the current protocol.
get_write_buffer_limits(self)
Get the high and low watermarks for write flow control.
Return a tuple (low, high) where low and high are
positive number of bytes.
get_write_buffer_size(self) Return the current size of the write buffer.
is_closing(self) Return True if the transport is closing or closed.
set_protocol(self, protocol) Set a new protocol.
set_write_buffer_limits(self, high=None, low=None)
Set the high- and low-water limits for write flow control.
These two values control when to call the protocol's
pause_writing() and resume_writing() methods. If specified,
the low-water limit must be less than or equal to the
high-water limit. Neither value can be negative.
The defaults are implementation-specific. If only the
high-water limit is given, the low-water limit defaults to an
implementation-specific value less than or equal to the
high-water limit. Setting high to zero forces low to zero as
well, and causes pause_writing() to be called whenever the
buffer becomes non-empty. Setting low to zero causes
resume_writing() to be called only once the buffer is empty.
Use of zero for either limit is generally sub-optimal as it
reduces opportunities for doing I/O and computation
concurrently.
write(self, data)
Write some data bytes to the transport.
This does not block; it buffers the data and arranges for it
to be sent out asynchronously.
write_eof(self)
Close the write end after flushing buffered data.
(This is like typing ^D into a UNIX program reading from stdin.)
Data may still be received.
writelines(self, list_of_data)
Write a list (or any iterable) of data bytes to the transport.
The default implementation concatenates the arguments and
calls write() on the result.
all_tasks(loop=None) Return a set of all tasks for the loop.
as_completed(fs, *, loop=None, timeout=None)
Return an iterator whose values are coroutines.
When waiting for the yielded coroutines you'll get the results (or
exceptions!) of the original Futures (or coroutines), in the order
in which and as soon as they complete.
This differs from PEP 3148; the proper way to use this is:
for f in as_completed(fs):
result = await f # The 'await' may raise.
# Use result.
If a timeout is specified, the 'await' will raise
TimeoutError when the timeout occurs before all Futures are done.
Note: The futures 'f' are not necessarily members of fs.
coroutine(func)
Decorator to mark coroutines.
If the coroutine is not yielded from before it is destroyed,
an error message is logged.
create_subprocess_exec(program, *args, stdin=None, stdout=None, stderr=None, loop=None, limit=65536, **kwds)
create_subprocess_shell(cmd, stdin=None, stdout=None, stderr=None, loop=None, limit=65536, **kwds)
create_task(coro, *, name=None)
Schedule the execution of a coroutine object in a spawn task.
Return a Task object.
current_task(loop=None) Return a currently executed task.
ensure_future(coro_or_future, *, loop=None)
Wrap a coroutine or an awaitable in a future.
If the argument is a Future, it is returned directly.
gather(*coros_or_futures, loop=None, return_exceptions=False)
Return a future aggregating results from the given coroutines/futures.
Coroutines will be wrapped in a future and scheduled in the event
loop. They will not necessarily be scheduled in the same order as
passed in.
All futures must share the same event loop. If all the tasks are
done successfully, the returned future's result is the list of
results (in the order of the original sequence, not necessarily
the order of results arrival). If *return_exceptions* is True,
exceptions in the tasks are treated the same as successful
results, and gathered in the result list; otherwise, the first
raised exception will be immediately propagated to the returned
future.
Cancellation: if the outer Future is cancelled, all children (that
have not completed yet) are also cancelled. If any child is
cancelled, this is treated as if it raised CancelledError --
the outer Future is *not* cancelled in this case. (This is to
prevent the cancellation of one child to cause other children to
be cancelled.)
If *return_exceptions* is False, cancelling gather() after it
has been marked done won't cancel any submitted awaitables.
For instance, gather can be marked done after propagating an
exception to the caller, therefore, calling ``gather.cancel()``
after catching an exception (raised by one of the awaitables) from
gather won't cancel any other awaitables.
get_child_watcher() Equivalent to calling get_event_loop_policy().get_child_watcher().
get_event_loop() Return an asyncio event loop. When called from a coroutine or a callback (e.g. scheduled with call_soon or similar API), this function will always return the running event loop. If there is no running event loop set, the function will return the result of `get_event_loop_policy().get_event_loop()` call.
get_event_loop_policy() Get the current event loop policy.
get_running_loop() Return the running event loop. Raise a RuntimeError if there is none. This function is thread-specific.
iscoroutine(obj) Return True if obj is a coroutine object.
iscoroutinefunction(func) Return True if func is a decorated coroutine function.
isfuture(obj)
Check for a Future.
This returns True when obj is a Future instance or is advertising
itself as duck-type compatible by setting _asyncio_future_blocking.
See comment in Future for more details.
new_event_loop() Equivalent to calling get_event_loop_policy().new_event_loop().
open_connection(host=None, port=None, *, loop=None, limit=65536, **kwds)
A wrapper for create_connection() returning a (reader, writer) pair.
The reader returned is a StreamReader instance; the writer is a
StreamWriter instance.
The arguments are all the usual arguments to create_connection()
except protocol_factory; most common are positional host and port,
with various optional keyword arguments following.
Additional optional keyword arguments are loop (to set the event loop
instance to use) and limit (to set the buffer limit passed to the
StreamReader).
(If you want to customize the StreamReader and/or
StreamReaderProtocol classes, just copy the code -- there's
really nothing special here except some convenience.)
open_unix_connection(path=None, *, loop=None, limit=65536, **kwds) Similar to `open_connection` but works with UNIX Domain Sockets.
run(main, *, debug=None)
Execute the coroutine and return the result.
This function runs the passed coroutine, taking care of
managing the asyncio event loop and finalizing asynchronous
generators.
This function cannot be called when another asyncio event loop is
running in the same thread.
If debug is True, the event loop will be run in debug mode.
This function always creates a new event loop and closes it at the end.
It should be used as a main entry point for asyncio programs, and should
ideally only be called once.
Example:
async def main():
await asyncio.sleep(1)
print('hello')
asyncio.run(main())
run_coroutine_threadsafe(coro, loop)
Submit a coroutine object to a given event loop.
Return a concurrent.futures.Future to access the result.
set_child_watcher(watcher)
Equivalent to calling
get_event_loop_policy().set_child_watcher(watcher).
set_event_loop(loop) Equivalent to calling get_event_loop_policy().set_event_loop(loop).
set_event_loop_policy(policy)
Set the current event loop policy.
If policy is None, the default policy is restored.
shield(arg, *, loop=None)
Wait for a future, shielding it from cancellation.
The statement
res = await shield(something())
is exactly equivalent to the statement
res = await something()
*except* that if the coroutine containing it is cancelled, the
task running in something() is not cancelled. From the POV of
something(), the cancellation did not happen. But its caller is
still cancelled, so the yield-from expression still raises
CancelledError. Note: If something() is cancelled by other means
this will still cancel shield().
If you want to completely ignore cancellation (not recommended)
you can combine shield() with a try/except clause, as follows:
try:
res = await shield(something())
except CancelledError:
res = None
sleep(delay, result=None, *, loop=None) Coroutine that completes after a given time (in seconds).
start_server(client_connected_cb, host=None, port=None, *, loop=None, limit=65536, **kwds)
Start a socket server, call back for each client connected.
The first parameter, `client_connected_cb`, takes two parameters:
client_reader, client_writer. client_reader is a StreamReader
object, while client_writer is a StreamWriter object. This
parameter can either be a plain callback function or a coroutine;
if it is a coroutine, it will be automatically converted into a
Task.
The rest of the arguments are all the usual arguments to
loop.create_server() except protocol_factory; most common are
positional host and port, with various optional keyword arguments
following. The return value is the same as loop.create_server().
Additional optional keyword arguments are loop (to set the event loop
instance to use) and limit (to set the buffer limit passed to the
StreamReader).
The return value is the same as loop.create_server(), i.e. a
Server object which can be used to stop the service.
start_unix_server(client_connected_cb, path=None, *, loop=None, limit=65536, **kwds) Similar to `start_server` but works with UNIX Domain Sockets.
to_thread(func, /, *args, **kwargs)
Asynchronously run function *func* in a separate thread.
Any *args and **kwargs supplied for this function are directly passed
to *func*. Also, the current :class:`contextvars.Context` is propagated,
allowing context variables from the main thread to be accessed in the
separate thread.
Return a coroutine that can be awaited to get the eventual result of *func*.
wait(fs, *, loop=None, timeout=None, return_when='ALL_COMPLETED')
Wait for the Futures and coroutines given by fs to complete.
The fs iterable must not be empty.
Coroutines will be wrapped in Tasks.
Returns two sets of Future: (done, pending).
Usage:
done, pending = await asyncio.wait(fs)
Note: This does not raise TimeoutError! Futures that aren't done
when the timeout occurs are returned in the second set.
wait_for(fut, timeout, *, loop=None)
Wait for the single Future or coroutine to complete, with timeout.
Coroutine will be wrapped in Task.
Returns result of the Future or coroutine. When a timeout occurs,
it cancels the task and raises TimeoutError. To avoid the task
cancellation, wrap it in shield().
If the wait is cancelled, the task is also cancelled.
This function is a coroutine.
wrap_future(future, *, loop=None) Wrap concurrent.futures.Future object.
ALL_COMPLETED = 'ALL_COMPLETED'
FIRST_COMPLETED = 'FIRST_COMPLETED'
FIRST_EXCEPTION = 'FIRST_EXCEPTION'