API Reference¶

`chumicro_sockets`¶

The three socket entry points (connector, listener, udp_socket), the SSL-context builders behind their tls= flag, and set_default_ca_bundle for replacing the shipped trust store.

`chumicro_sockets` ¶

Cross-runtime TCP, TLS, and UDP sockets for CircuitPython, MicroPython, and CPython.

The public factories are connector, listener, and udp_socket.

`UnsupportedSSLConfigError` ¶

Bases: RuntimeError

Raised when the requested TLS configuration is not supported on this runtime.

`connector(host, port, *, tls=False, context=None, radio=None)` ¶

Return a non-blocking, tick-driven TCP or TLS connector.

Parameters:

Name	Type	Description	Default
`host`	`str`	DNS name or IP literal; also the TLS `server_hostname` when `tls=True`.	required
`port`	`int`	Remote port.	required
`tls`	`bool`	`True` wraps the connection in TLS.	`False`
`context`	`object \| None`	SSLContext for the `tls=True` path; `None` uses the runtime default trust store.	`None`
`radio`	`object \| None`	CP-only radio object (pass `wifi.radio` on CP boards); ignored elsewhere.	`None`

Returns:

Type	Description
`object`	A `SocketConnector` in the `"awaiting_dns"` state.

`listener(host, port, *, tls=False, context=None, backlog=4, radio=None)` ¶

Open a non-blocking TCP or TLS listening socket.

Parameters:

Name	Type	Description	Default
`host`	`str`	Address to bind. `"0.0.0.0"` accepts on every interface.	required
`port`	`int`	TCP port to bind.	required
`tls`	`bool`	`True` TLS-wraps every accepted client.	`False`
`context`	`object \| None`	Server-side `ssl.SSLContext`; required when `tls=True`, ignored otherwise.	`None`
`backlog`	`int`	Depth of the pending-connection queue.	`4`
`radio`	`object \| None`	CP-only radio object (pass `wifi.radio` on CP boards); ignored elsewhere.	`None`

Returns:

Type	Description
`object`	A listening socket exposing `accept()` / `close()` / `setblocking()`.

Raises:

Type	Description
`ValueError`	`tls=True` was passed without a `context`.
`OSError`	Bind or listen failed (port in use, permission denied).
`UnsupportedSSLConfigError`	`tls=True` on CP-rp2 boards.
`TypeError`	The CircuitPython runtime was invoked with `radio=None`.

`ssl_context_with_cert_and_key(cert_pem, key_pem)` ¶

Build a server-side SSLContext from in-memory cert and key bytes.

Parameters:

Name	Type	Description	Default
`cert_pem`	`str \| bytes`	PEM-encoded server certificate (or chain).	required
`key_pem`	`str \| bytes`	PEM-encoded private key matching the certificate.	required

Returns:

Type	Description
`object`	A configured :class:`ssl.SSLContext`.

`ssl_context_with_cert_and_key_paths(cert_path, key_path)` ¶

Build a server-side SSLContext from cert and key files on flash.

Parameters:

Name	Type	Description	Default
`cert_path`	`str`	On-device path to the certificate PEM file.	required
`key_path`	`str`	On-device path to the private-key PEM file.	required

Returns:

Type	Description
`object`	A configured :class:`ssl.SSLContext`.

`udp_socket(bind_host='0.0.0.0', bind_port=0, *, radio=None, broadcast=False)` ¶

Open a UDP datagram socket bound to (bind_host, bind_port).

Parameters:

Name	Type	Description	Default
`bind_host`	`str`	Local address to bind. `"0.0.0.0"` binds every interface.	`'0.0.0.0'`
`bind_port`	`int`	Local port. `0` requests an ephemeral port.	`0`
`radio`	`object \| None`	CP-only radio object (pass `wifi.radio` on CP boards); ignored elsewhere.	`None`
`broadcast`	`bool`	Set `SO_BROADCAST` so `sendto` to a broadcast address succeeds.	`False`

Returns: A bound UDP socket.

Raises:

Type	Description
`OSError`	Bind failed (port in use, permission denied).
`TypeError`	The CircuitPython runtime was invoked with `radio=None`.

`ssl_context_with_ca(ca_pem)` ¶

Build an SSLContext that trusts the CA(s) in ca_pem.

Parameters:

Name	Type	Description	Default
`ca_pem`	`str \| bytes`	CA bundle; PEM on every runtime, DER (`bytes`) on MicroPython and CPython only.	required

Returns:

Type	Description
`object`	A configured :class:`ssl.SSLContext`.

Raises:

Type	Description
`ValueError`	The input is not an accepted format for the runtime.

