API Reference¶

A python library wrapping the Cap’n Proto C++ library

Example Usage:

import capnp

addressbook = capnp.load('addressbook.capnp')

# Building
addresses = addressbook.AddressBook.newMessage()
people = addresses.init('people', 1)

alice = people[0]
alice.id = 123
alice.name = 'Alice'
alice.email = 'alice@example.com'
alicePhone = alice.init('phones', 1)[0]
alicePhone.type = 'mobile'

f = open('example.bin', 'w')
addresses.write(f)
f.close()

# Reading
f = open('example.bin')

addresses = addressbook.AddressBook.read(f)

for person in addresses.people:
    print(person.name, ':', person.email)
    for phone in person.phones:
        print(phone.type, ':', phone.number)

Classes¶

RPC¶

Promise¶

capnp.Promise¶: alias of capnp.lib.capnp._Promise

Promise may be one of:

capnp.lib.capnp._Promise()
capnp.lib.capnp._RemotePromise()
capnp.lib.capnp._VoidPromise()
PromiseFulfillerPair()

class capnp.lib.capnp._Promise(obj=None)¶

attach(self, *args)¶

cancel(self, numParents=1)¶

is_consumed¶: is_consumed: ‘bool’

then(self, func, error_func=None)¶

wait(self)¶

class capnp.lib.capnp._RemotePromise¶

a_wait(self)¶

Asyncio version of wait(). Required when using asyncio for socket communication.

Will still work with non-asyncio socket communication, but requires async handling of the function call.

as_pypromise(self)¶

cancel(self, numParents=1)¶

is_consumed¶: is_consumed: ‘bool’

schema¶: A property that returns the _StructSchema object matching this reader

then(self, func, error_func=None)¶: Promise pipelining, use to queue up operations on a promise before executing the promise.

to_dict(self, verbose=False, ordered=False)¶

wait(self)¶: Wait on the promise. This will block until the promise has completed.

class capnp.lib.capnp._VoidPromise¶

as_pypromise(self)¶

attach(self, *args)¶

cancel(self, numParents=1)¶

is_consumed¶: is_consumed: ‘bool’

then(self, func, error_func=None)¶

wait(self)¶

class capnp.PromiseFulfillerPair¶

fulfill(self)¶

is_consumed¶: is_consumed: ‘bool’

promise¶: promise: capnp.lib.capnp._VoidPromise

Communication¶

class capnp.TwoPartyClient(socket=None, traversal_limit_in_words=None, nesting_limit=None)¶

TwoPartyClient for RPC Communication

Can be initialized using a socket wrapper (libcapnp) or using asyncio controlled sockets.

Parameters

