toxygen_wrapper/README.md

94 lines
4.0 KiB
Markdown
Raw Normal View History

2022-09-24 05:41:12 +02:00
# toxygen_wrapper
2022-09-26 06:37:38 +02:00
[ctypes](https://docs.python.org/3/library/ctypes.html)
2022-09-26 06:54:59 +02:00
wrapping of [Tox](https://tox.chat/)
[```libtoxcore```](https://github.com/TokTok/c-toxcore) into Python.
2022-09-26 06:37:38 +02:00
Taken from the ```wrapper``` directory of the now abandoned
2022-09-26 06:54:59 +02:00
<https://github.com/toxygen-project/toxygen> ```next_gen``` branch
2022-09-24 06:35:33 +02:00
by Ingvar.
2023-12-07 20:38:26 +01:00
2022-09-25 09:21:16 +02:00
The basics of NGC groups are supported, as well as AV and toxencryptsave.
2022-09-26 06:37:38 +02:00
There is no coverage of conferences as they are not used in ```toxygen```
2022-09-26 05:32:07 +02:00
and the list of still unwrapped calls as of Sept. 2022 can be found in
2023-12-15 15:24:07 +01:00
```tox.c-toxcore.missing```. The code is typed so that every call in
```tox*.py``` should have the right signature, and it runs
2022-09-26 06:54:59 +02:00
```toxygen``` with no apparent issues.
2022-09-26 05:32:07 +02:00
It has been tested with UDP and TCP proxy (Tor). It has ***not*** been
2022-09-26 06:37:38 +02:00
tested on Windows, and there may be some minor breakage, which should be
2023-12-15 15:24:07 +01:00
easy to fix. There is a good coverage integration testsuite in ```tox_wrapper/tests```.
2022-10-07 06:47:34 +02:00
Change to that directory and run ```tests_wrapper.py --help```; the test
suite gives a good set of examples of usage.
2022-09-24 06:00:03 +02:00
## Install
2023-12-15 15:24:07 +01:00
Run ```python3 setup.py install``` or put the parent of the wrapper
directory on your PYTHONPATH and touch a file called `__init__.py`
in its parent directory.
2022-09-24 06:00:03 +02:00
2023-12-15 15:24:07 +01:00
Then you need a ```libs``` directory beside the ```tox_wrapper``` directory
2022-09-26 06:37:38 +02:00
and you need to link your ```libtoxcore.so``` and ```libtoxav.so```
and ```libtoxencryptsave.so``` into it. 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```). If you want to be different,
2023-12-15 15:24:07 +01:00
the environment variable TOXCORE_LIBS overrides the location of ```libs```;
look in the file ```tox_wrapper/libtox.py``` for the details.
# Tests
To test, run ```python3 tox_wrapper/tests/tests_wrapper.py --help```
2022-09-26 06:37:38 +02:00
2022-09-26 08:20:28 +02:00
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
2023-12-15 15:24:07 +01:00
```tox_wrapper/tests/tests_wrapper.py```.
2022-09-26 08:20:28 +02:00
2022-09-24 06:00:03 +02:00
## Prerequisites
2022-09-24 06:35:33 +02:00
No prerequisites in Python3.
2022-09-24 06:00:03 +02:00
2022-09-24 06:35:33 +02:00
## Other wrappers
2022-09-24 06:00:03 +02:00
There are a number of other wrappings into Python of Tox core.
2022-09-26 06:37:38 +02:00
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
2022-09-26 06:54:59 +02:00
```gdb``` (```gdb -ex r --args /usr/bin/python3.9 <pyfile>```).
2022-09-26 06:37:38 +02:00
2022-09-25 09:21:16 +02:00
CTYPES code can be brittle, segfaulting if you've got things wrong,
2022-09-24 06:35:33 +02:00
but if your wrapping is right, it is very efficient and easy to work on.
2022-09-26 06:54:59 +02:00
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).
2022-09-24 06:00:03 +02:00
Others include:
2022-09-24 06:35:33 +02:00
* <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
2022-09-25 09:21:16 +02:00
java, rust, scalla, go, etc. bindings instead.
No support for NGC groups or toxencryptsave.
2022-09-24 06:35:33 +02:00
* <https://github.com/oxij/PyTox>
forked from https://github.com/aitjcize/PyTox
by Wei-Ning Huang <aitjcize@gmail.com>.
2022-09-25 09:21:16 +02:00
Hardcore C wrapping which is not easy to keep up to date.
2023-12-07 20:38:26 +01:00
No support for NGC or toxencryptsave. Abandonned.
2022-09-25 09:21:16 +02:00
This was the basis for the TokTok/py-toxcore-c code until recently.
2022-10-07 06:47:34 +02:00
To our point of view, the ability of CTYPEs to follow code in the
2022-10-24 00:14:35 +02:00
debugger is a crucial advantage.
2022-10-18 02:16:56 +02:00
Work on this project is suspended until the
2022-10-27 08:50:47 +02:00
[MultiDevice](https://git.plastiras.org/emdee/tox_profile/wiki/MultiDevice-Announcements-POC) problem is solved. Fork me!