refine example doc and address https://github.com/deltachat/deltachat-core-rust/pull/1307#pullrequestreview-380876587

python/doc/examples.rst

@@ -1,18 +1,18 @@
 
-
 examples
 ========
 
+Once you have :doc:`installed deltachat bindings <install>`
+you need email/password credentials for an IMAP/SMTP account.
+Delta Chat developers and the CI system use a special URL to create
+temporary e-mail accounts on [testrun.org](https://testrun.org) for testing.
 
 Receiving a Chat message from the command line
 ----------------------------------------------
 
-Once you have :doc:`installed deltachat bindings <install>`
+Here is a simple bot that:
-you can start playing from the python interpreter commandline.
 
-Here is a simple module that implements a bot that:
+- receives a message and sends back ("echoes") a message
-
-- receives a message and sends back an "echo" message
 
 - terminates the bot if the message `/quit` is sent
 
@@ -23,11 +23,35 @@ With this file in your working directory you can run the bot
 by specifying a database path, an e-mail address and password of
 a SMTP-IMAP account::
 
-    python echo_and_quit.py --db /tmp/db --email ADDRESS --password PASSWORD
+    $ cd examples
+    $ python echo_and_quit.py /tmp/db --email ADDRESS --password PASSWORD
 
 While this process is running you can start sending chat messages
 to `ADDRESS`.
 
+Track member additions and removals in a group
+----------------------------------------------
+
+Here is a simple bot that:
+
+- echoes messages sent to it
+
+- tracks if configuration completed
+
+- tracks member additions and removals for all chat groups
+
+.. include:: ../examples/group_tracking.py
+    :literal:
+
+With this file in your working directory you can run the bot
+by specifying a database path, an e-mail address and password of
+a SMTP-IMAP account::
+
+    python group_tracking.py --email ADDRESS --password PASSWORD /tmp/db
+
+When this process is running you can start sending chat messages
+to `ADDRESS`.
+
 Writing bots for real
 -------------------------
 

python/examples/echo_and_quit.py

@@ -1,11 +1,11 @@
 
 # content of echo_and_quit.py
 
-import deltachat
+from deltachat import account_hookimpl, run_cmdline
 
 
 class EchoPlugin:
-    @deltachat.hookspec.account_hookimpl
+    @account_hookimpl
     def process_incoming_message(self, message):
         print("process_incoming message", message)
         if message.text.strip() == "/quit":
@@ -17,13 +17,13 @@ class EchoPlugin:
             text = message.text
             message.chat.send_text("echoing from {}:\n{}".format(addr, text))
 
-    @deltachat.hookspec.account_hookimpl
+    @account_hookimpl
     def process_message_delivered(self, message):
         print("process_message_delivered", message)
 
 
 def main(argv=None):
-    deltachat.run_cmdline(argv=argv, account_plugins=[EchoPlugin()])
+    run_cmdline(argv=argv, account_plugins=[EchoPlugin()])
 
 
 if __name__ == "__main__":

python/examples/group_tracking.py

@@ -1,34 +1,39 @@
 
 # content of group_tracking.py
 
-import deltachat
+from deltachat import account_hookimpl, run_cmdline
 
 
 class GroupTrackingPlugin:
-    @deltachat.hookspec.account_hookimpl
+    @account_hookimpl
     def process_incoming_message(self, message):
-        print("*** process_incoming_message addr={} msg={!r}".format(
+        print("process_incoming message", message)
-              message.get_sender_contact().addr, message.text))
+        if message.text.strip() == "/quit":
-        for member in message.chat.get_contacts():
+            message.account.shutdown()
-            print("chat member: {}".format(member.addr))
+        else:
+            # unconditionally accept the chat
+            message.accept_sender_contact()
+            addr = message.get_sender_contact().addr
+            text = message.text
+            message.chat.send_text("echoing from {}:\n{}".format(addr, text))
 
-    @deltachat.hookspec.account_hookimpl
+    @account_hookimpl
     def configure_completed(self, success):
         print("*** configure_completed:", success)
 
-    @deltachat.hookspec.account_hookimpl
+    @account_hookimpl
     def member_added(self, chat, contact):
         print("*** member_added", contact.addr, "from", chat)
         for member in chat.get_contacts():
             print("chat member: {}".format(member.addr))
 
-    @deltachat.hookspec.account_hookimpl
+    @account_hookimpl
     def member_removed(self, chat, contact):
         print("*** member_removed", contact.addr, "from", chat)
 
 
 def main(argv=None):
-    deltachat.run_cmdline(argv=argv, account_plugins=[GroupTrackingPlugin()])
+    run_cmdline(argv=argv, account_plugins=[GroupTrackingPlugin()])
 
 
 if __name__ == "__main__":

python/examples/test_examples.py

@@ -57,6 +57,9 @@ def test_group_tracking_plugin(acfactory, lp):
     contact3 = ac1.create_contact(ac2.get_config("addr"))
     ch.add_contact(contact3)
 
+    reply = ac1._evtracker.wait_next_incoming_message()
+    assert "hello" in reply.text
+
     lp.sec("now looking at what the bot received")
     botproc.fnmatch_lines("""
         *member_added {}*

python/src/deltachat/__init__.py

@@ -4,6 +4,7 @@ from . import capi, const, hookspec
 from .capi import ffi
 from .account import Account  # noqa
 from . import eventlogger
+from .hookspec import account_hookimpl, global_hookimpl  # noqa
 
 from pkg_resources import get_distribution, DistributionNotFound
 try:
@@ -104,14 +105,13 @@ def run_cmdline(argv=None, account_plugins=None):
         argv = sys.argv
 
     parser = argparse.ArgumentParser(prog=argv[0] if argv else None)
+    parser.add_argument("db", action="store", help="database file")
     parser.add_argument("--show-ffi", action="store_true", help="show low level ffi events")
-    parser.add_argument("--db", action="store", help="database file")
     parser.add_argument("--email", action="store", help="email address")
     parser.add_argument("--password", action="store", help="password")
 
     args = parser.parse_args(argv[1:])
 
-    assert args.db, "you must specify --db"
     ac = Account(args.db)
 
     if args.show_ffi:

python/src/deltachat/testplugin.py

@@ -257,9 +257,9 @@ def acfactory(pytestconfig, tmpdir, request, session_liveconfig, datadir):
                 sys.executable,
                 fn,
                 "--show-ffi",
-                "--db", bot_ac.db_path,
                 "--email", bot_cfg["addr"],
                 "--password", bot_cfg["mail_pw"],
+                bot_ac.db_path,
             ]
             print("$", " ".join(args))
             popen = subprocess.Popen(
@@ -299,7 +299,6 @@ class BotProcess:
                 if not line:
                     break
                 line = line.strip()
-                print("QUEUING:", repr(line))
                 self.stdout_queue.put(line)
         finally:
             self.stdout_queue.put(None)