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)
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.
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
Returns a Reader for the unpacked object in buf.
| Parameters: |
|
|---|---|
| Return type: |
Returns a Reader for the packed object in buf.
| Parameters: |
|
|---|---|
| Return type: |
Warning
This method is deprecated and will be removed in the 0.5 release. Use the new_message() function instead with **kwargs
Warning
This method is deprecated and will be removed in the 0.5 release. Use the _DynamicStructReader.as_builder() or _DynamicStructBuilder.copy() functions instead
Returns a newly allocated builder message.
| Parameters: |
|
|---|---|
| Return type: |
Returns a Reader for the unpacked object read from file.
| Parameters: |
|
|---|---|
| Return type: |
Returns an iterable, that when traversed will return Readers for messages.
| Parameters: |
|
|---|---|
| Return type: | Iterable with elements of _DynamicStructReader |
Returns an iterable, that when traversed will return Readers for messages.
| Parameters: |
|
|---|---|
| Return type: | Iterable with elements of _DynamicStructReader |
Returns an iterable, that when traversed will return Readers for messages.
| Parameters: |
|
|---|---|
| Return type: | Iterable with elements of _DynamicStructReader |
Returns an iterable, that when traversed will return Readers for messages.
| Parameters: |
|
|---|---|
| Return type: | Iterable with elements of _DynamicStructReader |
Returns a Reader for the packed object read from file.
| Parameters: |
|
|---|---|
| Return type: |
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
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: ‘bool’
A property that returns the _StructSchema object matching this reader
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 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
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
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: |
|
|---|---|
| Return type: | void |
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 |
|---|
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 |
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 |
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: | |
|---|---|
| Return type: | |
| Raises: | KjException if the field isn’t in this struct |
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: ‘bool’
A property that returns the _StructSchema object matching this writer
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. |
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 |
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. |
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 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
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: |
|
|---|---|
| Return type: | void |
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 |
_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)
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 |
|---|
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.
Returns a python object corresponding to the DynamicValue owned by this orphan
Use this DynamicValue to set fields inside the orphan
KjException is a wrapper of the internal C++ exception type. There is an enum named Type listed below, and a bunch of fields
KjException.description(self)
KjException.file(self)
KjException.line(self)
KjException.type(self)
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: | |
|---|---|
| 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 |
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. |
|---|
Remove the import hook, and return python’s import to normal
TwoPartyClient(socket, restorer=None)
TwoPartyServer(socket, restorer=None, server_socket=None, bootstrap=None)
port_promise: object
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 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: | |
|---|---|
| Return type: | ModuleType |
| Returns: | A module corresponding to the loaded schema. You can access parsed schemas and constants with . syntax |
| Raises: |
|
modules_by_id: dict