mirror of
https://github.com/chatmail/core.git
synced 2026-04-05 23:22:11 +03:00
88402288f9
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.
132 lines
4.3 KiB
ReStructuredText
132 lines
4.3 KiB
ReStructuredText
=========================
|
|
DeltaChat Python bindings
|
|
=========================
|
|
|
|
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_
|
|
|
|
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::
|
|
|
|
virtualenv env # or: python -m venv
|
|
source env/bin/activate
|
|
|
|
Afterwards, invoking ``python`` or ``pip install`` only
|
|
modifies files in your ``env`` directory and leaves
|
|
your system installation alone.
|
|
|
|
For Linux we build wheels for all releases and push them to a python package
|
|
index. To install the latest release::
|
|
|
|
pip install deltachat
|
|
|
|
To verify it worked::
|
|
|
|
python -c "import deltachat"
|
|
|
|
Running tests
|
|
=============
|
|
|
|
Recommended way to run tests is using `tox <https://tox.wiki>`_.
|
|
After successful binding installation you can install tox
|
|
and run the 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
|
|
--------------------------------------------
|
|
|
|
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::
|
|
|
|
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.
|
|
One hour is enough to invoke pytest and run all offline and online tests::
|
|
|
|
tox -e py3
|
|
|
|
Each test run creates new accounts.
|
|
|
|
.. _sourceinstall:
|
|
|
|
Installing bindings from source
|
|
===============================
|
|
|
|
Install Rust and Cargo first.
|
|
The easiest is probably to use `rustup <https://rustup.rs/>`_.
|
|
|
|
Bootstrap Rust and Cargo by using rustup::
|
|
|
|
curl https://sh.rustup.rs -sSf | sh
|
|
|
|
Then clone the deltachat-core-rust repo::
|
|
|
|
git clone https://github.com/deltachat/deltachat-core-rust
|
|
cd deltachat-core-rust
|
|
|
|
To install the Delta Chat Python bindings make sure you have Python3 installed.
|
|
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 with dependencies using tox
|
|
and activate it in your shell::
|
|
|
|
cd python
|
|
tox --devenv env
|
|
source env/bin/activate
|
|
|
|
You should now be able to build the python bindings using the supplied script::
|
|
|
|
python3 install_python_bindings.py
|
|
|
|
The core compilation and bindings building might take a while,
|
|
depending on the speed of your machine.
|
|
|
|
Building manylinux based wheels
|
|
===============================
|
|
|
|
Building portable manylinux wheels which come with libdeltachat.so
|
|
can be done with Docker_ or Podman_.
|
|
|
|
.. _Docker: https://www.docker.com/
|
|
.. _Podman: https://podman.io/
|
|
|
|
If you want to build your own wheels, build container image first::
|
|
|
|
$ cd deltachat-core-rust # cd to deltachat-core-rust working tree
|
|
$ docker build -t deltachat/coredeps scripts/coredeps
|
|
|
|
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::
|
|
|
|
$ docker run -e DCC_NEW_TMP_EMAIL \
|
|
--rm -it -v $(pwd):/mnt -w /mnt \
|
|
deltachat/coredeps scripts/run_all.sh
|