From ae5f72cf4f70c242c184f54fbe5852ad0e98ab44 Mon Sep 17 00:00:00 2001 From: link2xt Date: Thu, 30 Mar 2023 09:33:04 +0000 Subject: [PATCH] Remove install_python_bindings.py script and update docs `install_python_bindings.py` was not used by CI and scripts, except for `scripts/run-python-test.sh` which only used it to invoke `cargo`. Instead of using an additional script, run cargo directly. The documentation is updated to remove references to `install_python_bindings.py`. The section "Installing bindings from source" was in fact incorrect as it suggested running `tox --devenv` first and only then compiling the library with `install_python_bindings.py`. Now it explicitly says to run cargo first and then install the package without using `tox`. `tox` is still used for running the tests and setting up development environment. --- CHANGELOG.md | 1 + python/README.rst | 79 +++++++++++++++++++++---------- python/install_python_bindings.py | 30 ------------ python/tox.ini | 2 +- scripts/run-python-test.sh | 4 +- 5 files changed, 59 insertions(+), 57 deletions(-) delete mode 100755 python/install_python_bindings.py diff --git a/CHANGELOG.md b/CHANGELOG.md index 39f985730..69a331938 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,7 @@ - Update rPGP to 0.10.1. #4236 ### Fixes +- Fix python bindings README documentation on installing the bindings from source. ## [1.112.3] - 2023-03-30 diff --git a/python/README.rst b/python/README.rst index af74606d4..c2b4d87e2 100644 --- a/python/README.rst +++ b/python/README.rst @@ -12,17 +12,17 @@ a low-level Chat/Contact/Message API to user interfaces and bots. 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 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 `_, -then create a fresh Python virtual environment and activate it in your shell:: +We recommend to first create a fresh Python virtual environment +and activate it in your shell:: - virtualenv env # or: python -m venv - source env/bin/activate + python -m venv env + source env/bin/activate Afterwards, invoking ``python`` or ``pip install`` only modifies files in your ``env`` directory and leaves @@ -40,16 +40,14 @@ To verify it worked:: Running tests ============= -Recommended way to run tests is using `tox `_. -After successful binding installation you can install tox -and run the tests:: +Recommended way to run tests is using `scripts/run-python-test.sh` +script provided in the core repository. - pip install tox - tox -e py3 - -This will run all "offline" tests and skip all functional +This script compiles the library in debug mode and runs the tests using `tox`_. +By default it will run all "offline" tests and skip all functional end-to-end tests that require accounts on real e-mail servers. +.. _`tox`: https://tox.wiki .. _livetests: Running "live" tests with temporary accounts @@ -61,13 +59,32 @@ Please feel free to contact us through a github issue or by e-mail and we'll sen 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:: +With this account-creation setting, pytest runs create ephemeral e-mail accounts on the http://testrun.org server. +These accounts are removed automatically as they expire. +After setting the variable, either rerun `scripts/run-python-test.sh` +or run offline and online tests with `tox` directly:: - tox -e py3 + tox -e py Each test run creates new accounts. +Developing the bindings +----------------------- + +If you want to develop or debug the bindings, +you can create a testing development environment using `tox`:: + + tox -c python --devenv env + . env/bin/activate + +Inside this environment the bindings are installed +in editable mode (as if installed with `python -m pip install -e`) +together with the testing dependencies like `pytest` and its plugins. + +You can then edit the source code in the development tree +and quickly run `pytest` manually without waiting for `tox` +to recreating the virtual environment each time. + .. _sourceinstall: Installing bindings from source @@ -89,20 +106,34 @@ 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:: +First, build the core library:: - cd python - tox --devenv env + cargo build --release -p deltachat_ffi --features jsonrpc + +`jsonrpc` feature is required even if not used by the bindings +because `deltachat.h` includes JSON-RPC functions unconditionally. + +Create the virtual environment and activate it: + + python -m venv env source env/bin/activate -You should now be able to build the python bindings using the supplied script:: +Build and install the bindings: - python3 install_python_bindings.py + export DCC_RS_DEV="$PWD" + export DCC_RS_TARGET=release + python -m pip install python -The core compilation and bindings building might take a while, -depending on the speed of your machine. +`DCC_RS_DEV` environment variable specifies the location of +the core development tree. If this variable is not set, +`libdeltachat` library and `deltachat.h` header are expected +to be installed system-wide. + +When `DCC_RS_DEV` is set, `DCC_RS_TARGET` specifies +the build profile name to look up the artifacts +in the target directory. +In this case setting it can be skipped because +`DCC_RS_TARGET=release` is the default. Building manylinux based wheels =============================== diff --git a/python/install_python_bindings.py b/python/install_python_bindings.py deleted file mode 100755 index 6e216c893..000000000 --- a/python/install_python_bindings.py +++ /dev/null @@ -1,30 +0,0 @@ -#!/usr/bin/env python3 - -""" - setup a python binding development in-place install with cargo debug symbols. -""" - -import os -import subprocess -import sys - -if __name__ == "__main__": - target = os.environ.get("DCC_RS_TARGET") - if target is None: - os.environ["DCC_RS_TARGET"] = target = "debug" - if "DCC_RS_DEV" not in os.environ: - dn = os.path.dirname(os.path.dirname(os.path.abspath(__file__))) - os.environ["DCC_RS_DEV"] = dn - - cmd = ["cargo", "build", "-p", "deltachat_ffi", "--features", "jsonrpc"] - - if target == "release": - os.environ["CARGO_PROFILE_RELEASE_LTO"] = "on" - cmd.append("--release") - - print("running:", " ".join(cmd)) - subprocess.check_call(cmd) - subprocess.check_call("rm -rf build/ src/deltachat/*.so src/deltachat/*.dylib src/deltachat/*.dll", shell=True) - - if len(sys.argv) <= 1 or sys.argv[1] != "onlybuild": - subprocess.check_call([sys.executable, "-m", "pip", "install", "-e", "."]) diff --git a/python/tox.ini b/python/tox.ini index 994f9c4c7..99fd0c703 100644 --- a/python/tox.ini +++ b/python/tox.ini @@ -43,7 +43,7 @@ deps = pygments restructuredtext_lint commands = - black --quiet --check --diff setup.py install_python_bindings.py src/deltachat examples/ tests/ + black --quiet --check --diff setup.py src/deltachat examples/ tests/ ruff src/deltachat tests/ examples/ rst-lint --encoding 'utf-8' README.rst diff --git a/scripts/run-python-test.sh b/scripts/run-python-test.sh index d14e833a1..93acd07cc 100755 --- a/scripts/run-python-test.sh +++ b/scripts/run-python-test.sh @@ -12,7 +12,7 @@ export DCC_RS_DEV=`pwd` cd python -python install_python_bindings.py onlybuild +cargo build -p deltachat_ffi --features jsonrpc # remove and inhibit writing PYC files rm -rf tests/__pycache__ @@ -22,4 +22,4 @@ export PYTHONDONTWRITEBYTECODE=1 # run python tests (tox invokes pytest to run tests in python/tests) #TOX_PARALLEL_NO_SPINNER=1 tox -e lint,doc tox -e lint -tox -e doc,py3 +tox -e doc,py