diff --git a/python/README.rst b/python/README.rst index 272c6c6ce..af74606d4 100644 --- a/python/README.rst +++ b/python/README.rst @@ -1,84 +1,77 @@ ========================= -deltachat python bindings +DeltaChat Python bindings ========================= -This package provides bindings to the deltachat-core_ Rust -library -which implements IMAP/SMTP/MIME/PGP e-mail standards and offers +This package provides `Python bindings`_ to the `deltachat-core library`_ +which implements IMAP/SMTP/MIME/OpenPGP e-mail standards and offers a low-level Chat/Contact/Message API to user interfaces and bots. +.. _`deltachat-core library`: https://github.com/deltachat/deltachat-core-rust +.. _`Python bindings`: https://py.delta.chat/ Installing pre-built packages (Linux-only) -======================================================== +========================================== If you have a Linux system you may try to install the ``deltachat`` binary "wheel" packages without any "build-from-source" steps. -Otherwise you need to `compile the Delta Chat bindings yourself <#sourceinstall>`_. +Otherwise you need to `compile the Delta Chat bindings yourself`__. + +__ sourceinstall_ We recommend to first `install virtualenv `_, then create a fresh Python virtual environment and activate it in your shell:: - virtualenv venv # or: python -m venv - source venv/bin/activate + virtualenv env # or: python -m venv + source env/bin/activate Afterwards, invoking ``python`` or ``pip install`` only -modifies files in your ``venv`` directory and leaves +modifies files in your ``env`` directory and leaves your system installation alone. -For Linux, we automatically build wheels for all github PR branches -and push them to a python package index. To install the latest -github ``master`` branch:: +For Linux we build wheels for all releases and push them to a python package +index. To install the latest release:: - pip install --pre -i https://m.devpi.net/dc/master deltachat + pip install deltachat To verify it worked:: python -c "import deltachat" -.. note:: - - If you can help to automate the building of wheels for Mac or Windows, - that'd be much appreciated! please then get - `in contact with us `_. - - Running tests ============= -After successful binding installation you can install a few more -Python packages before running the tests:: +Recommended way to run tests is using `tox `_. +After successful binding installation you can install tox +and run the tests:: - python -m pip install pytest pytest-xdist pytest-timeout pytest-rerunfailures requests - pytest -v tests + pip install tox + tox -e py3 This will run all "offline" tests and skip all functional end-to-end tests that require accounts on real e-mail servers. .. _livetests: -running "live" tests with temporary accounts ---------------------------------------------- +Running "live" tests with temporary accounts +-------------------------------------------- -If you want to run live functional tests you can set ``DCC_NEW_TMP_EMAIL`` to a URL that creates e-mail accounts. Most developers use https://testrun.org URLS created and managed by [mailadm](https://mailadm.readthedocs.io/en/latest/). +If you want to run live functional tests you can set ``DCC_NEW_TMP_EMAIL`` to a URL that creates e-mail accounts. Most developers use https://testrun.org URLs created and managed by `mailadm `_. -Please feel free to contact us through a github issue or by e-mail and we'll send you a URL that you can then use for functional tests like this: +Please feel free to contact us through a github issue or by e-mail and we'll send you a URL that you can then use for functional tests like this:: export DCC_NEW_TMP_EMAIL= With this account-creation setting, pytest runs create ephemeral e-mail accounts on the http://testrun.org server. These accounts exists only for one hour and then are removed completely. -One hour is enough to invoke pytest and run all offline and online tests: +One hour is enough to invoke pytest and run all offline and online tests:: - pytest - - # or if you have installed pytest-xdist for parallel test execution - pytest -n6 + tox -e py3 Each test run creates new accounts. - .. _sourceinstall: -Installing bindings from source (Updated: July 2020) -========================================================= +Installing bindings from source +=============================== Install Rust and Cargo first. The easiest is probably to use `rustup `_. @@ -97,74 +90,42 @@ E.g. on Debian-based systems `apt install python3 python3-pip python3-venv` should give you a usable python installation. Ensure you are in the deltachat-core-rust/python directory, create the -virtual environment and activate it in your shell:: +virtual environment with dependencies using tox +and activate it in your shell:: cd python - python3 -m venv venv # or: virtualenv venv - source venv/bin/activate + tox --devenv env + source env/bin/activate You should now be able to build the python bindings using the supplied script:: - python install_python_bindings.py + python3 install_python_bindings.py The core compilation and bindings building might take a while, depending on the speed of your machine. -The bindings will be installed in release mode but with debug symbols. -The release mode is currently necessary because some tests generate RSA keys -which is prohibitively slow in non-release mode. - - -Code examples -============= - -You may look at `examples `_. - - -.. _`deltachat-core-rust github repository`: https://github.com/deltachat/deltachat-core-rust -.. _`deltachat-core`: https://github.com/deltachat/deltachat-core-rust - Building manylinux based wheels -==================================== +=============================== Building portable manylinux wheels which come with libdeltachat.so -can be done with docker-tooling. +can be done with Docker_ or Podman_. -using docker pull / premade images ------------------------------------- +.. _Docker: https://www.docker.com/ +.. _Podman: https://podman.io/ -We publish a build environment under the ``deltachat/coredeps`` tag so -that you can pull it from the ``hub.docker.com`` site's "deltachat" -organization:: +If you want to build your own wheels, build container image first:: - $ docker pull deltachat/coredeps + $ cd deltachat-core-rust # cd to deltachat-core-rust working tree + $ docker build -t deltachat/coredeps scripts/coredeps -This docker image can be used to run tests and build Python wheels for all interpreters:: - - $ docker run -e DCC_NEW_TMP_EMAIL \ - --rm -it -v \$(pwd):/mnt -w /mnt \ - deltachat/coredeps scripts/run_all.sh - - -Optionally build your own docker image --------------------------------------- - -If you want to build your own custom docker image you can do this:: - - $ cd deltachat-core # cd to deltachat-core checkout directory - $ docker build -t deltachat/coredeps scripts/docker_coredeps - -This will use the ``scripts/docker_coredeps/Dockerfile`` to build -up docker image called ``deltachat/coredeps``. You can afterwards +This will use the ``scripts/coredeps/Dockerfile`` to build +container image called ``deltachat/coredeps``. You can afterwards find it with:: $ docker images +This docker image can be used to run tests and build Python wheels for all interpreters:: -Troubleshooting ---------------- - -On more recent systems running the docker image may crash. You can -fix this by adding ``vsyscall=emulate`` to the Linux kernel boot -arguments commandline. E.g. on Debian you'd add this to -``GRUB_CMDLINE_LINUX_DEFAULT`` in ``/etc/default/grub``. + $ docker run -e DCC_NEW_TMP_EMAIL \ + --rm -it -v $(pwd):/mnt -w /mnt \ + deltachat/coredeps scripts/run_all.sh