minor info

README.rst

@@ -42,7 +42,7 @@ Guide
 Basic
 ^^^^^
 
-Info about lib are at: *this page*, issues, pull requests, examples, source, stackoverflow.com
+Info about lib are at: *this page*, docstrings, issues, pull requests, examples, source, stackoverflow.com
 
 .. code-block:: python
 

docs/full_docs.rst

@@ -4,5 +4,3 @@ There is no full API reference docs.
 I tried to describe the library API as much as possible in README.rst
 If you are using some imap_tools entity, just look at its args at source code by your IDE:
 doc strings are present, argument types annotated.
-
-I will make docs after donation for it, see donate.rst

docs/todo.txt

@@ -1 +1,21 @@
 Release 1.0.0 after 3 month of quiet in issues and merge requests
+
+
+https://stackoverflow.com/questions/72942311/ some to docs?
+    The second problem is that you need to use imap_tools.MailBox.
+    Looking at the documentation and source at the repo it appears that the relevant classes to use are:
+
+        MailBox - for a normal encrypted connection. This is what most email servers use these days, aka IMAPS (imap with SSL/TLS)
+        MailBoxTls - For a STARTTLS connection: this creates a plaintext connection then upgrades
+        it later by using a STARTTLS command in the protocol. The internet has mostly gone to the "always encrypted"
+        rather than "upgrade" paradigm, so this is not the class to use.
+        MailBoxUnencrypted - Standard IMAP without SSL/TLS. You should not use this on the public internet.
+
+    The naming is a bit confusing. MailBox corresponds to imaplib.IMAP4_SSL;
+    MailBoxTls corresponds to imaplib.IMAP4, then using startls() on the resulting connection;
+    and MailboxUnencrypted corresponds to imaplib.IMAP4 with no security applied.
+    I imagine it's this way so the most common one (Mailbox) is a safe default.
+
+rambler mbox
+
+MailBoxUnencrypted

examples/email_edit.py

@@ -7,10 +7,10 @@
 """
 
 import email
-from imap_tools import MailBox
+from imap_tools import MailBox, A
 
 with MailBox('imap.mail.com').login('test@mail.com', 'password') as mailbox:
-    for msg in mailbox.fetch():
+    for msg in mailbox.fetch(A(subject='[some]')):
         altered_msg = email.message_from_bytes(msg.obj.as_bytes())
         altered_msg.replace_header('Subject', '[my own subject extension] ' + msg.subject)
         mailbox.append(altered_msg.as_bytes())