`ssl_context_no_verify()` ¶

Return an SSLContext that skips certificate verification.

Returns:

Type	Description
`object`	A configured :class:`ssl.SSLContext` with verification disabled.

`set_default_ca_bundle(pem_bytes)` ¶

Replace or revert the CA bundle used by connector(tls=True, context=None).

Parameters:

Name	Type	Description	Default
`pem_bytes`	`bytes \| str \| None`	PEM-encoded CA bundle as bytes or str, or `None` to revert to the shipped bundle.	required

`chumicro_sockets.sockets_factory`¶

Builders that turn hosts, ports, and TLS material into the transport callable a networking library asks for at construction. connector_factory returns the (host, port, use_tls) callable chumicro-requests and chumicro-websockets expect, and fixed_connector_factory pins one endpoint and returns the no-argument form chumicro-mqtt takes. listener_factory returns the listening-socket callable the HTTP and WebSocket servers take, and udp_socket_factory returns a fresh bound datagram socket per call, the way chumicro-ntp uses it.

`chumicro_sockets.sockets_factory` ¶

Generic transport factories for the chumicro networking libraries.

Builders take hosts, ports, and TLS material as parameters. Protocol config namespaces (mqtt.broker.host and friends) belong to each protocol library's from_config, never here.

The module name ends in _factory so the deploy walker's __chumicro_skip_factories__ family matching drops it from bring-your-own-transport deploys, and with it the only reference that would pull :mod:chumicro_sockets onto the board.

`connector_factory(*, radio=None, ssl_context=None)` ¶

Build a (host, port, use_tls) -> SocketConnector factory.

`fixed_connector_factory(host, port, *, radio=None, ssl_context=None)` ¶

Build a () -> SocketConnector factory for one fixed endpoint.

`listener_factory(host, port, *, radio=None, ssl_context=None, cert_path=None, key_path=None)` ¶

Build a () -> ListeningSocket factory, TLS when material is given.

TLS engages when ssl_context or cert_path is set; an explicit ssl_context wins over paths.

`udp_socket_factory(*, radio=None)` ¶

Build a () -> socket factory returning a fresh bound UDP socket.

`chumicro_sockets.generators`¶

Socket I/O as yield from steps for generators registered with Runner.add_generator: connect drives a connector until it hands back a connected socket, send_all writes a whole buffer, and recv_until and recv_exact read a delimited or a fixed-length chunk. Each one suspends whenever the socket would block, so the rest of the device keeps running while it waits.

`chumicro_sockets.generators` ¶

Generator helpers for socket I/O driven by a tick-based scheduler.

The public helpers are connect, send_all, recv_until, and recv_exact.

`connect(connector, *, timeout_ms=None, ticks=None)` ¶

Drive connector across runner ticks and return its connected socket.

Parameters:

Name	Type	Description	Default
`connector`	`object`	Any object exposing the `SocketConnector` surface.	required
`timeout_ms`	`int \| None`	Deadline in ms for the whole connect; `None` waits indefinitely.	`None`
`ticks`	`object \| None`	`chumicro_timing`-shaped tick source; required when timeout_ms is set.	`None`

Yields:

Type	Description
`object`	The connector itself, repeatedly, until terminal.

Returns:

Type	Description
`object`	The connected, non-blocking socket; the caller owns its lifecycle.

Raises:

Type	Description
`OSError`	The connector reached `failed`, or `ETIMEDOUT` on timeout.
`ValueError`	timeout_ms was given without a ticks source.

`send_all(sock, data)` ¶

Send every byte of data, yielding on EAGAIN.

Parameters:

Name	Type	Description	Default
`sock`	`object`	Non-blocking TCP socket.	required
`data`	`object`	Bytes-like object to transmit.	required

Yields:

Type	Description
`object`	A `WriteWait` carrying sock on each `EAGAIN`.

Raises:

Type	Description
`OSError`	The peer closed mid-send, or the socket reported a non-EAGAIN error.

`recv_until(sock, separator, *, max_bytes)` ¶

Read until separator appears; return everything up to and including it.

Parameters:

Name	Type	Description	Default
`sock`	`object`	Non-blocking TCP socket.	required
`separator`	`object`	Bytes pattern that terminates the read (for example `b"\r\n"`).	required
`max_bytes`	`int`	Hard cap on accumulated bytes, so a peer cannot force an unbounded read.	required

Yields:

Type	Description
`bytes`	A `ReadWait` on each `EAGAIN`.

Returns:

Type	Description
`bytes`	`bytes` from the start through the first occurrence of separator, inclusive.

Raises:

