deltachat-rpc-client 1.142.8__tar.gz → 2.24.0__tar.gz

{deltachat_rpc_client-1.142.8/src/deltachat_rpc_client.egg-info → deltachat_rpc_client-2.24.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: deltachat-rpc-client
-Version: 1.142.8
+Version: 2.24.0
 Summary: Python client for Delta Chat core JSON-RPC interface
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
@@ -12,11 +12,15 @@ Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Communications :: Chat
 Classifier: Topic :: Communications :: Email
+Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: imap-tools
+Dynamic: license-file
 
 # Delta Chat RPC python client
 
@@ -45,7 +49,8 @@ $ pip install .
 ## Testing
 
 1. Build `deltachat-rpc-server` with `cargo build -p deltachat-rpc-server`.
-2. Run `CHATMAIL_DOMAIN=nine.testrun.org PATH="../target/debug:$PATH" tox`.
+2. Install tox `pip install -U tox`
+3. Run `CHATMAIL_DOMAIN=nine.testrun.org PATH="../target/debug:$PATH" tox`.
 
 Additional arguments to `tox` are passed to pytest, e.g. `tox -- -s` does not capture test output.
 

{deltachat_rpc_client-1.142.8 → deltachat_rpc_client-2.24.0}/README.md

@@ -25,7 +25,8 @@ $ pip install .
 ## Testing
 
 1. Build `deltachat-rpc-server` with `cargo build -p deltachat-rpc-server`.
-2. Run `CHATMAIL_DOMAIN=nine.testrun.org PATH="../target/debug:$PATH" tox`.
+2. Install tox `pip install -U tox`
+3. Run `CHATMAIL_DOMAIN=nine.testrun.org PATH="../target/debug:$PATH" tox`.
 
 Additional arguments to `tox` are passed to pytest, e.g. `tox -- -s` does not capture test output.
 

{deltachat_rpc_client-1.142.8 → deltachat_rpc_client-2.24.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "deltachat-rpc-client"
-version = "1.142.8"
+version = "2.24.0"
 description = "Python client for Delta Chat core JSON-RPC interface"
 classifiers = [
     "Development Status :: 5 - Production/Stable",
@@ -17,13 +17,14 @@ classifiers = [
     "Programming Language :: Python :: 3.9",
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "Topic :: Communications :: Chat",
     "Topic :: Communications :: Email"
 ]
 readme = "README.md"
-dependencies = [
-    "imap-tools",
-]
+requires-python = ">=3.8"
 
 [tool.setuptools.package-data]
 deltachat_rpc_client = [
@@ -66,7 +67,18 @@ lint.select = [
 
   "RUF006" # asyncio-dangling-task
 ]
+lint.ignore = [
+  "PLC0415" # `import` should be at the top-level of a file
+]
 line-length = 120
 
 [tool.isort]
 profile = "black"
+
+[dependency-groups]
+dev = [
+    "imap-tools",
+    "pytest",
+    "pytest-timeout",
+    "pytest-xdist",
+]

{deltachat_rpc_client-1.142.8 → deltachat_rpc_client-2.24.0}/src/deltachat_rpc_client/__init__.py

@@ -1,4 +1,4 @@
-"""Delta Chat JSON-RPC high-level API"""
+"""Delta Chat JSON-RPC high-level API."""
 
 from ._utils import AttrDict, run_bot_cli, run_client_cli
 from .account import Account

{deltachat_rpc_client-1.142.8 → deltachat_rpc_client-2.24.0}/src/deltachat_rpc_client/_utils.py

@@ -1,4 +1,5 @@
 import argparse
+import os
 import re
 import sys
 from threading import Thread
@@ -89,8 +90,8 @@ def _run_cli(
         help="accounts folder (default: current working directory)",
         nargs="?",
     )
-    parser.add_argument("--email", action="store", help="email address")
-    parser.add_argument("--password", action="store", help="password")
+    parser.add_argument("--email", action="store", help="email address", default=os.getenv("DELTACHAT_EMAIL"))
+    parser.add_argument("--password", action="store", help="password", default=os.getenv("DELTACHAT_PASSWORD"))
     args = parser.parse_args(argv[1:])
 
     with Rpc(accounts_dir=args.accounts_dir, **kwargs) as rpc:
@@ -114,7 +115,7 @@ def _run_cli(
 
 
 def extract_addr(text: str) -> str:
-    """extract email address from the given text."""
+    """Extract email address from the given text."""
     match = re.match(r".*\((.+@.+)\)", text)
     if match:
         text = match.group(1)
@@ -123,7 +124,7 @@ def extract_addr(text: str) -> str:
 
 
 def parse_system_image_changed(text: str) -> Optional[Tuple[str, bool]]:
-    """return image changed/deleted info from parsing the given system message text."""
+    """Return image changed/deleted info from parsing the given system message text."""
     text = text.lower()
     match = re.match(r"group image (changed|deleted) by (.+).", text)
     if match:
@@ -142,7 +143,7 @@ def parse_system_title_changed(text: str) -> Optional[Tuple[str, str]]:
 
 
 def parse_system_add_remove(text: str) -> Optional[Tuple[str, str, str]]:
-    """return add/remove info from parsing the given system message text.
+    """Return add/remove info from parsing the given system message text.
 
     returns a (action, affected, actor) tuple.
     """

{deltachat_rpc_client-1.142.8 → deltachat_rpc_client-2.24.0}/src/deltachat_rpc_client/account.py

@@ -1,5 +1,8 @@
+"""Account module."""
+
 from __future__ import annotations
 
+import json
 from dataclasses import dataclass
 from typing import TYPE_CHECKING, Optional, Union
 from warnings import warn
@@ -26,18 +29,36 @@ class Account:
     def _rpc(self) -> "Rpc":
         return self.manager.rpc
 
-    def wait_for_event(self) -> AttrDict:
+    def wait_for_event(self, event_type=None) -> AttrDict:
         """Wait until the next event and return it."""
-        return AttrDict(self._rpc.wait_for_event(self.id))
+        while True:
+            next_event = AttrDict(self._rpc.wait_for_event(self.id))
+            if event_type is None or next_event.kind == event_type:
+                return next_event
 
     def clear_all_events(self):
-        """Removes all queued-up events for a given account. Useful for tests."""
+        """Remove all queued-up events for a given account.
+
+        Useful for tests.
+        """
         self._rpc.clear_all_events(self.id)
 
     def remove(self) -> None:
         """Remove the account."""
         self._rpc.remove_account(self.id)
 
+    def clone(self) -> "Account":
+        """Clone given account.
+
+        This uses backup-transfer via iroh, i.e. the 'Add second device' feature.
+        """
+        future = self._rpc.provide_backup.future(self.id)
+        qr = self._rpc.get_backup_qr(self.id)
+        new_account = self.manager.add_account()
+        new_account._rpc.get_backup(new_account.id, qr)
+        future()
+        return new_account
+
     def start_io(self) -> None:
         """Start the account I/O."""
         self._rpc.start_io(self.id)
@@ -67,7 +88,7 @@ class Account:
         return self._rpc.get_config(self.id, key)
 
     def update_config(self, **kwargs) -> None:
-        """update config values."""
+        """Update config values."""
         for key, value in kwargs.items():
             self.set_config(key, value)
 
@@ -83,9 +104,15 @@ class Account:
         return self.get_config("selfavatar")
 
     def check_qr(self, qr):
+        """Parse QR code contents.
+
+        This function takes the raw text scanned
+        and checks what can be done with it.
+        """
         return self._rpc.check_qr(self.id, qr)
 
     def set_config_from_qr(self, qr: str):
+        """Set configuration values from a QR code."""
         self._rpc.set_config_from_qr(self.id, qr)
 
     @futuremethod
@@ -93,15 +120,28 @@ class Account:
         """Configure an account."""
         yield self._rpc.configure.future(self.id)
 
+    @futuremethod
+    def add_or_update_transport(self, params):
+        """Add a new transport."""
+        yield self._rpc.add_or_update_transport.future(self.id, params)
+
+    @futuremethod
+    def add_transport_from_qr(self, qr: str):
+        """Add a new transport using a QR code."""
+        yield self._rpc.add_transport_from_qr.future(self.id, qr)
+
+    @futuremethod
+    def list_transports(self):
+        """Return the list of all email accounts that are used as a transport in the current profile."""
+        transports = yield self._rpc.list_transports.future(self.id)
+        return transports
+
     def bring_online(self):
         """Start I/O and wait until IMAP becomes IDLE."""
         self.start_io()
-        while True:
-            event = self.wait_for_event()
-            if event.kind == EventType.IMAP_INBOX_IDLE:
-                break
+        self.wait_for_event(EventType.IMAP_INBOX_IDLE)
 
-    def create_contact(self, obj: Union[int, str, Contact], name: Optional[str] = None) -> Contact:
+    def create_contact(self, obj: Union[int, str, Contact, "Account"], name: Optional[str] = None) -> Contact:
         """Create a new Contact or return an existing one.
 
         Calling this method will always result in the same
@@ -109,26 +149,63 @@ class Account:
         with that e-mail address, it is unblocked and its display
         name is updated if specified.
 
-        :param obj: email-address or contact id.
+        :param obj: email-address, contact id or account.
         :param name: (optional) display name for this contact.
         """
+        if isinstance(obj, Account):
+            vcard = obj.self_contact.make_vcard()
+            [contact] = self.import_vcard(vcard)
+            if name:
+                contact.set_name(name)
+            return contact
         if isinstance(obj, int):
             obj = Contact(self, obj)
         if isinstance(obj, Contact):
             obj = obj.get_snapshot().address
         return Contact(self, self._rpc.create_contact(self.id, obj, name))
 
+    def make_vcard(self, contacts: list[Contact]) -> str:
+        """Create vCard with the given contacts."""
+        assert all(contact.account == self for contact in contacts)
+        contact_ids = [contact.id for contact in contacts]
+        return self._rpc.make_vcard(self.id, contact_ids)
+
+    def import_vcard(self, vcard: str) -> list[Contact]:
+        """Import vCard.
+
+        Return created or modified contacts in the order they appear in vCard.
+        """
+        contact_ids = self._rpc.import_vcard_contents(self.id, vcard)
+        return [Contact(self, contact_id) for contact_id in contact_ids]
+
     def create_chat(self, account: "Account") -> Chat:
-        addr = account.get_config("addr")
-        contact = self.create_contact(addr)
-        return contact.create_chat()
+        """Create a 1:1 chat with another account."""
+        return self.create_contact(account).create_chat()
+
+    def get_device_chat(self) -> Chat:
+        """Return device chat."""
+        return self.device_contact.create_chat()
 
     def get_contact_by_id(self, contact_id: int) -> Contact:
         """Return Contact instance for the given contact ID."""
         return Contact(self, contact_id)
 
     def get_contact_by_addr(self, address: str) -> Optional[Contact]:
-        """Check if an e-mail address belongs to a known and unblocked contact."""
+        """Looks up a known and unblocked contact with a given e-mail address.
+        To get a list of all known and unblocked contacts, use contacts_get_contacts().
+
+        **POTENTIAL SECURITY ISSUE**: If there are multiple contacts with this address
+        (e.g. an address-contact and a key-contact),
+        this looks up the most recently seen contact,
+        i.e. which contact is returned depends on which contact last sent a message.
+        If the user just clicked on a mailto: link, then this is the best thing you can do.
+        But **DO NOT** internally represent contacts by their email address
+        and do not use this function to look them up;
+        otherwise this function will sometimes look up the wrong contact.
+        Instead, you should internally represent contacts by their ids.
+
+        To validate an e-mail address independently of the contact database
+        use check_email_validity()."""
         contact_id = self._rpc.lookup_contact_id_by_addr(self.id, address)
         return contact_id and Contact(self, contact_id)
 
@@ -154,8 +231,8 @@ class Account:
     def get_contacts(
         self,
         query: Optional[str] = None,
+        *,
         with_self: bool = False,
-        verified_only: bool = False,
         snapshot: bool = False,
     ) -> Union[list[Contact], list[AttrDict]]:
         """Get a filtered list of contacts.
@@ -163,12 +240,9 @@ class Account:
         :param query: if a string is specified, only return contacts
                       whose name or e-mail matches query.
         :param with_self: if True the self-contact is also included if it matches the query.
-        :param only_verified: if True only return verified contacts.
         :param snapshot: If True return a list of contact snapshots instead of Contact instances.
         """
         flags = 0
-        if verified_only:
-            flags |= ContactFlag.VERIFIED_ONLY
         if with_self:
             flags |= ContactFlag.ADD_SELF
 
@@ -180,9 +254,14 @@ class Account:
 
     @property
     def self_contact(self) -> Contact:
-        """This account's identity as a Contact."""
+        """Account's identity as a Contact."""
         return Contact(self, SpecialContactId.SELF)
 
+    @property
+    def device_contact(self) -> Chat:
+        """Account's device contact."""
+        return Contact(self, SpecialContactId.DEVICE)
+
     def get_chatlist(
         self,
         query: Optional[str] = None,
@@ -226,20 +305,51 @@ class Account:
             chats.append(AttrDict(item))
         return chats
 
-    def create_group(self, name: str, protect: bool = False) -> Chat:
+    def create_group(self, name: str) -> Chat:
         """Create a new group chat.
 
-        After creation, the group has only self-contact as member and is in unpromoted state.
+        After creation,
+        the group has only self-contact as member one member (see `SpecialContactId.SELF`)
+        and is in _unpromoted_ state.
+        This means, you can add or remove members, change the name,
+        the group image and so on without messages being sent to all group members.
+
+        This changes as soon as the first message is sent to the group members
+        and the group becomes _promoted_.
+        After that, all changes are synced with all group members
+        by sending status message.
+
+        To check, if a chat is still unpromoted, you can look at the `is_unpromoted` property of a chat
+        (see `get_full_snapshot()` / `get_basic_snapshot()`).
+        This may be useful if you want to show some help for just created groups.
         """
-        return Chat(self, self._rpc.create_group_chat(self.id, name, protect))
+        return Chat(self, self._rpc.create_group_chat(self.id, name, False))
+
+    def create_broadcast(self, name: str) -> Chat:
+        """Create a new, outgoing **broadcast channel**
+        (called "Channel" in the UI).
+
+        Broadcast channels are similar to groups on the sending device,
+        however, recipients get the messages in a read-only chat
+        and will not see who the other members are.
+
+        Called `broadcast` here rather than `channel`,
+        because the word "channel" already appears a lot in the code,
+        which would make it hard to grep for it.
+
+        After creation, the chat contains no recipients and is in _unpromoted_ state;
+        see `create_group()` for more information on the unpromoted state.
+
+        Returns the created chat.
+        """
+        return Chat(self, self._rpc.create_broadcast(self.id, name))
 
     def get_chat_by_id(self, chat_id: int) -> Chat:
         """Return the Chat instance with the given ID."""
         return Chat(self, chat_id)
 
     def secure_join(self, qrdata: str) -> Chat:
-        """Continue a Setup-Contact or Verified-Group-Invite protocol started on
-        another device.
+        """Continue a Setup-Contact or Verified-Group-Invite protocol started on another device.
 
         The function returns immediately and the handshake runs in background, sending
         and receiving several messages.
@@ -296,34 +406,40 @@ class Account:
 
     def wait_for_incoming_msg_event(self):
         """Wait for incoming message event and return it."""
-        while True:
-            event = self.wait_for_event()
-            if event.kind == EventType.INCOMING_MSG:
-                return event
+        return self.wait_for_event(EventType.INCOMING_MSG)
+
+    def wait_for_msgs_changed_event(self):
+        """Wait for messages changed event and return it."""
+        return self.wait_for_event(EventType.MSGS_CHANGED)
+
+    def wait_for_msgs_noticed_event(self):
+        """Wait for messages noticed event and return it."""
+        return self.wait_for_event(EventType.MSGS_NOTICED)
 
     def wait_for_incoming_msg(self):
         """Wait for incoming message and return it.
 
-        Consumes all events before the next incoming message event."""
+        Consumes all events before the next incoming message event.
+        """
         return self.get_message_by_id(self.wait_for_incoming_msg_event().msg_id)
 
     def wait_for_securejoin_inviter_success(self):
+        """Wait until SecureJoin process finishes successfully on the inviter side."""
         while True:
             event = self.wait_for_event()
             if event["kind"] == "SecurejoinInviterProgress" and event["progress"] == 1000:
                 break
 
     def wait_for_securejoin_joiner_success(self):
+        """Wait until SecureJoin process finishes successfully on the joiner side."""
         while True:
             event = self.wait_for_event()
             if event["kind"] == "SecurejoinJoinerProgress" and event["progress"] == 1000:
                 break
 
     def wait_for_reactions_changed(self):
-        while True:
-            event = self.wait_for_event()
-            if event.kind == EventType.REACTIONS_CHANGED:
-                return event
+        """Wait for reaction change event."""
+        return self.wait_for_event(EventType.REACTIONS_CHANGED)
 
     def get_fresh_messages_in_arrival_order(self) -> list[Message]:
         """Return fresh messages list sorted in the order of their arrival, with ascending IDs."""
@@ -352,3 +468,12 @@ class Account:
         """Import keys."""
         passphrase = ""  # Importing passphrase-protected keys is currently not supported.
         self._rpc.import_self_keys(self.id, str(path), passphrase)
+
+    def initiate_autocrypt_key_transfer(self) -> None:
+        """Send Autocrypt Setup Message."""
+        return self._rpc.initiate_autocrypt_key_transfer(self.id)
+
+    def ice_servers(self) -> list:
+        """Return ICE servers for WebRTC configuration."""
+        ice_servers_json = self._rpc.ice_servers(self.id)
+        return json.loads(ice_servers_json)

{deltachat_rpc_client-1.142.8 → deltachat_rpc_client-2.24.0}/src/deltachat_rpc_client/chat.py

@@ -1,3 +1,5 @@
+"""Chat module."""
+
 from __future__ import annotations
 
 import calendar
@@ -89,7 +91,8 @@ class Chat:
     def set_ephemeral_timer(self, timer: int) -> None:
         """Set ephemeral timer of this chat in seconds.
 
-        0 means the timer is disabled, use 1 for immediate deletion."""
+        0 means the timer is disabled, use 1 for immediate deletion.
+        """
         self._rpc.set_chat_ephemeral_timer(self.account.id, self.id, timer)
 
     def get_encryption_info(self) -> str:
@@ -124,6 +127,7 @@ class Chat:
         html: Optional[str] = None,
         viewtype: Optional[ViewType] = None,
         file: Optional[str] = None,
+        filename: Optional[str] = None,
         location: Optional[tuple[float, float]] = None,
         override_sender_name: Optional[str] = None,
         quoted_msg: Optional[Union[int, Message]] = None,
@@ -137,6 +141,7 @@ class Chat:
             "html": html,
             "viewtype": viewtype,
             "file": file,
+            "filename": filename,
             "location": location,
             "overrideSenderName": override_sender_name,
             "quotedMessageId": quoted_msg,
@@ -163,6 +168,11 @@ class Chat:
         msg_id = self._rpc.send_sticker(self.account.id, self.id, path)
         return Message(self.account, msg_id)
 
+    def resend_messages(self, messages: list[Message]) -> None:
+        """Resend a list of messages to this chat."""
+        msg_ids = [msg.id for msg in messages]
+        self._rpc.resend_messages(self.account.id, msg_ids)
+
     def forward_messages(self, messages: list[Message]) -> None:
         """Forward a list of messages to this chat."""
         msg_ids = [msg.id for msg in messages]
@@ -172,13 +182,14 @@ class Chat:
         self,
         text: Optional[str] = None,
         file: Optional[str] = None,
+        filename: Optional[str] = None,
         quoted_msg: Optional[int] = None,
         viewtype: Optional[str] = None,
     ) -> None:
         """Set draft message."""
         if isinstance(quoted_msg, Message):
             quoted_msg = quoted_msg.id
-        self._rpc.misc_set_draft(self.account.id, self.id, text, file, quoted_msg, viewtype)
+        self._rpc.misc_set_draft(self.account.id, self.id, text, file, filename, quoted_msg, viewtype)
 
     def remove_draft(self) -> None:
         """Remove draft message."""
@@ -196,12 +207,12 @@ class Chat:
         return snapshot
 
     def get_messages(self, info_only: bool = False, add_daymarker: bool = False) -> list[Message]:
-        """get the list of messages in this chat."""
+        """Get the list of messages in this chat."""
         msgs = self._rpc.get_message_ids(self.account.id, self.id, info_only, add_daymarker)
         return [Message(self.account, msg_id) for msg_id in msgs]
 
     def get_fresh_message_count(self) -> int:
-        """Get number of fresh messages in this chat"""
+        """Get number of fresh messages in this chat."""
         return self._rpc.get_fresh_msg_cnt(self.account.id, self.id)
 
     def mark_noticed(self) -> None:
@@ -238,6 +249,11 @@ class Chat:
         contacts = self._rpc.get_chat_contacts(self.account.id, self.id)
         return [Contact(self.account, contact_id) for contact_id in contacts]
 
+    def get_past_contacts(self) -> list[Contact]:
+        """Get past contacts for this chat."""
+        past_contacts = self._rpc.get_past_chat_contacts(self.account.id, self.id)
+        return [Contact(self.account, contact_id) for contact_id in past_contacts]
+
     def set_image(self, path: str) -> None:
         """Set profile image of this chat.
 
@@ -278,3 +294,8 @@ class Chat:
             f.write(vcard.encode())
             f.flush()
             self._rpc.send_msg(self.account.id, self.id, {"viewtype": ViewType.VCARD, "file": f.name})
+
+    def place_outgoing_call(self, place_call_info: str) -> Message:
+        """Starts an outgoing call."""
+        msg_id = self._rpc.place_outgoing_call(self.account.id, self.id, place_call_info)
+        return Message(self.account, msg_id)

{deltachat_rpc_client-1.142.8 → deltachat_rpc_client-2.24.0}/src/deltachat_rpc_client/client.py

@@ -48,6 +48,7 @@ class Client:
         self.add_hooks(hooks or [])
 
     def add_hooks(self, hooks: Iterable[tuple[Callable, Union[type, EventFilter]]]) -> None:
+        """Register multiple hooks."""
         for hook, event in hooks:
             self.add_hook(hook, event)
 
@@ -77,14 +78,15 @@ class Client:
         self._hooks.get(type(event), set()).remove((hook, event))
 
     def is_configured(self) -> bool:
+        """Return True if the client is configured."""
         return self.account.is_configured()
 
     def configure(self, email: str, password: str, **kwargs) -> None:
-        self.account.set_config("addr", email)
-        self.account.set_config("mail_pw", password)
+        """Configure the client."""
         for key, value in kwargs.items():
             self.account.set_config(key, value)
-        self.account.configure()
+        params = {"addr": email, "password": password}
+        self.account.add_or_update_transport(params)
         self.logger.debug("Account configured")
 
     def run_forever(self) -> None:
@@ -198,5 +200,6 @@ class Bot(Client):
     """Simple bot implementation that listens to events of a single account."""
 
     def configure(self, email: str, password: str, **kwargs) -> None:
+        """Configure the bot."""
         kwargs.setdefault("bot", "1")
         super().configure(email, password, **kwargs)