socket – Can be a string defining a socket (e.g. localhost:12345) or a file descriptor for a socket. Passes socket directly to libcapnp. Do not use with asyncio.
traversal_limit_in_words – Pointer derefence limit (see https://capnproto.org/cxx.html).
nesting_limit – Recursive limit when reading types (see https://capnproto.org/cxx.html).

bootstrap(self)¶

on_disconnect(self)¶

read(self, bufsize)¶

libcapnp reader (asyncio sockets only)

Parameters: bufsize – Buffer size to read from the libcapnp library

write(self, data)¶

libcapnp writer (asyncio sockets only)

Parameters: data – Buffer to write to the libcapnp library

class capnp.TwoPartyServer(socket=None, bootstrap=None, traversal_limit_in_words=None, nesting_limit=None)¶

TwoPartyServer for RPC Communication

Can be initialized using a socket wrapper (libcapnp) or using asyncio controlled sockets.

Parameters

socket – Can be a string defining a socket (e.g. localhost:12345, also supports *:12345) or a file descriptor for a socket. Passes socket directly to libcapnp. Do not use with asyncio.
bootstrap – Class object defining the implementation of the Cap’n’proto interface.
traversal_limit_in_words – Pointer derefence limit (see https://capnproto.org/cxx.html).
nesting_limit – Recursive limit when reading types (see https://capnproto.org/cxx.html).

bootstrap(self)¶

on_disconnect(self)¶

poll_forever(self)¶: Poll libcapnp library forever (asyncio)

poll_once(self)¶: Poll libcapnp library one cycle.

port¶

port_promise¶: port_promise: object

read(self, bufsize)¶

libcapnp reader (asyncio sockets only)

Parameters: bufsize – Buffer size to read from the libcapnp library

run_forever(self)¶

write(self, data)¶

libcapnp writer (asyncio sockets only)

Parameters: data – Buffer to write to the libcapnp library

Capability¶

class capnp.lib.capnp._DynamicCapabilityClient¶

cast_as(self, schema)¶

schema¶: A property that returns the _InterfaceSchema object matching this client

upcast(self, schema)¶

Response¶

class capnp.lib.capnp._Response¶

as_builder(self, num_first_segment_words=None)¶

A method for casting this Reader to a Builder

This is a copying operation with respect to the message’s buffer. Changes in the new builder will not reflect in the original reader.

Parameters: num_first_segment_words (int) – Size of the first segment to allocate in the message (in words ie. 8 byte increments)
Return type: _DynamicStructBuilder

is_root¶: is_root: ‘bool’

schema¶: A property that returns the _StructSchema object matching this reader

to_dict(self, verbose=False, ordered=False)¶

total_size¶

which¶

Returns the enum corresponding to the union in this struct

Return type: _DynamicEnumField
Returns: A string/enum corresponding to what field is set in the union
Raises: KjException if this struct doesn’t contain a union

Miscellaneous¶

class capnp.KjException(message=None, nature=None, durability=None, wrapper=None, type=None)¶

KjException is a wrapper of the internal C++ exception type. There is an enum named Type listed below, and a bunch of fields

class Type¶

DISCONNECTED = 'DISCONNECTED'¶

FAILED = 'FAILED'¶

OTHER = 'OTHER'¶

OVERLOADED = 'OVERLOADED'¶

UNIMPLEMENTED = 'UNIMPLEMENTED'¶

reverse_mapping = {'DISCONNECTED': 'DISCONNECTED', 'FAILED': 'FAILED', 'OTHER': 'OTHER', 'OVERLOADED': 'OVERLOADED', 'UNIMPLEMENTED': 'UNIMPLEMENTED'}¶

args¶

property description¶

property file¶

property line¶

property type¶

with_traceback()¶: Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class capnp.SchemaParser¶

A class for loading Cap’n Proto schema files.

Do not use this class unless you’re sure you know what you’re doing. Use the convenience method load() instead.

load(self, file_name, display_name=None, imports=[])¶

Load a Cap’n Proto schema from a file

You will have to load a schema before you can begin doing anything meaningful with this library. Loading a schema is much like loading a Python module (and load even returns a ModuleType). Once it’s been loaded, you use it much like any other Module:

parser = capnp.SchemaParser()
addressbook = parser.load('addressbook.capnp')
print addressbook.qux # qux is a top level constant
# 123
person = addressbook.Person.new_message()

Parameters

file_name (str) – A relative or absolute path to a Cap’n Proto schema
display_name (str) – The name internally used by the Cap’n Proto library for the loaded schema. By default, it’s just os.path.basename(file_name)
imports (list) – A list of str directories to add to the import path.

Return type

ModuleType

Returns

A module corresponding to the loaded schema. You can access parsed schemas and constants with . syntax

Raises

exceptions.IOError if file_name doesn’t exist
KjException if the Cap’n Proto C++ library has any problems loading the schema

modules_by_id¶: modules_by_id: dict

Functions¶

capnp.add_import_hook(additional_paths=[])¶

Add a hook to the python import system, so that Cap’n Proto modules are directly importable

After calling this function, you can use the python import syntax to directly import capnproto schemas. This function is automatically called upon first import of capnp, so you will typically never need to use this function.:

import capnp
capnp.add_import_hook()

import addressbook_capnp
# equivalent to capnp.load('addressbook.capnp', 'addressbook', sys.path), except it will search for 'addressbook.capnp' in all directories of sys.path

Parameters: additional_paths (list) – Additional paths, listed as strings, to be used to search for the .capnp files. It is prepended to the beginning of sys.path. It also affects imports inside of Cap’n Proto schemas.

capnp.cleanup_global_schema_parser()¶: Unloads all of the schema from the current context

capnp.create_event_loop(threaded=True)¶: Create a new global event loop. This will not remove the previous EventLoop for you, so make sure to do that first

capnp.getTimer()¶: Get libcapnp event loop timer

capnp.join_promises(promises)¶

capnp.load(file_name, display_name=None, imports=[])¶

Load a Cap’n Proto schema from a file

You will have to load a schema before you can begin doing anything meaningful with this library. Loading a schema is much like loading a Python module (and load even returns a ModuleType). Once it’s been loaded, you use it much like any other Module:

addressbook = capnp.load('addressbook.capnp')
print addressbook.qux # qux is a top level constant in the addressbook.capnp schema
# 123
person = addressbook.Person.new_message()

Parameters

file_name (str) – A relative or absolute path to a Cap’n Proto schema
display_name (str) – The name internally used by the Cap’n Proto library for the loaded schema. By default, it’s just os.path.basename(file_name)
imports (list) – A list of str directories to add to the import path.

Return type

ModuleType

Returns

A module corresponding to the loaded schema. You can access parsed schemas and constants with . syntax

Raises

KjException if file_name doesn’t exist

capnp.poll_once()¶: Poll libcapnp event loop once

capnp.remove_event_loop(ignore_errors=False)¶: Remove the global event loop

capnp.remove_import_hook()¶: Remove the import hook, and return python’s import to normal

capnp.reset_event_loop(ignore_errors=False, threaded=True)¶: Removes event loop, then creates a new one. See remove_event_loop and create_event_loop for more details.

capnp.wait_forever()¶: Use libcapnp event loop to poll/wait forever

Internal Classes¶

These classes are internal to the library. You will never need to allocate one yourself, but you may end up using some of their member methods.

Modules¶

These are classes that are made for you when you import a Cap’n Proto file:

import capnp
import addressbook_capnp

print type(addressbook_capnp.Person) # capnp.capnp._StructModule

class capnp._InterfaceModule(schema, name)¶

class capnp._StructModule(schema, name)¶

from_bytes(self, buf, traversal_limit_in_words=None, nesting_limit=None, builder=False)¶

Returns a Reader for the unpacked object in buf.

Parameters

buf (buffer) – Any Python object that supports the buffer interface.
traversal_limit_in_words (int) – Limits how many total words of data are allowed to be traversed. Is actually a uint64_t, and values can be up to 2^64-1. Default is 8*1024*1024.
nesting_limit (int) – Limits how many total words of data are allowed to be traversed. Default is 64.
builder (bool) – If true, return a builder object. This will allow you to change the contents of buf, so do this with care.

Return type

_DynamicStructReader or _DynamicStructBuilder

from_bytes_packed(self, buf, traversal_limit_in_words=None, nesting_limit=None)¶

Returns a Reader for the packed object in buf.

Parameters

buf (buffer) – Any Python object that supports the readable buffer interface.
traversal_limit_in_words (int) – Limits how many total words of data are allowed to be traversed. Is actually a uint64_t, and values can be up to 2^64-1. Default is 8*1024*1024.
nesting_limit (int) – Limits how many total words of data are allowed to be traversed. Default is 64.

Return type

_DynamicStructReader

from_segments(self, segments, traversal_limit_in_words=None, nesting_limit=None)¶

Returns a Reader for a list of segment bytes.

This avoids making copies.

NB: This is not currently supported on PyPy.

Return type: list

new_message(self, num_first_segment_words=None, **kwargs)¶

Returns a newly allocated builder message.

Parameters

num_first_segment_words (int) – Size of the first segment to allocate in the message (in words ie. 8 byte increments)
kwargs (dict) – A list of fields and their values to initialize in the struct. Note, this is not an actual argument, but refers to Python’s ability to pass keyword arguments. ie. new_message(my_field=100)

Return type

_DynamicStructBuilder

read(self, file, traversal_limit_in_words=None, nesting_limit=None)¶

Returns a Reader for the unpacked object read from file.

Parameters

file (file) – A python file-like object. It must be a “real” file, with a fileno() method.
traversal_limit_in_words (int) – Limits how many total words of data are allowed to be traversed. Is actually a uint64_t, and values can be up to 2^64-1. Default is 8*1024*1024.
nesting_limit (int) – Limits how many total words of data are allowed to be traversed. Default is 64.

Return type

_DynamicStructReader

read_multiple(self, file, traversal_limit_in_words=None, nesting_limit=None, skip_copy=False)¶

Returns an iterable, that when traversed will return Readers for messages.

Parameters

file (file) – A python file-like object. It must be a “real” file, with a fileno() method.
traversal_limit_in_words (int) – Limits how many total words of data are allowed to be traversed. Is actually a uint64_t, and values can be up to 2^64-1. Default is 8*1024*1024.
nesting_limit (int) – Limits how many total words of data are allowed to be traversed. Default is 64.
skip_copy (bool) – By default, each message is copied because the file needs to advance, even if the message is never read completely. Skip this only if you know what you’re doing.

Return type

Iterable with elements of _DynamicStructReader

read_multiple_bytes(self, buf, traversal_limit_in_words=None, nesting_limit=None)¶

Returns an iterable, that when traversed will return Readers for messages.

Parameters

buf (buffer) – Any Python object that supports the buffer interface.
traversal_limit_in_words (int) – Limits how many total words of data are allowed to be traversed. Is actually a uint64_t, and values can be up to 2^64-1. Default is 8*1024*1024.
nesting_limit (int) – Limits how many total words of data are allowed to be traversed. Default is 64.

Return type

Iterable with elements of _DynamicStructReader

read_multiple_bytes_packed(self, buf, traversal_limit_in_words=None, nesting_limit=None)¶

Returns an iterable, that when traversed will return Readers for messages.

Parameters

buf (buffer) – Any Python object that supports the buffer interface.
traversal_limit_in_words (int) – Limits how many total words of data are allowed to be traversed. Is actually a uint64_t, and values can be up to 2^64-1. Default is 8*1024*1024.
nesting_limit (int) – Limits how many total words of data are allowed to be traversed. Default is 64.

Return type

Iterable with elements of _DynamicStructReader

read_multiple_packed(self, file, traversal_limit_in_words=None, nesting_limit=None, skip_copy=False)¶

Returns an iterable, that when traversed will return Readers for messages.

Parameters

file (file) – A python file-like object. It must be a “real” file, with a fileno() method.
traversal_limit_in_words (int) – Limits how many total words of data are allowed to be traversed. Is actually a uint64_t, and values can be up to 2^64-1. Default is 8*1024*1024.
nesting_limit (int) – Limits how many total words of data are allowed to be traversed. Default is 64.
skip_copy (bool) – By default, each message is copied because the file needs to advance, even if the message is never read completely. Skip this only if you know what you’re doing.

Return type

Iterable with elements of _DynamicStructReader

read_packed(self, file, traversal_limit_in_words=None, nesting_limit=None)¶

Returns a Reader for the packed object read from file.

Parameters

file (file) – A python file-like object. It must be a “real” file, with a fileno() method.
traversal_limit_in_words (int) – Limits how many total words of data are allowed to be traversed. Is actually a uint64_t, and values can be up to 2^64-1. Default is 8*1024*1024.
nesting_limit (int) – Limits how many total words of data are allowed to be traversed. Default is 64.

Return type

_DynamicStructReader

Readers¶

class capnp._DynamicListReader¶

Class for reading Cap’n Proto Lists

This class thinly wraps the C++ Cap’n Proto DynamicList::Reader class. __getitem__ and __len__ have been defined properly, so you can treat this class mostly like any other iterable class:

...
person = addressbook.Person.read(file)

phones = person.phones # This returns a _DynamicListReader

phone = phones[0]
print phone.number

for phone in phones:
    print phone.number

class capnp._DynamicStructReader¶

Reads Cap’n Proto structs

This class is almost a 1 for 1 wrapping of the Cap’n Proto C++ DynamicStruct::Reader. The only difference is that instead of a get method, __getattr__ is overloaded and the field name is passed onto the C++ equivalent get. This means you just use . syntax to access any field. For field names that don’t follow valid python naming convention for fields, use the global function getattr():

person = addressbook.Person.read(file) # This returns a _DynamicStructReader
print person.name # using . syntax
print getattr(person, 'field-with-hyphens') # for names that are invalid for python, use getattr

as_builder(self, num_first_segment_words=None)¶

A method for casting this Reader to a Builder

This is a copying operation with respect to the message’s buffer. Changes in the new builder will not reflect in the original reader.

Parameters: num_first_segment_words (int) – Size of the first segment to allocate in the message (in words ie. 8 byte increments)
Return type: _DynamicStructBuilder

is_root¶: is_root: ‘bool’

schema¶: A property that returns the _StructSchema object matching this reader

to_dict(self, verbose=False, ordered=False)¶

total_size¶

which¶

Returns the enum corresponding to the union in this struct

Return type: _DynamicEnumField
Returns: A string/enum corresponding to what field is set in the union
Raises: KjException if this struct doesn’t contain a union

class capnp._PackedFdMessageReader(file, traversal_limit_in_words=None, nesting_limit=None)¶

Read a Cap’n Proto message from a file descriptor in a packed manner

You use this class to for reading message(s) from a file. It’s analagous to the inverse of _write_packed_message_to_fd() and _MessageBuilder, but in one class.:

f = open('out.txt')
message = _PackedFdMessageReader(f)
person = message.get_root(addressbook.Person)
print person.name

Parameters

fd (int) - A file descriptor

get_root(self, schema)¶

A method for instantiating Cap’n Proto structs

You will need to pass in a schema to specify which struct to instantiate. Schemas are available in a loaded Cap’n Proto module:

addressbook = capnp.load('addressbook.capnp')
...
person = message.get_root(addressbook.Person)

Parameters: schema (Schema) – A Cap’n proto schema specifying which struct to instantiate
Return type: _DynamicStructReader
Returns: An object with all the data of the read Cap’n Proto message. Access members with . syntax.

get_root_as_any(self)¶

A method for getting a Cap’n Proto AnyPointer, from an already pre-written buffer

Don’t use this method unless you know what you’re doing.

Return type: _DynamicObjectReader
Returns: An AnyPointer that you can read from

class capnp._StreamFdMessageReader(file, traversal_limit_in_words=None, nesting_limit=None)¶

Read a Cap’n Proto message from a file descriptor

You use this class to for reading message(s) from a file. It’s analagous to the inverse of _write_message_to_fd() and _MessageBuilder, but in one class:

f = open('out.txt')
message = _StreamFdMessageReader(f)
person = message.get_root(addressbook.Person)
print person.name

Parameters

fd (int) - A file descriptor

get_root(self, schema)¶

A method for instantiating Cap’n Proto structs

You will need to pass in a schema to specify which struct to instantiate. Schemas are available in a loaded Cap’n Proto module:

addressbook = capnp.load('addressbook.capnp')
...
person = message.get_root(addressbook.Person)

Parameters: schema (Schema) – A Cap’n proto schema specifying which struct to instantiate
Return type: _DynamicStructReader
Returns: An object with all the data of the read Cap’n Proto message. Access members with . syntax.

get_root_as_any(self)¶

A method for getting a Cap’n Proto AnyPointer, from an already pre-written buffer

Don’t use this method unless you know what you’re doing.

Return type: _DynamicObjectReader
Returns: An AnyPointer that you can read from

Builders¶

class capnp._DynamicResizableListBuilder(parent, field, schema)¶

Class for building growable Cap’n Proto Lists

Warning

You need to call finish() on this object before serializing the Cap’n Proto message. Failure to do so will cause your objects not to be written out as well as leaking orphan structs into your message.

This class works much like _DynamicListBuilder, but it allows growing the list dynamically. It is meant for lists of structs, since for primitive types like int or float, you’re much better off using a normal python list and then serializing straight to a Cap’n Proto list. It has __getitem__ and __len__ defined, but not __setitem__:

...
person = addressbook.Person.new_message()

phones = person.init_resizable_list('phones') # This returns a _DynamicResizableListBuilder

phone = phones.add()
phone.number = 'foo'
phone = phones.add()
phone.number = 'bar'

people.finish()

f = open('example', 'w')
person.write(f)

add(self)¶

A method for adding a new struct to the list

This will return a struct, in which you can set fields that will be reflected in the serialized Cap’n Proto message.

Return type: _DynamicStructBuilder

finish(self)¶

A method for closing this list and serializing all its members to the message

If you don’t call this method, the items you previously added from this object will leak into the message, ie. inaccessible but still taking up space.

class capnp._DynamicListBuilder¶

Class for building Cap’n Proto Lists

This class thinly wraps the C++ Cap’n Proto DynamicList::Bulder class. __getitem__, __setitem__, and __len__ have been defined properly, so you can treat this class mostly like any other iterable class:

...
person = addressbook.Person.new_message()

phones = person.init('phones', 2) # This returns a _DynamicListBuilder

phone = phones[0]
phone.number = 'foo'
phone = phones[1]
phone.number = 'bar'

for phone in phones:
    print phone.number

adopt(self, index, _DynamicOrphan orphan)¶

A method for adopting Cap’n Proto orphans

Don’t use this method unless you know what you’re doing. Orphans are useful for dynamically allocating objects for an unknown sized list.

Parameters

index (int) – The index of the element in the list to replace with the newly adopted object
orphan (_DynamicOrphan) – A Cap’n proto orphan to adopt. It will be unusable after this operation.

Return type

void

disown(self, index)¶

A method for disowning Cap’n Proto orphans

Don’t use this method unless you know what you’re doing.

Parameters: index (int) – The index of the element in the list to disown
Return type: _DynamicOrphan

init(self, index, size)¶

A method for initializing an element in a list

Parameters

index (int) – The index of the element in the list
size (int) – Size of the element to be initialized.

class capnp._DynamicStructBuilder¶

Builds Cap’n Proto structs

This class is almost a 1 for 1 wrapping of the Cap’n Proto C++ DynamicStruct::Builder. The only difference is that instead of a get/set method, __getattr__/__setattr__ is overloaded and the field name is passed onto the C++ equivalent function. This means you just use . syntax to access or set any field. For field names that don’t follow valid python naming convention for fields, use the global functions getattr()/setattr():

person = addressbook.Person.new_message() # This returns a _DynamicStructBuilder

person.name = 'foo' # using . syntax
print person.name # using . syntax

setattr(person, 'field-with-hyphens', 'foo') # for names that are invalid for python, use setattr
print getattr(person, 'field-with-hyphens') # for names that are invalid for python, use getattr

adopt(self, field, _DynamicOrphan orphan)¶

A method for adopting Cap’n Proto orphans

Don’t use this method unless you know what you’re doing. Orphans are useful for dynamically allocating objects for an unknown sized list.

Parameters

field (str) – The field name in the struct
orphan (_DynamicOrphan) – A Cap’n proto orphan to adopt. It will be unusable after this operation.

Return type

void

as_reader(self)¶

A method for casting this Builder to a Reader

This is a non-copying operation with respect to the message’s buffer. This means changes to the fields in the original struct will carry over to the new reader.

Return type: _DynamicStructReader

clear_write_flag(self)¶

A method used to clear the _is_written flag.

This allows you to write the struct more than once without seeing any warnings.

copy(self, num_first_segment_words=None)¶

A method for copying this Builder

This is a copying operation with respect to the message’s buffer. Changes in the new builder will not reflect in the original reader.

Parameters: num_first_segment_words (int) – Size of the first segment to allocate in the message (in words ie. 8 byte increments)
Return type: _DynamicStructBuilder

disown(self, field)¶

A method for disowning Cap’n Proto orphans

Don’t use this method unless you know what you’re doing.

Parameters: field (str) – The field name in the struct
Return type: _DynamicOrphan

from_dict(self, dict d)¶

init(self, field, size=None)¶

Method for initializing fields that are of type union/struct/list

Typically, you don’t have to worry about initializing structs/unions, so this method is mainly for lists.

Parameters

field (str) – The field name to initialize
size (int) – The size of the list to initiialize. This should be None for struct/union initialization.

Return type

_DynamicStructBuilder or _DynamicListBuilder

Raises

KjException if the field isn’t in this struct

init_resizable_list(self, field)¶

Method for initializing fields that are of type list (of structs)

This version of init returns a _DynamicResizableListBuilder that allows you to add members one at a time (ie. if you don’t know the size for sure). This is only meant for lists of Cap’n Proto objects, since for primitive types you can just define a normal python list and fill it yourself.

Warning

You need to call _DynamicResizableListBuilder.finish() on the list object before serializing the Cap’n Proto message. Failure to do so will cause your objects not to be written out as well as leaking orphan structs into your message.

Parameters: field (str) – The field name to initialize
Return type: _DynamicResizableListBuilder
Raises: KjException if the field isn’t in this struct

is_root¶: is_root: ‘bool’

schema¶: A property that returns the _StructSchema object matching this writer

to_bytes(self)¶

Returns the struct’s containing message as a Python bytes object in the unpacked binary format.

This is inefficient; it makes several copies.

Return type: bytes
Raises: KjException if this isn’t the message’s root struct.

to_bytes_packed(self)¶

to_dict(self, verbose=False, ordered=False)¶

to_segments(self)¶

Returns the struct’s containing message as a Python list of Python bytes objects.

This avoids making copies.

NB: This is not currently supported on PyPy.

Return type: list

total_size¶

which¶

Returns the enum corresponding to the union in this struct

Return type: _DynamicEnumField
Returns: A string/enum corresponding to what field is set in the union
Raises: KjException if this struct doesn’t contain a union

write(self, file)¶

Writes the struct’s containing message to the given file object in unpacked binary format.

This is a shortcut for calling capnp._write_message_to_fd(). This can only be called on the message’s root struct.

Parameters: file (file) – A file or socket object (or anything with a fileno() method), open for write.
Return type: void
Raises: KjException if this isn’t the message’s root struct.

write_packed(self, file)¶

Writes the struct’s containing message to the given file object in packed binary format.

This is a shortcut for calling capnp._write_packed_message_to_fd(). This can only be called on the message’s root struct.

Parameters: file (file) – A file or socket object (or anything with a fileno() method), open for write.
Return type: void
Raises: KjException if this isn’t the message’s root struct.

class capnp._MallocMessageBuilder(size=None)¶

The main class for building Cap’n Proto messages

You will use this class to handle arena allocation of the Cap’n Proto messages. You also use this object when you’re done assigning to Cap’n Proto objects, and wish to serialize them:

addressbook = capnp.load('addressbook.capnp')
message = capnp._MallocMessageBuilder()
person = message.init_root(addressbook.Person)
person.name = 'alice'
...
f = open('out.txt', 'w')
_write_message_to_fd(f.fileno(), message)

get_root(self, schema)¶

A method for instantiating Cap’n Proto structs, from an already pre-written buffer

Don’t use this method unless you know what you’re doing. You probably want to use init_root instead:

addressbook = capnp.load('addressbook.capnp')
...
person = message.init_root(addressbook.Person)
...
person = message.get_root(addressbook.Person)

Parameters: schema (Schema) – A Cap’n proto schema specifying which struct to instantiate
Return type: _DynamicStructBuilder
Returns: An object where you will set all the members

get_root_as_any(self)¶

A method for getting a Cap’n Proto AnyPointer, from an already pre-written buffer

Don’t use this method unless you know what you’re doing.

Return type: _DynamicObjectBuilder
Returns: An AnyPointer that you can set fields in

get_segments_for_output(self)¶

init_root(self, schema)¶

A method for instantiating Cap’n Proto structs

You will need to pass in a schema to specify which struct to instantiate. Schemas are available in a loaded Cap’n Proto module:

addressbook = capnp.load('addressbook.capnp')
...
person = message.init_root(addressbook.Person)

Parameters: schema (Schema) – A Cap’n proto schema specifying which struct to instantiate
Return type: _DynamicStructBuilder
Returns: An object where you will set all the members

new_orphan(self, schema)¶

A method for instantiating Cap’n Proto orphans

Don’t use this method unless you know what you’re doing. Orphans are useful for dynamically allocating objects for an unknown sized list, ie:

addressbook = capnp.load('addressbook.capnp')
m = capnp._MallocMessageBuilder()
alice = m.new_orphan(addressbook.Person)

Parameters: schema (Schema) – A Cap’n proto schema specifying which struct to instantiate
Return type: _DynamicOrphan
Returns: An orphan representing a _DynamicStructBuilder

set_root(self, value)¶

A method for instantiating Cap’n Proto structs by copying from an existing struct

Parameters: value (_DynamicStructReader) – A Cap’n Proto struct value to copy
Return type: void

RPC¶

class capnp._CapabilityClient¶

cast_as(self, schema)¶

class capnp._DynamicCapabilityClient¶

cast_as(self, schema)¶

schema¶: A property that returns the _InterfaceSchema object matching this client

upcast(self, schema)¶

Miscellaneous¶

class capnp._DynamicOrphan¶

get(self)¶

Returns a python object corresponding to the DynamicValue owned by this orphan

Use this DynamicValue to set fields inside the orphan

API Reference¶

Classes¶

RPC¶

Promise¶

Communication¶

Capability¶

Response¶

Miscellaneous¶

Functions¶

Internal Classes¶

Modules¶

Readers¶

Builders¶

RPC¶

Miscellaneous¶

Table of Contents

Previous topic

This Page