Sockets (Effect's Socket and NodeSocket).
A SocketService has a reader and a writer, both acquired in a
scope. Acquiring the reader opens the connection (closed with the scope);
its pull waits for the next batch of chunks and fails with a
SocketError once the socket closes (a SocketCloseError with code
1000 when the peer ended the stream). The writer writes to the open
connection; writing a CloseEvent closes it::
socket = make_net(8080, "127.0.0.1")
def talk():
writer = yield socket.writer
reader = yield socket.reader
yield writer.write_all([b"ping"])
return (yield reader.pull)
reply = yield from scoped(gen(talk))to_channel and to_stream turn a socket into a channel (input
written, output read) or a stream. The live sockets run on an asyncio loop
of their own, on a background thread, so they work under run_blocking too.
pyfect.socket.server listens for connections and
pyfect.socket.datagram sends and receives UDP packets. from_web_socket
adapts a browser-style WebSocket and make_web_socket opens a client
through the WebSocketConstructor service, which pyfect.socket.ws
provides on the websockets library (extra pyfect-dev[websockets]).
Values#
| Attribute | Type | Description |
|---|---|---|
SOCKET_ERROR_REASON | UnionSchema[SocketReadError | SocketWriteError | SocketOpenError | SocketUpgradeError | SocketCloseError, Mapping[str, object], Never, Never] | The schema of every reason (Effect's |
Types#
| Type | Definition | Description |
|---|---|---|
OpenErrorKind | type OpenErrorKind = Literal['Unknown', 'Timeout'] | |
SocketErrorReason | type SocketErrorReason = SocketReadError | SocketWriteError | SocketOpenError | SocketUpgradeError | SocketCloseError | |
Chunk | type Chunk = bytes | str | |
PemInput | type PemInput = str | bytes | |
SocketChannel | type SocketChannel[A, IE] = Channel[tuple[A, ...], SocketError | IE, None, tuple[Chunk | CloseEvent, ...], IE, object] | |
Upgrade | type Upgrade = Callable[[TlsUpgradeOptions | None], Effect[None, SocketError]] | |
Write | type Write = Callable[[Chunk | CloseEvent], Effect[None, SocketError]] | |
WriteAll | type WriteAll = Callable[[Sequence[Chunk]], Effect[None, SocketError]] | |
Listener | type Listener = Callable[[WebSocketEvent], None] | |
WebSocketConstructorService | type WebSocketConstructorService = Callable[[str, WebSocketClientOptions], WebSocketLike] | |
WebSocketEventType | type WebSocketEventType = Literal['open', 'message', 'error', 'close'] |
Classes#
Functions#
is_clean_close#
is_clean_close(error) -> boolWhether error is a normal close (code 1000).
| Parameter | Type | Description |
|---|---|---|
error | SocketError |
Returns bool
def is_clean_close(error: SocketError) -> bool:
"""Whether ``error`` is a normal close (code 1000)."""
return isinstance(error.reason, SocketCloseError) and error.reason.code == 1000from_socket#
from_socket(open, *, tls_server=False, open_timeout=None, chunk_size=DEFAULT_CHUNK_SIZE) -> SocketServiceA socket over the connected socket.socket each acquisition of
the reader gets from open (Effect's fromDuplex); the socket is
taken over and closed with the reader's scope. tls_server makes TLS
upgrades take the server side; each pull gives at most chunk_size chunks.
| Parameter | Type | Description |
|---|---|---|
open | Effect[socket.socket, SocketError, Scope] | |
tls_server | bool = False | |
open_timeout | DurationInput | None = None | |
chunk_size | float = DEFAULT_CHUNK_SIZE |
Returns SocketService
def from_socket(
open: Effect[socket.socket, SocketError, Scope],
*,
tls_server: bool = False,
open_timeout: DurationInput | None = None,
chunk_size: float = DEFAULT_CHUNK_SIZE,
) -> SocketService:
"""A socket over the connected ``socket.socket`` each acquisition of
the reader gets from ``open`` (Effect's ``fromDuplex``); the socket is
taken over and closed with the reader's scope. ``tls_server`` makes TLS
upgrades take the server side; each pull gives at most ``chunk_size`` chunks."""
require_effect(open, "open")
return from_connection(
open.flat_map(_adopt),
upgrade_side=ServerSide() if tls_server else client_side(None),
open_timeout=open_timeout,
chunk_size=chunk_size,
)layer_net#
layer_net(port, host='localhost', *, open_timeout=None, chunk_size=DEFAULT_CHUNK_SIZE) -> Layer[Socket]| Parameter | Type | Description |
|---|---|---|
port | int | |
host | str = 'localhost' | |
open_timeout | DurationInput | None = None | |
chunk_size | float = DEFAULT_CHUNK_SIZE |
Returns Layer[Socket]
def layer_net(
port: int,
host: str = "localhost",
*,
open_timeout: DurationInput | None = None,
chunk_size: float = DEFAULT_CHUNK_SIZE,
) -> Layer[Socket]:
return layer_effect(
Socket,
sync(lambda: make_net(port, host, open_timeout=open_timeout, chunk_size=chunk_size)),
)layer_tls#
layer_tls(port, host='localhost', *, tls=None, open_timeout=None, chunk_size=DEFAULT_CHUNK_SIZE) -> Layer[Socket]| Parameter | Type | Description |
|---|---|---|
port | int | |
host | str = 'localhost' | |
tls | TlsUpgradeOptions | None = None | |
open_timeout | DurationInput | None = None | |
chunk_size | float = DEFAULT_CHUNK_SIZE |
Returns Layer[Socket]
def layer_tls(
port: int,
host: str = "localhost",
*,
tls: TlsUpgradeOptions | None = None,
open_timeout: DurationInput | None = None,
chunk_size: float = DEFAULT_CHUNK_SIZE,
) -> Layer[Socket]:
return layer_effect(
Socket,
sync(
lambda: make_tls(port, host, tls=tls, open_timeout=open_timeout, chunk_size=chunk_size)
),
)make_net#
make_net(port, host='localhost', *, open_timeout=None, chunk_size=DEFAULT_CHUNK_SIZE) -> SocketServiceA TCP socket connecting to host:port; each pull gives at most
chunk_size chunks. A TLS upgrade without a servername checks the
certificate against host, or localhost for an IP literal.
| Parameter | Type | Description |
|---|---|---|
port | int | |
host | str = 'localhost' | |
open_timeout | DurationInput | None = None | |
chunk_size | float = DEFAULT_CHUNK_SIZE |
Returns SocketService
def make_net(
port: int,
host: str = "localhost",
*,
open_timeout: DurationInput | None = None,
chunk_size: float = DEFAULT_CHUNK_SIZE,
) -> SocketService:
"""A TCP socket connecting to ``host:port``; each pull gives at most
``chunk_size`` chunks. A TLS upgrade without a ``servername`` checks the
certificate against ``host``, or ``localhost`` for an IP literal."""
async def connect(conn: Connection) -> object:
return await get_loop().create_connection(lambda: conn, host, port)
target = _address(host, port)
return from_connection(
connecting(connect, target),
upgrade_side=client_side(host),
open_timeout=open_timeout,
chunk_size=chunk_size,
target=target,
)make_net_channel#
make_net_channel[IE = Never](port, host='localhost', *, open_timeout=None, chunk_size=DEFAULT_CHUNK_SIZE) -> SocketChannel[bytes, IE]| Parameter | Type | Description |
|---|---|---|
port | int | |
host | str = 'localhost' | |
open_timeout | DurationInput | None = None | |
chunk_size | float = DEFAULT_CHUNK_SIZE |
Returns SocketChannel[bytes, IE]
def make_net_channel[IE = Never](
port: int,
host: str = "localhost",
*,
open_timeout: DurationInput | None = None,
chunk_size: float = DEFAULT_CHUNK_SIZE,
) -> SocketChannel[bytes, IE]:
service = make_net(port, host, open_timeout=open_timeout, chunk_size=chunk_size)
return unwrap_channel(succeed(to_channel(service)))make_tls#
make_tls(port, host='localhost', *, tls=None, open_timeout=None, chunk_size=DEFAULT_CHUNK_SIZE) -> SocketServiceA TLS socket connecting to host:port; the certificate is checked
against tls.servername, else host. Each pull gives at most chunk_size
chunks.
| Parameter | Type | Description |
|---|---|---|
port | int | |
host | str = 'localhost' | |
tls | TlsUpgradeOptions | None = None | |
open_timeout | DurationInput | None = None | |
chunk_size | float = DEFAULT_CHUNK_SIZE |
Returns SocketService
def make_tls(
port: int,
host: str = "localhost",
*,
tls: TlsUpgradeOptions | None = None,
open_timeout: DurationInput | None = None,
chunk_size: float = DEFAULT_CHUNK_SIZE,
) -> SocketService:
"""A TLS socket connecting to ``host:port``; the certificate is checked
against ``tls.servername``, else ``host``. Each pull gives at most ``chunk_size``
chunks."""
options = tls or TlsUpgradeOptions()
async def connect(conn: Connection) -> None:
context = client_context(options)
await get_loop().create_connection(lambda: conn, host, port)
await conn.start_tls(context, server_side=False, hostname=options.servername or host)
target = _address(host, port)
return from_connection(
connecting(connect, target),
upgrade_side=client_side(host),
open_timeout=open_timeout,
chunk_size=chunk_size,
target=target,
)make_tls_channel#
make_tls_channel[IE = Never](port, host='localhost', *, tls=None, open_timeout=None, chunk_size=DEFAULT_CHUNK_SIZE) -> SocketChannel[bytes, IE]| Parameter | Type | Description |
|---|---|---|
port | int | |
host | str = 'localhost' | |
tls | TlsUpgradeOptions | None = None | |
open_timeout | DurationInput | None = None | |
chunk_size | float = DEFAULT_CHUNK_SIZE |
Returns SocketChannel[bytes, IE]
def make_tls_channel[IE = Never](
port: int,
host: str = "localhost",
*,
tls: TlsUpgradeOptions | None = None,
open_timeout: DurationInput | None = None,
chunk_size: float = DEFAULT_CHUNK_SIZE,
) -> SocketChannel[bytes, IE]:
service = make_tls(port, host, tls=tls, open_timeout=open_timeout, chunk_size=chunk_size)
return unwrap_channel(succeed(to_channel(service)))make_unix#
make_unix(path, *, open_timeout=None) -> SocketServiceA socket connecting to the Unix socket at path.
| Parameter | Type | Description |
|---|---|---|
path | str | |
open_timeout | DurationInput | None = None |
Returns SocketService
def make_unix(path: str, *, open_timeout: DurationInput | None = None) -> SocketService:
"""A socket connecting to the Unix socket at ``path``."""
async def connect(conn: Connection) -> object:
return await get_loop().create_unix_connection(lambda: conn, path)
return from_connection(
connecting(connect, path),
upgrade_side=client_side(None),
open_timeout=open_timeout,
target=path,
)make#
make(reader, writer) -> SocketService| Parameter | Type | Description |
|---|---|---|
reader | Effect[Reader, SocketError, Scope] | |
writer | Effect[Writer, Never, Scope] |
Returns SocketService
def make(
reader: Effect[Reader, SocketError, Scope], writer: Effect[Writer, Never, Scope]
) -> SocketService:
require_effect(reader, "reader")
require_effect(writer, "writer")
return SocketService(reader, writer)make_channel#
make_channel[IE = Never]() -> Channel[tuple[bytes, ...], SocketError | IE, None, tuple[Chunk | CloseEvent, ...], IE, object, Socket]to_channel of the Socket service.
Returns Channel[tuple[bytes, ...], SocketError | IE, None, tuple[Chunk | CloseEvent, ...], IE, object, Socket]
def make_channel[IE = Never]() -> Channel[
tuple[bytes, ...], SocketError | IE, None, tuple[Chunk | CloseEvent, ...], IE, object, Socket
]:
"""``to_channel`` of the ``Socket`` service."""
def channel(socket: SocketService) -> SocketChannel[bytes, IE]:
return to_channel(socket)
return unwrap_channel(Socket().map(channel))reader_bytes#
reader_bytes(socket) -> Effect[Effect[tuple[bytes, ...], SocketError], SocketError, Scope]The reader's pull, with text frames encoded as UTF-8.
| Parameter | Type | Description |
|---|---|---|
socket | SocketService |
Returns Effect[Effect[tuple[bytes, ...], SocketError], SocketError, Scope]
def reader_bytes(
socket: SocketService,
) -> Effect[Effect[tuple[bytes, ...], SocketError], SocketError, Scope]:
"""The reader's pull, with text frames encoded as UTF-8."""
return socket.reader.map(lambda reader: reader.pull.map(lambda c: tuple(map(encode_chunk, c))))reader_string#
reader_string(socket, encoding='utf-8') -> Effect[Effect[tuple[str, ...], SocketError], SocketError, Scope]The reader's pull, decoding bytes with encoding across pulls. An
incomplete character is flushed (as U+FFFD) before a text frame and on a
normal close.
| Parameter | Type | Description |
|---|---|---|
socket | SocketService | |
encoding | str = 'utf-8' |
Returns Effect[Effect[tuple[str, ...], SocketError], SocketError, Scope]
def reader_string(
socket: SocketService, encoding: str = "utf-8"
) -> Effect[Effect[tuple[str, ...], SocketError], SocketError, Scope]:
"""The reader's pull, decoding bytes with ``encoding`` across pulls. An
incomplete character is flushed (as U+FFFD) before a text frame and on a
normal close."""
def make_pull(reader: Reader) -> Effect[tuple[str, ...], SocketError]:
decoder = text_decoder(encoding)
state = {"needs_flush": False}
def flush() -> str:
state["needs_flush"] = False
text = decoder.decode(b"", final=True)
decoder.reset()
return text
def decode(chunk: tuple[Chunk, ...]) -> tuple[str, ...]:
out: list[str] = []
for item in chunk:
if isinstance(item, str):
out.append(flush() + item if state["needs_flush"] else item)
else:
out.append(decoder.decode(item))
state["needs_flush"] = True
return tuple(out)
def on_error(error: SocketError) -> Effect[tuple[str, ...], SocketError]:
if state["needs_flush"] and is_clean_close(error):
last = flush()
if last:
return succeed((last,))
return fail(error)
return reader.pull.map(decode).catch_all(on_error)
return socket.reader.map(make_pull)to_channel#
to_channel[IE = Never](socket) -> SocketChannel[bytes, IE]The socket as a channel: its input chunks are written (a
CloseEvent closes the socket), its output is what the reader pulls,
as bytes. A failed write fails the channel.
| Parameter | Type | Description |
|---|---|---|
socket | SocketService |
Returns SocketChannel[bytes, IE]
def to_channel[IE = Never](socket: SocketService) -> SocketChannel[bytes, IE]:
"""The socket as a channel: its input chunks are written (a
``CloseEvent`` closes the socket), its output is what the reader pulls,
as bytes. A failed write fails the channel."""
return _to_channel_with_reader(socket, reader_bytes(socket))to_channel_string#
to_channel_string[IE = Never](socket, encoding='utf-8') -> SocketChannel[str, IE]to_channel, with the output decoded as by reader_string.
| Parameter | Type | Description |
|---|---|---|
socket | SocketService | |
encoding | str = 'utf-8' |
Returns SocketChannel[str, IE]
def to_channel_string[IE = Never](
socket: SocketService, encoding: str = "utf-8"
) -> SocketChannel[str, IE]:
"""``to_channel``, with the output decoded as by ``reader_string``."""
return _to_channel_with_reader(socket, reader_string(socket, encoding))to_stream#
to_stream(socket) -> Stream[bytes, SocketError]What the socket's reader pulls, as a stream of bytes.
| Parameter | Type | Description |
|---|---|---|
socket | SocketService |
Returns Stream[bytes, SocketError]
def to_stream(socket: SocketService) -> Stream[bytes, SocketError]:
"""What the socket's reader pulls, as a stream of bytes."""
channel: Channel[tuple[bytes, ...], SocketError] = from_transform(
lambda _upstream, scope: reader_bytes(socket).pipe(_in_scope(scope))
)
return from_channel(channel)unsupported_upgrade#
unsupported_upgrade(_options=None) -> Effect[None, SocketError]The upgrade of a socket that cannot do TLS (Effect's
SocketUpgradeError.unsupported).
| Parameter | Type | Description |
|---|---|---|
_options | TlsUpgradeOptions | None = None |
Returns Effect[None, SocketError]
def unsupported_upgrade(_options: TlsUpgradeOptions | None = None) -> Effect[None, SocketError]:
"""The upgrade of a socket that cannot do TLS (Effect's
``SocketUpgradeError.unsupported``)."""
return fail(upgrade_error())from_web_socket#
from_web_socket(acquire, *, open_timeout=None, high_water_mark=None) -> SocketServiceA socket over the WebSocket each acquisition of the reader gets from
acquire. The reader waits for it to open (open_timeout, ten
seconds by default); a close fails pulls with a SocketCloseError
(code 1000 for a normal close). On a Drainable WebSocket a write
waits while high_water_mark (64 KiB by default) bytes are unsent.
| Parameter | Type | Description |
|---|---|---|
acquire | Effect[WebSocketLike, SocketError, Scope] | |
open_timeout | DurationInput | None = None | |
high_water_mark | int | None = None |
Returns SocketService
def from_web_socket(
acquire: Effect[WebSocketLike, SocketError, Scope],
*,
open_timeout: DurationInput | None = None,
high_water_mark: int | None = None,
) -> SocketService:
"""A socket over the WebSocket each acquisition of the reader gets from
``acquire``. The reader waits for it to open (``open_timeout``, ten
seconds by default); a close fails pulls with a ``SocketCloseError``
(code 1000 for a normal close). On a ``Drainable`` WebSocket a write
waits while ``high_water_mark`` (64 KiB by default) bytes are unsent."""
require_effect(acquire, "acquire")
current = _Current(DEFAULT_HIGH_WATER_MARK if high_water_mark is None else high_water_mark)
timeout = DEFAULT_OPEN_TIMEOUT if open_timeout is None else open_timeout
def reader():
scope = yield from Scope()
ws = yield from acquire
buffer = _Buffer(ws, high_water_mark)
buffer.attach()
def release(_: Exit[object, object]) -> Effect[None]:
def run_release() -> None:
buffer.detach()
current.latch.close_unsafe()
current.ws = None
return sync(run_release)
yield from scope.add_finalizer(release)
if ws.ready_state >= CLOSING:
return (yield from fail(buffer.error or close_error(1006)))
if not buffer.open:
yield from buffer.wait_open().timeout_or_else(
timeout, lambda: _open_timeout(buffer.target)
)
buffer.started()
current.ws = ws
current.latch.open_unsafe()
return Reader(buffer.pull(), unsupported_upgrade)
return make(gen(reader), succeed(Writer(current.write, current.write_all)))layer_web_socket#
layer_web_socket(url, *, open_timeout=None, protocols=None, headers=None, high_water_mark=None) -> Layer[Socket, Never, WebSocketConstructor]Socket as a make_web_socket client.
| Parameter | Type | Description |
|---|---|---|
url | str | Effect[str] | |
open_timeout | DurationInput | None = None | |
protocols | str | Sequence[str] | None = None | |
headers | Mapping[str, str] | None = None | |
high_water_mark | int | None = None |
Returns Layer[Socket, Never, WebSocketConstructor]
def layer_web_socket(
url: str | Effect[str],
*,
open_timeout: DurationInput | None = None,
protocols: str | Sequence[str] | None = None,
headers: Mapping[str, str] | None = None,
high_water_mark: int | None = None,
) -> Layer[Socket, Never, WebSocketConstructor]:
"""``Socket`` as a ``make_web_socket`` client."""
return layer_effect(
Socket,
make_web_socket(
url,
open_timeout=open_timeout,
protocols=protocols,
headers=headers,
high_water_mark=high_water_mark,
),
)make_web_socket#
make_web_socket(url, *, open_timeout=None, protocols=None, headers=None, high_water_mark=None) -> Effect[SocketService, Never, WebSocketConstructor]A WebSocket client socket: each acquisition of the reader connects
to url through the WebSocketConstructor (closed with code 1000
when its scope closes).
| Parameter | Type | Description |
|---|---|---|
url | str | Effect[str] | |
open_timeout | DurationInput | None = None | |
protocols | str | Sequence[str] | None = None | |
headers | Mapping[str, str] | None = None | |
high_water_mark | int | None = None |
Returns Effect[SocketService, Never, WebSocketConstructor]
def make_web_socket(
url: str | Effect[str],
*,
open_timeout: DurationInput | None = None,
protocols: str | Sequence[str] | None = None,
headers: Mapping[str, str] | None = None,
high_water_mark: int | None = None,
) -> Effect[SocketService, Never, WebSocketConstructor]:
"""A WebSocket client socket: each acquisition of the reader connects
to ``url`` through the ``WebSocketConstructor`` (closed with code 1000
when its scope closes)."""
if not isinstance(url, str):
require_effect(url, "url")
url_effect: Effect[str] = succeed(url) if isinstance(url, str) else url
options = WebSocketClientOptions(protocols=protocols, headers=headers)
def build(construct: WebSocketConstructorService) -> SocketService:
acquire = acquire_release(
url_effect.map(lambda target: construct(target, options)),
lambda ws, _: sync(lambda: ws.close(1000)),
)
return from_web_socket(acquire, open_timeout=open_timeout, high_water_mark=high_water_mark)
return WebSocketConstructor().map(build)make_web_socket_channel#
make_web_socket_channel[IE = Never](url, *, open_timeout=None, protocols=None, headers=None, high_water_mark=None) -> Channel[tuple[bytes, ...], SocketError | IE, None, tuple[Chunk | CloseEvent, ...], IE, object, WebSocketConstructor]to_channel of a make_web_socket socket.
| Parameter | Type | Description |
|---|---|---|
url | str | |
open_timeout | DurationInput | None = None | |
protocols | str | Sequence[str] | None = None | |
headers | Mapping[str, str] | None = None | |
high_water_mark | int | None = None |
Returns Channel[tuple[bytes, ...], SocketError | IE, None, tuple[Chunk | CloseEvent, ...], IE, object, WebSocketConstructor]
def make_web_socket_channel[IE = Never](
url: str,
*,
open_timeout: DurationInput | None = None,
protocols: str | Sequence[str] | None = None,
headers: Mapping[str, str] | None = None,
high_water_mark: int | None = None,
) -> Channel[
tuple[bytes, ...],
SocketError | IE,
None,
tuple[Chunk | CloseEvent, ...],
IE,
object,
WebSocketConstructor,
]:
"""``to_channel`` of a ``make_web_socket`` socket."""
def channel(socket: SocketService) -> SocketChannel[bytes, IE]:
return to_channel(socket)
socket = make_web_socket(
url,
open_timeout=open_timeout,
protocols=protocols,
headers=headers,
high_water_mark=high_water_mark,
)
return unwrap_channel(socket.map(channel))Modules#
On This Page
ValuesTypesClassesFunctionsis_clean_closefrom_socketlayer_netlayer_tlsmake_netmake_net_channelmake_tlsmake_tls_channelmake_unixmakemake_channelreader_bytesreader_stringto_channelto_channel_stringto_streamunsupported_upgradefrom_web_socketlayer_web_socketmake_web_socketmake_web_socket_channelModules