GitHub

API reference for socket.

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

AttributeTypeDescription
SOCKET_ERROR_REASONUnionSchema[SocketReadError | SocketWriteError | SocketOpenError | SocketUpgradeError | SocketCloseError, Mapping[str, object], Never, Never]

The schema of every reason (Effect's SocketErrorReason schema).

Types

TypeDefinitionDescription
OpenErrorKindtype OpenErrorKind = Literal['Unknown', 'Timeout']
SocketErrorReasontype SocketErrorReason = SocketReadError | SocketWriteError | SocketOpenError | SocketUpgradeError | SocketCloseError
Chunktype Chunk = bytes | str
PemInputtype PemInput = str | bytes
SocketChanneltype SocketChannel[A, IE] = Channel[tuple[A, ...], SocketError | IE, None, tuple[Chunk | CloseEvent, ...], IE, object]
Upgradetype Upgrade = Callable[[TlsUpgradeOptions | None], Effect[None, SocketError]]
Writetype Write = Callable[[Chunk | CloseEvent], Effect[None, SocketError]]
WriteAlltype WriteAll = Callable[[Sequence[Chunk]], Effect[None, SocketError]]
Listenertype Listener = Callable[[WebSocketEvent], None]
WebSocketConstructorServicetype WebSocketConstructorService = Callable[[str, WebSocketClientOptions], WebSocketLike]
WebSocketEventTypetype WebSocketEventType = Literal['open', 'message', 'error', 'close']

Classes

Functions

is_clean_close

is_clean_close(error) -> bool

Whether error is a normal close (code 1000).

ParameterTypeDescription
errorSocketError

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 == 1000

from_socket

from_socket(open, *, tls_server=False, open_timeout=None, chunk_size=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.

ParameterTypeDescription
openEffect[socket.socket, SocketError, Scope]
tls_serverbool = False
open_timeoutDurationInput | None = None
chunk_sizefloat = 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]
ParameterTypeDescription
portint
hoststr = 'localhost'
open_timeoutDurationInput | None = None
chunk_sizefloat = 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]
ParameterTypeDescription
portint
hoststr = 'localhost'
tlsTlsUpgradeOptions | None = None
open_timeoutDurationInput | None = None
chunk_sizefloat = 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) -> 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.

ParameterTypeDescription
portint
hoststr = 'localhost'
open_timeoutDurationInput | None = None
chunk_sizefloat = 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]
ParameterTypeDescription
portint
hoststr = 'localhost'
open_timeoutDurationInput | None = None
chunk_sizefloat = 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) -> 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.

ParameterTypeDescription
portint
hoststr = 'localhost'
tlsTlsUpgradeOptions | None = None
open_timeoutDurationInput | None = None
chunk_sizefloat = 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]
ParameterTypeDescription
portint
hoststr = 'localhost'
tlsTlsUpgradeOptions | None = None
open_timeoutDurationInput | None = None
chunk_sizefloat = 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) -> SocketService

A socket connecting to the Unix socket at path.

ParameterTypeDescription
pathstr
open_timeoutDurationInput | 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
ParameterTypeDescription
readerEffect[Reader, SocketError, Scope]
writerEffect[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.

ParameterTypeDescription
socketSocketService

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.

ParameterTypeDescription
socketSocketService
encodingstr = '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.

ParameterTypeDescription
socketSocketService

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.

ParameterTypeDescription
socketSocketService
encodingstr = '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.

ParameterTypeDescription
socketSocketService

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).

ParameterTypeDescription
_optionsTlsUpgradeOptions | 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) -> 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.

ParameterTypeDescription
acquireEffect[WebSocketLike, SocketError, Scope]
open_timeoutDurationInput | None = None
high_water_markint | 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.

ParameterTypeDescription
urlstr | Effect[str]
open_timeoutDurationInput | None = None
protocolsstr | Sequence[str] | None = None
headersMapping[str, str] | None = None
high_water_markint | 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).

ParameterTypeDescription
urlstr | Effect[str]
open_timeoutDurationInput | None = None
protocolsstr | Sequence[str] | None = None
headersMapping[str, str] | None = None
high_water_markint | 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.

ParameterTypeDescription
urlstr
open_timeoutDurationInput | None = None
protocolsstr | Sequence[str] | None = None
headersMapping[str, str] | None = None
high_water_markint | 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