yetangitu/deltachat-core
1
0
Fork 0
mirror of https://github.com/deltachat/deltachat-core.git synced 2025-10-05 10:39:27 +02:00
Code Issues Releases Wiki Activity

initial sphinx docs and many docstrings.

Browse source
This commit is contained in:
holger krekel 2018-09-14 11:30:09 +02:00
parent dd060d7cf2
commit 66d6621f93
19 changed files with 1277 additions and 27 deletions
Download patch file Download diff file Expand all files Collapse all files

100
python/src/deltachat/account.py
View file

@ -1,3 +1,5 @@
""" Delta.Chat high level API objects. """
from __future__ import print_function
import threading
import re
@ -11,7 +13,7 @@ except ImportError:
import deltachat
from . import capi
from .capi import ffi, lib
from .types import cached_property
from .types import cached_property, property_with_doc
import attr
from attr import validators as v
@ -81,6 +83,10 @@ class EventLogger:
@attr.s
class Contact(object):
""" Delta-Chat Contact. You obtain instances of it through the :class:`Account`.
:ivar id: integer id of this chat.
"""
dc_context = attr.ib(validator=v.instance_of(ffi.CData))
id = attr.ib(validator=v.instance_of(int))
@ -92,12 +98,14 @@ class Contact(object):
if self._property_cache:
dc_contact_unref(self.dc_contact_t)
@property
@property_with_doc
def addr(self):
""" normalized e-mail address for this account. """
return ffi_unicode(capi.lib.dc_contact_get_addr(self.dc_contact_t))
@property
@property_with_doc
def display_name(self):
""" display name for this contact. """
return ffi_unicode(capi.lib.dc_contact_get_display_name(self.dc_contact_t))
def is_blocked(self):
@ -111,6 +119,9 @@ class Contact(object):
@attr.s
class Chat(object):
""" Chat object which manages members and through which you can send and retrieve messages.
"""
dc_context = attr.ib(validator=v.instance_of(ffi.CData))
id = attr.ib(validator=v.instance_of(int))
@ -127,19 +138,29 @@ class Chat(object):
return self.id == lib.DC_CHAT_ID_DEADDROP
def send_text_message(self, msg):
""" send a text message and return the resulting Message instance. """
""" send a text message and return the resulting Message instance.
:param msg: unicode text
:returns: the resulting :class:`Message` instance
"""
msg = convert_to_bytes_utf8(msg)
print ("chat id", self.id)
msg_id = capi.lib.dc_send_text_msg(self.dc_context, self.id, msg)
return Message(self.dc_context, msg_id)
def get_messages(self):
""" return list of messages in this chat. """
""" return list of messages in this chat.
:returns: list of Message objects for this chat.
"""
dc_array_t = lib.dc_get_chat_msgs(self.dc_context, self.id, 0, 0)
return list(iter_array_and_unref(dc_array_t, lambda x: Message(self.dc_context, x)))
def count_fresh_messages(self):
""" return number of fresh messages in this chat. """
""" return number of fresh messages in this chat.
:returns: number of fresh messages
"""
return lib.dc_get_fresh_msg_cnt(self.dc_context, self.id)
def mark_noticed(self):
@ -152,6 +173,7 @@ class Chat(object):
@attr.s
class Message(object):
""" Message object. """
dc_context = attr.ib(validator=v.instance_of(ffi.CData))
id = attr.ib(validator=v.instance_of(int))
@ -163,18 +185,34 @@ class Message(object):
if self._property_cache:
dc_msg_unref(self.dc_msg_t)
@property
@property_with_doc
def text(self):
"""unicode representation. """
return ffi_unicode(capi.lib.dc_msg_get_text(self.dc_msg_t))
@property
def chat(self):
"""chat this message was posted in.
:returns: :class:`Chat` object
"""
chat_id = capi.lib.dc_msg_get_chat_id(self.dc_msg_t)
return Chat(self.dc_context, chat_id)
class Account(object):
""" An account contains configuration and provides methods
for configuration, contact and chat creation and manipulation.
"""
def __init__(self, db_path, logid=None):
""" initialize account object.
:param db_path: a path to the account database. The database
will be created if it doesn't exist.
:param logid: an optional logging prefix that should be used with
the default internal logging.
"""
self.dc_context = ctx = capi.lib.dc_context_new(
capi.lib.py_dc_callback,
capi.ffi.NULL, capi.ffi.NULL)
@ -189,39 +227,66 @@ class Account(object):
dc_context_unref(self.dc_context)
def set_config(self, **kwargs):
""" set configuration values.
:param kwargs: name=value settings for this account.
values need to be unicode.
:returns: None
"""
for name, value in kwargs.items():
name = name.encode("utf8")
value = value.encode("utf8")
capi.lib.dc_set_config(self.dc_context, name, value)
def get_config(self, name):
""" return unicode string value.
:param name: configuration key to lookup (eg "addr" or "mail_pw")
:returns: unicode value
"""
name = name.encode("utf8")
res = capi.lib.dc_get_config(self.dc_context, name, b'')
return ffi_unicode(res)
def is_configured(self):
""" determine if the account is configured already.
:returns: True if account is configured.
"""
return capi.lib.dc_is_configured(self.dc_context)
def check_is_configured(self):
""" Raise ValueError if this account is not configured. """
if not self.is_configured():
raise ValueError("need to configure first")
def get_self_contact(self):
""" return this account's identity as a :class:`Contact`.
:returns: :class:`Contact`
"""
self.check_is_configured()
return Contact(self.dc_context, capi.lib.DC_CONTACT_ID_SELF)
def create_contact(self, email, name=ffi.NULL):
""" Return a :class:`Contact` object.
:param email: email-address (text type)
:param name: display name for this contact (optional)
:returns: :class:`Contact` instance.
"""
name = convert_to_bytes_utf8(name)
email = convert_to_bytes_utf8(email)
contact_id = capi.lib.dc_create_contact(self.dc_context, name, email)
return Contact(self.dc_context, contact_id)
def get_contacts(self, query=ffi.NULL, with_self=False, only_verified=False):
""" return list of :pyclass:`Contact` objects.
""" return list of :class:`Contact` objects.
:query: if a string is specified, only return contacts whose name or e-mail matches query.
:only_verified: if true only return verified contacts.
:with_self: if true the self-contact is also returned.
:param query: if a string is specified, only return contacts
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.
"""
flags = 0
query = convert_to_bytes_utf8(query)
@ -235,7 +300,7 @@ class Account(object):
def create_chat_by_contact(self, contact):
""" return a Chat object with the specified contact.
@param contact: chat_id (int) or contact object.
:param contact: chat_id (int) or contact object.
"""
contact_id = getattr(contact, "id", contact)
assert isinstance(contact_id, int)
@ -246,7 +311,7 @@ class Account(object):
def create_chat_by_message(self, message):
""" return a Chat object for the given message.
@param message: messsage id or message instance.
:param message: messsage id or message instance.
"""
msg_id = getattr(message, "id", message)
assert isinstance(msg_id, int)
@ -254,12 +319,16 @@ class Account(object):
return Chat(self.dc_context, chat_id)
def get_message_by_id(self, msg_id):
""" return a message object.
:returns: :class:`Message` instance.
"""
return Message(self.dc_context, msg_id)
def mark_seen_messages(self, messages):
""" mark the given set of messages as seen.
:messages: a list of message ids or Message instances.
:param messages: a list of message ids or Message instances.
"""
arr = array("i")
for msg in messages:
@ -269,11 +338,14 @@ class Account(object):
lib.dc_markseen_msgs(self.dc_context, msg_ids, len(messages))
def start(self):
""" configure this account object, start receiving events,
start IMAP/SMTP threads. """
deltachat.set_context_callback(self.dc_context, self._process_event)
capi.lib.dc_configure(self.dc_context)
self._threads.start()
def shutdown(self):
""" shutdown IMAP/SMTP threads and stop receiving events"""
deltachat.clear_context_callback(self.dc_context)
self._threads.stop(wait=True)