Package: pycapnp
pycapnpCap'n'proto Mailing ListDocumentationRequirementsC++14 supported compilergcc 6.1+ (5+ may work)clang 6 (3.4+ may work)Visual Studio 2017+cmake (needed for bundled capnproto)ninja (macOS + Linux)Visual Studio 2017+capnproto-0.8.0 (>=0.7.0 will also work if linking to system libraries)Not necessary if using bundled capnprotoPython development headers (i.e. Python.h)Distributables from python.org include these, however they are usually in a separate package on Linux distributions32-bit Linux requires that capnproto be compiled with-fPIC. This is usually set correctly unless you are compiling canproto yourself. This is also called-DCMAKE_POSITION_INDEPENDENT_CODE=1for cmake.pycapnp has additional development dependencies, including cython and pytest. See requirements.txt for them all.Building and installationInstall withpip install pycapnp. You can set the CC environment variable to control which compiler is used, ieCC=gcc-8.2 pip install pycapnp.Or you can clone the repo like so:gitclonehttps://github.com/capnproto/pycapnp.gitcdpycapnp
pipinstall.If you wish to install using the latest upstream C++ Cap'n Proto:pipinstall\--install-option"--libcapnp-url"\--install-option"https://github.com/capnproto/capnproto/archive/master.tar.gz"\--install-option"--force-bundled-libcapnp".To force bundled python:pipinstall--install-option"--force-bundled-libcapnp".Slightly more prompt error messages using distutils rather than pip.pythonsetup.pyinstall--force-bundled-libcapnpThe bundling system isn't that smart so it might be necessary to clean up the bundled build when changing versions:pythonsetup.pycleanPython VersionsPython 3.7+ is supported.
Earlier versions of Python have asyncio bugs that might be possible to work around, but may require significant work (3.5 and 3.6).DevelopmentGit flow has been abandoned, use master.To test, use a pipenv (or install requirements.txt and run pytest manually).pipinstallpipenv
pipenvinstall
pipenvrunpytestBinary PackagesBuilding a dumb binary distribution:pythonsetup.pybdist_dumbBuilding a Python wheel distributiion:pythonsetup.pybdist_wheelDocumentation/ExampleThere is some basic documentationhere.Make sure to look at theexamples. The examples are generally kept up to date with the recommended usage of the library.The examples directory has one example that shows off pycapnp quite nicely. Here it is, reproduced:importosimportcapnpimportaddressbook_capnpdefwriteAddressBook(file):addresses=addressbook_capnp.AddressBook.new_message()people=addresses.init('people',2)alice=people[0]alice.id=123alice.name='Alice'alice.email='alice@example.com'alicePhones=alice.init('phones',1)alicePhones[0].number="555-1212"alicePhones[0].type='mobile'alice.employment.school="MIT"bob=people[1]bob.id=456bob.name='Bob'bob.email='bob@example.com'bobPhones=bob.init('phones',2)bobPhones[0].number="555-4567"bobPhones[0].type='home'bobPhones[1].number="555-7654"bobPhones[1].type='work'bob.employment.unemployed=Noneaddresses.write(file)defprintAddressBook(file):addresses=addressbook_capnp.AddressBook.read(file)forpersoninaddresses.people:print(person.name,':',person.email)forphoneinperson.phones:print(phone.type,':',phone.number)which=person.employment.which()print(which)ifwhich=='unemployed':print('unemployed')elifwhich=='employer':print('employer:',person.employment.employer)elifwhich=='school':print('student at:',person.employment.school)elifwhich=='selfEmployed':print('self employed')print()if__name__=='__main__':f=open('example','w')writeAddressBook(f)f=open('example','r')printAddressBook(f)Also, pycapnp has gained RPC features that include pipelining and a promise style API. Refer to the calculator example in the examples directory for a much better demonstration:importcapnpimportsocketimporttest_capability_capnpclassServer(test_capability_capnp.TestInterface.Server):def__init__(self,val=1):self.val=valdeffoo(self,i,j,**kwargs):returnstr(i*5+self.val)defserver(write_end):server=capnp.TwoPartyServer(write_end,bootstrap=Server(100))defclient(read_end):client=capnp.TwoPartyClient(read_end)cap=client.bootstrap()cap=cap.cast_as(test_capability_capnp.TestInterface)remote=cap.foo(i=5)response=remote.wait()assertresponse.x=='125'if__name__=='__main__':read_end,write_end=socket.socketpair(socket.AF_UNIX)# This is a toy example using socketpair.# In real situations, you can use any socket.server(write_end)client(read_end)Changelogv1.3.0 (2023-01-26)Update to bundled capnproto-0.10.3Add Python 3.11 to Github Actions builds (#306)Prevent race condition in example code (#305)v1.2.2 (2022-12-01)Update bundled bundled capnp to 0.8.1 due to CVE-2022-46149Bundle lib/capnp_api.h and helpers/capabilityHelper.cpp (#301)Avoid reading random values for reader options from dangling reference (#300)v1.2.1 (2022-09-11)Fix packaging for Apple Siliconv1.2.0 (2022-08-29)Added support for Apple Siliconv1.1.1 (2022-05-23)Added Python 3.10 supportaarch64 wheel supportFix doc string for_DynamicResizableListBuilderfix for unreleased buffers under mmap (issue 280)v1.1.0 (2021-06-09)Validated compatibility with Python 3.10.0b2Remove all bare exceptImprove_StructModuleWhichto inherit fromenum.EnumAdd Union on top level union messagesFixed memory leak in_SegmentArrayMessageReaderRemoved many pycodestyle warningsAvoid crash if__file__is not set by importerFixed module.pyx_set_<field>for boolean fieldsFixed setup.py.tmpl support for*.c++filesFixed_gen.pyfor python3 asdict_keysobject are not indexable.Add test data to sdistAddpyproject.yamlAdd missing inheritance to_Schemafor_StructSchemav1.0.0 (2020-11-20)Validated Python 3.9 (3.7 and 3.8 are also supported)Updated package to include LICENSE fileUpdated examples to avoid run_forever() as ctrl+c will not workAdding xfail to pytest cases which fail sometimes due to network port oddities (please use asyncio, as Python handles things more gracefully)v1.0.0b2 (2020-06-14)Minimum capnproto version is now 0.8.0Added asyncio ssl calculator testAdded poll_once to TwoPartyServer APIMore cleanupFix absolute and circular importsFix Promise aliasing issue (Promise to _Promise)Documentation updateUpdated installation instructionsAdded RPC documentation for asynciov1.0.0b1 (2019-12-26)Python 3.7+ required (asyncio support)TLS/SSL support using asyncioWindows supportGeneral cleanupMay be incompatible with code written for pycapnp 0.6.4 and lowerRemoving pypandoc/pandoc packaging requirementMinimum capnproto version is now 0.7.0v0.6.4 (2019-01-31)Fix bugs inread_multiple_bytes(thanks to @tsh56)Remove end-of-life Python versions 2.6, 3.2, and 3.3. Add CI tests for 3.6Expose SchemaParser in Cython headerv0.6.3 (2018-01-14)Bump bundled capnp version to v0.6.1 (thanks to @E8Yuval)Fix a memleak in RemotePromise (thanks to @E8Yuval)v0.6.2 (2017-11-30)Add support for buffers/memoryviews infrom_bytes(thanks to @aldanor)v0.6.1 (2017-07-27)Fixed upload to PyPi (forgot to cythonize)v0.6.0 (2017-07-27)Update bundled capnp version to v0.6.0 and fix related problems (thanks to @benmoran)Fix memleak with KjException (thanks to @tsh56)v0.5.12 (2017-04-18)Bump bundled capnp version to v0.5.3.1v0.5.11 (2017-04-10)Make enums hashable (thanks to @madeleine-empirical)Rework logic on when to build bundled libcapnp. Fixes cross-compilation (thanks to @benizl)Add traversal_limit_in_words and nesting_limit to RPC classes (thanks to @asilversempirical)Include class attributes indir. This allows for code completion of class methods (thanks to @chaoflow )Allow setting lists with python tuples (thanks to @chaoflow)Fix traversal_limit_in_words and nesting_limit being ignored byfrom_bytes(thanks to @plesner)v0.5.10 (2016-11-28)Fix bug that prevented event loop from actually being lazy initializedFix possible recursive loop in KjExceptionAddclear_write_flagmethod to builder classesv0.5.9 (2016-07-07)Make the event loop be lazy initializedAdd support for segment (de)serialization (thanks to @gcv). See to_segments/from_segments methods.Fix response objects not referencing parents correctlyAdd test for large readsv0.5.8 (2016-05-27)Fix build problem with Cython v0.24Include the changelog in the manifest (should fix install problems if pandoc is present)Include the traceback in exceptionsMake sure to encode to utf-8, not the default encoding (thanks to @novas0x2a)Add --libcapnp-url option in installer to allow installing arbitrary libcapnp versionsSupport mmap objects for reading with from_bytes (thanks to @bpiwowar)Change read_multiple and read_multiple_packed to copy by defaultFix mistakenly discarding the file parameter on readsAdd reraise_kj_exception to the prettyPrint functions. (thanks to @kdienes)Fix KjException init (missing wrapper). (thanks to @E8-Storage)Addresult_typeto InterfaceMethodSchemav0.5.7 (2015-06-16)Update bundled libcapnp to v0.5.2Add warnings for using old restorer methods. You should usebootstrapinsteadFix warning from PyEventPortHandle AnyPointers better as arguments to RPC functionsAdd support for using keyword arguments with a named struct in an RPCAdd bootstrap method to TwoPartyServerAddinitmethod to listsAdd support for unix sockets in RPCv0.5.6 (2015-04-13)Fix a serious bug in TwoPartyServer that was preventing it from working when passed a string address.Fix bugs that were exposed by defining KJDEBUG (thanks @davidcarne for finding this)v0.5.5 (2015-03-06)Update bundled C++ libcapnp to v0.5.1.2 security releasev0.5.4 (2015-03-02)Update bundled C++ libcapnp to v0.5.1.1 security releaseAdd bootstrap RPC methodsFix possible segfault when importing multiple schemasv0.5.3 (2015-02-23)Fix possible crash due to bad destructor ordering in MessageReader (by @JohnEmhoff)Default to no longer using cythonv0.5.2 (2015-02-20)Add read_multiple_bytes/read_multiple_bytes_packed methodsAdded Python 3.4 to the travis build matrixBump version for bundled C++ libcapnp to v0.5.1v0.5.1 (2014-12-27)Remove installation dependency on cython. We now have no dependencies since libcapnp will automatically build as well.v0.5.0 (2014-12-15)Timer classcapnp.getTimer()pycapnp is now thread-safe and allows an event loop to be run in each threadYou must destroy and re-create the event loop to get this functionality (seetest_threads.py)Inheritance now works correctly for interfaces (previously inherited methods were inaccessible from pycapnp)Add ability to import modules with dashes or spaces. Use underscores in place of themfrom_byteswith builder=True is no longer zero copy. It never worked correctly, and is much safer nowAddnum_first_segment_wordsargument wherever message creation can occurAllow restoring a null objectId by passing None to restoreSupport ordered dictionary into_dictAdd ListSchema class and schemas for native types undercapnp.typeswhich completes all the Schemas needed to be wrapped. Seetest_schema.pyfor examples using itAdd automatic build of C++ libcapnp if it's not detected on the system. Also add flags --force-bundled-libcapnp and --force-system-libcapnp respectivelyv0.4.6 (2014-9-10)Fix build for new 0.21 release of Cython. 0.21 is now the minimum supported version of Cython.v0.4.5 (2014-6-26)Fixto_dictnot converting enums to stringsv0.4.4 (2014-04-25)Fix compilation problem with gcc 4.8v0.4.3 (2014-02-18)Fix problem with uninitialized unions in _from_dictAdd accesible version numbers for C++ libcapnpv0.4.2 (2014-02-13)Remove onDrained since it was removed upstreamReplace usage of strings as enum type with custom_DynamicEnumclass.Also changeStruct.which()method to be a propertyStruct.whichand return an enum type (_DynamicEnumField, which behaves much like_DynamicEnum).TwoPartyServer.run_forever() now will handle more than 1 simulataneous connection.Change exception wrapper to detect and raise AttributeError for field lookup exceptions (Fixes problem in Python3.x__dir__)Allow setting of fields with python dicts.0.4.1 (2013-12-18)Remove python 3.2 from travis tests. Python 3.2 still should work fine, but it's more trouble than it's worth to write unicode tests that work in both it and Python2.Fix problems with null characters in Text/Data fields. Fixes #190.4.0 (2013-12-12)Initial working version of RPCAdd get_root_as_any to _MessageReaderAdd capnp.pxd for public declarations of cython classesFix problems compiling with gcc4.7v0.3.18 (2013-11-05)Change naming of ReaderOption parameters to be pep8 compliantv0.3.17 (2013-11-05)Add ReaderOptions to read/read_packed/from_bytesv0.3.16 (2013-10-28)Add defaults flag to capnp-json. Also remove 'which' fieldAdd capnp-json serializer script. Also fix bugs in from_dictFix build for clang/python3. Also remove -fpermissiveAddas_buildermethod to Struct ReaderAdd warning when writing the same message more than onceFirst working version of capability interfacesWrap InterfaceSchemaFix setting string fields to support all types of stringsFix changed API for DynamicObject/ObjectPointerv0.3.15 (2013-09-19)Add not having installed the C++ libcapnp library to 'Common Problems'Add _short_str function for use in capnp_test_pycapnp.pyAdd test script for testing withhttps://github.com/kaos/capnp_testAdd handling of DynamicObjectFix lists of lists or dicts for from_dictv0.3.14 (2013-09-04)Fix problem with to_dictv0.3.13 (2013-09-04)Add _DynamicStructBuilder.to_bytes() and .from_bytes()Change == on StructSchema to return cboolAdd Builder and Reader ABCs for each struct typev0.3.12 (2013-09-03)Fix handling of empty path '' in load_moduleAdd from_dictFix bug in exception handling for which(). Also standardize exceptions.Change import hook to require modules to end in '_capnp'Add import monkey patch function.Change naming for functions to conform to PEP 8. Also deprecate old read/write APIUpdate preferred method for reading/writing messages from filesv0.3.11 (2013-09-01)Forgot to change project name in setup.pyv0.3.10 (2013-09-01)Change all references to old project name (change from capnpc-python-cpp to pycapnp)Change DynamicValue.Reader lists to be returned as _DynamicListReaderUnify setters for DynamicList and DynamicStructAdd shortcuts for reading from / writing to files.  In Python, it doesn't make much sense to force people to muck around with MessageReaders and MessageBuilders since everything is landing on the heap anyway.  Instead, let's make it easy:  MyType.read[Packed]From(file) reads a file and returns a MyType reader.  MyType.newMessage() returns a MyType builder representing the root of a new message.  You can call this builder's write[Packed]To(file) method to write it to a file.Store Builders by value rather than allocate them separately on the heap (matches treatment of Readers).  v0.3 fixes the bug that made this not work.Wrap MessageBuilder::setRoot().Add tests based on TestAllTypes from the C++ test.capnp.  Fix problems uncovered in capnp.pyx.Implementstrandreprfor struct and list builders.struses prettyPrint whilereprshows the type name and the low-whitespace stringification.  Also implementreprfor StructSchema, just because why not?v0.3.9 (2013-08-30)Change load to use a global SchemaParser. Make structs settable as fieldAdd docstrings for new functions and _DynamicResizableListBuilderv0.3.8 (2013-08-29)Add initial testsAdd _capnp for original Cython module. Meant for testing.Lowercase schema so it conforms to member naming conventionsExpose _StructSchema's raw nodeAdd some useful _StructSchema, reader, and builder methodsAdd full orphan functionality. Also, allow special orphan listsFinish up adding docstrings to all public classes/methodsv0.3.7 (2013-08-26)Add a ton of docstrings and add to official docsAdd DynamicOrphanv0.3.6 (2013-08-26)Add intersphinx for linking to python docsAdd C++ library version checkv0.3.5 (2013-08-25)Add handling of constants in schemasFix new error with DynamicValue.Builder no longer being copyablev0.3.4 (2013-08-22)Fix Void namespace changeUpdated capnp schema to conform with new union rulesv0.3.3 (2013-08-22)Fix for the removal of DynamicUnion from the C++ APIv0.3.2 (2013-08-21)Add MANIFEST.in to include READMEv0.3.1 (2013-08-21)Update docs with lines about upgrading setuptools0.3.0 (2013-08-21)Initial commit of docsAdd querying unnamed enums to structs0.2.1 (2013-08-13)Fix enum interface change for benchmarkRandom formatting cleanupAllow import paths in the schema loaderAdd travis CI0.2.0 (2013-08-12)Initial working version