On Wed, 26 May 2021 08:25:49 +1000, Cameron Simpson <cs@cskk.id.au>
declaimed the following:

>That depends on the library - it is of course at the whim of the
>developer. Heavily used powerful libraries are usually well documented,
>eg numpy. A random hacker's published module? Might have nothing.
>
>Wrappers for protocols like IMAP might have a bit of doco and expect the
>useful to infer stuff from knowledge of the protocol itself.

Like...

>>> import imaplib
>>> help(imaplib)
Help on module imaplib:

NAME
imaplib - IMAP4 client.

MODULE REFERENCE
https://docs.python.org/3.8/library/imaplib

The following documentation is automatically generated from the Python
source files. It may be incomplete, incorrect or include features that
are considered implementation detail and may vary between Python
implementations. When in doubt, consult the module reference at the
location listed above.

DESCRIPTION
Based on RFC 2060.

Public class: IMAP4
Public variable: Debug
Public functions: Internaldate2tuple
Int2AP
ParseFlags
Time2Internaldate

CLASSES
builtins.object
IMAP4
IMAP4_SSL
IMAP4_stream

class IMAP4(builtins.object)
| IMAP4(host='', port=143)
|
| IMAP4 client class.
|
| Instantiate with: IMAP4([host[, port]])
|
| host - host's name (default: localhost);
| port - port number (default: standard IMAP4 port).
|
| All IMAP4rev1 commands are supported by methods of the same
| name (in lower-case).
|
| All arguments to commands are converted to strings, except for
| AUTHENTICATE, and the last argument to APPEND which is passed as
| an IMAP4 literal. If necessary (the string contains any
| non-printing characters or white-space and isn't enclosed with
| either parentheses or double quotes) each string is quoted.
| However, the 'password' argument to the LOGIN command is always
| quoted. If you want to avoid having an argument string quoted
| (eg: the 'flags' argument to STORE) then enclose the string in
| parentheses (eg: "(\Deleted)").
|
| Each command returns a tuple: (type, [data, ...]) where 'type'
| is usually 'OK' or 'NO', and 'data' is either the text from the
| tagged response, or untagged results from command. Each 'data'
| is either a string, or a tuple. If a tuple, then the first part
| is the header of the response, and the second part contains
| the data (ie: 'literal' value).
|
| Errors raise the exception class <instance>.error("<reason>").
| IMAP4 server errors raise <instance>.abort("<reason>"),
| which is a sub-class of 'error'. Mailbox status changes
| from READ-WRITE to READ-ONLY raise the exception class
| <instance>.readonly("<reason>"), which is a sub-class of 'abort'.
|
| "error" exceptions imply a program error.
| "abort" exceptions imply the connection should be reset, and
| the command re-tried.
| "readonly" exceptions imply the command should be re-tried.
|
| Note: to use this module, you must read the RFCs pertaining to the
| IMAP4 protocol, as the semantics of the arguments to each IMAP4
| command are left to the invoker, not to mention the results. Also,
| most IMAP servers implement a sub-set of the commands available
here.
|
(and a lot more which I'm not going to duplicate -- basically it is the
same text as the on-line documentation without links and coloring...)

However, I would point the OP to the last paragraph shown above: "to
use this module, you must read the RFCs pertaining to the IMAP4
protocol..."

--
Wulfraed Dennis Lee Bieber AF6VN
wlfraed@ix.netcom.com http://wlfraed.microdiversity.freeddns.org/