From 04db204481f0d11874989abe7e88a9471ec09256 Mon Sep 17 00:00:00 2001 From: Volker Birk Date: Sun, 4 Sep 2016 14:24:20 +0200 Subject: [PATCH] nicer interface and documentation --- src/message.cc | 29 +++++--- src/message.hh | 6 +- src/pEpmodule.cc | 174 +++++++++++++++++++++++++++++++++++++++-------- 3 files changed, 169 insertions(+), 40 deletions(-) diff --git a/src/message.cc b/src/message.cc index 9f3b4fd..65061a9 100644 --- a/src/message.cc +++ b/src/message.cc @@ -5,6 +5,7 @@ #include #include #include +#include #include #include #include @@ -287,20 +288,32 @@ namespace pEp { _msg->attachments = bl; } - Message Message::encrypt(list extra, int enc_format, int flags) { - return encrypt_message(*this, extra, enc_format, flags); + static const vector< string > enc_format_s + = { "none", "partitioned", "S/MIME", "PGP/MIME", "pEp" }; + + static string _enc_format(int n) + { + return enc_format_s[n % enc_format_s.size()]; } - Message Message::encrypt(list extra, int enc_format) { - return encrypt_message(*this, extra, enc_format); + static int _enc_format(string s) + { + if (s == "p≡p") + return 4; + int i=0; + for (auto _s=enc_format_s.begin(); _s != enc_format_s.end(); _s++, i++) { + if (*_s == s) + return i; + } + return -1; } - Message Message::encrypt(list extra) { - return encrypt_message(*this, extra); + Message Message::encrypt(list extra, string enc_format, int flags) { + return encrypt_message(*this, extra, _enc_format(enc_format), flags); } - Message Message::encrypt() { - return encrypt_message(*this); + Message Message::_encrypt(list extra, int enc_format, int flags) { + return encrypt_message(*this, extra, enc_format, flags); } boost::python::tuple Message::decrypt() { diff --git a/src/message.hh b/src/message.hh index 92fe1e2..6505b50 100644 --- a/src/message.hh +++ b/src/message.hh @@ -123,10 +123,8 @@ namespace pEp { PEP_enc_format enc_format() { return _msg->enc_format; } void enc_format(PEP_enc_format value) { _msg->enc_format = value; } - Message encrypt(list extra, int enc_format, int flags); - Message encrypt(list extra, int enc_format); - Message encrypt(list extra); - Message encrypt(); + Message encrypt(list extra=list(), string enc_format="", int flags=0); + Message _encrypt(list extra=list(), int enc_format=4, int flags=0); boost::python::tuple decrypt(); int outgoing_rating(); int outgoing_color(); diff --git a/src/pEpmodule.cc b/src/pEpmodule.cc index 84637af..c84b51d 100644 --- a/src/pEpmodule.cc +++ b/src/pEpmodule.cc @@ -50,14 +50,30 @@ BOOST_PYTHON_MODULE(pEp) using namespace boost::locale; using namespace pEp::PythonAdapter; - docstring_options doc_options(true); + docstring_options doc_options(true, false, false); generator gen; std::locale::global(gen("")); scope().attr("about") = about(); - auto identity_class = class_("Identity", "p≡p identity") + auto identity_class = class_("Identity", + "Identity(address, username, user_id='', fpr='', comm_type=0, lang='en')\n" + "\n" + "represents a p≡p identity\n" + "\n" + "an identity is a network address, under which a user is represented in\n" + "the network\n" + "\n" + " address network address, either an SMTP address or a URI\n" + " username real name or nickname for user\n" + " user_id ID this user is handled by the application\n" + " fpr full fingerprint of the key being used as key ID,\n" + " hex encoded\n" + " comm_type first rating level of this communication channel\n" + " lang ISO 639-1 language code for language being preferred\n" + " on this communication cahnnel\n" + ) .def(init()) .def(init()) .def(init()) @@ -65,7 +81,10 @@ BOOST_PYTHON_MODULE(pEp) .def(init()) .def(init()) .def("__repr__", &Identity::_repr) - .def("__str__", &Identity::_str) + .def("__str__", &Identity::_str, + "string representation of this identity\n" + "following the pattern 'username < address >'\n" + ) .add_property("address", (string(Identity::*)()) &Identity::address, (void(Identity::*)(string)) &Identity::address, "email address or URI") @@ -82,7 +101,7 @@ BOOST_PYTHON_MODULE(pEp) (PEP_comm_type(Identity::*)()) &Identity::comm_type, (void(Identity::*)(int)) (void(Identity::*)(PEP_comm_type)) &Identity::comm_type, - "communication type (p≡p internal)") + "communication type, first rating level (p≡p internal)") .add_property("lang", (string(Identity::*)()) &Identity::lang, (void(Identity::*)(string)) &Identity::lang, "ISO 639-1 language code") @@ -99,15 +118,27 @@ BOOST_PYTHON_MODULE(pEp) identity_class.attr("PEP_OWN_USERID") = "pEp_own_userId"; - auto blob_class = class_("Blob", "Binary large object", - init< object, char const*, char const* >(args("data", "mime_type", "filename"), - "init buffer with binary data") ) + auto blob_class = class_("Blob", + "Blob(data, mime_type='', filename='')\n" + "\n" + "Binary large object\n" + "\n" + " data bytes-like object\n" + " mime_type MIME type for the data\n" + " filename filename to store the data\n" , + init< object, char const*, char const* >(args("data", "mime_type", "filename"))) .def(init()) .def(init()) .def("__repr__", &Message::Blob::_repr) .def("__len__", &Message::Blob::size, "size of Blob data in bytes") - .def("decode", (string(Message::Blob::*)(string)) &Message::Blob::decode, "decode Blob data into string") - .def("decode", (string(Message::Blob::*)()) &Message::Blob::decode, "decode Blob data into string") + .def("decode", (string(Message::Blob::*)()) &Message::Blob::decode) + .def("decode", (string(Message::Blob::*)(string)) &Message::Blob::decode, + "text = decode(self, encoding='')\n" + "\n" + "decode Blob data into string depending on MIME type if encoding=''\n" + " mime_type='application/pEp.sync' decode as 'pEp.sync'\n" + " other mime_type decode as 'ascii' by default\n" + ) .add_property("mime_type", (string(Message::Blob::*)()) &Message::Blob::mime_type, (void(Message::Blob::*)(string)) &Message::Blob::mime_type, "MIME type of object in Blob") @@ -117,9 +148,17 @@ BOOST_PYTHON_MODULE(pEp) ((PyTypeObject *)(void *)blob_class.ptr())->tp_as_buffer = &Message::Blob::bp; - auto message_class = class_("Message", "p≡p message") + auto message_class = class_("Message", + "Message(mime_text)\n" + "\n" + "p≡p message\n" + "\n" + " mime_text text in Multipurpose Internet Mail Extensions format\n" + ) .def(init()) - .def("__str__", &Message::_str) + .def("__str__", &Message::_str, + "the string representation of a Message is it's MIME text" + ) .def("__repr__", &Message::_repr) .add_property("dir", (int(Message::*)()) (PEP_msg_direction(Message::*)()) &Message::dir, @@ -185,11 +224,31 @@ BOOST_PYTHON_MODULE(pEp) (void(Message::*)(int)) (void(Message::*)(PEP_enc_format)) &Message::enc_format, "0: unencrypted, 1: inline PGP, 2: S/MIME, 3: PGP/MIME, 4: p≡p format") - .def("encrypt", (Message(Message::*)())&Message::encrypt, "msg = encrypt message()") - .def("encrypt", (Message(Message::*)(list))&Message::encrypt, "msg = encrypt message(extra_keys)") - .def("encrypt", (Message(Message::*)(list,int))&Message::encrypt, "msg = encrypt message(extra_keys, enc_format)") - .def("encrypt", (Message(Message::*)(list,int,int))&Message::encrypt, "msg = encrypt message(extra_keys, enc_format, flags)") - .def("decrypt", &Message::decrypt, "msg, keys, rating, flags = decrypt message()") + .def("encrypt", (Message(Message::*)())&Message::encrypt) + .def("encrypt", (Message(Message::*)(list))&Message::encrypt) + .def("encrypt", (Message(Message::*)(list,string))&Message::encrypt) + .def("encrypt", (Message(Message::*)(list,string,int))&Message::encrypt) + .def("encrypt", (Message(Message::*)(list,int))&Message::_encrypt) + .def("encrypt", (Message(Message::*)(list,int,int))&Message::_encrypt, + "msg = encrypt(self, extra_keys=[], enc_format='pEp', flags=0)\n" + "\n" + "encrypts a p≡p message and returns the encrypted message\n" + "\n" + " extra_keys list of strings with fingerprints for extra keys to use\n" + " for encryption\n" + " enc_format 'none', 'partitioned', 'S/MIME', 'PGP/MIME' or 'pEp'\n" + " flags 1 is force encryption\n" + ) + .def("decrypt", &Message::decrypt, + "msg, keys, rating, flags = decrypt()\n" + "\n" + "decrypts a p≡p message and returns a tuple with data\n" + "\n" + " msg the decrypted p≡p message\n" + " keys a list of keys being used\n" + " rating the rating of the message as integer\n" + " flags flags set while decryption (reserved)\n" + ) .add_property("outgoing_rating", &Message::outgoing_rating, "rating outgoing message will have") .add_property("outgoing_color", &Message::outgoing_color, "color outgoing message will have") .def("__deepcopy__", &Message::deepcopy) @@ -197,29 +256,88 @@ BOOST_PYTHON_MODULE(pEp) // basic API - def("update_identity", &update_identity, "update identity information"); - def("myself", &myself, "ensures that the own identity is being complete"); + def("update_identity", &update_identity, + "update_identity(ident)\n" + "\n" + "update identity information\n" + "call this to complete identity information when you at least have an address\n" + ); + def("myself", &myself, + "myself(ident)\n" + "\n" + "ensures that the own identity is being complete\n" + "supply ident.address and ident.username\n" + ); // message API - def("incoming_message", &incoming_message, "create an incoming message from a MIME text"); - def("outgoing_message", &outgoing_message, "create an outgoing message using an own identity"); - def("color", &_color, "calculate color value out of rating"); - def("trustwords", &_trustwords, "calculate trustwords for two Identities"); - def("config_keep_sync_msg", &_config_keep_sync_msg, "configure if sync messages are being kept or not"); + def("incoming_message", &incoming_message, + "msg = incoming_message(mime_text)\n" + "\n" + "create an incoming message from a MIME text" + ); + def("outgoing_message", &outgoing_message, + "msg = outgoing_message(ident)\n" + "\n" + "create an outgoing message using an own identity" + ); + def("color", &_color, + "c = color(rating)\n" + "\n" + "calculate color value out of rating" + ); + def("trustwords", &_trustwords, + "text = trustwords(ident_own, ident_partner)\n" + "\n" + "calculate trustwords for two Identities"); + def("config_keep_sync_msg", &_config_keep_sync_msg, + "config_keep_sync_msg(enabled)\n" + "\n" + "configure if sync messages are being kept or automatically removed (default)"); // key sync API auto sync_mixin_class = class_( - "SyncMixIn", "p≡p Sync MixIn") - .def("messageToSend", &SyncMixIn::messageToSend, "overwrite this method") - .def("showHandshake", &SyncMixIn::showHandshake, "overwrite this method") + "SyncMixIn", + "class MySyncHandler(SyncMixIn)\n" + " def messageToSend(self, msg):\n" + " ...\n" + "\n" + " def showHandshake(self, me, partner):\n" + " ...\n" + "\n" + "p≡p Sync MixIn\n" + "\n" + "write a handler class to enable p≡p sync protocol\n") + .def("messageToSend", &SyncMixIn::messageToSend, + "messageToSend(self, msg)" + "\n" + " msg p≡p message to send\n" + "\n" + "overwrite this method with code actually sending msg") + .def("showHandshake", &SyncMixIn::showHandshake, + "showHandshake(self, me, partner)\n" + "\n" + " me own identity\n" + " partner identity of communication partner\n" + "\n" + "overwrite this method with code showing a trustwords dialog") #ifndef NDEBUG .def("inject", &SyncMixIn::_inject, - "inject an event into the sync state machine (for debugging purposes only") + "inject(self, event, partner, extra)\n" + "\n" + " event number of event to inject\n" + " partner identity of communication partner\n" + " extra optional extra data or None\n" + "\n" + "inject an event into the sync state machine (for debugging purposes only)") #endif .def("deliverHandshakeResult", &SyncMixIn::deliverHandshakeResult, - "call to deliver the handshake result"); + "deliverHandshakeResult(self, result)\n" + "\n" + " result -1: cancel, 0: accepted, 1: rejected\n" + "\n" + "call to deliver the handshake result"); // codecs