first

README.md

@@ -0,0 +1,101 @@
+# 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.
+
+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](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://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](https://git.plastiras.org/emdee/tox_profile/wiki/MultiDevice-Announcements-POC) problem is solved. Fork me!
+