diff --git a/python/doc/examples.rst b/python/doc/examples.rst index badb17725..dd8f2a023 100644 --- a/python/doc/examples.rst +++ b/python/doc/examples.rst @@ -1,18 +1,18 @@ - examples ======== +Once you have :doc:`installed deltachat bindings ` +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 ` -you can start playing from the python interpreter commandline. +Here is a simple bot that: -Here is a simple module that implements a bot that: - -- receives a message and sends back an "echo" message +- receives a message and sends back ("echoes") a 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 ------------------------- diff --git a/python/examples/echo_and_quit.py b/python/examples/echo_and_quit.py index 2ad9450e4..eea1ffafb 100644 --- a/python/examples/echo_and_quit.py +++ b/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__": diff --git a/python/examples/group_tracking.py b/python/examples/group_tracking.py index 290af5eea..da6c07031 100644 --- a/python/examples/group_tracking.py +++ b/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( - message.get_sender_contact().addr, message.text)) - for member in message.chat.get_contacts(): - print("chat member: {}".format(member.addr)) + print("process_incoming message", message) + if message.text.strip() == "/quit": + message.account.shutdown() + 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__": diff --git a/python/examples/test_examples.py b/python/examples/test_examples.py index 572b4ac68..343528aa2 100644 --- a/python/examples/test_examples.py +++ b/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 {}* diff --git a/python/src/deltachat/__init__.py b/python/src/deltachat/__init__.py index 2df36bd2b..7def90569 100644 --- a/python/src/deltachat/__init__.py +++ b/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: diff --git a/python/src/deltachat/testplugin.py b/python/src/deltachat/testplugin.py index bbdc7eaeb..6f1b3437e 100644 --- a/python/src/deltachat/testplugin.py +++ b/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)