Pyjo.IOLoop.Stream - Non-blocking I/O stream

from Pyjo.IOLoop.Stream import Stream

# Create stream
stream = Stream(handle)
stream.on('read', lambda stream, chunk: ...)
stream.on('close', lambda stream: ...)
stream.on('error', lambda stream, err: ...)

# Or import the module, as in Google Python Style Guide

import Pyjo.IOLoop.Stream

# Create stream
stream = Pyjo.IOLoop.Stream.new(handle)
stream.on('read', lambda stream, chunk: ...)
stream.on('close', lambda stream: ...)
stream.on('error', lambda stream, err: ...)

# Start and stop watching for new data
stream.start()
stream.stop()

# Start reactor if necessary
if not stream.reactor.is_running:
    stream.reactor.start()

Pyjo.IOLoop.Stream is a container for I/O streams used by Pyjo.IOLoop. A handle is a socket, an ssl.SSLSocket too, or anything else with a file descriptor, like a pipe.

The end of a with block closes the stream.

Events

Pyjo.IOLoop.Stream inherits all events from Pyjo.EventEmitter and can emit the following new ones.

close

stream.on('close', lambda stream: ...)

Emitted if the stream gets closed.

drain

stream.on('drain', lambda stream: ...)

Emitted once all data has been written.

error

stream.on('error', lambda stream, err: ...)

Emitted if an error occurs on the stream, fatal if unhandled. The error is the OSError of the handle.

read

stream.on('read', lambda stream, chunk: ...)

Emitted if new data arrives on the stream.

timeout

stream.on('timeout', lambda stream: ...)

Emitted if the stream has been inactive for too long and will get closed automatically.

write

stream.on('write', lambda stream, chunk: ...)

Emitted if new data has been written to the stream.

See also

Pyjoyment, https://mojolicious.org.

Ported from Mojo::IOLoop::Stream of Mojolicious 9.49.

class Pyjo.IOLoop.Stream.Pyjo_IOLoop_Stream(handle: Any = None)[source]

Pyjo.IOLoop.Stream inherits all methods from Pyjo.EventEmitter and implements the following new ones.

property bytes_read: int[source]
num = stream.bytes_read

Number of bytes received.

property bytes_waiting: int[source]
num = stream.bytes_waiting

Number of bytes that have been enqueued with write() and are waiting to be written.

property bytes_written: int[source]
num = stream.bytes_written

Number of bytes written.

property can_write: bool[source]
boolean = stream.can_write

True if calling write() is safe.

close() → None[source]
stream.close()

Close stream immediately.

close_gracefully() → None[source]
stream.close_gracefully()

Close stream gracefully.

close_gracefully_p() → Pyjo_Promise[source]
promise = stream.close_gracefully_p()

Same as close_gracefully(), but returns a Pyjo.Promise object, which is fulfilled once the stream has been closed, also when it is closed already.

await stream.write_p(b'Bye!')
await stream.close_gracefully_p()
property handle: Any[source]
handle = stream.handle

Get handle for stream, usually a socket.socket or ssl.SSLSocket object.

high_water_mark
size = stream.high_water_mark
stream.high_water_mark = 1024

Maximum size of write() buffer in bytes before can_write is false, defaults to 1048576 (1MiB).

property is_readable: bool[source]
boolean = stream.is_readable

Quick non-blocking check if stream is readable, useful for identifying tainted sockets.

property is_writing: bool[source]
boolean = stream.is_writing

Check if stream is writing.

iterate(size: int | None = None) → Pyjo_Iterator[bytes][source]
async for chunk in stream.iterate():
    ...
async for chunk in stream.iterate(1024):
    ...

The chunks as a Pyjo.Iterator, at most size bytes each, until the end of the stream, which read_p() takes.

# Echo in capitals
async for chunk in stream:
    await stream.write_p(chunk.upper())

# The same in a chain
async for chunk in stream.iterate().map(bytes.upper):
    await stream.write_p(chunk)
once_p(name: str) → Pyjo_Promise[source]
promise = stream.once_p('close')

Same as once_p() of Pyjo.EventEmitter, but fulfilled at once for the event close of a stream that is closed already, as it comes no more.

property reactor: Pyjo_Reactor[source]
reactor = stream.reactor
stream.reactor = Pyjo.Reactor.Poll.new()

Low-level event reactor, defaults to the reactor attribute value of the global Pyjo.IOLoop singleton. Note that this attribute is weakened.

read_all_p() → Pyjo_Promise[source]
promise = stream.read_all_p()

Return a Pyjo.Promise object, which is fulfilled with all the data of the stream until its end as a Pyjo.String.Bytes object, as read_p() takes it.

data = await stream.read_all_p()
read_p(size: int | None = None) → Pyjo_Promise[source]
promise = stream.read_p()
promise = stream.read_p(1024)

Return a Pyjo.Promise object, which is fulfilled with the next chunk of the stream, at most size bytes, or None at its end, the event close, or end of Pyjo.IOLoop.Stdio, or when it is closed already, and rejected with the error of the event error, or a TimeoutError when the stream has been inactive for too long. The stream reads only while a promise waits, and stops in between, so that a chunk that comes before is kept for the next promise, and a stream that is read no more stops reading, as the streams of Node.js in their paused mode. The subscribers of the event read get the chunks that the stream reads then.

# Read until the end
while (chunk := await stream.read_p()) is not None:
    print(chunk)
start() → None[source]
stream.start()

Start or resume watching for new data on the stream.

steal_handle() → Any[source]
handle = stream.steal_handle()

Steal handle and prevent it from getting closed automatically.

stop() → None[source]
stream.stop()

Stop watching for new data on the stream.

property timeout: float[source]
timeout = stream.timeout
stream.timeout = 45

Maximum amount of time in seconds stream can be inactive before getting closed automatically, defaults to 15. Setting the value to 0 will allow this stream to be inactive indefinitely.

write(chunk: bytes, cb: DrainCallback | None = None) → Self[source]
stream = stream.write(chunk)
stream = stream.write(chunk, lambda stream: ...)

Enqueue data to be written to the stream as soon as possible, the optional drain callback will be executed once all data has been written.

write_p(chunk: bytes) → Pyjo_Promise[source]
promise = stream.write_p(chunk)

Same as write(), but returns a Pyjo.Promise object, which is fulfilled once all data has been written, and rejected if the stream closes before, or is closed already, or with a TimeoutError when it has been inactive for too long.

await stream.write_p(b'Hello World!')