Mirrors/chatmail-core
1
0
Fork 0
mirror of https://github.com/chatmail/core.git synced 2026-05-08 09:26:29 +03:00
Code Issues Packages Projects Releases Wiki Activity

Update Python bindings README

Browse Source 
Wheels are now published to PyPI, recommend it instead of devpi. We
build the wheels only for releases anyway.

Suggest using tox instead of listing all the pytest dependencies to
avoid keeping them up to date in the readme.

We no longer publish `docker/coredeps` images, they cannot be
pulled from a container registry anymore.

Troubleshooting section is outdated, because vsyscall emulation is
only needed for manylinux2010 images, not manylinux2014 or
musllinux_1_1 images.

Mention Podman as an alternative to Docker.

Link to https://py.delta.chat/ instead of only examples.

Remove note about wheels for Mac and Windows. Nobody requests them
anyway.
This commit is contained in:
link2xt
2022-07-09 17:26:29 +00:00
parent 64b4d421c7
commit 88402288f9
1 changed files with 46 additions and 85 deletions
Download Patch File Download Diff File Expand all files Collapse all files

131
python/README.rst
View File

@@ -1,84 +1,77 @@
========================= =========================
deltachat python bindings DeltaChat Python bindings
========================= =========================
This package provides bindings to the deltachat-core_ Rust -library This package provides `Python bindings`_ to the `deltachat-core library`_
which implements IMAP/SMTP/MIME/PGP e-mail standards and offers which implements IMAP/SMTP/MIME/OpenPGP e-mail standards and offers
a low-level Chat/Contact/Message API to user interfaces and bots. 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) Installing pre-built packages (Linux-only)
======================================================== ==========================================
If you have a Linux system you may try to install the ``deltachat`` binary "wheel" packages If you have a Linux system you may try to install the ``deltachat`` binary "wheel" packages
without any "build-from-source" steps. 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 <https://virtualenv.pypa.io/en/stable/installation.html>`_, We recommend to first `install virtualenv <https://virtualenv.pypa.io/en/stable/installation.html>`_,
then create a fresh Python virtual environment and activate it in your shell:: then create a fresh Python virtual environment and activate it in your shell::
virtualenv venv # or: python -m venv virtualenv env # or: python -m venv
source venv/bin/activate source env/bin/activate
Afterwards, invoking ``python`` or ``pip install`` only 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. your system installation alone.
For Linux, we automatically build wheels for all github PR branches For Linux we build wheels for all releases and push them to a python package
and push them to a python package index. To install the latest index. To install the latest release::
github ``master`` branch::
pip install --pre -i https://m.devpi.net/dc/master deltachat pip install deltachat
To verify it worked:: To verify it worked::
python -c "import deltachat" 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 <https://delta.chat/en/contribute>`_.
Running tests Running tests
============= =============
After successful binding installation you can install a few more Recommended way to run tests is using `tox <https://tox.wiki>`_.
Python packages before running the tests:: After successful binding installation you can install tox
and run the tests::
python -m pip install pytest pytest-xdist pytest-timeout pytest-rerunfailures requests pip install tox
pytest -v tests tox -e py3
This will run all "offline" tests and skip all functional This will run all "offline" tests and skip all functional
end-to-end tests that require accounts on real e-mail servers. end-to-end tests that require accounts on real e-mail servers.
.. _livetests: .. _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 <https://mailadm.readthedocs.io/>`_.
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=<URL you got from us> export DCC_NEW_TMP_EMAIL=<URL you got from us>
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. 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 tox -e py3
# or if you have installed pytest-xdist for parallel test execution
pytest -n6
Each test run creates new accounts. Each test run creates new accounts.
.. _sourceinstall: .. _sourceinstall:
Installing bindings from source (Updated: July 2020) Installing bindings from source
========================================================= ===============================
Install Rust and Cargo first. Install Rust and Cargo first.
The easiest is probably to use `rustup <https://rustup.rs/>`_. The easiest is probably to use `rustup <https://rustup.rs/>`_.
@@ -97,74 +90,42 @@ E.g. on Debian-based systems `apt install python3 python3-pip
python3-venv` should give you a usable python installation. python3-venv` should give you a usable python installation.
Ensure you are in the deltachat-core-rust/python directory, create the 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 cd python
python3 -m venv venv # or: virtualenv venv tox --devenv env
source venv/bin/activate source env/bin/activate
You should now be able to build the python bindings using the supplied script:: 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, The core compilation and bindings building might take a while,
depending on the speed of your machine. 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 <https://py.delta.chat/examples.html>`_.
.. _`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 manylinux based wheels
==================================== ===============================
Building portable manylinux wheels which come with libdeltachat.so 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 If you want to build your own wheels, build container image first::
that you can pull it from the ``hub.docker.com`` site's "deltachat"
organization::
$ 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:: This will use the ``scripts/coredeps/Dockerfile`` to build
container image called ``deltachat/coredeps``. You can afterwards
$ 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
find it with:: find it with::
$ docker images $ docker images
This docker image can be used to run tests and build Python wheels for all interpreters::
Troubleshooting $ docker run -e DCC_NEW_TMP_EMAIL \
--------------- --rm -it -v $(pwd):/mnt -w /mnt \
deltachat/coredeps scripts/run_all.sh
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``.