major rehault of docs at root and python level,

preparing a deltachat-0.6 release

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]