From 031058ebd20416febfe973cdf413b5435dd44060 Mon Sep 17 00:00:00 2001 From: holger krekel Date: Thu, 27 Sep 2018 15:50:52 +0200 Subject: [PATCH] major rehault of docs at root and python level, preparing a deltachat-0.6 release --- .travis.yml | 3 +- README.md | 92 ++++++++++++++++++++++++++------ python/CHANGELOG | 2 +- python/MANIFEST.in | 2 + python/README.rst | 34 +++++++----- python/doc/examples.rst | 31 ++++++++--- python/setup.py | 2 +- python/src/deltachat/__init__.py | 2 +- python/{ => tests}/conftest.py | 7 ++- python/tox.ini | 4 +- 10 files changed, 132 insertions(+), 47 deletions(-) create mode 100644 python/MANIFEST.in rename python/{ => tests}/conftest.py (98%) diff --git a/.travis.yml b/.travis.yml index 9fdcce52..0120c3a0 100644 --- a/.travis.yml +++ b/.travis.yml @@ -45,7 +45,8 @@ script: - source venv/bin/activate - pip install tox - ldd /usr/local/lib/x86_64-linux-gnu/libdeltachat.so - - tox + - tox + - tox -e doc deploy: provider: script diff --git a/README.md b/README.md index 6775adf6..bda9f847 100644 --- a/README.md +++ b/README.md @@ -5,16 +5,75 @@ The _Delta Chat Core Library_ is written in cross-platform **C**, documented at . - -## Building the C-library - Delta Chat Core is built as a C-library using the -[meson build system](http://mesonbuild.com). -It depends on a number of external libraries, most of which are detected using +[meson build system](http://mesonbuild.com). + +## binary/distribution packages (work-in-progress) + +There are work-in-progress efforts for creating (binary) packages which +do not require the steps outlined further below: + +- [a libdeltachat-core-git archlinux package] + (https://aur.archlinux.org/packages/libdeltachat-core-git/>) + +- [a Debian package](https://github.com/deltachat/deltachat-core/issues/299) + +- [a Windows build](https://github.com/deltachat/deltachat-core/issues/306) + +If you can help with advancing or adding to these efforts, be our guest. +Otherwise read on for how to get ``libdeltachat.so`` and ``deltachat.h`` +installed into your system. + +## building your own ``libdeltachat.so`` + +### getting a recent enough ``meson`` for building + +If you have installed ``meson`` in your environment check the version:: + + meson --version + +You need to have version ``0.47.2`` at least. If you version +is older here is one recommended way of getting a better version: + +1. uninstall your system-level ``meson`` package (if possible) + +2. ensure you have at least ``python3.4`` installed and type: + ``` + python3 -m pip + ``` + + to check that you have "pip" installed. If not available, you + might get it as a ``python3-pip`` package or similar. + + See also [installing pip](https://pip.pypa.io/en/stable/installing/) + +3. then pip-install meson: + ``` + python3 -u -m pip install meson + ``` + + the ``-u`` causes the pip-install to put a ``meson`` command line tool into + ``~/.local/`` or %APPDATA%\Python on Windows. + +4. run ``meson --version`` verify it's at at least version 0.48.0 now. + If the ``meson`` command is not found, add ``~/.local/bin`` to ``PATH`` + and try again (``export PATH=~/.local/bin:$PATH`` on many unix-y terminals). + + +### installing "ninja-build" + +On Linux and Mac you need to install 'ninja-build' (debian package name) +to be able to actually build/compile things. + +Note that most dependencies below are detected using [pkg-config](https://www.freedesktop.org/wiki/Software/pkg-config/). -Usually this just works automatically, provided the depending libraries are -installed correctly. You may need to install "development" packages of -these dependencies: +Usually this just works automatically, provided the depending libraries +are installed correctly. + +### installing c-level dependencies + +The deltachat core library depends on a number of external libraries, +which you may need to install (we have some fallbacks if you don't): - [LibEtPan](https://github.com/dinhviethoa/libetpan); Note that this library does not use pkg-config so the system-provided version will @@ -29,15 +88,16 @@ these dependencies: - [libsasl](https://cyrusimap.org/sasl/) -- [meson build system at least in version 0.47.2](http://mesonbuild.com) - and [ninja](https://ninja-build.org). +To install these on debian you can type: +``` + sudo apt install libetpan-dev libssl-dev libsqlite3-dev libsasl2-dev libbz2-dev zlib1g-dev +``` -On Linux (e.g. Debian Stretch) you can install all these using: -`sudo apt install libetpan-dev libssl-dev libsqlite3-dev libsasl2-dev libbz2-dev zlib1g-dev meson ninja-build`. +### performing the actual build Once all dependencies are installed, creating a build is as follows, -starting from the project's root directory: +starting from a [deltachat-core github checkout](https://github.com/deltachat/deltachat-core): ``` mkdir builddir @@ -56,15 +116,14 @@ is thus also supported: ``` sudo ninja uninstall ``` - -Note that the above assumes `/usr/local/lib` is configured somewhere +**NOTE** that the above assumes `/usr/local/lib` is configured somewhere in `/etc/ld.so.conf` or `/etc/ld.so.conf.d/*`, which is fairly standard. It is possible your system uses `/usr/local/lib/x86_64-linux-gnu` which should be auto-detected and just work as well. -## Building without system-level dependencies +### Building without system-level dependencies By default stripped-down versions of the dependencies are bundled with Delta Chat Core and these will be used when a dependency is missing. @@ -96,7 +155,6 @@ or its language bindings: - [Desktop](https://github.com/deltachat/deltachat-desktop) - [Pidgin](https://gitlab.com/lupine/purple-plugin-delta) - ## Testing program After a successful build there is also a little testing program in `builddir/cmdline`. diff --git a/python/CHANGELOG b/python/CHANGELOG index 96d741cd..9dc014ab 100644 --- a/python/CHANGELOG +++ b/python/CHANGELOG @@ -1,5 +1,5 @@ -0.5 +0.6 --- - initial release with full low level C-API, and a first diff --git a/python/MANIFEST.in b/python/MANIFEST.in new file mode 100644 index 00000000..4d84ff46 --- /dev/null +++ b/python/MANIFEST.in @@ -0,0 +1,2 @@ +include tox.ini +recursive-include tests *.py diff --git a/python/README.rst b/python/README.rst index 8c4985aa..f124f4cc 100644 --- a/python/README.rst +++ b/python/README.rst @@ -2,36 +2,43 @@ deltachat python bindings ========================= -This package provides bindings to the delta-core_ C-library +This package provides bindings to the deltachat-core_ C-library which provides imap/smtp/crypto handling as well as chat/group/messages handling to Android, Desktop and IO user interfaces. Install ------- -.. note:: +1. First you need to `install the delta-core C-library + `_. - Currently the install instructions exist only for Debian based systems (Ubuntu etc.). +2. `Install virtualenv `_ + if you don't have it, then create and use a fresh clean python environment:: -First you need to execute all the build steps to install the delta-core C-library, -see https://github.com/deltachat/deltachat-core/blob/master/README.md#build + virtualenv -p python3 venv + source venv/bin/activate -Presuming you have the delta-core library installed, you can then from the root of the repo:: + Afterwards invoking ``python`` or ``pip install`` will only modify files + in your ``venv`` directory. - cd python - pip install -e . +3. Install the bindings with pip:: -Afterwards you should be able to successfully import the bindings:: + pip install deltachat + + Afterwards you should be able to successfully import the bindings:: + + python -c "import deltachat" + +You may now look at `examples `_. - python -c "import deltachat" Running tests ------------- -Install the delta-core C-library and the deltachat bindings (see _Install) -and then type the following to execute tests:: +Get a checkout of the `deltachat-core github repository`_ and type:: + cd python pip install tox tox @@ -48,4 +55,5 @@ And then run the tests with this live-accounts config file:: tox -- --liveconfig liveconfig -.. _`delta-core`: https://github.com/deltachat/deltachat-core +.. _`deltachat-core github repository`: https://github.com/deltachat/deltachat-core +.. _`deltachat-core`: https://github.com/deltachat/deltachat-core diff --git a/python/doc/examples.rst b/python/doc/examples.rst index 0d655b2c..d2cc19f6 100644 --- a/python/doc/examples.rst +++ b/python/doc/examples.rst @@ -3,17 +3,36 @@ examples ======== -:: + +Playing around on the commandline +---------------------------------- + +Once you have :doc:`installed deltachat bindings ` +you can start playing from the python interpreter commandline:: + +For example you can type ``python`` and then:: # instantiate and configure deltachat account import deltachat - ac1 = deltachat.Account("/tmp/db") - ac.set_config(addr="test2@hq5.merlinux.eu", mail_pw="********") + ac = deltachat.Account("/tmp/db") # start configuration activity and smtp/imap threads - ac.start() + ac.start_threads() + ac.configure(addr="test2@hq5.merlinux.eu", mail_pw="********") # create a contact and send a message - contact = ac.create_contact("test3@hq5.merlinux.eu") + contact = ac.create_contact("someother@email.address") + chat = ac.create_chat_by_contact(contact) + chat.send_text_message("hi from the python interpreter command line") + +Checkout our :doc:`api` for the various high-level things you can do +to send/receive messages, create contacts and chats. + + +Looking at a real example +------------------------- + +The `deltabot repository `_ +contains a real-life example of Python bindings usage. + - ... diff --git a/python/setup.py b/python/setup.py index 32137937..c3b19265 100644 --- a/python/setup.py +++ b/python/setup.py @@ -17,7 +17,7 @@ def main(): package_dir={'': 'src'}, cffi_modules=['src/deltachat/_build.py:ffibuilder'], classifiers=[ - 'Development Status :: 3 - Alpha', + 'Development Status :: 4 - Beta', 'Intended Audience :: Developers', 'License :: OSI Approved :: GNU General Public License (GPL)', 'Programming Language :: Python :: 3', diff --git a/python/src/deltachat/__init__.py b/python/src/deltachat/__init__.py index 25d1a83c..493ecf02 100644 --- a/python/src/deltachat/__init__.py +++ b/python/src/deltachat/__init__.py @@ -2,7 +2,7 @@ from deltachat import capi, const from deltachat.capi import ffi from deltachat.account import Account # noqa -__version__ = "0.5.dev5" +__version__ = "0.6.0" _DC_CALLBACK_MAP = {} diff --git a/python/conftest.py b/python/tests/conftest.py similarity index 98% rename from python/conftest.py rename to python/tests/conftest.py index 20c50e66..cf161a0a 100644 --- a/python/conftest.py +++ b/python/tests/conftest.py @@ -1,7 +1,5 @@ from __future__ import print_function import pytest -import re -import threading from deltachat import Account from deltachat.types import cached_property from deltachat.capi import lib @@ -32,7 +30,7 @@ def acfactory(pytestconfig, tmpdir, request): fin() @cached_property - def configlist (self): + def configlist(self): configlist = [] for line in open(fn): if line.strip(): @@ -59,7 +57,7 @@ def acfactory(pytestconfig, tmpdir, request): lib.dc_set_config(ac._dc_context, b"configured_addr", addr.encode("ascii")) ac.set_config("mail_pw", "123") lib.dc_set_config(ac._dc_context, b"configured_mail_pw", b"123") - lib.dc_set_config_int(ac._dc_context, b"configured", 1); + lib.dc_set_config_int(ac._dc_context, b"configured", 1) return ac def get_online_configuring_account(self): @@ -89,6 +87,7 @@ def lp(): def sec(self, msg): print() print("=" * 10, msg, "=" * 10) + def step(self, msg): print("-" * 5, "step " + msg, "-" * 5) return Printer() diff --git a/python/tox.ini b/python/tox.ini index 4864835e..da618536 100644 --- a/python/tox.ini +++ b/python/tox.ini @@ -4,7 +4,6 @@ envlist = py27 py35 lint - doc [testenv] commands = pytest -rsXx {posargs:tests} @@ -35,10 +34,9 @@ deps = sphinx breathe -whitelist_externals = make changedir = doc commands = - make html + sphinx-build -b html . _build [pytest]