tobias/docker-offlineimap
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

IMAP.py docstrings

Browse Source 
This patch includes the docstrings for IMAP.py file.
This commit is contained in:
Rodolfo García Peñas (kix) 2020-11-01 12:31:18 +01:00
parent 852bc9acd9
commit 316fcfbbee
1 changed files with 203 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

206
offlineimap/repository/IMAP.py
View File

@ -30,6 +30,9 @@ from offlineimap.utils.distro_utils import get_os_sslcertfile, \
class IMAPRepository(BaseRepository):
"""
IMAP Repository Class, children of BaseRepository
"""
def __init__(self, reposname, account):
self.idlefolders = None
BaseRepository.__init__(self, reposname, account)
@ -93,11 +96,25 @@ class IMAPRepository(BaseRepository):
return self.copy_ignore_eval(foldername)
def getholdconnectionopen(self):
"""
Value of holdconnectionopen or False if it is not set
Returns: Value of holdconnectionopen or False if it is not set
"""
if self.getidlefolders():
return True
return self.getconfboolean("holdconnectionopen", False)
def getkeepalive(self):
"""
This function returns the keepalive value. If it is not set, then
check if the getidlefolders is set. If getidlefolders is set, then
returns 29 * 60
Returns: keepalive value
"""
num = self.getconfint("keepalive", 0)
if num == 0 and self.getidlefolders():
return 29 * 60
@ -156,6 +173,13 @@ class IMAPRepository(BaseRepository):
return identity
def get_auth_mechanisms(self):
"""
Get the AUTH mechanisms. We have (ranged from the strongest to weakest)
these methods: "GSSAPI", "XOAUTH2", "CRAM-MD5", "PLAIN", "LOGIN"
Returns: The supported AUTH Methods
"""
supported = ["GSSAPI", "XOAUTH2", "CRAM-MD5", "PLAIN", "LOGIN"]
# Mechanisms are ranged from the strongest to the
# weakest ones.
@ -176,6 +200,12 @@ class IMAPRepository(BaseRepository):
return mechs
def getuser(self):
"""
Returns the remoteusereval or remoteuser or netrc user value.
Returns: Returns the remoteusereval or remoteuser or netrc user value.
"""
localeval = self.localeval
if self.config.has_option(self.getsection(), 'remoteusereval'):
@ -210,6 +240,12 @@ class IMAPRepository(BaseRepository):
return netrcentry[0]
def getport(self):
"""
Returns remoteporteval value or None if not found.
Returns: Returns remoteporteval int value or None if not found.
"""
port = None
if self.config.has_option(self.getsection(), 'remoteporteval'):
@ -220,16 +256,40 @@ class IMAPRepository(BaseRepository):
return self.getconfint('remoteport', None)
def getipv6(self):
"""
Returns if IPv6 is set. If not set, then return None
Returns: Boolean flag if IPv6 is set.
"""
return self.getconfboolean('ipv6', None)
def getssl(self):
"""
Get the boolean SSL value. Default is True, used if not found.
Returns: Get the boolean SSL value. Default is True
"""
return self.getconfboolean('ssl', True)
def getsslclientcert(self):
"""
Return the SSL client cert (sslclientcert) or None if not found
Returns: SSL client key (sslclientcert) or None if not found
"""
xforms = [os.path.expanduser, os.path.expandvars, os.path.abspath]
return self.getconf_xform('sslclientcert', xforms, None)
def getsslclientkey(self):
"""
Return the SSL client key (sslclientkey) or None if not found
Returns: SSL client key (sslclientkey) or None if not found
"""
xforms = [os.path.expanduser, os.path.expandvars, os.path.abspath]
return self.getconf_xform('sslclientkey', xforms, None)
@ -280,12 +340,30 @@ class IMAPRepository(BaseRepository):
return cacertfile
def gettlslevel(self):
"""
Returns the TLS level (tls_level). If not set, returns 'tls_compat'
Returns: TLS level (tls_level). If not set, returns 'tls_compat'
"""
return self.getconf('tls_level', 'tls_compat')
def getsslversion(self):
"""
Returns the SSL version. If not set, returns None.
Returns: SSL version. If not set, returns None.
"""
return self.getconf('ssl_version', None)
def getstarttls(self):
"""
Get the value of starttls. If not set, returns True
Returns: Value of starttls. If not set, returns True
"""
return self.getconfboolean('starttls', True)
def get_ssl_fingerprint(self):
@ -299,9 +377,25 @@ class IMAPRepository(BaseRepository):
for f in value.split(',') if f]
def setoauth2_request_url(self, url):
"""
Set the OAUTH2 URL request.
Args:
url: OAUTH2 URL request
Returns: None
"""
self.oauth2_request_url = url
def getoauth2_request_url(self):
"""
Returns the OAUTH2 URL request from configuration (oauth2_request_url).
If it is not found, then returns None
Returns: OAUTH2 URL request (oauth2_request_url)
"""
if self.oauth2_request_url is not None: # Use cached value if possible.
return self.oauth2_request_url
@ -309,6 +403,14 @@ class IMAPRepository(BaseRepository):
return self.oauth2_request_url
def getoauth2_refresh_token(self):
"""
Get the OAUTH2 refresh token from the configuration
(oauth2_refresh_token)
If the access token is not found, then returns None.
Returns: OAUTH2 refresh token (oauth2_refresh_token)
"""
refresh_token = self.getconf('oauth2_refresh_token', None)
if refresh_token is None:
refresh_token = self.localeval.eval(
@ -319,6 +421,13 @@ class IMAPRepository(BaseRepository):
return refresh_token
def getoauth2_access_token(self):
"""
Get the OAUTH2 access token from the configuration (oauth2_access_token)
If the access token is not found, then returns None.
Returns: OAUTH2 access token (oauth2_access_token)
"""
access_token = self.getconf('oauth2_access_token', None)
if access_token is None:
access_token = self.localeval.eval(
@ -329,6 +438,13 @@ class IMAPRepository(BaseRepository):
return access_token
def getoauth2_client_id(self):
"""
Get the OAUTH2 client id (oauth2_client_id) from the configuration.
If not found, returns None
Returns: OAUTH2 client id (oauth2_client_id)
"""
client_id = self.getconf('oauth2_client_id', None)
if client_id is None:
client_id = self.localeval.eval(
@ -339,6 +455,13 @@ class IMAPRepository(BaseRepository):
return client_id
def getoauth2_client_secret(self):
"""
Get the OAUTH2 client secret (oauth2_client_secret) from the
configuration. If it is not found, then returns None.
Returns: OAUTH2 client secret
"""
client_secret = self.getconf('oauth2_client_secret', None)
if client_secret is None:
client_secret = self.localeval.eval(
@ -349,18 +472,51 @@ class IMAPRepository(BaseRepository):
return client_secret
def getpreauthtunnel(self):
"""
Get the value of preauthtunnel. If not found, then returns None.
Returns: Returns preauthtunnel value. If not found, returns None.
"""
return self.getconf('preauthtunnel', None)
def gettransporttunnel(self):
"""
Get the value of transporttunnel. If not found, then returns None.
Returns: Returns transporttunnel value. If not found, returns None.
"""
return self.getconf('transporttunnel', None)
def getreference(self):
"""
Get the reference value in the configuration. If the value is not found
then returns a double quote ("") as string.
Returns: The reference variable. If not set, then returns '""'
"""
return self.getconf('reference', '""')
def getdecodefoldernames(self):
"""
Get the boolean value of decodefoldernames configuration variable,
if the value is not found, returns False.
Returns: Boolean value of decodefoldernames, else False
"""
return self.getconfboolean('decodefoldernames', False)
def getidlefolders(self):
"""
Get the list of idlefolders from configuration. If the value is not
found, returns an empty list.
Returns: A list of idle folders
"""
if self.idlefolders is None:
self.idlefolders = self.localeval.eval(
self.getconf('idlefolders', '[]')
@ -368,11 +524,25 @@ class IMAPRepository(BaseRepository):
return self.idlefolders
def getmaxconnections(self):
"""
Get the maxconnections configuration value from configuration.
If the value is not set, returns 1 connection
Returns: Integer value of maxconnections configuration variable, else 1
"""
num1 = len(self.getidlefolders())
num2 = self.getconfint('maxconnections', 1)
return max(num1, num2)
def getexpunge(self):
"""
Get the expunge configuration value from configuration.
If the value is not set in the configuration, then returns True
Returns: Boolean value of expunge configuration variable
"""
return self.getconfboolean('expunge', True)
def getpassword(self):
@ -438,6 +608,13 @@ class IMAPRepository(BaseRepository):
return self.getfoldertype()(self.imapserver, foldername, self, decode)
def getfoldertype(self):
"""
This function returns the folder type, in this case
folder.IMAP.IMAPFolder
Returns: folder.IMAP.IMAPFolder
"""
return folder.IMAP.IMAPFolder
def connect(self):
@ -511,12 +688,16 @@ class IMAPRepository(BaseRepository):
retval.sort(key=lambda x: str.lower(x.getvisiblename()))
else:
# do foldersort in a python3-compatible way
# http://bytes.com/topic/python/answers/844614-python-3-sorting-comparison-function
# http://bytes.com/topic/python/answers/ \
# 844614-python-3-sorting-comparison-function
def cmp2key(mycmp):
"""Converts a cmp= function into a key= function
We need to keep cmp functions for backward compatibility"""
class K:
"""
Class to compare getvisiblename() between two objects.
"""
def __init__(self, obj, *args):
self.obj = obj
@ -547,14 +728,19 @@ class IMAPRepository(BaseRepository):
self.imapserver.releaseconnection(imapobj)
def makefolder(self, foldername):
"""Create a folder on the IMAP server
"""
Create a folder on the IMAP server
This will not update the list cached in :meth:`getfolders`. You
will need to invoke :meth:`forgetfolders` to force new caching
when you are done creating folders yourself.
:param foldername: Full path of the folder to be created."""
Args:
foldername: Full path of the folder to be created
Returns: None
"""
if foldername == '':
return
@ -576,6 +762,15 @@ class IMAPRepository(BaseRepository):
raise
def makefolder_single(self, foldername):
"""
Create a IMAP folder.
Args:
foldername: Folder's name to create
Returns: None
"""
self.ui.makefolder(self, foldername)
if self.account.dryrun:
return
@ -594,5 +789,10 @@ class IMAPRepository(BaseRepository):
class MappedIMAPRepository(IMAPRepository):
"""
This subclass of IMAPRepository includes only the method
getfoldertype modified that returns folder.UIDMaps.MappedIMAPFolder
instead of folder.IMAP.IMAPFolder
"""
def getfoldertype(self):
return folder.UIDMaps.MappedIMAPFolder