diff --git a/python/doc/api.rst b/python/doc/api.rst index fc5dcd4b7..d82364b75 100644 --- a/python/doc/api.rst +++ b/python/doc/api.rst @@ -8,8 +8,8 @@ high level API reference - :class:`deltachat.account.Account` (your main entry point, creates the other classes) -- :class:`deltachat.chatting.Contact` -- :class:`deltachat.chatting.Chat` +- :class:`deltachat.contact.Contact` +- :class:`deltachat.chat.Chat` - :class:`deltachat.message.Message` Account @@ -22,13 +22,13 @@ Account Contact ------- -.. autoclass:: deltachat.chatting.Contact +.. autoclass:: deltachat.contact.Contact :members: Chat ---- -.. autoclass:: deltachat.chatting.Chat +.. autoclass:: deltachat.chat.Chat :members: Message diff --git a/python/src/deltachat/account.py b/python/src/deltachat/account.py index 4d8ba0b83..338c947ed 100644 --- a/python/src/deltachat/account.py +++ b/python/src/deltachat/account.py @@ -15,12 +15,14 @@ import deltachat from . import const from .capi import ffi, lib from .cutil import as_dc_charpointer, from_dc_charpointer, iter_array, DCLot -from .chatting import Contact, Chat, Message +from .chat import Chat +from .message import Message +from .contact import Contact class Account(object): """ Each account is tied to a sqlite database file which is fully managed - by the underlying deltachat c-library. All public Account methods are + by the underlying deltachat core library. All public Account methods are meant to be memory-safe and return memory-safe objects. """ def __init__(self, db_path, logid=None, eventlogging=True, debug=True): @@ -160,9 +162,9 @@ class Account(object): return from_dc_charpointer(lib.dc_get_blobdir(self._dc_context)) def get_self_contact(self): - """ return this account's identity as a :class:`deltachat.chatting.Contact`. + """ return this account's identity as a :class:`deltachat.contact.Contact`. - :returns: :class:`deltachat.chatting.Contact` + :returns: :class:`deltachat.contact.Contact` """ self.check_is_configured() return Contact(self._dc_context, const.DC_CONTACT_ID_SELF) @@ -174,7 +176,7 @@ class Account(object): :param email: email-address (text type) :param name: display name for this contact (optional) - :returns: :class:`deltachat.chatting.Contact` instance. + :returns: :class:`deltachat.contact.Contact` instance. """ name = as_dc_charpointer(name) email = as_dc_charpointer(email) @@ -200,7 +202,7 @@ class Account(object): whose name or e-mail matches query. :param only_verified: if true only return verified contacts. :param with_self: if true the self-contact is also returned. - :returns: list of :class:`deltachat.chatting.Contact` objects. + :returns: list of :class:`deltachat.contact.Contact` objects. """ flags = 0 query = as_dc_charpointer(query) @@ -218,7 +220,7 @@ class Account(object): """ create or get an existing 1:1 chat object for the specified contact or contact id. :param contact: chat_id (int) or contact object. - :returns: a :class:`deltachat.chatting.Chat` object. + :returns: a :class:`deltachat.chat.Chat` object. """ if hasattr(contact, "id"): if contact._dc_context != self._dc_context: @@ -235,7 +237,7 @@ class Account(object): the specified message. :param message: messsage id or message instance. - :returns: a :class:`deltachat.chatting.Chat` object. + :returns: a :class:`deltachat.chat.Chat` object. """ if hasattr(message, "id"): if self._dc_context != message._dc_context: @@ -253,7 +255,7 @@ class Account(object): Chats are unpromoted until the first message is sent. :param verified: if true only verified contacts can be added. - :returns: a :class:`deltachat.chatting.Chat` object. + :returns: a :class:`deltachat.chat.Chat` object. """ bytes_name = name.encode("utf8") chat_id = lib.dc_create_group_chat(self._dc_context, int(verified), bytes_name) @@ -262,7 +264,7 @@ class Account(object): def get_chats(self): """ return list of chats. - :returns: a list of :class:`deltachat.chatting.Chat` objects. + :returns: a list of :class:`deltachat.chat.Chat` objects. """ dc_chatlist = ffi.gc( lib.dc_get_chatlist(self._dc_context, 0, ffi.NULL, 0), @@ -299,7 +301,7 @@ class Account(object): """ Forward list of messages to a chat. :param messages: list of :class:`deltachat.message.Message` object. - :param chat: :class:`deltachat.chatting.Chat` object. + :param chat: :class:`deltachat.chat.Chat` object. :returns: None """ msg_ids = [msg.id for msg in messages] @@ -411,7 +413,7 @@ class Account(object): """ setup contact and return a Chat after contact is established. Note that this function may block for a long time as messages are exchanged - with the emitter of the QR code. On success a :class:`deltachat.chatting.Chat` instance + with the emitter of the QR code. On success a :class:`deltachat.chat.Chat` instance is returned. :param qr: valid "setup contact" QR code (all other QR codes will result in an exception) """ @@ -425,7 +427,7 @@ class Account(object): """ join a chat group through a QR code. Note that this function may block for a long time as messages are exchanged - with the emitter of the QR code. On success a :class:`deltachat.chatting.Chat` instance + with the emitter of the QR code. On success a :class:`deltachat.chat.Chat` instance is returned which is the chat that we just joined. :param qr: valid "join-group" QR code (all other QR codes will result in an exception) diff --git a/python/src/deltachat/chatting.py b/python/src/deltachat/chat.py similarity index 89% rename from python/src/deltachat/chatting.py rename to python/src/deltachat/chat.py index 3c23bf9ee..dfc68a16c 100644 --- a/python/src/deltachat/chatting.py +++ b/python/src/deltachat/chat.py @@ -1,60 +1,15 @@ -""" chatting related objects: Contact, Chat, Message. """ +""" Chat and Location related API. """ import mimetypes import calendar from datetime import datetime import os -from . import props from .cutil import as_dc_charpointer, from_dc_charpointer, iter_array from .capi import lib, ffi from . import const from .message import Message -class Contact(object): - """ Delta-Chat Contact. - - You obtain instances of it through :class:`deltachat.account.Account`. - """ - def __init__(self, dc_context, id): - self._dc_context = dc_context - self.id = id - - def __eq__(self, other): - return self._dc_context == other._dc_context and self.id == other.id - - def __ne__(self, other): - return not (self == other) - - def __repr__(self): - return "".format(self.id, self.addr, self._dc_context) - - @property - def _dc_contact(self): - return ffi.gc( - lib.dc_get_contact(self._dc_context, self.id), - lib.dc_contact_unref - ) - - @props.with_doc - def addr(self): - """ normalized e-mail address for this account. """ - return from_dc_charpointer(lib.dc_contact_get_addr(self._dc_contact)) - - @props.with_doc - def display_name(self): - """ display name for this contact. """ - return from_dc_charpointer(lib.dc_contact_get_display_name(self._dc_contact)) - - def is_blocked(self): - """ Return True if the contact is blocked. """ - return lib.dc_contact_is_blocked(self._dc_contact) - - def is_verified(self): - """ Return True if the contact is verified. """ - return lib.dc_contact_is_verified(self._dc_contact) - - class Chat(object): """ Chat object which manages members and through which you can send and retrieve messages. @@ -314,9 +269,10 @@ class Chat(object): def get_contacts(self): """ get all contacts for this chat. :params: contact object. - :returns: list of :class:`deltachat.chatting.Contact` objects for this chat + :returns: list of :class:`deltachat.contact.Contact` objects for this chat """ + from .contact import Contact dc_array = ffi.gc( lib.dc_get_chat_contacts(self._dc_context, self.id), lib.dc_array_unref @@ -368,6 +324,8 @@ class Chat(object): return None return from_dc_charpointer(dc_res) + # ------ group management API ------------------------------ + def is_sending_locations(self): """return True if this chat has location-sending enabled currently. :returns: True if location sending is enabled. @@ -387,7 +345,7 @@ class Chat(object): :param contact: the contact for which locations shall be returned. :param timespan_from: a datetime object or None (indicating "since beginning") :param timespan_to: a datetime object or None (indicating up till now) - :returns: list of :class:`deltachat.chatting.Location` objects. + :returns: list of :class:`deltachat.chat.Location` objects. """ if timestamp_from is None: time_from = 0 diff --git a/python/src/deltachat/contact.py b/python/src/deltachat/contact.py new file mode 100644 index 000000000..70197e8ae --- /dev/null +++ b/python/src/deltachat/contact.py @@ -0,0 +1,49 @@ +""" Contact object. """ + +from . import props +from .cutil import from_dc_charpointer +from .capi import lib, ffi + + +class Contact(object): + """ Delta-Chat Contact. + + You obtain instances of it through :class:`deltachat.account.Account`. + """ + def __init__(self, dc_context, id): + self._dc_context = dc_context + self.id = id + + def __eq__(self, other): + return self._dc_context == other._dc_context and self.id == other.id + + def __ne__(self, other): + return not (self == other) + + def __repr__(self): + return "".format(self.id, self.addr, self._dc_context) + + @property + def _dc_contact(self): + return ffi.gc( + lib.dc_get_contact(self._dc_context, self.id), + lib.dc_contact_unref + ) + + @props.with_doc + def addr(self): + """ normalized e-mail address for this account. """ + return from_dc_charpointer(lib.dc_contact_get_addr(self._dc_contact)) + + @props.with_doc + def display_name(self): + """ display name for this contact. """ + return from_dc_charpointer(lib.dc_contact_get_display_name(self._dc_contact)) + + def is_blocked(self): + """ Return True if the contact is blocked. """ + return lib.dc_contact_is_blocked(self._dc_contact) + + def is_verified(self): + """ Return True if the contact is verified. """ + return lib.dc_contact_is_verified(self._dc_contact) diff --git a/python/src/deltachat/message.py b/python/src/deltachat/message.py index cba72df5b..1cec5cb5d 100644 --- a/python/src/deltachat/message.py +++ b/python/src/deltachat/message.py @@ -1,4 +1,4 @@ -""" chatting related objects: Contact, Chat, Message. """ +""" The Message object. """ import os import shutil @@ -13,7 +13,7 @@ class Message(object): """ Message object. You obtain instances of it through :class:`deltachat.account.Account` or - :class:`deltachat.chatting.Chat`. + :class:`deltachat.chat.Chat`. """ def __init__(self, account, dc_msg): self.account = account @@ -169,18 +169,18 @@ class Message(object): def chat(self): """chat this message was posted in. - :returns: :class:`deltachat.chatting.Chat` object + :returns: :class:`deltachat.chat.Chat` object """ - from .chatting import Chat + from .chat import Chat chat_id = lib.dc_msg_get_chat_id(self._dc_msg) return Chat(self.account, chat_id) def get_sender_contact(self): """return the contact of who wrote the message. - :returns: :class:`deltachat.chatting.Contact` instance + :returns: :class:`deltachat.chat.Contact` instance """ - from .chatting import Contact + from .contact import Contact contact_id = lib.dc_msg_get_from_id(self._dc_msg) return Contact(self._dc_context, contact_id)