Skip to content

Python API reference

Jump to bottom
Radovan Blažek edited this page Jul 4, 2025 · 1 revision

Python API

Main module of Compost

class compost_rpc.BitU(value, *args, **kwargs)

Bases: int

Unsigned bit precise integer

classmethod pack(buffer: memoryview, offset: MemUnit, value: int)

Serializes integer numeric type to specific bit offset in the buffer. The value may be packed to lower bit-size.

size = MemUnit(bits=0, bytes=0)

classmethod unpack(buffer: memoryview, offset: MemUnit)

class compost_rpc.CCodeGenerator(protocol: type[Protocol])

Bases: CodeGenerator

property features : CodeGeneratorFeatures

Features that the generator supports

generate(endpoint: Endpoint = Endpoint.REMOTE)

Generates the source code as a list of filepaths and string contents. :param endpoint: The endpoint to generate the code for. :type endpoint: Endpoint

property name : str

Full long name of the language

property path

Path used for generated source files.

property path_header : Path

Change path where the header file (.h) will be generated.

property path_source : Path

Change path where the source file (.c) will be generated.

property short_name : str

Short name used for user input

class compost_rpc.CSharpCodeGenerator(protocol: type[Protocol])

Bases: CodeGenerator

classmethod doc_string(doc: str)

property features : CodeGeneratorFeatures

Features that the generator supports

generate(endpoint: Endpoint = Endpoint.LOCAL)

Generates the source code as a list of filepaths and string contents. :param endpoint: The endpoint to generate the code for. :type endpoint: Endpoint

property is_partial : bool

If true, the protocol class is declared as partial.

property name : str

Full long name of the language

property namespace : str

Specifies the namespace for the generated code.

property short_name : str

Short name used for user input

property use_collection_expression : bool

