4.6 KiB
tox_wrapper
ctypes
wrapping of Tox
libtoxcore into Python
using ctypesgen
The full c-toxcore library is covered, but it doesn't actually work yet -
dunno why.
The code is typed so that every call in tox*.py should have the
right signature.
It has been tested with UDP and TCP proxy (Tor). It has not been
tested on Windows, and there may be some minor breakage, which should be
easy to fix. There is a good coverage integration testsuite in
tox_wrapper/tests. Change to that directory and run
tests_wrapper.py --help; the test suite gives a good set of examples of usage.
Install
Run make install or put the parent of the wrapper directory on
your PYTHONPATH and touch a file called __init__.py in its parent
directory.
Set the TOXCORE_LIBS environment variable to say where to find
your libtoxcore.so and libtoxav.so and libtoxencryptsave.so
files. Link all 3 filenames to libtoxcore.so if you have only
libtoxcore.so (which is usually the case if you built
c-toxcore with cmake rather than
autogen/configure). The environment variable TOXCORE_LIBS overrides;
look in the file tox_wrapper/libtox.py for the details.
Tests
To test, run python3 tox_wrapper/tests/tests_wrapper.py --help
As is, the code in tox.py is very verbose. Edit the file to change
def LOG_ERROR(a): print('EROR> '+a)
def LOG_WARN(a): print('WARN> '+a)
def LOG_INFO(a): print('INFO> '+a)
def LOG_DEBUG(a): print('DBUG> '+a)
def LOG_TRACE(a): pass # print('TRAC> '+a)
to all pass # or use logging.logger to suite your tastes.
logging.logger can be dangerous in callbacks in Qt applications,
so we use simple print statements as default. The same applies to
tox_wrapper/tests/tests_wrapper.py.
Prerequisites
No prerequisites in Python3 other than ctypesgen.
Other wrappers
There are a number of other wrappings into Python of Tox core.
This one uses ctypes
which has its merits - there is no need to recompile anything as with
Cython - change the Python file and it's done. And you can follow things
in a Python debugger, or with the utterly stupendous Python feature of
gdb (gdb -ex r --args /usr/bin/python3.11 <pyfile>).
CTYPES code can be brittle, segfaulting if you've got things wrong,
but if your wrapping is right, it is very efficient and easy to work on.
The faulthandler
module can be helpful in debugging crashes
(e.g. from segmentation faults produced by erroneous C library wrapping).
Others include:
-
https://git.plastiras.org/emdee/toxygen_wrapper Ctypes bindings originally from https://github.com/toxygen-project/toxygen
next_genbranch by Ingvar. Those bindings work, unlike these. Because it's ctypes you can follow things in a Python debugger, or with the utterly stupendous Python feature ofgdb. -
https://github.com/TokTok/py-toxcore-c Cython bindings. Incomplete and not really actively supported. Maybe it will get worked on in the future, but TokTok seems to be working on java, rust, scalla, go, etc. bindings instead. No support for NGC groups or toxencryptsave.
-
https://github.com/oxij/PyTox forked from https://github.com/aitjcize/PyTox by Wei-Ning Huang aitjcize@gmail.com. Hardcore C wrapping which is not easy to keep up to date. No support for NGC or toxencryptsave. Abandonned. This was the basis for the TokTok/py-toxcore-c code until recently.
To our point of view, the ability of CTYPEs to follow code in the debugger is a crucial advantage.
Updates
Although Tox works over Tor, we do not recommend its usage for anonymity as it leaks DNS requests due to a 6-year old known security issue: https://github.com/TokTok/c-toxcore/issues/469 unless your Tox client does hostname lookups before calling Tox (like toxygen does). Otherwise, do not use it for anonymous communication unless you have a firewall in place.
The Tox project does not follow semantic versioning of its main structures so the project may break the underlying ctypes wrapper at any time, so you should run ctypesgen each time you install a new version of c-toxcore.
Up-to-date code is on https://git.plastiras.org/emdee/tox_wrapper
Work on this project is suspended until the MultiDevice problem is solved. Fork me!