major rehault of docs at root and python level,

preparing a deltachat-0.6 release

.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

README.md

@@ -5,16 +5,75 @@
 The _Delta Chat Core Library_ is written in cross-platform **C**,
 documented at <https://c.delta.chat>.
 
-
-## 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`.

python/CHANGELOG

@@ -1,5 +1,5 @@
 
-0.5
+0.6
 ---
 
 - initial release with full low level C-API, and a first

python/MANIFEST.in

@@ -0,0 +1,2 @@
+include tox.ini
+recursive-include tests *.py

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
+   <https://github.com/deltachat/deltachat-core/blob/master/README.md>`_.
 
-    Currently the install instructions exist only for Debian based systems (Ubuntu etc.).
+2. `Install virtualenv <https://virtualenv.pypa.io/en/stable/installation/>`_
+   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 <https://py.delta.chat/examples.html>`_.
 
-    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

python/doc/examples.rst

@@ -3,17 +3,36 @@
 examples
 ========
 
-::
+
+Playing around on the commandline
+----------------------------------
+
+Once you have :doc:`installed deltachat bindings <install>`
+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 <https://github.com/deltachat/deltabot#deltachat-example-bot>`_
+contains a real-life example of Python bindings usage.
+
 
-    ...

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',

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 = {}

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()

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]