If true, the arguments for InvokeRpcAsync will be passed as collection expression (C# 12 and later) instead of collection initializer.

property use_primary_constructor : bool

If true, the mandatory protocol constructor will be generated as primary constructor (C# 12 and later).

class compost_rpc.CallDirection(value, names=, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

TO_LOCAL = 1

TO_REMOTE = 0

TWO_WAY = 2

class compost_rpc.CodeGenerator(protocol: type[Protocol])

Bases: ABC

abstract property features : CodeGeneratorFeatures

Features that the generator supports

property filename : str

Filename used for generated source files.

abstract generate(endpoint: Endpoint)

Generates the source code as a list of filepaths and string contents. :param endpoint: The endpoint to generate the code for. :type endpoint: Endpoint

abstract property name : str

Full long name of the language

property path

Filename used for generated source files.

abstract property short_name : str

Short name used for user input

class compost_rpc.CodeGeneratorFeatures(inbound_remote: bool, outbound_remote: bool, inbound_notification: bool, outbound_notification: bool)

Bases: object

property inbound_notification : bool

Target language can handle incoming notifications

property inbound_rpc : bool

Target language can handle incoming RPC calls

property outbound_notification : bool

Target language can invoke notification

property outbound_rpc : bool

Target language can invoke RPC

class compost_rpc.CompostSlice

Bases: bytes

Represents dynamically sized array of U8

fmt = ''

size = MemUnit(bits=0, bytes=0)

class compost_rpc.CompostString

Bases: str

String based on the compost_slice_u8

fmt = ''

size = MemUnit(bits=0, bytes=0)

class compost_rpc.Endpoint(value, names=, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

LOCAL = 1

REMOTE = 0

is_call_inbound(call: Rpc)

is_call_outbound(call: Rpc)

class compost_rpc.F32(value, *args, **kwargs)

Bases: float

32-bit floating point number

fmt = '>f'

size = MemUnit(bits=32, bytes=4)

class compost_rpc.F64(value, *args, **kwargs)

Bases: float

64-bit floating point number

fmt = '>d'

size = MemUnit(bits=64, bytes=8)

class compost_rpc.Generator(protocol: type[Protocol])

Bases: object

property c : CCodeGenerator

property csharp : CSharpCodeGenerator

property force_overwrite : bool

If true, existing files will be overwritten without prompt.

run()

class compost_rpc.Header(len_: int, txn: int, resp: bool, rpc_id: int)

Bases: object

Compost message header

header_struct = Struct('>BBH')

msg_byte_len()

Returns the length of the message in bytes.

pack()

payload_byte_len()

Returns the length of the payload in bytes.

classmethod unpack(header: bytes)

class compost_rpc.I16(value, *args, **kwargs)

Bases: int

16-bit signed integer

fmt = '>h'

size = MemUnit(bits=16, bytes=2)

class compost_rpc.I32(value, *args, **kwargs)

Bases: int

32-bit signed integer

fmt = '>i'

size = MemUnit(bits=32, bytes=4)

class compost_rpc.I64(value, *args, **kwargs)

Bases: int

64-bit signed integer

fmt = '>q'

size = MemUnit(bits=64, bytes=8)

class compost_rpc.I8(value, *args, **kwargs)

Bases: int

8-bit signed integer

fmt = '>b'

size = MemUnit(bits=8, bytes=1)

class compost_rpc.MemUnit(bits: int = 0)

Bases: object

Represents a memory size that can be specified in bits or bytes. Now immutable.

BITS_PER_BYTE = 8

property bits : int

byte_align()

Aligns the MemUnit to the next byte boundary if not already aligned.

property bytes : int

classmethod from_bytes(bytes_: int)

is_byte_aligned()

class compost_rpc.Msg(header: Header, payload: bytes)

Bases: object

Raw Compost message that does not know the meaning of the payload.

classmethod from_data(txn: int, response: bool, rpc_id: int, payload: bytes)

pack()

classmethod unpack(payload: bytes)

class compost_rpc.PayloadSerdes(types: list[type])

Bases: object

pack(*args)

unpack(data: bytes)

class compost_rpc.Protocol(transport: Transport, timeout: float = 1)

Bases: object

class compost_rpc.RawEthernetTransport(interface: str, destination_mac: bytes, source_mac: bytes)

Bases: Transport

receive()

Receives Compost message over the transport

send(msg: bytes)

Sends Compost message over the transport

exception compost_rpc.RequestError

Bases: RpcError

Received error message instead of a result.

exception compost_rpc.RequestTimeoutError

Bases: RpcError

Response not received in time.

class compost_rpc.Rpc(rpc_id: int, name: str, req_serdes: PayloadSerdes, resp_serdes: PayloadSerdes, call_sig: Signature, is_notification: bool, direction: CallDirection, doc: str | None)

Bases: object

get_param_items()

subscribe(callback)

unsubscribe(callback)

exception compost_rpc.RpcError

Bases: Exception

Generic RPC error.

class compost_rpc.RpcTypingProtocol(*args, **kwargs)

Bases: Protocol[P, R]

subscribe(handler)

unsubscribe(handler)

class compost_rpc.SerialTransport(serial_port: str, baudrate: int)

Bases: Transport

receive()

Receives Compost message over the transport

send(msg: bytes)

Sends Compost message over the transport

class compost_rpc.StdioTransport(executable: str)

Bases: Transport

receive()

Receives Compost message over the transport

send(msg: bytes)

Sends Compost message over the transport

class compost_rpc.TcpTransport(target_ip: str, target_port: int)

Bases: Transport

receive()

Receives Compost message over the transport

send(msg: bytes)

Sends Compost message over the transport

class compost_rpc.Transport(*args, **kwargs)

Bases: Protocol

receive()

Receives Compost message over the transport

send(msg: bytes)

Sends Compost message over the transport

class compost_rpc.U16(value, *args, **kwargs)

Bases: int

16-bit unsigned integer

fmt = '>H'

size = MemUnit(bits=16, bytes=2)

class compost_rpc.U32(value, *args, **kwargs)

Bases: int

32-bit unsigned integer

fmt = '>I'

size = MemUnit(bits=32, bytes=4)

class compost_rpc.U64(value, *args, **kwargs)

Bases: int

64-bit unsigned integer

fmt = '>Q'

size = MemUnit(bits=64, bytes=8)

class compost_rpc.U8(value, *args, **kwargs)

Bases: int

8-bit unsigned integer

fmt = '>B'

size = MemUnit(bits=8, bytes=1)

class compost_rpc.UdpTransport(target_ip: str, target_port: int)

Bases: Transport

receive()

Receives Compost message over the transport

send(msg: bytes)

Sends Compost message over the transport

exception compost_rpc.UnexpectedTxnError

Bases: RpcError

Received unexpected txn value.

exception compost_rpc.UnknownRpcIdError

Bases: RpcError

Remote does not know the rpc_id. Incompatible protocol.

compost_rpc.colorful_exception_hook(exc_type, exc_value, exc_traceback)

compost_rpc.enum(cls: C)

Decorator for enums to make them usable with Compost RPC defintions.

Use this for enum definitions ala C.

Example:

from compost_rpc import enum

@enum
class OtaResult(I8, Enum):
    OTA_OK = 0
    OTA_ERR = 1

compost_rpc.main()

compost_rpc.notification(rpc_id: int, direction: CallDirection = CallDirection.TO_LOCAL)

Registers function as notification.

Example:

from compost_rpc import struct

@struct
class LogMessage:
    severity: U8
    tag: U8
    message: list[U8]

@notification(0x100)
def notify_log(self, log: LogMessage):
    """Sends the log message."""

compost_rpc.pack_payload(types: list[type], *args)

Serializes Python objects in arguments to bytes

compost_rpc.rpc(rpc_id: int, notification: bool = False, direction: CallDirection = CallDirection.TO_REMOTE)

Registers function as remotely callable.

Example:

from compost_rpc import rpc

@rpc(0x001)
def read8(self, address: U32) -> U8:
    """Reads 8 bits of data from the specified address"""

compost_rpc.struct(cls: C)

Decorator for classes to make them usable with Compost RPC definitions.

Use this for structure definitions ala C.

Example:

from compost_rpc import struct

@struct
class OtaCoreLoad:
    core0: I8
    core1: I8
    dsph: I8

compost_rpc.unpack_payload(types: list[type], payload: bytes)

Deserializes message payload into a tuple of Python objects

Clone this wiki locally