tox_wrapper/README.md

# tox_wrapper

[ctypes](https://docs.python.org/3/library/ctypes.html)
wrapping of [Tox](https://tox.chat/)
[```libtoxcore```](https://github.com/TokTok/c-toxcore) into Python
using [ctypesgen](https://github.com/ctypesgen/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.
You can use pip to install the package from the source:
```
make install
```

# 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 GUI applications
if it's wired up to a console, 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](https://docs.python.org/3/library/ctypes.html)
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](https://docs.python.org/3/library/faulthandler.html)
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_gen``` branch 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 of ```gdb```.

* <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

To regerate the bindings to a new c-toxcore, install ctypesgen
and exit the Makefile to set CTOXCORE to where your c-toxcore is. Then
```
make install
```
Then try patching the resulting file with:
```
patch -b -z .dst src/tox_wrapper/tox_ctypesgen.py \
      < src/tox_wrapper/tox_ctypesgen.py.diff
```
You may need to resolve any rejections if the ctypesgen file has changed.

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](https://git.plastiras.org/emdee/tox_wrapper) 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](https://git.plastiras.org/emdee/tox_profile/wiki/MultiDevice-Announcements-POC) problem is solved. Fork me!