Type	Description
`OSError`	The peer closed before the separator, growth exceeded max_bytes, or a non-EAGAIN error.
`ValueError`	max_bytes is not positive.

`recv_exact(sock, byte_count, *, max_bytes)` ¶

Read exactly byte_count bytes and return them as bytes.

Parameters:

Name	Type	Description	Default
`sock`	`object`	Non-blocking TCP socket.	required
`byte_count`	`int`	Number of bytes to read. Must be positive.	required
`max_bytes`	`int`	Hard cap on the buffer, so a peer-controlled length cannot force an unbounded allocation.	required

Yields:

Type	Description
`bytes`	A `ReadWait` on each `EAGAIN`.

Returns:

Type	Description
`bytes`	`bytes` of length exactly byte_count.

Raises:

Type	Description
`OSError`	The peer closed before byte_count bytes arrived, or a non-EAGAIN error.
`ValueError`	byte_count or max_bytes is not positive, or byte_count exceeds max_bytes.

`chumicro_sockets.waits`¶

The two wait objects the generator helpers yield. ReadWait(sock) and WriteWait(sock) tell the runner which socket to poll and, given a deadline_ms, when to give up. Yield them directly when you write a generator helper of your own.

`chumicro_sockets.waits` ¶

The socket I/O wait vocabulary: ReadWait and WriteWait.

`ReadWait` ¶

Wait for sock to become readable, optionally bounded by a deadline.

`WriteWait` ¶

Wait for sock to become writable, optionally bounded by a deadline.

API Reference¶

chumicro_sockets¶

chumicro_sockets ¶

UnsupportedSSLConfigError ¶

connector(host, port, *, tls=False, context=None, radio=None) ¶

listener(host, port, *, tls=False, context=None, backlog=4, radio=None) ¶

ssl_context_with_cert_and_key(cert_pem, key_pem) ¶

ssl_context_with_cert_and_key_paths(cert_path, key_path) ¶

udp_socket(bind_host='0.0.0.0', bind_port=0, *, radio=None, broadcast=False) ¶

ssl_context_with_ca(ca_pem) ¶

ssl_context_no_verify() ¶

set_default_ca_bundle(pem_bytes) ¶

chumicro_sockets.sockets_factory¶

chumicro_sockets.sockets_factory ¶

connector_factory(*, radio=None, ssl_context=None) ¶

fixed_connector_factory(host, port, *, radio=None, ssl_context=None) ¶

listener_factory(host, port, *, radio=None, ssl_context=None, cert_path=None, key_path=None) ¶

udp_socket_factory(*, radio=None) ¶

chumicro_sockets.generators¶

chumicro_sockets.generators ¶

connect(connector, *, timeout_ms=None, ticks=None) ¶

send_all(sock, data) ¶

recv_until(sock, separator, *, max_bytes) ¶

recv_exact(sock, byte_count, *, max_bytes) ¶

chumicro_sockets.waits¶

chumicro_sockets.waits ¶

ReadWait ¶

WriteWait ¶

`chumicro_sockets`¶

`chumicro_sockets` ¶

`UnsupportedSSLConfigError` ¶

`connector(host, port, *, tls=False, context=None, radio=None)` ¶

`listener(host, port, *, tls=False, context=None, backlog=4, radio=None)` ¶

`ssl_context_with_cert_and_key(cert_pem, key_pem)` ¶

`ssl_context_with_cert_and_key_paths(cert_path, key_path)` ¶

`udp_socket(bind_host='0.0.0.0', bind_port=0, *, radio=None, broadcast=False)` ¶

`ssl_context_with_ca(ca_pem)` ¶

`ssl_context_no_verify()` ¶

`set_default_ca_bundle(pem_bytes)` ¶

`chumicro_sockets.sockets_factory`¶

`chumicro_sockets.sockets_factory` ¶

`connector_factory(*, radio=None, ssl_context=None)` ¶

`fixed_connector_factory(host, port, *, radio=None, ssl_context=None)` ¶

`listener_factory(host, port, *, radio=None, ssl_context=None, cert_path=None, key_path=None)` ¶

`udp_socket_factory(*, radio=None)` ¶

`chumicro_sockets.generators`¶

`chumicro_sockets.generators` ¶

`connect(connector, *, timeout_ms=None, ticks=None)` ¶

`send_all(sock, data)` ¶

`recv_until(sock, separator, *, max_bytes)` ¶

`recv_exact(sock, byte_count, *, max_bytes)` ¶

`chumicro_sockets.waits`¶

`chumicro_sockets.waits` ¶

`ReadWait` ¶

`WriteWait` ¶