API Reference¶
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 |
required |
port
|
int
|
Remote port. |
required |
tls
|
bool
|
|
False
|
context
|
object | None
|
SSLContext for the |
None
|
radio
|
object | None
|
CP-only radio object (pass |
None
|
Returns:
| Type | Description |
|---|---|
object
|
A |
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. |
required |
port
|
int
|
TCP port to bind. |
required |
tls
|
bool
|
|
False
|
context
|
object | None
|
Server-side |
None
|
backlog
|
int
|
Depth of the pending-connection queue. |
4
|
radio
|
object | None
|
CP-only radio object (pass |
None
|
Returns:
| Type | Description |
|---|---|
object
|
A listening socket exposing |
Raises:
| Type | Description |
|---|---|
ValueError
|
|
OSError
|
Bind or listen failed (port in use, permission denied). |
UnsupportedSSLConfigError
|
|
TypeError
|
The CircuitPython runtime was invoked with |
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_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: |
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'
|
bind_port
|
int
|
Local port. |
0
|
radio
|
object | None
|
CP-only radio object (pass |
None
|
broadcast
|
bool
|
Set |
False
|
Returns: A bound UDP socket.
Raises:
| Type | Description |
|---|---|
OSError
|
Bind failed (port in use, permission denied). |
TypeError
|
The CircuitPython runtime was invoked with |
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 ( |
required |
Returns:
| Type | Description |
|---|---|
object
|
A configured :class: |
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: |
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 |
required |