From 7f22d89872f1a47654d69fb7658e67b663826893 Mon Sep 17 00:00:00 2001 From: Sebastian Spaeth Date: Mon, 6 Feb 2012 17:40:02 +0100 Subject: [PATCH 01/58] fix type: logging.info --> logging.INFO We mean the (numeric) logging level here and not the info() function. logger.isEnabledFor() takes the logging level as argument, obviously. This was a stupid typo that failed under python3. Signed-off-by: Sebastian Spaeth --- offlineimap/ui/UIBase.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/offlineimap/ui/UIBase.py b/offlineimap/ui/UIBase.py index 7cd8895..06dbd01 100644 --- a/offlineimap/ui/UIBase.py +++ b/offlineimap/ui/UIBase.py @@ -269,7 +269,7 @@ class UIBase(object): def connecting(self, hostname, port): """Log 'Establishing connection to'""" - if not self.logger.isEnabledFor(logging.info): return + if not self.logger.isEnabledFor(logging.INFO): return displaystr = '' hostname = hostname if hostname else '' port = "%s" % port if port else '' From 0844d27f9f417c9ea3be09117566077d8fb08508 Mon Sep 17 00:00:00 2001 From: Sebastian Spaeth Date: Sun, 5 Feb 2012 10:14:23 +0100 Subject: [PATCH 02/58] except Ex, e: --> except Ex as e: Nudge us towards python3 compatability by converting deprecated python2 syntax. Signed-off-by: Sebastian Spaeth --- offlineimap/accounts.py | 10 +++++----- offlineimap/folder/Base.py | 8 ++++---- offlineimap/folder/IMAP.py | 10 +++++----- offlineimap/folder/LocalStatus.py | 2 +- offlineimap/folder/Maildir.py | 4 ++-- offlineimap/imaplibutil.py | 2 +- offlineimap/imapserver.py | 12 ++++++------ offlineimap/init.py | 2 +- offlineimap/repository/Base.py | 4 ++-- offlineimap/repository/IMAP.py | 12 ++++++------ offlineimap/repository/Maildir.py | 4 ++-- offlineimap/threadutil.py | 2 +- 12 files changed, 36 insertions(+), 36 deletions(-) diff --git a/offlineimap/accounts.py b/offlineimap/accounts.py index 81edbe3..780ad04 100644 --- a/offlineimap/accounts.py +++ b/offlineimap/accounts.py @@ -231,7 +231,7 @@ class SyncableAccount(Account): self.sync() except (KeyboardInterrupt, SystemExit): raise - except OfflineImapError, e: + except OfflineImapError as e: # Stop looping and bubble up Exception if needed. if e.severity >= OfflineImapError.ERROR.REPO: if looping: @@ -239,7 +239,7 @@ class SyncableAccount(Account): if e.severity >= OfflineImapError.ERROR.CRITICAL: raise self.ui.error(e, exc_info()[2]) - except Exception, e: + except Exception as e: self.ui.error(e, exc_info()[2], msg = "While attempting to sync" " account '%s'" % self) else: @@ -344,7 +344,7 @@ class SyncableAccount(Account): self.ui.callhook("Hook return code: %d" % p.returncode) except (KeyboardInterrupt, SystemExit): raise - except Exception, e: + except Exception as e: self.ui.error(e, exc_info()[2], msg = "Calling hook") def syncfolder(account, remotefolder, quick): @@ -445,7 +445,7 @@ def syncfolder(account, remotefolder, quick): localrepos.restore_atime() except (KeyboardInterrupt, SystemExit): raise - except OfflineImapError, e: + except OfflineImapError as e: # bubble up severe Errors, skip folder otherwise if e.severity > OfflineImapError.ERROR.FOLDER: raise @@ -459,7 +459,7 @@ def syncfolder(account, remotefolder, quick): # we reconstruct foldername above rather than using # localfolder, as the localfolder var is not # available if assignment fails. - except Exception, e: + except Exception as e: ui.error(e, msg = "ERROR in syncfolder for %s folder %s: %s" % \ (account, remotefolder.getvisiblename(), traceback.format_exc())) diff --git a/offlineimap/folder/Base.py b/offlineimap/folder/Base.py index 5e3d1e5..c9d86c7 100644 --- a/offlineimap/folder/Base.py +++ b/offlineimap/folder/Base.py @@ -321,11 +321,11 @@ class BaseFolder(object): OfflineImapError.ERROR.MESSAGE) except (KeyboardInterrupt): # bubble up CTRL-C raise - except OfflineImapError, e: + except OfflineImapError as e: if e.severity > OfflineImapError.ERROR.MESSAGE: raise # buble severe errors up self.ui.error(e, exc_info()[2]) - except Exception, e: + except Exception as e: self.ui.error(e, "Copying message %s [acc: %s]:\n %s" %\ (uid, self.accountname, exc_info()[2])) @@ -474,11 +474,11 @@ class BaseFolder(object): action(dstfolder, statusfolder) except (KeyboardInterrupt): raise - except OfflineImapError, e: + except OfflineImapError as e: if e.severity > OfflineImapError.ERROR.FOLDER: raise self.ui.error(e, exc_info()[2]) - except Exception, e: + except Exception as e: self.ui.error(e, exc_info()[2], "Syncing folder %s [acc: %s]" %\ (self, self.accountname)) raise # raise unknown Exceptions so we can fix them diff --git a/offlineimap/folder/IMAP.py b/offlineimap/folder/IMAP.py index 3dbcaa8..9cdf752 100644 --- a/offlineimap/folder/IMAP.py +++ b/offlineimap/folder/IMAP.py @@ -97,7 +97,7 @@ class IMAPFolder(BaseFolder): # Select folder and get number of messages restype, imapdata = imapobj.select(self.getfullname(), True, True) - except OfflineImapError, e: + except OfflineImapError as e: # retry on dropped connections, raise otherwise self.imapserver.releaseconnection(imapobj, True) if e.severity == OfflineImapError.ERROR.FOLDER_RETRY: @@ -219,7 +219,7 @@ class IMAPFolder(BaseFolder): res_type, data = imapobj.uid('fetch', str(uid), '(BODY.PEEK[])') fails_left = 0 - except imapobj.abort, e: + except imapobj.abort as e: # Release dropped connection, and get a new one self.imapserver.releaseconnection(imapobj, True) imapobj = self.imapserver.acquireconnection() @@ -314,7 +314,7 @@ class IMAPFolder(BaseFolder): headervalue = imapobj._quote(headervalue) try: matchinguids = imapobj.uid('search', 'HEADER', headername, headervalue)[1][0] - except imapobj.error, err: + except imapobj.error as err: # IMAP server doesn't implement search or had a problem. self.ui.debug('imap', "savemessage_searchforheader: got IMAP error '%s' while attempting to UID SEARCH for message with header %s" % (err, headername)) return 0 @@ -545,7 +545,7 @@ class IMAPFolder(BaseFolder): imaputil.flagsmaildir2imap(flags), date, content) retry_left = 0 # Mark as success - except imapobj.abort, e: + except imapobj.abort as e: # connection has been reset, release connection and retry. retry_left -= 1 self.imapserver.releaseconnection(imapobj, True) @@ -557,7 +557,7 @@ class IMAPFolder(BaseFolder): (self, self.getrepository(), str(e), dbg_output), OfflineImapError.ERROR.MESSAGE) self.ui.error(e, exc_info()[2]) - except imapobj.error, e: # APPEND failed + except imapobj.error as e: # APPEND failed # If the server responds with 'BAD', append() # raise()s directly. So we catch that too. # drop conn, it might be bad. diff --git a/offlineimap/folder/LocalStatus.py b/offlineimap/folder/LocalStatus.py index 3d2cd37..9466d4f 100644 --- a/offlineimap/folder/LocalStatus.py +++ b/offlineimap/folder/LocalStatus.py @@ -79,7 +79,7 @@ class LocalStatusFolder(BaseFolder): uid, flags = line.split(':') uid = long(uid) flags = set(flags) - except ValueError, e: + except ValueError as e: errstr = "Corrupt line '%s' in cache file '%s'" % \ (line, self.filename) self.ui.warn(errstr) diff --git a/offlineimap/folder/Maildir.py b/offlineimap/folder/Maildir.py index fe85308..e778bfd 100644 --- a/offlineimap/folder/Maildir.py +++ b/offlineimap/folder/Maildir.py @@ -257,7 +257,7 @@ class MaildirFolder(BaseFolder): try: fd = os.open(os.path.join(tmpdir, messagename), os.O_EXCL|os.O_CREAT|os.O_WRONLY, 0666) - except OSError, e: + except OSError as e: if e.errno == 17: #FILE EXISTS ALREADY severity = OfflineImapError.ERROR.MESSAGE @@ -313,7 +313,7 @@ class MaildirFolder(BaseFolder): try: os.rename(os.path.join(self.getfullname(), oldfilename), os.path.join(self.getfullname(), newfilename)) - except OSError, e: + except OSError as e: raise OfflineImapError("Can't rename file '%s' to '%s': %s" % ( oldfilename, newfilename, e[1]), OfflineImapError.ERROR.FOLDER) diff --git a/offlineimap/imaplibutil.py b/offlineimap/imaplibutil.py index b4345fa..4732446 100644 --- a/offlineimap/imaplibutil.py +++ b/offlineimap/imaplibutil.py @@ -53,7 +53,7 @@ class UsefulIMAPMixIn(object): del self.untagged_responses[:] try: result = super(UsefulIMAPMixIn, self).select(mailbox, readonly) - except self.abort, e: + except self.abort as e: # self.abort is raised when we are supposed to retry errstr = "Server '%s' closed connection, error on SELECT '%s'. Ser"\ "ver said: %s" % (self.host, mailbox, e.args[0]) diff --git a/offlineimap/imapserver.py b/offlineimap/imapserver.py index a355eaf..609b6fa 100644 --- a/offlineimap/imapserver.py +++ b/offlineimap/imapserver.py @@ -153,7 +153,7 @@ class IMAPServer: rc = kerberos.authGSSClientWrap(self.gss_vc, response, self.username) response = kerberos.authGSSClientResponse(self.gss_vc) - except kerberos.GSSError, err: + except kerberos.GSSError as err: # Kerberos errored out on us, respond with None to cancel the # authentication self.ui.debug('imap', '%s: %s' % (err[0][0], err[1][0])) @@ -232,7 +232,7 @@ class IMAPServer: 'Attempting GSSAPI authentication') try: imapobj.authenticate('GSSAPI', self.gssauth) - except imapobj.error, val: + except imapobj.error as val: self.gssapi = False self.ui.debug('imap', 'GSSAPI Authentication failed') @@ -258,7 +258,7 @@ class IMAPServer: try: imapobj.authenticate('CRAM-MD5', self.md5handler) - except imapobj.error, val: + except imapobj.error as val: self.plainauth(imapobj) else: # Use plaintext login, unless @@ -271,7 +271,7 @@ class IMAPServer: # Would bail by here if there was a failure. success = 1 self.goodpassword = self.password - except imapobj.error, val: + except imapobj.error as val: self.passworderror = str(val) raise @@ -304,7 +304,7 @@ class IMAPServer: self.lastowner[imapobj] = get_ident() self.connectionlock.release() return imapobj - except Exception, e: + except Exception as e: """If we are here then we did not succeed in getting a connection - we should clean up and then re-raise the error...""" @@ -540,7 +540,7 @@ class IdleThread(object): imapobj = self.parent.acquireconnection() try: imapobj.select(self.folder) - except OfflineImapError, e: + except OfflineImapError as e: if e.severity == OfflineImapError.ERROR.FOLDER_RETRY: # Connection closed, release connection and retry self.ui.error(e, exc_info()[2]) diff --git a/offlineimap/init.py b/offlineimap/init.py index 5cd1894..51d535d 100644 --- a/offlineimap/init.py +++ b/offlineimap/init.py @@ -351,7 +351,7 @@ class OfflineImap: self.ui.terminate() except (SystemExit): raise - except Exception, e: + except Exception as e: self.ui.error(e) self.ui.terminate() diff --git a/offlineimap/repository/Base.py b/offlineimap/repository/Base.py index 084841f..bc2c15a 100644 --- a/offlineimap/repository/Base.py +++ b/offlineimap/repository/Base.py @@ -165,7 +165,7 @@ class BaseRepository(object, CustomConfig.ConfigHelperMixin): try: dst_repo.makefolder(src_name) dst_haschanged = True # Need to refresh list - except OfflineImapError, e: + except OfflineImapError as e: self.ui.error(e, exc_info()[2], "Creating folder %s on repository %s" %\ (src_name, dst_repo)) @@ -212,7 +212,7 @@ class BaseRepository(object, CustomConfig.ConfigHelperMixin): try: src_repo.makefolder(newsrc_name) src_haschanged = True # Need to refresh list - except OfflineImapError, e: + except OfflineImapError as e: self.ui.error(e, exc_info()[2], "Creating folder %s on " "repository %s" % (newsrc_name, src_repo)) raise diff --git a/offlineimap/repository/IMAP.py b/offlineimap/repository/IMAP.py index c2633dc..d4b6599 100644 --- a/offlineimap/repository/IMAP.py +++ b/offlineimap/repository/IMAP.py @@ -95,7 +95,7 @@ class IMAPRepository(BaseRepository): host = self.getconf('remotehosteval') try: host = self.localeval.eval(host) - except Exception, e: + except Exception as e: raise OfflineImapError("remotehosteval option for repository "\ "'%s' failed:\n%s" % (self, e), OfflineImapError.ERROR.REPO) @@ -128,7 +128,7 @@ class IMAPRepository(BaseRepository): try: netrcentry = netrc.netrc().authenticators(self.gethost()) - except IOError, inst: + except IOError as inst: if inst.errno != errno.ENOENT: raise else: @@ -137,7 +137,7 @@ class IMAPRepository(BaseRepository): try: netrcentry = netrc.netrc('/etc/netrc').authenticators(self.gethost()) - except IOError, inst: + except IOError as inst: if inst.errno not in (errno.ENOENT, errno.EACCES): raise else: @@ -223,7 +223,7 @@ class IMAPRepository(BaseRepository): # 4. read password from ~/.netrc try: netrcentry = netrc.netrc().authenticators(self.gethost()) - except IOError, inst: + except IOError as inst: if inst.errno != errno.ENOENT: raise else: @@ -234,7 +234,7 @@ class IMAPRepository(BaseRepository): # 5. read password from /etc/netrc try: netrcentry = netrc.netrc('/etc/netrc').authenticators(self.gethost()) - except IOError, inst: + except IOError as inst: if inst.errno not in (errno.ENOENT, errno.EACCES): raise else: @@ -297,7 +297,7 @@ class IMAPRepository(BaseRepository): for foldername in self.folderincludes: try: imapobj.select(foldername, readonly = True) - except OfflineImapError, e: + except OfflineImapError as e: # couldn't select this folderinclude, so ignore folder. if e.severity > OfflineImapError.ERROR.FOLDER: raise diff --git a/offlineimap/repository/Maildir.py b/offlineimap/repository/Maildir.py index 66a3ebd..139ddb4 100644 --- a/offlineimap/repository/Maildir.py +++ b/offlineimap/repository/Maildir.py @@ -98,7 +98,7 @@ class MaildirRepository(BaseRepository): self.debug("makefolder: calling makedirs '%s'" % full_path) try: os.makedirs(full_path, 0700) - except OSError, e: + except OSError as e: if e.errno == 17 and os.path.isdir(full_path): self.debug("makefolder: '%s' already a directory" % foldername) else: @@ -106,7 +106,7 @@ class MaildirRepository(BaseRepository): for subdir in ['cur', 'new', 'tmp']: try: os.mkdir(os.path.join(full_path, subdir), 0700) - except OSError, e: + except OSError as e: if e.errno == 17 and os.path.isdir(full_path): self.debug("makefolder: '%s' already has subdir %s" % (foldername, subdir)) diff --git a/offlineimap/threadutil.py b/offlineimap/threadutil.py index c102446..7499ec4 100644 --- a/offlineimap/threadutil.py +++ b/offlineimap/threadutil.py @@ -165,7 +165,7 @@ class ExitNotifyThread(Thread): pass prof.dump_stats(os.path.join(ExitNotifyThread.profiledir, "%s_%s.prof" % (self.threadid, self.getName()))) - except Exception, e: + except Exception as e: # Thread exited with Exception, store it tb = traceback.format_exc() self.set_exit_exception(e, tb) From 55da31c84bbf4e0d4b9ec474fbdd71b338d70969 Mon Sep 17 00:00:00 2001 From: Sebastian Spaeth Date: Sun, 5 Feb 2012 11:31:54 +0100 Subject: [PATCH 03/58] octal notation 0700 -> 0o700 Use octal notation that python3 understands. Works >=python2.6 Signed-off-by: Sebastian Spaeth --- offlineimap/CustomConfig.py | 2 +- offlineimap/accounts.py | 2 +- offlineimap/folder/Maildir.py | 2 +- offlineimap/repository/Base.py | 6 +++--- offlineimap/repository/LocalStatus.py | 2 +- offlineimap/repository/Maildir.py | 6 +++--- 6 files changed, 10 insertions(+), 10 deletions(-) diff --git a/offlineimap/CustomConfig.py b/offlineimap/CustomConfig.py index dae20b6..e00b59d 100644 --- a/offlineimap/CustomConfig.py +++ b/offlineimap/CustomConfig.py @@ -49,7 +49,7 @@ class CustomConfigParser(SafeConfigParser): def getmetadatadir(self): metadatadir = os.path.expanduser(self.getdefault("general", "metadata", "~/.offlineimap")) if not os.path.exists(metadatadir): - os.mkdir(metadatadir, 0700) + os.mkdir(metadatadir, 0o700) return metadatadir def getlocaleval(self): diff --git a/offlineimap/accounts.py b/offlineimap/accounts.py index 780ad04..429dc19 100644 --- a/offlineimap/accounts.py +++ b/offlineimap/accounts.py @@ -216,7 +216,7 @@ class SyncableAccount(Account): self.ui.registerthread(self) accountmetadata = self.getaccountmeta() if not os.path.exists(accountmetadata): - os.mkdir(accountmetadata, 0700) + os.mkdir(accountmetadata, 0o700) self.remoterepos = Repository(self, 'remote') self.localrepos = Repository(self, 'local') diff --git a/offlineimap/folder/Maildir.py b/offlineimap/folder/Maildir.py index e778bfd..11541e4 100644 --- a/offlineimap/folder/Maildir.py +++ b/offlineimap/folder/Maildir.py @@ -256,7 +256,7 @@ class MaildirFolder(BaseFolder): # open file and write it out try: fd = os.open(os.path.join(tmpdir, messagename), - os.O_EXCL|os.O_CREAT|os.O_WRONLY, 0666) + os.O_EXCL|os.O_CREAT|os.O_WRONLY, 0o666) except OSError as e: if e.errno == 17: #FILE EXISTS ALREADY diff --git a/offlineimap/repository/Base.py b/offlineimap/repository/Base.py index bc2c15a..a096a15 100644 --- a/offlineimap/repository/Base.py +++ b/offlineimap/repository/Base.py @@ -35,13 +35,13 @@ class BaseRepository(object, CustomConfig.ConfigHelperMixin): self._accountname = self.account.getname() self.uiddir = os.path.join(self.config.getmetadatadir(), 'Repository-' + self.name) if not os.path.exists(self.uiddir): - os.mkdir(self.uiddir, 0700) + os.mkdir(self.uiddir, 0o700) self.mapdir = os.path.join(self.uiddir, 'UIDMapping') if not os.path.exists(self.mapdir): - os.mkdir(self.mapdir, 0700) + os.mkdir(self.mapdir, 0o700) self.uiddir = os.path.join(self.uiddir, 'FolderValidity') if not os.path.exists(self.uiddir): - os.mkdir(self.uiddir, 0700) + os.mkdir(self.uiddir, 0o700) self.nametrans = lambda foldername: foldername self.folderfilter = lambda foldername: 1 diff --git a/offlineimap/repository/LocalStatus.py b/offlineimap/repository/LocalStatus.py index fdd1e19..b1e9fd0 100644 --- a/offlineimap/repository/LocalStatus.py +++ b/offlineimap/repository/LocalStatus.py @@ -41,7 +41,7 @@ class LocalStatusRepository(BaseRepository): % (backend, account.name)) if not os.path.exists(self.root): - os.mkdir(self.root, 0700) + os.mkdir(self.root, 0o700) # self._folders is a list of LocalStatusFolders() self._folders = None diff --git a/offlineimap/repository/Maildir.py b/offlineimap/repository/Maildir.py index 139ddb4..67f659b 100644 --- a/offlineimap/repository/Maildir.py +++ b/offlineimap/repository/Maildir.py @@ -37,7 +37,7 @@ class MaildirRepository(BaseRepository): # Create the top-level folder if it doesn't exist if not os.path.isdir(self.root): - os.mkdir(self.root, 0700) + os.mkdir(self.root, 0o700) def _append_folder_atimes(self, foldername): """Store the atimes of a folder's new|cur in self.folder_atimes""" @@ -97,7 +97,7 @@ class MaildirRepository(BaseRepository): # sub-folders may be created before higher-up ones. self.debug("makefolder: calling makedirs '%s'" % full_path) try: - os.makedirs(full_path, 0700) + os.makedirs(full_path, 0o700) except OSError as e: if e.errno == 17 and os.path.isdir(full_path): self.debug("makefolder: '%s' already a directory" % foldername) @@ -105,7 +105,7 @@ class MaildirRepository(BaseRepository): raise for subdir in ['cur', 'new', 'tmp']: try: - os.mkdir(os.path.join(full_path, subdir), 0700) + os.mkdir(os.path.join(full_path, subdir), 0o700) except OSError as e: if e.errno == 17 and os.path.isdir(full_path): self.debug("makefolder: '%s' already has subdir %s" % From a8ab269ada0c9376e2eb3fe03662c86e60ec96fb Mon Sep 17 00:00:00 2001 From: Sebastian Spaeth Date: Sun, 5 Feb 2012 11:38:07 +0100 Subject: [PATCH 04/58] Import configparser for python3 compatability Attempt to load first ConfigParser and then configparser. At some point this should be switched to do the python3 thing first. Signed-off-by: Sebastian Spaeth --- offlineimap/CustomConfig.py | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/offlineimap/CustomConfig.py b/offlineimap/CustomConfig.py index e00b59d..b5869e7 100644 --- a/offlineimap/CustomConfig.py +++ b/offlineimap/CustomConfig.py @@ -1,5 +1,4 @@ -# Copyright (C) 2003 John Goerzen -# +# Copyright (C) 2003-2012 John Goerzen & contributors # # This program is free software; you can redistribute it and/or modify # it under the terms of the GNU General Public License as published by @@ -15,7 +14,10 @@ # along with this program; if not, write to the Free Software # Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA -from ConfigParser import SafeConfigParser +try: + from ConfigParser import SafeConfigParser +except ImportError: #python3 + from configparser import SafeConfigParser from offlineimap.localeval import LocalEval import os From 9df7f34d4c7dab72de991416fff5d678e02abdab Mon Sep 17 00:00:00 2001 From: Sebastian Spaeth Date: Sun, 5 Feb 2012 11:49:28 +0100 Subject: [PATCH 05/58] Remove unused locked() function We do not use ui.locked() anymore to output an error message, the text comes directly from the exception. Signed-off-by: Sebastian Spaeth --- offlineimap/accounts.py | 3 ++- offlineimap/ui/UIBase.py | 3 --- 2 files changed, 2 insertions(+), 4 deletions(-) diff --git a/offlineimap/accounts.py b/offlineimap/accounts.py index 429dc19..ed08cad 100644 --- a/offlineimap/accounts.py +++ b/offlineimap/accounts.py @@ -199,7 +199,8 @@ class SyncableAccount(Account): pass except IOError: self._lockfd.close() - raise OfflineImapError("Could not lock account %s." % self, + raise OfflineImapError("Could not lock account %s. Is another " + "instance using this account?" % self, OfflineImapError.ERROR.REPO) def unlock(self): diff --git a/offlineimap/ui/UIBase.py b/offlineimap/ui/UIBase.py index 06dbd01..74ef22e 100644 --- a/offlineimap/ui/UIBase.py +++ b/offlineimap/ui/UIBase.py @@ -203,9 +203,6 @@ class UIBase(object): def invaliddebug(self, debugtype): self.warn("Invalid debug type: %s" % debugtype) - def locked(s): - raise Exception, "Another OfflineIMAP is running with the same metadatadir; exiting." - def getnicename(self, object): """Return the type of a repository or Folder as string From c5468ae599e9f008bedb06250537a89a11b960e9 Mon Sep 17 00:00:00 2001 From: Sebastian Spaeth Date: Sun, 5 Feb 2012 11:51:02 +0100 Subject: [PATCH 06/58] raise Exception, "text" --> raise Exception("text") To have the code work in python3, we need to convert all occurences of raise Exception, "text" to be proper functions. This style also adheres to PEP8. Signed-off-by: Sebastian Spaeth --- offlineimap/folder/IMAP.py | 4 +++- offlineimap/imaputil.py | 2 +- offlineimap/repository/__init__.py | 6 +++--- 3 files changed, 7 insertions(+), 5 deletions(-) diff --git a/offlineimap/folder/IMAP.py b/offlineimap/folder/IMAP.py index 9cdf752..17364d3 100644 --- a/offlineimap/folder/IMAP.py +++ b/offlineimap/folder/IMAP.py @@ -328,7 +328,9 @@ class IMAPFolder(BaseFolder): self.ui.debug('imap', 'savemessage_searchforheader: matchinguids now ' + \ repr(matchinguids)) if len(matchinguids) != 1 or matchinguids[0] == None: - raise ValueError, "While attempting to find UID for message with header %s, got wrong-sized matchinguids of %s" % (headername, str(matchinguids)) + raise ValueError("While attempting to find UID for message with " + "header %s, got wrong-sized matchinguids of %s" %\ + (headername, str(matchinguids))) matchinguids.sort() return long(matchinguids[0]) diff --git a/offlineimap/imaputil.py b/offlineimap/imaputil.py index 3955683..f9b021c 100644 --- a/offlineimap/imaputil.py +++ b/offlineimap/imaputil.py @@ -58,7 +58,7 @@ def flagsplit(string): ['FLAGS,'(\\Seen Old)','UID', '4807'] """ if string[0] != '(' or string[-1] != ')': - raise ValueError, "Passed string '%s' is not a flag list" % string + raise ValueError("Passed string '%s' is not a flag list" % string) return imapsplit(string[1:-1]) def options2hash(list): diff --git a/offlineimap/repository/__init__.py b/offlineimap/repository/__init__.py index c63f6db..0059bdf 100644 --- a/offlineimap/repository/__init__.py +++ b/offlineimap/repository/__init__.py @@ -47,15 +47,15 @@ class Repository(object): return LocalStatusRepository(name, account) else: - raise ValueError, "Request type %s not supported" % reqtype + raise ValueError("Request type %s not supported" % reqtype) config = account.getconfig() repostype = config.get('Repository ' + name, 'type').strip() try: repo = typemap[repostype] except KeyError: - raise Exception, "'%s' repository not supported for %s repositories."%\ - (repostype, reqtype) + raise ValueError("'%s' repository not supported for %s repositories" + "." % (repostype, reqtype)) return repo(name, account) From 06a78b611275df9d7613d63dbd6547510bafba67 Mon Sep 17 00:00:00 2001 From: Sebastian Spaeth Date: Sun, 5 Feb 2012 11:55:26 +0100 Subject: [PATCH 07/58] python3: Queue -> queue import queue (python3) if Queue is not available (python2) Signed-off-by: Sebastian Spaeth --- offlineimap/threadutil.py | 7 +++++-- offlineimap/ui/UIBase.py | 5 ++++- 2 files changed, 9 insertions(+), 3 deletions(-) diff --git a/offlineimap/threadutil.py b/offlineimap/threadutil.py index 7499ec4..92c54e2 100644 --- a/offlineimap/threadutil.py +++ b/offlineimap/threadutil.py @@ -1,4 +1,4 @@ -# Copyright (C) 2002-2011 John Goerzen & contributors +# Copyright (C) 2002-2012 John Goerzen & contributors # Thread support module # # This program is free software; you can redistribute it and/or modify @@ -16,7 +16,10 @@ # Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA from threading import Lock, Thread, BoundedSemaphore -from Queue import Queue, Empty +try: + from Queue import Queue, Empty +except ImportError: # python3 + from queue import Queue, Empty import traceback from thread import get_ident # python < 2.6 support import os.path diff --git a/offlineimap/ui/UIBase.py b/offlineimap/ui/UIBase.py index 74ef22e..bf46e6f 100644 --- a/offlineimap/ui/UIBase.py +++ b/offlineimap/ui/UIBase.py @@ -22,7 +22,10 @@ import sys import os import traceback import threading -from Queue import Queue +try: + from Queue import Queue +except ImportError: #python3 + from queue import Queue from collections import deque from offlineimap.error import OfflineImapError import offlineimap From 74fc90296702ad71b47727f1f761814adf21e8f4 Mon Sep 17 00:00:00 2001 From: Sebastian Spaeth Date: Sun, 5 Feb 2012 11:57:19 +0100 Subject: [PATCH 08/58] python3: import absolute package name This import failed in python3, we need to either specify "." (relative) or from OfflineImap.ui. (absolute). Done the latter. Signed-off-by: Sebastian Spaeth --- offlineimap/repository/LocalStatus.py | 2 +- offlineimap/repository/Maildir.py | 2 +- offlineimap/ui/Machine.py | 2 +- offlineimap/ui/Noninteractive.py | 4 ++-- 4 files changed, 5 insertions(+), 5 deletions(-) diff --git a/offlineimap/repository/LocalStatus.py b/offlineimap/repository/LocalStatus.py index b1e9fd0..30c8560 100644 --- a/offlineimap/repository/LocalStatus.py +++ b/offlineimap/repository/LocalStatus.py @@ -16,9 +16,9 @@ # along with this program; if not, write to the Free Software # Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA -from Base import BaseRepository from offlineimap.folder.LocalStatus import LocalStatusFolder, magicline from offlineimap.folder.LocalStatusSQLite import LocalStatusSQLiteFolder +from offlineimap.repository.Base import BaseRepository import os import re diff --git a/offlineimap/repository/Maildir.py b/offlineimap/repository/Maildir.py index 67f659b..7c08d64 100644 --- a/offlineimap/repository/Maildir.py +++ b/offlineimap/repository/Maildir.py @@ -16,10 +16,10 @@ # along with this program; if not, write to the Free Software # Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA -from Base import BaseRepository from offlineimap import folder from offlineimap.ui import getglobalui from offlineimap.error import OfflineImapError +from offlineimap.repository.Base import BaseRepository import os from stat import * diff --git a/offlineimap/ui/Machine.py b/offlineimap/ui/Machine.py index a87395d..8bf77da 100644 --- a/offlineimap/ui/Machine.py +++ b/offlineimap/ui/Machine.py @@ -17,8 +17,8 @@ from urllib import urlencode import sys import time import logging -from UIBase import UIBase from threading import currentThread +from offlineimap.ui.UIBase import UIBase import offlineimap protocol = '7.0.0' diff --git a/offlineimap/ui/Noninteractive.py b/offlineimap/ui/Noninteractive.py index 36bb92b..de1e8df 100644 --- a/offlineimap/ui/Noninteractive.py +++ b/offlineimap/ui/Noninteractive.py @@ -1,5 +1,5 @@ # Noninteractive UI -# Copyright (C) 2002-2011 John Goerzen & contributors +# Copyright (C) 2002-2012 John Goerzen & contributors # # This program is free software; you can redistribute it and/or modify # it under the terms of the GNU General Public License as published by @@ -16,7 +16,7 @@ # Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA import logging -from UIBase import UIBase +from offlineimap.ui.UIBase import UIBase class Basic(UIBase): """'Quiet' simply sets log level to INFO""" From 8b6af63d830b826b4e21c42d0c272ce69bf0a3d4 Mon Sep 17 00:00:00 2001 From: Sebastian Spaeth Date: Sun, 5 Feb 2012 12:00:28 +0100 Subject: [PATCH 09/58] [MachineUI] Remove unneeded "print 't'" statement 1) it's print('t') now and 2) this was a superfluous statement. This broke python3 Signed-off-by: Sebastian Spaeth --- offlineimap/ui/Machine.py | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/offlineimap/ui/Machine.py b/offlineimap/ui/Machine.py index 8bf77da..c7f1557 100644 --- a/offlineimap/ui/Machine.py +++ b/offlineimap/ui/Machine.py @@ -122,12 +122,11 @@ class MachineUI(UIBase): "\f".join(flags), dest)) - def threadException(s, thread): - print s.getThreadExceptionString(thread) - s._printData('threadException', "%s\n%s" % \ - (thread.getName(), s.getThreadExceptionString(thread))) - s.delThreadDebugLog(thread) - s.terminate(100) + def threadException(self, thread): + self._printData('threadException', "%s\n%s" % \ + (thread.getName(), self.getThreadExceptionString(thread))) + self.delThreadDebugLog(thread) + self.terminate(100) def terminate(s, exitstatus = 0, errortitle = '', errormsg = ''): s._printData('terminate', "%d\n%s\n%s" % (exitstatus, errortitle, errormsg)) From 93f4a19778b1a6c1977cc784a5b2706dfd32e1f4 Mon Sep 17 00:00:00 2001 From: Sebastian Spaeth Date: Sun, 5 Feb 2012 12:06:18 +0100 Subject: [PATCH 10/58] python3: urlencode is in a different module import urlencode from urllib.parse if neeeded for python3. Signed-off-by: Sebastian Spaeth --- offlineimap/ui/Machine.py | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/offlineimap/ui/Machine.py b/offlineimap/ui/Machine.py index c7f1557..069bb35 100644 --- a/offlineimap/ui/Machine.py +++ b/offlineimap/ui/Machine.py @@ -13,7 +13,10 @@ # You should have received a copy of the GNU General Public License # along with this program; if not, write to the Free Software # Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA -from urllib import urlencode +try: + from urllib import urlencode +except ImportError: # python3 + from urllib.parse import urlencode import sys import time import logging From 81fc20c7cadbc4dea221208479e29522610501f7 Mon Sep 17 00:00:00 2001 From: Sebastian Spaeth Date: Sun, 5 Feb 2012 12:17:02 +0100 Subject: [PATCH 11/58] Remove python<2.6 import workarounds (set & ssl) 'set' is builtin since python2.6, so remove the imports. Also 'ssl' exists since 2.6 and has everything we need, so no need for conditional import tests here anymore. Signed-off-by: Sebastian Spaeth --- offlineimap/folder/Base.py | 5 +---- offlineimap/folder/IMAP.py | 4 ---- offlineimap/folder/LocalStatus.py | 5 +---- offlineimap/folder/LocalStatusSQLite.py | 4 ---- offlineimap/imaplibutil.py | 6 +----- offlineimap/imapserver.py | 8 ++------ offlineimap/imaputil.py | 5 +---- 7 files changed, 6 insertions(+), 31 deletions(-) diff --git a/offlineimap/folder/Base.py b/offlineimap/folder/Base.py index c9d86c7..1c05370 100644 --- a/offlineimap/folder/Base.py +++ b/offlineimap/folder/Base.py @@ -23,10 +23,7 @@ import os.path import re from sys import exc_info import traceback -try: # python 2.6 has set() built in - set -except NameError: - from sets import Set as set + class BaseFolder(object): def __init__(self, name, repository): diff --git a/offlineimap/folder/IMAP.py b/offlineimap/folder/IMAP.py index 17364d3..9d53e89 100644 --- a/offlineimap/folder/IMAP.py +++ b/offlineimap/folder/IMAP.py @@ -24,10 +24,6 @@ from sys import exc_info from Base import BaseFolder from offlineimap import imaputil, imaplibutil, OfflineImapError from offlineimap.imaplib2 import MonthNames -try: # python 2.6 has set() built in - set -except NameError: - from sets import Set as set class IMAPFolder(BaseFolder): diff --git a/offlineimap/folder/LocalStatus.py b/offlineimap/folder/LocalStatus.py index 9466d4f..e637d94 100644 --- a/offlineimap/folder/LocalStatus.py +++ b/offlineimap/folder/LocalStatus.py @@ -18,13 +18,10 @@ from Base import BaseFolder import os import threading -try: # python 2.6 has set() built in - set -except NameError: - from sets import Set as set magicline = "OFFLINEIMAP LocalStatus CACHE DATA - DO NOT MODIFY - FORMAT 1" + class LocalStatusFolder(BaseFolder): def __init__(self, name, repository): self.sep = '.' #needs to be set before super.__init__() diff --git a/offlineimap/folder/LocalStatusSQLite.py b/offlineimap/folder/LocalStatusSQLite.py index 6bfa667..f59d4b2 100644 --- a/offlineimap/folder/LocalStatusSQLite.py +++ b/offlineimap/folder/LocalStatusSQLite.py @@ -23,10 +23,6 @@ try: except: pass #fail only if needed later on, not on import -try: # python 2.6 has set() built in - set -except NameError: - from sets import Set as set class LocalStatusSQLiteFolder(LocalStatusFolder): """LocalStatus backend implemented with an SQLite database diff --git a/offlineimap/imaplibutil.py b/offlineimap/imaplibutil.py index 4732446..2d5fc39 100644 --- a/offlineimap/imaplibutil.py +++ b/offlineimap/imaplibutil.py @@ -19,6 +19,7 @@ import os import fcntl import re import socket +import ssl import time import subprocess import threading @@ -28,11 +29,6 @@ from offlineimap.ui import getglobalui from offlineimap import OfflineImapError from offlineimap.imaplib2 import IMAP4, IMAP4_SSL, zlib, IMAP4_PORT, InternalDate, Mon2num -try: - import ssl -except ImportError: - #fails on python <2.6 - pass class UsefulIMAPMixIn(object): def getselectedfolder(self): diff --git a/offlineimap/imapserver.py b/offlineimap/imapserver.py index 609b6fa..16d0cac 100644 --- a/offlineimap/imapserver.py +++ b/offlineimap/imapserver.py @@ -27,11 +27,7 @@ import time import errno from sys import exc_info from socket import gaierror -try: - from ssl import SSLError, cert_time_to_seconds -except ImportError: - # Protect against python<2.6, use dummy and won't get SSL errors. - SSLError = None +from ssl import SSLError, cert_time_to_seconds try: # do we have a recent pykerberos? @@ -323,7 +319,7 @@ class IMAPServer: (self.hostname, self.repos) raise OfflineImapError(reason, severity) - elif SSLError and isinstance(e, SSLError) and e.errno == 1: + elif isinstance(e, SSLError) and e.errno == 1: # SSL unknown protocol error # happens e.g. when connecting via SSL to a non-SSL service if self.port != 993: diff --git a/offlineimap/imaputil.py b/offlineimap/imaputil.py index f9b021c..f1be3c7 100644 --- a/offlineimap/imaputil.py +++ b/offlineimap/imaputil.py @@ -20,10 +20,7 @@ import re import string import types from offlineimap.ui import getglobalui -try: # python 2.6 has set() built in - set -except NameError: - from sets import Set as set + # find the first quote in a string quotere = re.compile( From dc67f515b61834a9ac4afe56f9c04d806e3a1787 Mon Sep 17 00:00:00 2001 From: Sebastian Spaeth Date: Sun, 5 Feb 2012 12:20:28 +0100 Subject: [PATCH 12/58] no need for type(s) == types.StringType All we want to do here is to test whether we got a string'ish type or a list (literal), so testing for basestring will be fine. Signed-off-by: Sebastian Spaeth --- offlineimap/imaputil.py | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/offlineimap/imaputil.py b/offlineimap/imaputil.py index f1be3c7..ba1f458 100644 --- a/offlineimap/imaputil.py +++ b/offlineimap/imaputil.py @@ -18,7 +18,6 @@ import re import string -import types from offlineimap.ui import getglobalui @@ -88,7 +87,7 @@ def imapsplit(imapstring): ['(\\HasNoChildren)', '"."', '"INBOX.Sent"']""" - if type(imapstring) != types.StringType: + if not isinstance(imapstring, basestring): debug("imapsplit() got a non-string input; working around.") # Sometimes, imaplib will throw us a tuple if the input # contains a literal. See Python bug From ba3a698a6741ebfc05052b2add720f8000cd0949 Mon Sep 17 00:00:00 2001 From: Sebastian Spaeth Date: Sun, 5 Feb 2012 12:23:49 +0100 Subject: [PATCH 13/58] No need to test for types.StringType all we want to know is if we got some string'ish type and testing for isinstance 'basestring' is sufficient for that. Remove the import. Signed-off-by: Sebastian Spaeth --- offlineimap/repository/IMAP.py | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/offlineimap/repository/IMAP.py b/offlineimap/repository/IMAP.py index d4b6599..f008592 100644 --- a/offlineimap/repository/IMAP.py +++ b/offlineimap/repository/IMAP.py @@ -20,7 +20,6 @@ from offlineimap import folder, imaputil, imapserver, OfflineImapError from offlineimap.folder.UIDMaps import MappedIMAPFolder from offlineimap.threadutil import ExitNotifyThread from threading import Event -import types import os from sys import exc_info import netrc @@ -274,9 +273,9 @@ class IMAPRepository(BaseRepository): self.imapserver.releaseconnection(imapobj) for string in listresult: if string == None or \ - (type(string) == types.StringType and string == ''): + (isinstance(string, basestring) and string == ''): # Bug in imaplib: empty strings in results from - # literals. + # literals. TODO: still relevant? continue flags, delim, name = imaputil.imapsplit(string) flaglist = [x.lower() for x in imaputil.flagsplit(flags)] From 03566b203723655daff1e3cd6d6ba378e5f41eae Mon Sep 17 00:00:00 2001 From: Sebastian Spaeth Date: Sun, 5 Feb 2012 12:34:27 +0100 Subject: [PATCH 14/58] Replace thread.get_ident() Replace low-level thread.get_ident() with threading.currentThread().ident. This works both in python2.6 and python3. (thread is renamed _thread and its direct use is not recommended) Signed-off-by: Sebastian Spaeth --- offlineimap/imapserver.py | 8 ++++---- offlineimap/threadutil.py | 6 ++---- offlineimap/ui/Curses.py | 1 - 3 files changed, 6 insertions(+), 9 deletions(-) diff --git a/offlineimap/imapserver.py b/offlineimap/imapserver.py index 16d0cac..22c5c16 100644 --- a/offlineimap/imapserver.py +++ b/offlineimap/imapserver.py @@ -18,7 +18,6 @@ from offlineimap import imaplibutil, imaputil, threadutil, OfflineImapError from offlineimap.ui import getglobalui from threading import Lock, BoundedSemaphore, Thread, Event, currentThread -from thread import get_ident # python < 2.6 support import offlineimap.accounts import hmac import socket @@ -167,6 +166,7 @@ class IMAPServer: self.semaphore.acquire() self.connectionlock.acquire() + curThread = currentThread() imapobj = None if len(self.availableconnections): # One is available. @@ -176,7 +176,7 @@ class IMAPServer: imapobj = None for i in range(len(self.availableconnections) - 1, -1, -1): tryobj = self.availableconnections[i] - if self.lastowner[tryobj] == get_ident(): + if self.lastowner[tryobj] == curThread.ident: imapobj = tryobj del(self.availableconnections[i]) break @@ -184,7 +184,7 @@ class IMAPServer: imapobj = self.availableconnections[0] del(self.availableconnections[0]) self.assignedconnections.append(imapobj) - self.lastowner[imapobj] = get_ident() + self.lastowner[imapobj] = curThread.ident self.connectionlock.release() return imapobj @@ -297,7 +297,7 @@ class IMAPServer: self.connectionlock.acquire() self.assignedconnections.append(imapobj) - self.lastowner[imapobj] = get_ident() + self.lastowner[imapobj] = curThread.ident self.connectionlock.release() return imapobj except Exception as e: diff --git a/offlineimap/threadutil.py b/offlineimap/threadutil.py index 92c54e2..054fa11 100644 --- a/offlineimap/threadutil.py +++ b/offlineimap/threadutil.py @@ -15,13 +15,12 @@ # along with this program; if not, write to the Free Software # Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA -from threading import Lock, Thread, BoundedSemaphore +from threading import Lock, Thread, BoundedSemaphore, currentThread try: from Queue import Queue, Empty except ImportError: # python3 from queue import Queue, Empty import traceback -from thread import get_ident # python < 2.6 support import os.path import sys from offlineimap.ui import getglobalui @@ -152,7 +151,6 @@ class ExitNotifyThread(Thread): def run(self): global exitthreads - self.threadid = get_ident() try: if not ExitNotifyThread.profiledir: # normal case Thread.run(self) @@ -167,7 +165,7 @@ class ExitNotifyThread(Thread): except SystemExit: pass prof.dump_stats(os.path.join(ExitNotifyThread.profiledir, - "%s_%s.prof" % (self.threadid, self.getName()))) + "%s_%s.prof" % (self.ident, self.getName()))) except Exception as e: # Thread exited with Exception, store it tb = traceback.format_exc() diff --git a/offlineimap/ui/Curses.py b/offlineimap/ui/Curses.py index af41d35..365be60 100644 --- a/offlineimap/ui/Curses.py +++ b/offlineimap/ui/Curses.py @@ -16,7 +16,6 @@ # Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA from threading import RLock, currentThread, Lock, Event -from thread import get_ident # python < 2.6 support from collections import deque import time import sys From 014caddee60243d02904926c8d56d49151239f18 Mon Sep 17 00:00:00 2001 From: Sebastian Spaeth Date: Sun, 5 Feb 2012 12:49:08 +0100 Subject: [PATCH 15/58] folder/Base: Create unambigous MRO inheritence class BaseRepository(object, CustomConfig.ConfigHelperMixin): led to TypeError: Cannot create a consistent method resolution order (MRO) for bases ConfigHelperMixin, object. Switching the inherited classes helps. Signed-off-by: Sebastian Spaeth --- offlineimap/repository/Base.py | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/offlineimap/repository/Base.py b/offlineimap/repository/Base.py index a096a15..cbbc5f4 100644 --- a/offlineimap/repository/Base.py +++ b/offlineimap/repository/Base.py @@ -1,6 +1,5 @@ # Base repository support -# Copyright (C) 2002-2007 John Goerzen -# +# Copyright (C) 2002-2012 John Goerzen & contributors # # This program is free software; you can redistribute it and/or modify # it under the terms of the GNU General Public License as published by @@ -24,7 +23,7 @@ from offlineimap import CustomConfig from offlineimap.ui import getglobalui from offlineimap.error import OfflineImapError -class BaseRepository(object, CustomConfig.ConfigHelperMixin): +class BaseRepository(CustomConfig.ConfigHelperMixin, object): def __init__(self, reposname, account): self.ui = getglobalui() From b33f2452f07b9fcb891717b0046b82dac1b7267a Mon Sep 17 00:00:00 2001 From: Sebastian Spaeth Date: Sun, 5 Feb 2012 12:52:12 +0100 Subject: [PATCH 16/58] Use "from . import" for relative imports Will fail in python3 otherwise. Signed-off-by: Sebastian Spaeth --- offlineimap/folder/Gmail.py | 2 +- offlineimap/folder/IMAP.py | 2 +- offlineimap/folder/LocalStatus.py | 2 +- offlineimap/folder/LocalStatusSQLite.py | 2 +- offlineimap/folder/Maildir.py | 2 +- offlineimap/folder/UIDMaps.py | 2 +- offlineimap/folder/__init__.py | 2 +- 7 files changed, 7 insertions(+), 7 deletions(-) diff --git a/offlineimap/folder/Gmail.py b/offlineimap/folder/Gmail.py index 5d11119..e3433c0 100644 --- a/offlineimap/folder/Gmail.py +++ b/offlineimap/folder/Gmail.py @@ -18,7 +18,7 @@ """Folder implementation to support features of the Gmail IMAP server. """ -from IMAP import IMAPFolder +from .IMAP import IMAPFolder class GmailFolder(IMAPFolder): """Folder implementation to support features of the Gmail IMAP server. diff --git a/offlineimap/folder/IMAP.py b/offlineimap/folder/IMAP.py index 9d53e89..4e7e885 100644 --- a/offlineimap/folder/IMAP.py +++ b/offlineimap/folder/IMAP.py @@ -21,7 +21,7 @@ import binascii import re import time from sys import exc_info -from Base import BaseFolder +from .Base import BaseFolder from offlineimap import imaputil, imaplibutil, OfflineImapError from offlineimap.imaplib2 import MonthNames diff --git a/offlineimap/folder/LocalStatus.py b/offlineimap/folder/LocalStatus.py index e637d94..7f27768 100644 --- a/offlineimap/folder/LocalStatus.py +++ b/offlineimap/folder/LocalStatus.py @@ -15,7 +15,7 @@ # along with this program; if not, write to the Free Software # Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA -from Base import BaseFolder +from .Base import BaseFolder import os import threading diff --git a/offlineimap/folder/LocalStatusSQLite.py b/offlineimap/folder/LocalStatusSQLite.py index f59d4b2..dbe3e66 100644 --- a/offlineimap/folder/LocalStatusSQLite.py +++ b/offlineimap/folder/LocalStatusSQLite.py @@ -17,7 +17,7 @@ import os.path import re from threading import Lock -from LocalStatus import LocalStatusFolder +from .LocalStatus import LocalStatusFolder try: import sqlite3 as sqlite except: diff --git a/offlineimap/folder/Maildir.py b/offlineimap/folder/Maildir.py index 11541e4..8ca32e5 100644 --- a/offlineimap/folder/Maildir.py +++ b/offlineimap/folder/Maildir.py @@ -19,7 +19,7 @@ import socket import time import re import os -from Base import BaseFolder +from .Base import BaseFolder from threading import Lock try: diff --git a/offlineimap/folder/UIDMaps.py b/offlineimap/folder/UIDMaps.py index ac0a9b4..36e92af 100644 --- a/offlineimap/folder/UIDMaps.py +++ b/offlineimap/folder/UIDMaps.py @@ -15,7 +15,7 @@ # along with this program; if not, write to the Free Software # Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA from threading import Lock -from IMAP import IMAPFolder +from .IMAP import IMAPFolder import os.path class MappedIMAPFolder(IMAPFolder): diff --git a/offlineimap/folder/__init__.py b/offlineimap/folder/__init__.py index 425148b..2b54a71 100644 --- a/offlineimap/folder/__init__.py +++ b/offlineimap/folder/__init__.py @@ -1,2 +1,2 @@ -import Base, Gmail, IMAP, Maildir, LocalStatus +from . import Base, Gmail, IMAP, Maildir, LocalStatus From e6e708ec786bbdb3b94a8d4ef7bd10559ee2fd2c Mon Sep 17 00:00:00 2001 From: Sebastian Spaeth Date: Sun, 5 Feb 2012 13:17:16 +0100 Subject: [PATCH 17/58] Don't use sort() on dict values() This won't work in python3 anymore, so just use sorted() when needed. In one case, we could remove the sort() completely as were were sanity checking one line above, that we only having one UID as response which makes sorting unneeded. Signed-off-by: Sebastian Spaeth --- offlineimap/folder/IMAP.py | 3 +-- offlineimap/imaputil.py | 5 ++--- 2 files changed, 3 insertions(+), 5 deletions(-) diff --git a/offlineimap/folder/IMAP.py b/offlineimap/folder/IMAP.py index 4e7e885..0bbe746 100644 --- a/offlineimap/folder/IMAP.py +++ b/offlineimap/folder/IMAP.py @@ -1,5 +1,5 @@ # IMAP folder support -# Copyright (C) 2002-2011 John Goerzen & contributors +# Copyright (C) 2002-2012 John Goerzen & contributors # # This program is free software; you can redistribute it and/or modify # it under the terms of the GNU General Public License as published by @@ -327,7 +327,6 @@ class IMAPFolder(BaseFolder): raise ValueError("While attempting to find UID for message with " "header %s, got wrong-sized matchinguids of %s" %\ (headername, str(matchinguids))) - matchinguids.sort() return long(matchinguids[0]) def savemessage_fetchheaders(self, imapobj, headername, headervalue): diff --git a/offlineimap/imaputil.py b/offlineimap/imaputil.py index ba1f458..7165e09 100644 --- a/offlineimap/imaputil.py +++ b/offlineimap/imaputil.py @@ -182,13 +182,12 @@ def flagsimap2maildir(flagstring): return retval def flagsmaildir2imap(maildirflaglist): - """Convert set of flags ([DR]) into a string '(\\Draft \\Deleted)'""" + """Convert set of flags ([DR]) into a string '(\\Deleted \\Draft)'""" retval = [] for imapflag, maildirflag in flagmap: if maildirflag in maildirflaglist: retval.append(imapflag) - retval.sort() - return '(' + ' '.join(retval) + ')' + return '(' + ' '.join(sorted(retval)) + ')' def uid_sequence(uidlist): """Collapse UID lists into shorter sequence sets From 046210b93d3585066b6970b7bc2f246434f23b0c Mon Sep 17 00:00:00 2001 From: Sebastian Spaeth Date: Sun, 5 Feb 2012 13:23:12 +0100 Subject: [PATCH 18/58] Fix mixed space/tabs Signed-off-by: Sebastian Spaeth --- offlineimap/imaputil.py | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/offlineimap/imaputil.py b/offlineimap/imaputil.py index 7165e09..557064b 100644 --- a/offlineimap/imaputil.py +++ b/offlineimap/imaputil.py @@ -133,12 +133,12 @@ def imapsplit(imapstring): if workstr[0] == '(': rparenc = 1 # count of right parenthesis to match rpareni = 1 # position to examine - while rparenc: # Find the end of the group. - if workstr[rpareni] == ')': # end of a group - rparenc -= 1 - elif workstr[rpareni] == '(': # start of a group - rparenc += 1 - rpareni += 1 # Move to next character. + while rparenc: # Find the end of the group. + if workstr[rpareni] == ')': # end of a group + rparenc -= 1 + elif workstr[rpareni] == '(': # start of a group + rparenc += 1 + rpareni += 1 # Move to next character. parenlist = workstr[0:rpareni] workstr = workstr[rpareni:].lstrip() retval.append(parenlist) From 8aba2800e6336e64b6aad0a64c23163a245ecc42 Mon Sep 17 00:00:00 2001 From: Sebastian Spaeth Date: Sun, 5 Feb 2012 13:28:00 +0100 Subject: [PATCH 19/58] long(0) -> 0 There is no need to cast 0 to 'long' even if we want to compare it to long numbers in modern pythons. Signed-off-by: Sebastian Spaeth --- offlineimap/folder/Maildir.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/offlineimap/folder/Maildir.py b/offlineimap/folder/Maildir.py index 8ca32e5..16745ab 100644 --- a/offlineimap/folder/Maildir.py +++ b/offlineimap/folder/Maildir.py @@ -40,7 +40,7 @@ re_uidmatch = re.compile(',U=(\d+)') re_timestampmatch = re.compile('(\d+)'); timeseq = 0 -lasttime = long(0) +lasttime = 0 timelock = Lock() def gettimeseq(): From 5c598d7e74b11c3b6e171570164bdf3a17f7cc76 Mon Sep 17 00:00:00 2001 From: Sebastian Spaeth Date: Sun, 5 Feb 2012 13:40:06 +0100 Subject: [PATCH 20/58] dict.has_key(a) --> a in dict has_key() is gone in python3, so use a more modern syntax here. Signed-off-by: Sebastian Spaeth --- offlineimap/folder/IMAP.py | 2 +- offlineimap/folder/UIDMaps.py | 4 ++-- offlineimap/imaplibutil.py | 2 +- offlineimap/threadutil.py | 2 +- offlineimap/ui/UIBase.py | 6 +++--- 5 files changed, 8 insertions(+), 8 deletions(-) diff --git a/offlineimap/folder/IMAP.py b/offlineimap/folder/IMAP.py index 0bbe746..d06c740 100644 --- a/offlineimap/folder/IMAP.py +++ b/offlineimap/folder/IMAP.py @@ -186,7 +186,7 @@ class IMAPFolder(BaseFolder): continue messagestr = messagestr.split(' ', 1)[1] options = imaputil.flags2hash(messagestr) - if not options.has_key('UID'): + if not 'UID' in options: self.ui.warn('No UID in message with options %s' %\ str(options), minor = 1) diff --git a/offlineimap/folder/UIDMaps.py b/offlineimap/folder/UIDMaps.py index 36e92af..f306459 100644 --- a/offlineimap/folder/UIDMaps.py +++ b/offlineimap/folder/UIDMaps.py @@ -94,7 +94,7 @@ class MappedIMAPFolder(IMAPFolder): # summary that have been deleted from the folder. for luid in self.diskl2r.keys(): - if not reallist.has_key(luid): + if not luid in reallist: ruid = self.diskl2r[luid] del self.diskr2l[ruid] del self.diskl2r[luid] @@ -107,7 +107,7 @@ class MappedIMAPFolder(IMAPFolder): self.l2r = self.diskl2r.copy() for luid in reallist.keys(): - if not self.l2r.has_key(luid): + if not luid in self.l2r: ruid = nextneg nextneg -= 1 self.l2r[luid] = ruid diff --git a/offlineimap/imaplibutil.py b/offlineimap/imaplibutil.py index 2d5fc39..2aa81d9 100644 --- a/offlineimap/imaplibutil.py +++ b/offlineimap/imaplibutil.py @@ -137,7 +137,7 @@ class WrappedIMAP4_SSL(UsefulIMAPMixIn, IMAP4_SSL): """Improved version of imaplib.IMAP4_SSL overriding select()""" def __init__(self, *args, **kwargs): self._fingerprint = kwargs.get('fingerprint', None) - if kwargs.has_key('fingerprint'): + if 'fingerprint' in kwargs: del kwargs['fingerprint'] super(WrappedIMAP4_SSL, self).__init__(*args, **kwargs) diff --git a/offlineimap/threadutil.py b/offlineimap/threadutil.py index 054fa11..a29e68f 100644 --- a/offlineimap/threadutil.py +++ b/offlineimap/threadutil.py @@ -209,7 +209,7 @@ def initInstanceLimit(instancename, instancemax): """Initialize the instance-limited thread implementation to permit up to intancemax threads with the given instancename.""" instancelimitedlock.acquire() - if not instancelimitedsems.has_key(instancename): + if not instancename in instancelimitedsems: instancelimitedsems[instancename] = BoundedSemaphore(instancemax) instancelimitedlock.release() diff --git a/offlineimap/ui/UIBase.py b/offlineimap/ui/UIBase.py index bf46e6f..a8aeeaf 100644 --- a/offlineimap/ui/UIBase.py +++ b/offlineimap/ui/UIBase.py @@ -159,7 +159,7 @@ class UIBase(object): def unregisterthread(self, thr): """Unregister a thread as being associated with an account name""" - if self.threadaccounts.has_key(thr): + if thr in self.threadaccounts: del self.threadaccounts[thr] self.debug('thread', "Unregister thread '%s'" % thr.getName()) @@ -175,7 +175,7 @@ class UIBase(object): def debug(self, debugtype, msg): cur_thread = threading.currentThread() - if not self.debugmessages.has_key(cur_thread): + if not cur_thread in self.debugmessages: # deque(..., self.debugmsglen) would be handy but was # introduced in p2.6 only, so we'll need to work around and # shorten our debugmsg list manually :-( @@ -403,7 +403,7 @@ class UIBase(object): ################################################## Threads def getThreadDebugLog(self, thread): - if self.debugmessages.has_key(thread): + if thread in self.debugmessages: message = "\nLast %d debug messages logged for %s prior to exception:\n"\ % (len(self.debugmessages[thread]), thread.getName()) message += "\n".join(self.debugmessages[thread]) From 19c014c6cdbe67fdeb727164767901e5e00ba18b Mon Sep 17 00:00:00 2001 From: Sebastian Spaeth Date: Mon, 6 Feb 2012 17:33:50 +0100 Subject: [PATCH 21/58] Implement foldersort in a python3 compatible way By default we sort folders alphabetically (for IMAP) according to their transposed names. For python3, we need to bend a bit backwards to still allow the use of a cmp() function for foldersort. While going through, I discovered that we never sort folders for Maildir. Signed-off-by: Sebastian Spaeth --- offlineimap.conf | 13 +++++++------ offlineimap/repository/Base.py | 2 +- offlineimap/repository/IMAP.py | 20 ++++++++++++++++++-- 3 files changed, 26 insertions(+), 9 deletions(-) diff --git a/offlineimap.conf b/offlineimap.conf index 2656ef6..b4f6a99 100644 --- a/offlineimap.conf +++ b/offlineimap.conf @@ -496,13 +496,14 @@ remoteuser = username # one. For example: # folderincludes = ['debian.user', 'debian.personal'] -# You can specify foldersort to determine how folders are sorted. +# You can specify 'foldersort' to determine how folders are sorted. # This affects order of synchronization and mbnames. The expression -# should return -1, 0, or 1, as the default Python cmp() does. The -# two arguments, x and y, are strings representing the names of the folders -# to be sorted. The sorting is applied *AFTER* nametrans, if any. -# -# To reverse the sort: +# should return -1, 0, or 1, as the default Python cmp() does. The two +# arguments, x and y, are strings representing the names of the folders +# to be sorted. The sorting is applied *AFTER* nametrans, if any. The +# default is to sort IMAP folders alphabetically +# (case-insensitive). Usually, you should never have to modify this. To +# eg. reverse the sort: # # foldersort = lambda x, y: -cmp(x, y) diff --git a/offlineimap/repository/Base.py b/offlineimap/repository/Base.py index cbbc5f4..cca5cf3 100644 --- a/offlineimap/repository/Base.py +++ b/offlineimap/repository/Base.py @@ -45,7 +45,7 @@ class BaseRepository(CustomConfig.ConfigHelperMixin, object): self.nametrans = lambda foldername: foldername self.folderfilter = lambda foldername: 1 self.folderincludes = [] - self.foldersort = cmp + self.foldersort = None if self.config.has_option(self.getsection(), 'nametrans'): self.nametrans = self.localeval.eval( self.getconf('nametrans'), {'re': re}) diff --git a/offlineimap/repository/IMAP.py b/offlineimap/repository/IMAP.py index f008592..1b13d79 100644 --- a/offlineimap/repository/IMAP.py +++ b/offlineimap/repository/IMAP.py @@ -308,8 +308,24 @@ class IMAPRepository(BaseRepository): self)) finally: self.imapserver.releaseconnection(imapobj) - - retval.sort(lambda x, y: self.foldersort(x.getvisiblename(), y.getvisiblename())) + + if self.foldersort is None: + # default sorting by case insensitive transposed name + 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 + def cmp2key(mycmp): + """Converts a cmp= function into a key= function + We need to keep cmp functions for backward compatibility""" + class K: + def __init__(self, obj, *args): + self.obj = obj + def __cmp__(self, other): + return mycmp(self.obj, other.obj) + return K + retval.sort(key=cmp2key(self.foldersort)) + self.folders = retval return self.folders From da0ba2e26687a2f6b7d5149b133ebb66151c36f2 Mon Sep 17 00:00:00 2001 From: Sebastian Spaeth Date: Mon, 13 Feb 2012 16:07:33 +0100 Subject: [PATCH 22/58] Improve nametrans user documentation Fill in more details on nametrans and folder filtering. Also give them a separate section in our user documentation. Everything will be immediately online at docs.offlineimap.org. The main change is to describe the reverse nametrans settings that are needed since 6.4.0 to support remote folder creation. Signed-off-by: Sebastian Spaeth --- Changelog.draft.rst | 4 + docs/MANUAL.rst | 151 ++++----------------------- docs/dev-doc-src/index.rst | 2 + docs/dev-doc-src/nametrans.rst | 182 +++++++++++++++++++++++++++++++++ offlineimap.conf | 19 ++-- offlineimap.conf.minimal | 2 +- 6 files changed, 221 insertions(+), 139 deletions(-) create mode 100644 docs/dev-doc-src/nametrans.rst diff --git a/Changelog.draft.rst b/Changelog.draft.rst index 76a0ea3..9a046ac 100644 --- a/Changelog.draft.rst +++ b/Changelog.draft.rst @@ -16,5 +16,9 @@ New Features Changes ------- +* internal code changes to prepare for Python3 + +* Improve user documentation of nametrans/folderfilter + Bug Fixes --------- diff --git a/docs/MANUAL.rst b/docs/MANUAL.rst index 21a5dd6..8d7a8b7 100644 --- a/docs/MANUAL.rst +++ b/docs/MANUAL.rst @@ -328,18 +328,22 @@ Upgrading from plain text cache to SQLITE based cache OfflineImap uses a cache to store the last know status of mails (flags etc). Historically that has meant plain text files, but recently we introduced sqlite-based cache, which helps with performance and CPU usage on large folders. Here is how to upgrade existing plain text cache installations to sqlite based one: - 1) Sync to make sure things are reasonably similar - 3) Change the account section to status_backend = sqlite - 4) A new sync will convert your plain text cache to an sqlite cache (but - leave the old plain text cache around for easy reverting) - This should be quick and not involve any mail up/downloading. - 5) See if it works :-) - 6a) If it does not work, go back to the old version or set - status_backend=plain - 6b) Or once you are sure it works, you can delete the - .offlineimap/Account-foo/LocalStatus folder (the new cache will be in - the LocalStatus-sqlite folder) +1) Sync to make sure things are reasonably similar +2) Change the account section to status_backend = sqlite + +3) A new sync will convert your plain text cache to an sqlite cache + (but leave the old plain text cache around for easy reverting) This + should be quick and not involve any mail up/downloading. + +4) See if it works :-) + +5) If it does not work, go back to the old version or set + status_backend=plain + +6) Or, once you are sure it works, you can delete the + .offlineimap/Account-foo/LocalStatus folder (the new cache will be + in the LocalStatus-sqlite folder) Security and SSL ================ @@ -399,128 +403,10 @@ accounts will abort any current sleep and will exit after a currently running synchronization has finished. This signal can be used to gracefully exit out of a running offlineimap "daemon". -Folder filtering and Name translation -===================================== +Folder filtering and nametrans +============================== -OfflineImap provides advanced and potentially complex possibilities for -filtering and translating folder names. If you don't need this, you can -safely skip this section. - -folderfilter ------------- - -If you do not want to synchronize all your filters, you can specify a folderfilter function that determines which folders to include in a sync and which to exclude. Typically, you would set a folderfilter option on the remote repository only, and it would be a lambda or any other python function. - -If the filter function returns True, the folder will be synced, if it -returns False, it. The folderfilter operates on the *UNTRANSLATED* name -(before any nametrans translation takes place). - -Example 1: synchronizing only INBOX and Sent:: - - folderfilter = lambda foldername: foldername in ['INBOX', 'Sent'] - -Example 2: synchronizing everything except Trash:: - - folderfilter = lambda foldername: foldername not in ['Trash'] - -Example 3: Using a regular expression to exclude Trash and all folders -containing the characters "Del":: - - folderfilter = lambda foldername: not re.search('(^Trash$|Del)', foldername) - -If folderfilter is not specified, ALL remote folders will be -synchronized. - -You can span multiple lines by indenting the others. (Use backslashes -at the end when required by Python syntax) For instance:: - - folderfilter = lambda foldername: foldername in - ['INBOX', 'Sent Mail', 'Deleted Items', - 'Received'] - -You only need a folderfilter option on the local repository if you want to prevent some folders on the local repository to be created on the remote one. - -Even if you filtered out folders, You can specify folderincludes to -include additional folders. It should return a Python list. This might -be used to include a folder that was excluded by your folderfilter rule, -to include a folder that your server does not specify with its LIST -option, or to include a folder that is outside your basic reference. The -'reference' value will not be prefixed to this folder name, even if you -have specified one. For example:: - - folderincludes = ['debian.user', 'debian.personal'] - -nametrans ----------- - -Sometimes, folders need to have different names on the remote and the -local repositories. To achieve this you can specify a folder name -translator. This must be a eval-able Python expression that takes a -foldername arg and returns the new value. I suggest a lambda. This -example below will remove "INBOX." from the leading edge of folders -(great for Courier IMAP users):: - - nametrans = lambda foldername: re.sub('^INBOX\.', '', foldername) - -Using Courier remotely and want to duplicate its mailbox naming -locally? Try this:: - - nametrans = lambda foldername: re.sub('^INBOX\.*', '.', foldername) - - -WARNING: you MUST construct nametrans rules such that it NEVER returns -the same value for two folders, UNLESS the second values are -filtered out by folderfilter below. That is, two filters on one side may never point to the same folder on the other side. Failure to follow this rule -will result in undefined behavior. See also *Sharing a maildir with multiple IMAP servers* in the `PITFALLS & ISSUES`_ section. - -Where to put nametrans rules, on the remote and/or local repository? -++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ - -If you never intend to create new folders on the LOCAL repository that -need to be synced to the REMOTE repository, it is sufficient to create a -nametrans rule on the remote Repository section. This will be used to -determine the names of new folder names on the LOCAL repository, and to -match existing folders that correspond. - -*IF* you create folders on the local repository, that are supposed to be - automatically created on the remote repository, you will need to create - a nametrans rule that provides the reverse name translation. - -(A nametrans rule provides only a one-way translation of names and in -order to know which names folders on the LOCAL side would have on the -REMOTE side, you need to specify the reverse nametrans rule on the local -repository) - -OfflineImap will complain if it needs to create a new folder on the -remote side and a back-and-forth nametrans-lation does not yield the -original foldername (as that could potentially lead to infinite folder -creation cycles). - -What folder separators do I need to use in nametrans rules? -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ - -**Q:** If I sync from an IMAP server with folder separator '/' to a - Maildir using the default folder separator '.' which do I need to use - in nametrans rules?:: - - nametrans = lambda f: "INBOX/" + f -or:: - nametrans = lambda f: "INBOX." + f - -**A:** Generally use the folder separator as defined in the repository - you write the nametrans rule for. That is, use '/' in the above - case. We will pass in the untranslated name of the IMAP folder as - parameter (here `f`). The translated name will ultimately have all - folder separators be replaced with the destination repositories' - folder separator. - -So if 'f' was "Sent", the first nametrans yields the translated name -"INBOX/Sent" to be used on the other side. As that repository uses the -folder separator '.' rather than '/', the ultimate name to be used will -be "INBOX.Sent". - -(As a final note, the smart will see that both variants of the above -nametrans rule would have worked identically in this case) +OfflineImap offers flexible (and complex) ways of filtering and transforming folder names. Please see the docs/dev-docs-src/folderfilters.rst document about details how to use folder filters and name transformations. The documentation will be autogenerated by a "make dev-doc" in the docs directory. It is also viewable at :ref:`folder_filtering_and_name_translation`. KNOWN BUGS ========== @@ -566,6 +452,7 @@ KNOWN BUGS * Use cygwin managed mount (not tested) - not available anymore since cygwin 1.7 +.. _pitfalls: PITFALLS & ISSUES ================= diff --git a/docs/dev-doc-src/index.rst b/docs/dev-doc-src/index.rst index e1b957e..d6aa939 100644 --- a/docs/dev-doc-src/index.rst +++ b/docs/dev-doc-src/index.rst @@ -17,6 +17,7 @@ More information on specific topics can be found on the following pages: **User documentation** * :doc:`installation/uninstall ` * :doc:`user manual/Configuration ` + * :doc:`Folder filtering & name transformation guide ` * :doc:`command line options ` * :doc:`Frequently Asked Questions ` @@ -29,6 +30,7 @@ More information on specific topics can be found on the following pages: INSTALL MANUAL + nametrans offlineimap FAQ diff --git a/docs/dev-doc-src/nametrans.rst b/docs/dev-doc-src/nametrans.rst new file mode 100644 index 0000000..fabf7a4 --- /dev/null +++ b/docs/dev-doc-src/nametrans.rst @@ -0,0 +1,182 @@ +.. _folder_filtering_and_name_translation: + +Folder filtering and Name translation +===================================== + +OfflineImap provides advanced and potentially complex possibilities for +filtering and translating folder names. If you don't need any of this, you can +safely skip this section. + +.. warning:: + Starting with v6.4.0, OfflineImap supports the creation of folders on the remote repostory. This change means that people that only had a nametrans option on the remote repository (everyone) will need to have a nametrans setting on the local repository too that will reverse the name transformation. See section `Reverse nametrans`_ for details. + +folderfilter +------------ + +If you do not want to synchronize all your filters, you can specify a `folderfilter`_ function that determines which folders to include in a sync and which to exclude. Typically, you would set a folderfilter option on the remote repository only, and it would be a lambda or any other python function. + +The only parameter to that function is the folder name. If the filter +function returns True, the folder will be synced, if it returns False, +it. will be skipped. The folderfilter operates on the *UNTRANSLATED* +name (before any `nametrans`_ fudging takes place). Consider the +examples below to get an idea of what they do. + +Example 1: synchronizing only INBOX and Sent:: + + folderfilter = lambda folder: folder in ['INBOX', 'Sent'] + +Example 2: synchronizing everything except Trash:: + + folderfilter = lambda folder: folder not in ['Trash'] + +Example 3: Using a regular expression to exclude Trash and all folders +containing the characters "Del":: + + folderfilter = lambda folder: not re.search('(^Trash$|Del)', folder) + +.. note:: + If folderfilter is not specified, ALL remote folders will be + synchronized. + +You can span multiple lines by indenting the others. (Use backslashes +at the end when required by Python syntax) For instance:: + + folderfilter = lambda foldername: foldername in + ['INBOX', 'Sent Mail', 'Deleted Items', + 'Received'] + +Usually it suffices to put a `folderfilter`_ setting in the remote repository section. You might want to put a folderfilter option on the local repository if you want to prevent some folders on the local repository to be created on the remote one. (Even in this case, folder filters on the remote repository will prevent that) + +folderincludes +^^^^^^^^^^^^^^ + +You can specify `folderincludes`_ to manually include additional folders to be synced, even if they had been filtered out by a folderfilter setting. `folderincludes`_ should return a Python list. + +This can be used to 1) add a folder that was excluded by your +folderfilter rule, 2) to include a folder that your server does not specify +with its LIST option, or 3) to include a folder that is outside your basic +`reference`. The `reference` value will not be prefixed to this folder +name, even if you have specified one. For example:: + + folderincludes = ['debian.user', 'debian.personal'] + +This will add the "debian.user" and "debian.personal" folders even if you +have filtered out everything starting with "debian" in your folderfilter +settings. + + +nametrans +---------- + +Sometimes, folders need to have different names on the remote and the +local repositories. To achieve this you can specify a folder name +translator. This must be a eval-able Python expression that takes a +foldername arg and returns the new value. We suggest a lambda function, +but it could be any python function really. If you use nametrans rules, you will need to set them both on the remote and the local repository, see `Reverse nametrans`_ just below for details. The following examples are thought to be put in the remote repository section. + +The below will remove "INBOX." from the leading edge of folders (great +for Courier IMAP users):: + + nametrans = lambda folder: re.sub('^INBOX\.', '', folder) + +Using Courier remotely and want to duplicate its mailbox naming +locally? Try this:: + + nametrans = lambda folder: re.sub('^INBOX\.*', '.', folder) + +.. warning:: + You MUST construct nametrans rules such that it NEVER returns the + same value for two folders, UNLESS the second values are filtered + out by folderfilter below. That is, two filters on one side may + never point to the same folder on the other side. Failure to follow + this rule will result in undefined behavior. See also *Sharing a + maildir with multiple IMAP servers* in the :ref:`pitfalls` section. + +Reverse nametrans +^^^^^^^^^^^^^^^^^^ + +Since 6.4.0, OfflineImap supports the creation of folders on the remote repository and that complicates things. Previously, only one nametrans setting on the remote repository was needed and that transformed a remote to a local name. However, nametrans transformations are one-way, and OfflineImap has no way using those rules on the remote repository to back local names to remote names. + +Take a remote nametrans rule `lambda f: re.sub('^INBOX/','',f)` which cuts of any existing INBOX prefix. Now, if we parse a list of local folders, finding e.g. a folder "Sent", is it supposed to map to "INBOX/Sent" or to "Sent"? We have no way of knowing. This is why **every nametrans setting on a remote repository requires an equivalent nametrans rule on the local repository that reverses the transformation**. + +Take the above examples. If your remote nametrans setting was:: + + nametrans = lambda folder: re.sub('^INBOX\.', '', folder) + +then you will want to have this in your local repository, prepending "INBOX" to any local folder name:: + + nametrans = lambda folder: 'INBOX' + folder + +Failure to set the local nametrans rule will lead to weird-looking error messages of -for instance- this type:: + + ERROR: Creating folder moo.foo on repository remote + Folder 'moo.foo'[remote] could not be created. Server responded: ('NO', ['Unknown namespace.']) + +(This indicates that you attempted to create a folder "Sent" when all remote folders needed to be under the prefix of "INBOX."). + +OfflineImap will make some sanity checks if it needs to create a new +folder on the remote side and a back-and-forth nametrans-lation does not +yield the original foldername (as that could potentially lead to +infinite folder creation cycles). + +You can probably already see now that creating nametrans rules can be a pretty daunting and complex endeavour. Check out the Use cases in the manual. If you have some interesting use cases that we can present as examples here, please let us know. + +Debugging folderfilter and nametrans +------------------------------------ + +Given the complexity of the functions and regexes involved, it is easy to misconfigure things. One way to test your configuration without danger to corrupt anything or to create unwanted folders is to invoke offlineimap with the `--info` option. + +It will output a list of folders and their transformations on the screen (save them to a file with -l info.log), and will help you to tweak your rules as well as to understand your configuration. It also provides good output for bug reporting. + +FAQ on nametrans +---------------- + +Where to put nametrans rules, on the remote and/or local repository? +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +If you never intend to create new folders on the LOCAL repository that +need to be synced to the REMOTE repository, it is sufficient to create a +nametrans rule on the remote Repository section. This will be used to +determine the names of new folder names on the LOCAL repository, and to +match existing folders that correspond. + +*IF* you create folders on the local repository, that are supposed to be + automatically created on the remote repository, you will need to create + a nametrans rule that provides the reverse name translation. + +(A nametrans rule provides only a one-way translation of names and in +order to know which names folders on the LOCAL side would have on the +REMOTE side, you need to specify the reverse nametrans rule on the local +repository) + +OfflineImap will complain if it needs to create a new folder on the +remote side and a back-and-forth nametrans-lation does not yield the +original foldername (as that could potentially lead to infinite folder +creation cycles). + +What folder separators do I need to use in nametrans rules? ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +**Q:** If I sync from an IMAP server with folder separator '/' to a + Maildir using the default folder separator '.' which do I need to use + in nametrans rules?:: + + nametrans = lambda f: "INBOX/" + f +or:: + nametrans = lambda f: "INBOX." + f + +**A:** Generally use the folder separator as defined in the repository + you write the nametrans rule for. That is, use '/' in the above + case. We will pass in the untranslated name of the IMAP folder as + parameter (here `f`). The translated name will ultimately have all + folder separators be replaced with the destination repositories' + folder separator. + +So if 'f' was "Sent", the first nametrans yields the translated name +"INBOX/Sent" to be used on the other side. As that repository uses the +folder separator '.' rather than '/', the ultimate name to be used will +be "INBOX.Sent". + +(As a final note, the smart will see that both variants of the above +nametrans rule would have worked identically in this case) + diff --git a/offlineimap.conf b/offlineimap.conf index b4f6a99..627b237 100644 --- a/offlineimap.conf +++ b/offlineimap.conf @@ -1,11 +1,14 @@ # Offlineimap sample configuration file -# This file documents all possible options and can be quite scary. -# Looking for a quick start? Take a look at offlineimap.conf.minimal. -# Settings generally support interpolation. This means values can -# contain python format strings which refer to other values in the same -# section, or values in a special DEFAULT section. This allows you for -# example to use common settings for multiple accounts: +# This file documents *all* possible options and can be quite scary. +# Looking for a quick start? Take a look at offlineimap.conf.minimal. +# More details can be found in the included user documention, which is +# also available at: http://docs.offlineimap.org/en/latest/ + +# NOTE: Settings generally support python interpolation. This means +# values can contain python format strings which refer to other values +# in the same section, or values in a special DEFAULT section. This +# allows you for example to use common settings for multiple accounts: # # [Repository Gmail1] # trashfolder: %(gmailtrashfolder)s @@ -443,6 +446,10 @@ remoteuser = username # value. I suggest a lambda. This example below will remove "INBOX." from # the leading edge of folders (great for Courier IMAP users) # +# See the user documentation for details and use cases. They are also +# online at: +# http://docs.offlineimap.org/en/latest/nametrans.html +# # WARNING: you MUST construct this such that it NEVER returns # the same value for two folders, UNLESS the second values are # filtered out by folderfilter below. Failure to follow this rule diff --git a/offlineimap.conf.minimal b/offlineimap.conf.minimal index 2979d3d..3ca6e09 100644 --- a/offlineimap.conf.minimal +++ b/offlineimap.conf.minimal @@ -1,5 +1,5 @@ # Sample minimal config file. Copy this to ~/.offlineimaprc and edit to -# suit to get started fast. +# get started fast. [general] accounts = Test From c1f75a6c945609d1f2a9ff51e5db259ff52e50f5 Mon Sep 17 00:00:00 2001 From: Sebastian Spaeth Date: Thu, 16 Feb 2012 09:55:26 +0100 Subject: [PATCH 23/58] test: Create all intermediary maildirs Don't fail if root maildir folder does not exist it. Create it recursively. Signed-off-by: Sebastian Spaeth --- test/OLItest/TestRunner.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/test/OLItest/TestRunner.py b/test/OLItest/TestRunner.py index 183f67a..742d118 100644 --- a/test/OLItest/TestRunner.py +++ b/test/OLItest/TestRunner.py @@ -108,7 +108,7 @@ class OLITestLib(): maildir = os.path.join(cls.testdir, 'mail', folder) for subdir in ('','tmp','cur','new'): try: - os.mkdir(os.path.join(maildir, subdir)) + os.makedirs(os.path.join(maildir, subdir)) except OSError as e: if e.errno != 17: # 'already exists' is ok. raise From 75ea403278ec080d110589914fb1cb63431836bd Mon Sep 17 00:00:00 2001 From: Sebastian Spaeth Date: Thu, 16 Feb 2012 09:31:14 +0100 Subject: [PATCH 24/58] test: Split configuration generation so we can tweak values Use get_default_config and write_config_file (which can be handed an optional config object), so we can manipulate configuration options easily from within the test function. Signed-off-by: Sebastian Spaeth --- test/OLItest/TestRunner.py | 27 ++++++++++++++++++++------- 1 file changed, 20 insertions(+), 7 deletions(-) diff --git a/test/OLItest/TestRunner.py b/test/OLItest/TestRunner.py index 742d118..3c21257 100644 --- a/test/OLItest/TestRunner.py +++ b/test/OLItest/TestRunner.py @@ -54,23 +54,36 @@ class OLITestLib(): cls.testdir = os.path.abspath( tempfile.mkdtemp(prefix='tmp_%s_'%suffix, dir=os.path.dirname(cls.cred_file))) - cls.create_config_file() + cls.write_config_file() return cls.testdir @classmethod - def create_config_file(cls): - """Creates a OLI configuration file + def get_default_config(cls): + """Creates a default ConfigParser file and returns it - It is created in testdir (so create_test_dir has to be called - earlier) using the credentials information given (so they had to - be set earlier). Failure to do either of them will raise an - AssertionException.""" + The returned config can be manipulated and then saved with + write_config_file()""" assert cls.cred_file != None assert cls.testdir != None config = SafeConfigParser() config.readfp(default_conf) + default_conf.seek(0) # rewind config_file to start config.read(cls.cred_file) config.set("general", "metadata", cls.testdir) + return config + + @classmethod + def write_config_file(cls, config=None): + """Creates a OLI configuration file + + It is created in testdir (so create_test_dir has to be called + earlier) using the credentials information given (so they had + to be set earlier). Failure to do either of them will raise an + AssertionException. If config is None, a default one will be + used via get_default_config, otherwise it needs to be a config + object derived from that.""" + if config is None: + config = cls.get_default_config() localfolders = os.path.join(cls.testdir, 'mail') config.set("Repository Maildir", "localfolders", localfolders) with open(os.path.join(cls.testdir, 'offlineimap.conf'), "wa") as f: From 10dd317026fbbb62d2f2b2edad5ac8a0f20b2da9 Mon Sep 17 00:00:00 2001 From: Sebastian Spaeth Date: Thu, 16 Feb 2012 11:03:33 +0100 Subject: [PATCH 25/58] Folder: Implement __eq__ for folders This allows to compare folders directly with strings. It also allows constructs such as "if 'moo' in repo.getfolders()". See the code documentation for the exact behavior (it basically is equal if it's the same instance *or* a string matching the untranslated folder name. Signed-off-by: Sebastian Spaeth --- offlineimap/folder/Base.py | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/offlineimap/folder/Base.py b/offlineimap/folder/Base.py index 1c05370..fcea99d 100644 --- a/offlineimap/folder/Base.py +++ b/offlineimap/folder/Base.py @@ -479,3 +479,20 @@ class BaseFolder(object): self.ui.error(e, exc_info()[2], "Syncing folder %s [acc: %s]" %\ (self, self.accountname)) raise # raise unknown Exceptions so we can fix them + + def __eq__(self, other): + """Comparisons work either on string comparing folder names or + on the same instance + + MailDirFolder('foo') == 'foo' --> True + a = MailDirFolder('foo'); a == b --> True + MailDirFolder('foo') == 'moo' --> False + MailDirFolder('foo') == IMAPFolder('foo') --> False + MailDirFolder('foo') == MaildirFolder('foo') --> False + """ + if isinstance(other, basestring): + return other == self.name + return id(self) == id(other) + + def __ne__(self, other): + return not self.__eq__(other) From 189d78cc5c5215ad265f23374a13209d49dacec8 Mon Sep 17 00:00:00 2001 From: Sebastian Spaeth Date: Thu, 16 Feb 2012 11:12:07 +0100 Subject: [PATCH 26/58] sync_folder_structure: make more readable Rename variable src_name to src_name_t to indicate that it is the transposed name. Also rather than testing the hash thingie, we can simply test for "if source_name_t in dst_folders" now. Signed-off-by: Sebastian Spaeth --- offlineimap/repository/Base.py | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/offlineimap/repository/Base.py b/offlineimap/repository/Base.py index cca5cf3..22fc15f 100644 --- a/offlineimap/repository/Base.py +++ b/offlineimap/repository/Base.py @@ -156,20 +156,20 @@ class BaseRepository(CustomConfig.ConfigHelperMixin, object): dst_hash[folder.name] = folder # Find new folders on src_repo. - for src_name, src_folder in src_hash.iteritems(): + for src_name_t, src_folder in src_hash.iteritems(): # Don't create on dst_repo, if it is readonly if dst_repo.getconfboolean('readonly', False): break - if src_folder.sync_this and not src_name in dst_hash: + if src_folder.sync_this and not src_name_t in dst_folders: try: - dst_repo.makefolder(src_name) + dst_repo.makefolder(src_name_t) dst_haschanged = True # Need to refresh list except OfflineImapError as e: self.ui.error(e, exc_info()[2], "Creating folder %s on repository %s" %\ - (src_name, dst_repo)) + (src_name_t, dst_repo)) raise - status_repo.makefolder(src_name.replace(dst_repo.getsep(), + status_repo.makefolder(src_name_t.replace(dst_repo.getsep(), status_repo.getsep())) # Find new folders on dst_repo. for dst_name, dst_folder in dst_hash.iteritems(): From ac033c68fd693029fc53bc697eb6be892a368145 Mon Sep 17 00:00:00 2001 From: Sebastian Spaeth Date: Thu, 16 Feb 2012 11:45:18 +0100 Subject: [PATCH 27/58] Improve nametrans local->remote folder syncing While improving the test suite, I noticed that we would not create folders on the remote in some cases when we should (yay for test suites!). This is because we were testing the untransposed LOCAL foldername and check if it existed on the remote side when deciding whether we should potentially create a new folder. Simplify the code by transposing the LOCAL folder names in dst_hash, saving us to create another confusing "newsrc" temp variable. Make the code a bit more readable by using dst_name_t to indicate we operate a transposed folder name. This now passes test 03 (using invalid nametrans rules) when test 03 would pass before. Signed-off-by: Sebastian Spaeth --- offlineimap/repository/Base.py | 33 +++++++++++++++++---------------- test/tests/test_01_basic.py | 18 ++++++++++++++++++ 2 files changed, 35 insertions(+), 16 deletions(-) diff --git a/offlineimap/repository/Base.py b/offlineimap/repository/Base.py index 22fc15f..e855210 100644 --- a/offlineimap/repository/Base.py +++ b/offlineimap/repository/Base.py @@ -153,7 +153,8 @@ class BaseRepository(CustomConfig.ConfigHelperMixin, object): src_repo.getsep(), dst_repo.getsep())] = folder dst_hash = {} for folder in dst_folders: - dst_hash[folder.name] = folder + dst_hash[folder.getvisiblename().replace( + dst_repo.getsep(), src_repo.getsep())] = folder # Find new folders on src_repo. for src_name_t, src_folder in src_hash.iteritems(): @@ -172,30 +173,30 @@ class BaseRepository(CustomConfig.ConfigHelperMixin, object): status_repo.makefolder(src_name_t.replace(dst_repo.getsep(), status_repo.getsep())) # Find new folders on dst_repo. - for dst_name, dst_folder in dst_hash.iteritems(): + for dst_name_t, dst_folder in dst_hash.iteritems(): if self.getconfboolean('readonly', False): # Don't create missing folder on readonly repo. break - if dst_folder.sync_this and not dst_name in src_hash: + if dst_folder.sync_this and not dst_name_t in src_folders: # nametrans sanity check! # Does nametrans back&forth lead to identical names? - #src_name is the unmodified full src_name that would be created - newsrc_name = dst_folder.getvisiblename().replace( - dst_repo.getsep(), - src_repo.getsep()) - folder = self.getfolder(newsrc_name) - # would src repo filter out the new folder name? In this + # 1) would src repo filter out the new folder name? In this # case don't create it on it: - if not self.folderfilter(newsrc_name): + if not self.folderfilter(dst_name_t): self.ui.debug('', "Not creating folder '%s' (repository '%s" "') as it would be filtered out on that repository." % - (newsrc_name, self)) + (dst_name_t, self)) continue + # get IMAPFolder and see if the reverse nametrans + # works fine TODO: getfolder() works only because we + # succeed in getting inexisting folders which I would + # like to change. Take care! + folder = self.getfolder(dst_name_t) # apply reverse nametrans to see if we end up with the same name newdst_name = folder.getvisiblename().replace( src_repo.getsep(), dst_repo.getsep()) - if dst_name != newdst_name: + if dst_folder.name != newdst_name: raise OfflineImapError("INFINITE FOLDER CREATION DETECTED! " "Folder '%s' (repository '%s') would be created as fold" "er '%s' (repository '%s'). The latter becomes '%s' in " @@ -204,18 +205,18 @@ class BaseRepository(CustomConfig.ConfigHelperMixin, object): "itories so they lead to identical names if applied bac" "k and forth. 2) Use folderfilter settings on a reposit" "ory to prevent some folders from being created on the " - "other side." % (dst_name, dst_repo, newsrc_name, + "other side." % (dst_folder.name, dst_repo, dst_name_t, src_repo, newdst_name), OfflineImapError.ERROR.REPO) # end sanity check, actually create the folder try: - src_repo.makefolder(newsrc_name) + src_repo.makefolder(dst_name_t) src_haschanged = True # Need to refresh list except OfflineImapError as e: self.ui.error(e, exc_info()[2], "Creating folder %s on " - "repository %s" % (newsrc_name, src_repo)) + "repository %s" % (dst_name_t, src_repo)) raise - status_repo.makefolder(newsrc_name.replace( + status_repo.makefolder(dst_name_t.replace( src_repo.getsep(), status_repo.getsep())) # Find deleted folders. # TODO: We don't delete folders right now. diff --git a/test/tests/test_01_basic.py b/test/tests/test_01_basic.py index a0697ec..926baa0 100644 --- a/test/tests/test_01_basic.py +++ b/test/tests/test_01_basic.py @@ -72,3 +72,21 @@ class TestBasicFunctions(unittest.TestCase): self.assertEqual(res, "") boxes, mails = OLITestLib.count_maildir_mails('') logging.warn("%d boxes and %d mails" % (boxes, mails)) + + def test_03_nametransmismatch(self): + """Create mismatching remote and local nametrans rules + + This should raise an error.""" + config = OLITestLib.get_default_config() + config.set('Repository IMAP', 'nametrans', + 'lambda f: f' ) + config.set('Repository Maildir', 'nametrans', + 'lambda f: f + "moo"' ) + OLITestLib.write_config_file(config) + code, res = OLITestLib.run_OLI() + #logging.warn("%s %s "% (code, res)) + # We expect an INFINITE FOLDER CREATION WARNING HERE.... + mismatch = "ERROR: INFINITE FOLDER CREATION DETECTED!" in res + self.assertEqual(mismatch, True, "Mismatching nametrans rules did NOT" + "trigger an 'infinite folder generation' error.") + boxes, mails = OLITestLib.count_maildir_mails('') From b69a74541737d84ed7c1229f7414564a9c7171cf Mon Sep 17 00:00:00 2001 From: Sebastian Spaeth Date: Thu, 16 Feb 2012 11:54:53 +0100 Subject: [PATCH 28/58] Changelog entry Signed-off-by: Sebastian Spaeth --- Changelog.draft.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/Changelog.draft.rst b/Changelog.draft.rst index 9a046ac..a612ab8 100644 --- a/Changelog.draft.rst +++ b/Changelog.draft.rst @@ -20,5 +20,10 @@ Changes * Improve user documentation of nametrans/folderfilter +* Fixed some cases where invalid nametrans rules were not caught and + we would not propagate local folders to the remote repository. + (now tested in test03) + + Bug Fixes --------- From 7da50e638d45bcea1d456c6fadbe2a17934660df Mon Sep 17 00:00:00 2001 From: Sebastian Spaeth Date: Thu, 16 Feb 2012 16:49:06 +0100 Subject: [PATCH 29/58] folder/IMAP: better error when savemessage fails If we cannot identify the new UID after a sendmessage(), log a better error message, including the server response for better debugging. Signed-off-by: Sebastian Spaeth --- offlineimap/folder/IMAP.py | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/offlineimap/folder/IMAP.py b/offlineimap/folder/IMAP.py index d06c740..8b46996 100644 --- a/offlineimap/folder/IMAP.py +++ b/offlineimap/folder/IMAP.py @@ -577,7 +577,10 @@ class IMAPFolder(BaseFolder): "appending a message.") else: uid = long(resp[-1].split(' ')[1]) - + if uid == 0: + self.ui.warn("savemessage: Server supports UIDPLUS, but" + " we got no usable uid back. APPENDUID reponse was " + "'%s'" % str(resp)) else: # Don't support UIDPLUS # Checkpoint. Let it write out stuff, etc. Eg searches for @@ -593,9 +596,11 @@ class IMAPFolder(BaseFolder): # compare the message size... if uid == 0: self.ui.debug('imap', 'savemessage: attempt to get new UID ' - 'UID failed. Search headers manually.') + 'UID failed. Search headers manually.') uid = self.savemessage_fetchheaders(imapobj, headername, headervalue) + self.ui.warn('imap', "savemessage: Searching mails for new " + "Message-ID failed. Could not determine new UID.") finally: self.imapserver.releaseconnection(imapobj) From bf44d30b46d530b0c6723a2128b4cd5a8ba1ff95 Mon Sep 17 00:00:00 2001 From: Sebastian Spaeth Date: Fri, 17 Feb 2012 08:48:59 +0100 Subject: [PATCH 30/58] UIDMaps: Better error message when not finding a mapping Bail out with a better Exception and error text. The whole mapped UID situation needs to be improved though. Signed-off-by: Sebastian Spaeth --- offlineimap/folder/UIDMaps.py | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/offlineimap/folder/UIDMaps.py b/offlineimap/folder/UIDMaps.py index f306459..99ad2d3 100644 --- a/offlineimap/folder/UIDMaps.py +++ b/offlineimap/folder/UIDMaps.py @@ -82,7 +82,13 @@ class MappedIMAPFolder(IMAPFolder): if dolock: self.maplock.release() def _uidlist(self, mapping, items): - return [mapping[x] for x in items] + try: + return [mapping[x] for x in items] + except KeyError as e: + raise OfflineImapError("Could not find UID for msg '{0}' (f:'{1}'." + " This is usually a bad thing and should be reported on the ma" + "iling list.".format(e.args[0], self), + OfflineImapError.ERROR.MESSAGE) def cachemessagelist(self): self._mb.cachemessagelist() From 79ddb0be71fb83968dc578969cb06405439f913e Mon Sep 17 00:00:00 2001 From: Sebastian Spaeth Date: Fri, 17 Feb 2012 10:12:53 +0100 Subject: [PATCH 31/58] tests: add delete remote folder helper function We need to clean out the remote folders before we invoke the test suite. Implement a helper function that does this, and improve the test output (less verbose) and the setup.py --help-commands (more verbose). Document that it is possible to run a single test only. (although it is not guaranteed that a test does not rely on the output of previous tests). Signed-off-by: Sebastian Spaeth --- setup.py | 5 +++- test/OLItest/TestRunner.py | 49 +++++++++++++++++++++++++++++++++++++ test/tests/test_01_basic.py | 28 +++++++++++++++------ 3 files changed, 73 insertions(+), 9 deletions(-) diff --git a/setup.py b/setup.py index 3d04af2..27932eb 100644 --- a/setup.py +++ b/setup.py @@ -29,7 +29,10 @@ from test.OLItest import TextTestRunner, TestLoader, OLITestLib class TestCommand(Command): """runs the OLI testsuite""" - description = "Runs the test suite" + description = """Runs the test suite. In order to execute only a single + test, you could also issue e.g. 'python -m unittest + test.tests.test_01_basic.TestBasicFunctions.test_01_olistartup' on the + command line.""" user_options = [] def initialize_options(self): diff --git a/test/OLItest/TestRunner.py b/test/OLItest/TestRunner.py index 3c21257..e6277f2 100644 --- a/test/OLItest/TestRunner.py +++ b/test/OLItest/TestRunner.py @@ -13,9 +13,11 @@ # You should have received a copy of the GNU General Public License # along with this program; if not, write to the Free Software # Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA +import imaplib import unittest import logging import os +import re import sys import shutil import subprocess @@ -50,6 +52,7 @@ class OLITestLib(): directory at a time. OLITestLib is not suited for running several tests in parallel. The user is responsible for cleaning that up herself.""" + assert cls.cred_file != None # creating temporary dir for testing in same dir as credentials.conf cls.testdir = os.path.abspath( tempfile.mkdtemp(prefix='tmp_%s_'%suffix, @@ -63,6 +66,7 @@ class OLITestLib(): The returned config can be manipulated and then saved with write_config_file()""" + #TODO, only do first time and cache then for subsequent calls? assert cls.cred_file != None assert cls.testdir != None config = SafeConfigParser() @@ -112,6 +116,51 @@ class OLITestLib(): return (e.returncode, e.output) return (0, output) + @classmethod + def delete_remote_testfolders(cls, reponame=None): + """Delete all INBOX.OLITEST* folders on the remote IMAP repository + + reponame: All on `reponame` or all IMAP-type repositories if None""" + config = cls.get_default_config() + if reponame: + sections = ['Repository {}'.format(reponame)] + else: + sections = [r for r in config.sections() \ + if r.startswith('Repository')] + sections = filter(lambda s: \ + config.get(s, 'Type', None).lower() == 'imap', + sections) + for sec in sections: + # Connect to each IMAP repo and delete all folders + # matching the folderfilter setting. We only allow basic + # settings and no fancy password getting here... + # 1) connect and get dir listing + host = config.get(sec, 'remotehost') + user = config.get(sec, 'remoteuser') + passwd = config.get(sec, 'remotepass') + imapobj = imaplib.IMAP4(host) + imapobj.login(user, passwd) + res_t, data = imapobj.list() + assert res_t == 'OK' + dirs = [] + for d in data: + m = re.search(r''' # Find last quote + "((?: # Non-tripple quoted can contain... + [^"] | # a non-quote + \\" # a backslashded quote + )*)" # closing quote + [^"]*$ # followed by no more quotes + ''', d, flags=re.VERBOSE) + folder = m.group(1) + folder = folder.replace(r'\"', '"') # remove quoting + dirs.append(folder) + # 2) filter out those not starting with INBOX.OLItest and del... + dirs = [d for d in dirs if d.startswith('INBOX.OLItest')] + for folder in dirs: + res_t, data = imapobj.delete(folder) + assert res_t == 'OK' + imapobj.logout() + @classmethod def create_maildir(cls, folder): """Create empty maildir 'folder' in our test maildir diff --git a/test/tests/test_01_basic.py b/test/tests/test_01_basic.py index 926baa0..0967d9d 100644 --- a/test/tests/test_01_basic.py +++ b/test/tests/test_01_basic.py @@ -19,6 +19,12 @@ import logging import os, sys from test.OLItest import OLITestLib +# Things need to be setup first, usually setup.py initializes everything. +# but if e.g. called from command line, we take care of default values here: +if not OLITestLib.cred_file: + OLITestLib(cred_file='./test/credentials.conf', cmd='./offlineimap.py') + + def setUpModule(): logging.info("Set Up test module %s" % __name__) tdir = OLITestLib.create_test_dir(suffix=__name__) @@ -52,13 +58,16 @@ class TestBasicFunctions(unittest.TestCase): def test_01_olistartup(self): """Tests if OLI can be invoked without exceptions - It syncs all "OLItest* (specified in the default config) to our - local Maildir at keeps it there.""" + Cleans existing remote tet folders. Then syncs all "OLItest* + (specified in the default config) to our local Maildir. The + result should be 0 folders and 0 mails.""" + OLITestLib.delete_remote_testfolders() code, res = OLITestLib.run_OLI() self.assertEqual(res, "") - boxes, mails = OLITestLib.count_maildir_mails('') - logging.warn("%d boxes and %d mails" % (boxes, mails)) + self.assertTrue((boxes, mails)==(0,0), msg="Expected 0 folders and 0" + "mails, but sync led to {} folders and {} mails".format( + boxes, mails)) def test_02_createdir(self): """Create local OLItest 1 & OLItest "1" maildir, sync @@ -71,7 +80,9 @@ class TestBasicFunctions(unittest.TestCase): #logging.warn("%s %s "% (code, res)) self.assertEqual(res, "") boxes, mails = OLITestLib.count_maildir_mails('') - logging.warn("%d boxes and %d mails" % (boxes, mails)) + self.assertTrue((boxes, mails)==(2,0), msg="Expected 2 folders and 0" + "mails, but sync led to {} folders and {} mails".format( + boxes, mails)) def test_03_nametransmismatch(self): """Create mismatching remote and local nametrans rules @@ -87,6 +98,7 @@ class TestBasicFunctions(unittest.TestCase): #logging.warn("%s %s "% (code, res)) # We expect an INFINITE FOLDER CREATION WARNING HERE.... mismatch = "ERROR: INFINITE FOLDER CREATION DETECTED!" in res - self.assertEqual(mismatch, True, "Mismatching nametrans rules did NOT" - "trigger an 'infinite folder generation' error.") - boxes, mails = OLITestLib.count_maildir_mails('') + self.assertEqual(mismatch, True, msg="Mismatching nametrans rules did " + "NOT trigger an 'infinite folder generation' error. Output was:\n" + "{}".format(res)) + From 5979cc8ff9867ec30592e8e97aaad5f3996fa1d8 Mon Sep 17 00:00:00 2001 From: Sebastian Spaeth Date: Fri, 17 Feb 2012 10:26:43 +0100 Subject: [PATCH 32/58] tests: Add MappedIMAP test skeleton No working tests yet. Signed-off-by: Sebastian Spaeth --- test/tests/test_02_MappedIMAP.py | 71 ++++++++++++++++++++++++++++++++ 1 file changed, 71 insertions(+) create mode 100644 test/tests/test_02_MappedIMAP.py diff --git a/test/tests/test_02_MappedIMAP.py b/test/tests/test_02_MappedIMAP.py new file mode 100644 index 0000000..05aa394 --- /dev/null +++ b/test/tests/test_02_MappedIMAP.py @@ -0,0 +1,71 @@ +# Copyright (C) 2012- Sebastian Spaeth & contributors +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA +import random +import unittest +import logging +import os, sys +from test.OLItest import OLITestLib + +# Things need to be setup first, usually setup.py initializes everything. +# but if e.g. called from command line, we take care of default values here: +if not OLITestLib.cred_file: + OLITestLib(cred_file='./test/credentials.conf', cmd='./offlineimap.py') + + +def setUpModule(): + logging.info("Set Up test module %s" % __name__) + tdir = OLITestLib.create_test_dir(suffix=__name__) + +def tearDownModule(): + logging.info("Tear Down test module") + OLITestLib.delete_test_dir() + +#Stuff that can be used +#self.assertEqual(self.seq, range(10)) +# should raise an exception for an immutable sequence +#self.assertRaises(TypeError, random.shuffle, (1,2,3)) +#self.assertTrue(element in self.seq) +#self.assertFalse(element in self.seq) + +class TestBasicFunctions(unittest.TestCase): + #@classmethod + #def setUpClass(cls): + #This is run before all tests in this class + # cls._connection = createExpensiveConnectionObject() + + #@classmethod + #This is run after all tests in this class + #def tearDownClass(cls): + # cls._connection.destroy() + + # This will be run before each test + #def setUp(self): + # self.seq = range(10) + + def test_01_MappedImap(self): + """Tests if a MappedIMAP sync can be invoked without exceptions + + Cleans existing remote test folders. Then syncs all "OLItest* + (specified in the default config) to our local IMAP (Gmail). The + result should be 0 folders and 0 mails.""" + pass #TODO + #OLITestLib.delete_remote_testfolders() + #code, res = OLITestLib.run_OLI() + #self.assertEqual(res, "") + #boxes, mails = OLITestLib.count_maildir_mails('') + #self.assertTrue((boxes, mails)==(0,0), msg="Expected 0 folders and 0" + # "mails, but sync led to {} folders and {} mails".format( + # boxes, mails)) From a8c6407f50dfcdebbb3de38713637848bcadc241 Mon Sep 17 00:00:00 2001 From: Sebastian Spaeth Date: Thu, 15 Sep 2011 13:08:04 +0200 Subject: [PATCH 33/58] Implement CustomConfig.set_if_not_exists() A convenience helper function that allows to set a configuration value if the user has not explicitly configured anything ie the option does not exist yet in the configuration. It won't do anything, if the option exists. Signed-off-by: Sebastian Spaeth --- offlineimap/CustomConfig.py | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/offlineimap/CustomConfig.py b/offlineimap/CustomConfig.py index b5869e7..3cd1cef 100644 --- a/offlineimap/CustomConfig.py +++ b/offlineimap/CustomConfig.py @@ -71,6 +71,14 @@ class CustomConfigParser(SafeConfigParser): return [x[len(key):] for x in self.sections() \ if x.startswith(key)] + def set_if_not_exists(self, section, option, value): + """Set a value if it does not exist yet + + This allows to set default if the user has not explicitly + configured anything.""" + if not self.has_option(section, option): + self.set(section, option, value) + def CustomConfigDefault(): """Just a constant that won't occur anywhere else. From b7e0a51751ac95138095969121c612f34047e52d Mon Sep 17 00:00:00 2001 From: Sebastian Spaeth Date: Thu, 15 Sep 2011 13:24:48 +0200 Subject: [PATCH 34/58] Add command line option --dry-run And set the [general]dry-run=True setting if yes. It is not used yet. Also set ui.dryrun to True so we can output what WE WOULD HAVE DONE in dryrun mode. Signed-off-by: Sebastian Spaeth --- offlineimap/init.py | 13 +++++++++++++ offlineimap/ui/UIBase.py | 2 ++ 2 files changed, 15 insertions(+) diff --git a/offlineimap/init.py b/offlineimap/init.py index 51d535d..d381a65 100644 --- a/offlineimap/init.py +++ b/offlineimap/init.py @@ -52,6 +52,13 @@ class OfflineImap: description="%s.\n\n%s" % (offlineimap.__copyright__, offlineimap.__license__)) + parser.add_option("--dry-run", + action="store_true", dest="dryrun", + default=False, + help="Do not actually modify any store but check and print " + "what synchronization actions would be taken if a sync would be" + " performed.") + parser.add_option("-1", action="store_true", dest="singlethreading", default=False, @@ -201,6 +208,12 @@ class OfflineImap: logging.warning('Using old interface name, consider using one ' 'of %s' % ', '.join(UI_LIST.keys())) if options.diagnostics: ui_type = 'basic' # enforce basic UI for --info + + #dry-run? Set [general]dry-run=True + if options.dryrun: + dryrun = config.set('general','dry-run', "True") + config.set_if_not_exists('general','dry-run','False') + try: # create the ui class self.ui = UI_LIST[ui_type.lower()](config) diff --git a/offlineimap/ui/UIBase.py b/offlineimap/ui/UIBase.py index a8aeeaf..d716968 100644 --- a/offlineimap/ui/UIBase.py +++ b/offlineimap/ui/UIBase.py @@ -48,6 +48,8 @@ def getglobalui(): class UIBase(object): def __init__(self, config, loglevel = logging.INFO): self.config = config + # Is this a 'dryrun'? + self.dryrun = config.getboolean('general', 'dry-run') self.debuglist = [] """list of debugtypes we are supposed to log""" self.debugmessages = {} From 33f55b5362f6edef64d00bb41206d083ff285d73 Mon Sep 17 00:00:00 2001 From: Sebastian Spaeth Date: Thu, 15 Sep 2011 13:56:04 +0200 Subject: [PATCH 35/58] Implement dry-run on Account() level 1) Set attribute self.dryrun depending on whether we are in dry-run mode. 2) Don't actually call hooks in --dry-run (just log what you would invoke 3) Don't write out the mbnames file in --dry-run mode. Repository, and Folder levels still need to be protected in dry-run mode as of now. Signed-off-by: Sebastian Spaeth --- offlineimap/accounts.py | 10 ++++++++-- offlineimap/ui/UIBase.py | 5 ++++- 2 files changed, 12 insertions(+), 3 deletions(-) diff --git a/offlineimap/accounts.py b/offlineimap/accounts.py index ed08cad..8b39c7e 100644 --- a/offlineimap/accounts.py +++ b/offlineimap/accounts.py @@ -65,9 +65,11 @@ class Account(CustomConfig.ConfigHelperMixin): self.name = name self.metadatadir = config.getmetadatadir() self.localeval = config.getlocaleval() - #Contains the current :mod:`offlineimap.ui`, and can be used for logging etc. + # current :mod:`offlineimap.ui`, can be used for logging: self.ui = getglobalui() self.refreshperiod = self.getconffloat('autorefresh', 0.0) + # should we run in "dry-run" mode? + self.dryrun = self.config.getboolean('general', 'dry-run') self.quicknum = 0 if self.refreshperiod == 0.0: self.refreshperiod = None @@ -312,7 +314,9 @@ class SyncableAccount(Account): # wait for all threads to finish for thr in folderthreads: thr.join() - mbnames.write() + # Write out mailbox names if required and not in dry-run mode + if not self.dryrun: + mbnames.write() localrepos.forgetfolders() remoterepos.forgetfolders() except: @@ -337,6 +341,8 @@ class SyncableAccount(Account): return try: self.ui.callhook("Calling hook: " + cmd) + if self.dryrun: # don't if we are in dry-run mode + return p = Popen(cmd, shell=True, stdin=PIPE, stdout=PIPE, stderr=PIPE, close_fds=True) diff --git a/offlineimap/ui/UIBase.py b/offlineimap/ui/UIBase.py index d716968..da77b5a 100644 --- a/offlineimap/ui/UIBase.py +++ b/offlineimap/ui/UIBase.py @@ -461,7 +461,10 @@ class UIBase(object): ################################################## Hooks def callhook(self, msg): - self.info(msg) + if self.dryrun: + self.info("[DRYRUN] {}".format(msg)) + else: + self.info(msg) ################################################## Other From b6807355b5133dae5c669381aa9965f44c38b7a0 Mon Sep 17 00:00:00 2001 From: Sebastian Spaeth Date: Thu, 15 Sep 2011 15:37:52 +0200 Subject: [PATCH 36/58] Implement ui.makefolder and abort repo.makefolder() in dry-run mode IMAP, Maildir, and LocalStatus abort if in dry-run mode. IMAP and Maildir will log that they "would have" created a new folder. This will probably fail later on as we can not cache messagelists on folder that don't exist, so --dry-run is not yet safe when new folders have been created. Signed-off-by: Sebastian Spaeth --- offlineimap/repository/Base.py | 1 + offlineimap/repository/IMAP.py | 6 +++--- offlineimap/repository/LocalStatus.py | 7 ++++--- offlineimap/repository/Maildir.py | 4 +++- offlineimap/ui/UIBase.py | 6 ++++++ 5 files changed, 17 insertions(+), 7 deletions(-) diff --git a/offlineimap/repository/Base.py b/offlineimap/repository/Base.py index e855210..606294e 100644 --- a/offlineimap/repository/Base.py +++ b/offlineimap/repository/Base.py @@ -124,6 +124,7 @@ class BaseRepository(CustomConfig.ConfigHelperMixin, object): raise NotImplementedError def makefolder(self, foldername): + """Create a new folder""" raise NotImplementedError def deletefolder(self, foldername): diff --git a/offlineimap/repository/IMAP.py b/offlineimap/repository/IMAP.py index 1b13d79..28e73b7 100644 --- a/offlineimap/repository/IMAP.py +++ b/offlineimap/repository/IMAP.py @@ -341,11 +341,11 @@ class IMAPRepository(BaseRepository): foldername = self.getreference() + self.getsep() + foldername if not foldername: # Create top level folder as folder separator foldername = self.getsep() - + self.ui.makefolder(self, foldername) + if self.account.dryrun: + return imapobj = self.imapserver.acquireconnection() try: - self.ui._msg("Creating new IMAP folder '%s' on server %s" %\ - (foldername, self)) result = imapobj.create(foldername) if result[0] != 'OK': raise OfflineImapError("Folder '%s'[%s] could not be created. " diff --git a/offlineimap/repository/LocalStatus.py b/offlineimap/repository/LocalStatus.py index 30c8560..3e5db2f 100644 --- a/offlineimap/repository/LocalStatus.py +++ b/offlineimap/repository/LocalStatus.py @@ -67,10 +67,11 @@ class LocalStatusRepository(BaseRepository): Empty Folder for plain backend. NoOp for sqlite backend as those are created on demand.""" - # Invalidate the cache. - self._folders = None if self._backend == 'sqlite': - return + return # noop for sqlite which creates on-demand + + if self.account.dryrun: + return # bail out in dry-run mode filename = self.getfolderfilename(foldername) file = open(filename + ".tmp", "wt") diff --git a/offlineimap/repository/Maildir.py b/offlineimap/repository/Maildir.py index 7c08d64..f197002 100644 --- a/offlineimap/repository/Maildir.py +++ b/offlineimap/repository/Maildir.py @@ -81,7 +81,9 @@ class MaildirRepository(BaseRepository): levels will be created if they do not exist yet. 'cur', 'tmp', and 'new' subfolders will be created in the maildir. """ - self.debug("makefolder called with arg '%s'" % (foldername)) + self.ui.makefolder(self, foldername) + if self.account.dryrun: + return full_path = os.path.abspath(os.path.join(self.root, foldername)) # sanity tests diff --git a/offlineimap/ui/UIBase.py b/offlineimap/ui/UIBase.py index da77b5a..4ff98c3 100644 --- a/offlineimap/ui/UIBase.py +++ b/offlineimap/ui/UIBase.py @@ -298,6 +298,12 @@ class UIBase(object): (src_repo, dst_repo)) ############################## Folder syncing + def makefolder(self, repo, foldername): + """Called when a folder is created""" + prefix = "[DRYRUN] " if self.dryrun else "" + self.info("{}Creating folder {}[{}]".format( + prefix, foldername, repo)) + def syncingfolder(self, srcrepos, srcfolder, destrepos, destfolder): """Called when a folder sync operation is started.""" self.logger.info("Syncing %s: %s -> %s" % (srcfolder, From 5ef69e95c02f69f0a13818d418e6a5768bd4be04 Mon Sep 17 00:00:00 2001 From: Sebastian Spaeth Date: Fri, 16 Sep 2011 11:44:50 +0200 Subject: [PATCH 37/58] Prevent modifications on a folder level to occur in dry-run Prevent savemessage(), and savemessageflags() to occur in dryrun mode in all backends. Still need to protect against deletemessage(). Signed-off-by: Sebastian Spaeth --- offlineimap/folder/Base.py | 37 +++++++++++++++++++++++-- offlineimap/folder/IMAP.py | 12 ++++++-- offlineimap/folder/LocalStatus.py | 5 ++++ offlineimap/folder/LocalStatusSQLite.py | 5 ++++ offlineimap/folder/Maildir.py | 14 ++++++++-- offlineimap/folder/UIDMaps.py | 10 +++++++ offlineimap/ui/UIBase.py | 5 ++++ 7 files changed, 81 insertions(+), 7 deletions(-) diff --git a/offlineimap/folder/Base.py b/offlineimap/folder/Base.py index fcea99d..01a6ab5 100644 --- a/offlineimap/folder/Base.py +++ b/offlineimap/folder/Base.py @@ -208,6 +208,10 @@ class BaseFolder(object): If the uid is > 0, the backend should set the uid to this, if it can. If it cannot set the uid to that, it will save it anyway. It will return the uid assigned in any case. + + Note that savemessage() does not check against dryrun settings, + so you need to ensure that savemessage is never called in a + dryrun mode. """ raise NotImplementedException @@ -220,27 +224,48 @@ class BaseFolder(object): raise NotImplementedException def savemessageflags(self, uid, flags): - """Sets the specified message's flags to the given set.""" + """Sets the specified message's flags to the given set. + + Note that this function does not check against dryrun settings, + so you need to ensure that it is never called in a + dryrun mode.""" raise NotImplementedException def addmessageflags(self, uid, flags): """Adds the specified flags to the message's flag set. If a given flag is already present, it will not be duplicated. + + Note that this function does not check against dryrun settings, + so you need to ensure that it is never called in a + dryrun mode. + :param flags: A set() of flags""" newflags = self.getmessageflags(uid) | flags self.savemessageflags(uid, newflags) def addmessagesflags(self, uidlist, flags): + """ + Note that this function does not check against dryrun settings, + so you need to ensure that it is never called in a + dryrun mode.""" for uid in uidlist: self.addmessageflags(uid, flags) def deletemessageflags(self, uid, flags): """Removes each flag given from the message's flag set. If a given - flag is already removed, no action will be taken for that flag.""" + flag is already removed, no action will be taken for that flag. + + Note that this function does not check against dryrun settings, + so you need to ensure that it is never called in a + dryrun mode.""" newflags = self.getmessageflags(uid) - flags self.savemessageflags(uid, newflags) def deletemessagesflags(self, uidlist, flags): + """ + Note that this function does not check against dryrun settings, + so you need to ensure that it is never called in a + dryrun mode.""" for uid in uidlist: self.deletemessageflags(uid, flags) @@ -345,6 +370,10 @@ class BaseFolder(object): statusfolder.uidexists(uid), self.getmessageuidlist()) num_to_copy = len(copylist) + if num_to_copy and self.repository.account.dryrun: + self.ui.info("[DRYRUN] Copy {} messages from {}[{}] to {}".format( + num_to_copy, self, self.repository, dstfolder.repository)) + return for num, uid in enumerate(copylist): # bail out on CTRL-C or SIGTERM if offlineimap.accounts.Account.abort_NOW_signal.is_set(): @@ -422,11 +451,15 @@ class BaseFolder(object): for flag, uids in addflaglist.items(): self.ui.addingflags(uids, flag, dstfolder) + if self.repository.account.dryrun: + continue #don't actually add in a dryrun dstfolder.addmessagesflags(uids, set(flag)) statusfolder.addmessagesflags(uids, set(flag)) for flag,uids in delflaglist.items(): self.ui.deletingflags(uids, flag, dstfolder) + if self.repository.account.dryrun: + continue #don't actually remove in a dryrun dstfolder.deletemessagesflags(uids, set(flag)) statusfolder.deletemessagesflags(uids, set(flag)) diff --git a/offlineimap/folder/IMAP.py b/offlineimap/folder/IMAP.py index 8b46996..f783d22 100644 --- a/offlineimap/folder/IMAP.py +++ b/offlineimap/folder/IMAP.py @@ -488,12 +488,16 @@ class IMAPFolder(BaseFolder): This function will update the self.messagelist dict to contain the new message after sucessfully saving it. + See folder/Base for details. Note that savemessage() does not + check against dryrun settings, so you need to ensure that + savemessage is never called in a dryrun mode. + :param rtime: A timestamp to be used as the mail date :returns: the UID of the new message as assigned by the server. If the message is saved, but it's UID can not be found, it will return 0. If the message can't be written (folder is read-only for example) it will return -1.""" - self.ui.debug('imap', 'savemessage: called') + self.ui.savemessage('imap', uid, flags, self) # already have it, just save modified flags if uid > 0 and self.uidexists(uid): @@ -611,7 +615,11 @@ class IMAPFolder(BaseFolder): return uid def savemessageflags(self, uid, flags): - """Change a message's flags to `flags`.""" + """Change a message's flags to `flags`. + + Note that this function does not check against dryrun settings, + so you need to ensure that it is never called in a + dryrun mode.""" imapobj = self.imapserver.acquireconnection() try: try: diff --git a/offlineimap/folder/LocalStatus.py b/offlineimap/folder/LocalStatus.py index 7f27768..b3779fd 100644 --- a/offlineimap/folder/LocalStatus.py +++ b/offlineimap/folder/LocalStatus.py @@ -111,6 +111,11 @@ class LocalStatusFolder(BaseFolder): return self.messagelist def savemessage(self, uid, content, flags, rtime): + """Writes a new message, with the specified uid. + + See folder/Base for detail. Note that savemessage() does not + check against dryrun settings, so you need to ensure that + savemessage is never called in a dryrun mode.""" if uid < 0: # We cannot assign a uid. return uid diff --git a/offlineimap/folder/LocalStatusSQLite.py b/offlineimap/folder/LocalStatusSQLite.py index dbe3e66..ac67c2f 100644 --- a/offlineimap/folder/LocalStatusSQLite.py +++ b/offlineimap/folder/LocalStatusSQLite.py @@ -216,6 +216,11 @@ class LocalStatusSQLiteFolder(LocalStatusFolder): # assert False,"getmessageflags() called on non-existing message" def savemessage(self, uid, content, flags, rtime): + """Writes a new message, with the specified uid. + + See folder/Base for detail. Note that savemessage() does not + check against dryrun settings, so you need to ensure that + savemessage is never called in a dryrun mode.""" if uid < 0: # We cannot assign a uid. return uid diff --git a/offlineimap/folder/Maildir.py b/offlineimap/folder/Maildir.py index 16745ab..24d943c 100644 --- a/offlineimap/folder/Maildir.py +++ b/offlineimap/folder/Maildir.py @@ -237,13 +237,18 @@ class MaildirFolder(BaseFolder): uid, self._foldermd5, self.infosep, ''.join(sorted(flags))) def savemessage(self, uid, content, flags, rtime): + """Writes a new message, with the specified uid. + + See folder/Base for detail. Note that savemessage() does not + check against dryrun settings, so you need to ensure that + savemessage is never called in a dryrun mode.""" # This function only ever saves to tmp/, # but it calls savemessageflags() to actually save to cur/ or new/. - self.ui.debug('maildir', 'savemessage: called to write with flags %s ' - 'and content %s' % (repr(flags), repr(content))) + self.ui.savemessage('maildir', uid, flags, self) if uid < 0: # We cannot assign a new uid. return uid + if uid in self.messagelist: # We already have it, just update flags. self.savemessageflags(uid, flags) @@ -291,8 +296,11 @@ class MaildirFolder(BaseFolder): """Sets the specified message's flags to the given set. This function moves the message to the cur or new subdir, - depending on the 'S'een flag.""" + depending on the 'S'een flag. + Note that this function does not check against dryrun settings, + so you need to ensure that it is never called in a + dryrun mode.""" oldfilename = self.messagelist[uid]['filename'] dir_prefix, filename = os.path.split(oldfilename) # If a message has been seen, it goes into 'cur' diff --git a/offlineimap/folder/UIDMaps.py b/offlineimap/folder/UIDMaps.py index 99ad2d3..f1c11e4 100644 --- a/offlineimap/folder/UIDMaps.py +++ b/offlineimap/folder/UIDMaps.py @@ -184,7 +184,12 @@ class MappedIMAPFolder(IMAPFolder): If the uid is > 0, the backend should set the uid to this, if it can. If it cannot set the uid to that, it will save it anyway. It will return the uid assigned in any case. + + See folder/Base for details. Note that savemessage() does not + check against dryrun settings, so you need to ensure that + savemessage is never called in a dryrun mode. """ + self.ui.savemessage('imap', uid, flags, self) # Mapped UID instances require the source to already have a # positive UID, so simply return here. if uid < 0: @@ -217,6 +222,11 @@ class MappedIMAPFolder(IMAPFolder): return None def savemessageflags(self, uid, flags): + """ + + Note that this function does not check against dryrun settings, + so you need to ensure that it is never called in a + dryrun mode.""" self._mb.savemessageflags(self.r2l[uid], flags) def addmessageflags(self, uid, flags): diff --git a/offlineimap/ui/UIBase.py b/offlineimap/ui/UIBase.py index 4ff98c3..32511a4 100644 --- a/offlineimap/ui/UIBase.py +++ b/offlineimap/ui/UIBase.py @@ -408,6 +408,11 @@ class UIBase(object): if conn: #release any existing IMAP connection repository.imapserver.close() + def savemessage(self, debugtype, uid, flags, folder): + """Output a log line stating that we save a msg""" + self.debug(debugtype, "Write mail '%s:%d' with flags %s" % + (folder, uid, repr(flags))) + ################################################## Threads def getThreadDebugLog(self, thread): From 256a26a64911ceebe6ed004600f96e3d03e62f62 Mon Sep 17 00:00:00 2001 From: Sebastian Spaeth Date: Fri, 17 Feb 2012 11:43:41 +0100 Subject: [PATCH 38/58] dry-run mode: Protect us from actually deleting a message in dry-run mode Document which functions honor dry-run mode and which don't. Signed-off-by: Sebastian Spaeth --- offlineimap/folder/Base.py | 23 ++++++++++++++++++++++- offlineimap/ui/UIBase.py | 5 +++-- 2 files changed, 25 insertions(+), 3 deletions(-) diff --git a/offlineimap/folder/Base.py b/offlineimap/folder/Base.py index 01a6ab5..77cc8ad 100644 --- a/offlineimap/folder/Base.py +++ b/offlineimap/folder/Base.py @@ -279,15 +279,27 @@ class BaseFolder(object): raise NotImplementedException def deletemessage(self, uid): + """ + Note that this function does not check against dryrun settings, + so you need to ensure that it is never called in a + dryrun mode.""" raise NotImplementedException def deletemessages(self, uidlist): + """ + Note that this function does not check against dryrun settings, + so you need to ensure that it is never called in a + dryrun mode.""" for uid in uidlist: self.deletemessage(uid) def copymessageto(self, uid, dstfolder, statusfolder, register = 1): """Copies a message from self to dst if needed, updating the status + Note that this function does not check against dryrun settings, + so you need to ensure that it is never called in a + dryrun mode. + :param uid: uid of the message to be copied. :param dstfolder: A BaseFolder-derived instance :param statusfolder: A LocalStatusFolder instance @@ -363,6 +375,8 @@ class BaseFolder(object): 2) invoke copymessageto() on those which: - If dstfolder doesn't have it yet, add them to dstfolder. - Update statusfolder + + This function checks and protects us from action in ryrun mode. """ threads = [] @@ -400,12 +414,17 @@ class BaseFolder(object): Get all UIDS in statusfolder but not self. These are messages that were deleted in 'self'. Delete those from dstfolder and - statusfolder.""" + statusfolder. + + This function checks and protects us from action in ryrun mode. + """ deletelist = filter(lambda uid: uid>=0 \ and not self.uidexists(uid), statusfolder.getmessageuidlist()) if len(deletelist): self.ui.deletingmessages(deletelist, [dstfolder]) + if self.repository.account.dryrun: + return #don't delete messages in dry-run mode # delete in statusfolder first to play safe. In case of abort, we # won't lose message, we will just retransmit some unneccessary. for folder in [statusfolder, dstfolder]: @@ -418,6 +437,8 @@ class BaseFolder(object): msg has a valid UID and exists on dstfolder (has not e.g. been deleted there), sync the flag change to both dstfolder and statusfolder. + + This function checks and protects us from action in ryrun mode. """ # For each flag, we store a list of uids to which it should be # added. Then, we can call addmessagesflags() to apply them in diff --git a/offlineimap/ui/UIBase.py b/offlineimap/ui/UIBase.py index 32511a4..4bf4423 100644 --- a/offlineimap/ui/UIBase.py +++ b/offlineimap/ui/UIBase.py @@ -345,8 +345,9 @@ class UIBase(object): def deletingmessages(self, uidlist, destlist): ds = self.folderlist(destlist) - self.logger.info("Deleting %d messages (%s) in %s" % ( - len(uidlist), + prefix = "[DRYRUN] " if self.dryrun else "" + self.info("{}Deleting {} messages ({}) in {}".format( + prefix, len(uidlist), offlineimap.imaputil.uid_sequence(uidlist), ds)) def addingflags(self, uidlist, flags, dest): From 3a73d4bf6426a397c8d07f070cefd188ce6e8784 Mon Sep 17 00:00:00 2001 From: Sebastian Spaeth Date: Fri, 17 Feb 2012 11:59:27 +0100 Subject: [PATCH 39/58] Add Changelog entry for dry-run mode Signed-off-by: Sebastian Spaeth --- Changelog.draft.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/Changelog.draft.rst b/Changelog.draft.rst index a612ab8..cd252b3 100644 --- a/Changelog.draft.rst +++ b/Changelog.draft.rst @@ -13,6 +13,12 @@ others. New Features ------------ +* --dry-run mode protects us from performing any actual action. + It will not precisely give the exact information what will + happen. If e.g. it would need to create a folder, it merely + outputs "Would create folder X", but not how many and which mails + it would transfer. + Changes ------- From aa01fe754a3c79d0a68a27ae6255335f93775b70 Mon Sep 17 00:00:00 2001 From: Sebastian Spaeth Date: Fri, 17 Feb 2012 11:59:37 +0100 Subject: [PATCH 40/58] Improve command line option help text Shuffle around and update command line option descriptions in the docs. Signed-off-by: Sebastian Spaeth --- docs/MANUAL.rst | 97 +++----------------------------- docs/dev-doc-src/offlineimap.rst | 9 +++ offlineimap/init.py | 55 ++++++++++-------- 3 files changed, 46 insertions(+), 115 deletions(-) diff --git a/docs/MANUAL.rst b/docs/MANUAL.rst index 8d7a8b7..9715cb8 100644 --- a/docs/MANUAL.rst +++ b/docs/MANUAL.rst @@ -43,6 +43,10 @@ Most configuration is done via the configuration file. However, any setting can OfflineImap is well suited to be frequently invoked by cron jobs, or can run in daemon mode to periodically check your email (however, it will exit in some error situations). +The documentation is included in the git repository and can be created by +issueing `make dev-doc` in the `doc` folder (python-sphinx required), or it can +be viewed online at `http://docs.offlineimap.org`_. + .. _configuration: Configuration @@ -66,96 +70,9 @@ Check out the `Use Cases`_ section for some example configurations. OPTIONS ======= - --1 Disable most multithreading operations - - Use solely a single-connection sync. This effectively sets the - maxsyncaccounts and all maxconnections configuration file variables to 1. - - --P profiledir - - Sets OfflineIMAP into profile mode. The program will create profiledir (it - must not already exist). As it runs, Python profiling information about each - thread is logged into profiledir. Please note: This option is present for - debugging and optimization only, and should NOT be used unless you have a - specific reason to do so. It will significantly slow program performance, may - reduce reliability, and can generate huge amounts of data. You must use the - -1 option when you use -P. - - --a accountlist - - Overrides the accounts option in the general section of the configuration - file. You might use this to exclude certain accounts, or to sync some - accounts that you normally prefer not to. Separate the accounts by commas, - and use no embedded spaces. - - --c configfile - - Specifies a configuration file to use in lieu of the default, - ``~/.offlineimaprc``. - - --d debugtype[,...] - - Enables debugging for OfflineIMAP. This is useful if you are trying to track - down a malfunction or figure out what is going on under the hood. I suggest - that you use this with -1 to make the results more sensible. - - -d requires one or more debugtypes, separated by commas. These define what - exactly will be debugged, and include three options: imap, maildir, and - thread. The imap option will enable IMAP protocol stream and parsing - debugging. Note that the output may contain passwords, so take care to remove - that from the debugging output before sending it to anyone else. The maildir - option will enable debugging for certain Maildir operations. And thread will - debug the threading model. - - --f foldername[,foldername] - - Only sync the specified folders. The foldernames are the untranslated - foldernames. This command-line option overrides any folderfilter and - folderincludes options in the configuration file. - - --k [section:]option=value - - Override configuration file option. If "section" is omitted, it defaults to - general. Any underscores "_" in the section name are replaced with spaces: - for instance, to override option autorefresh in the "[Account Personal]" - section in the config file one would use "-k Account_Personal:autorefresh=30". - You may give more than one -k on the command line if you wish. - - --l filename - - Enables logging to filename. This will log everything that goes to the screen - to the specified file. Additionally, if any debugging is specified with -d, - then debug messages will not go to the screen, but instead to the logfile - only. - - --o Run only once, - - ignoring all autorefresh settings in the configuration file. - - --q Run only quick synchronizations. - - Ignore any flag updates on IMAP servers. - - --h|--help Show summary of options. - - --u interface - - Specifies an alternative user interface module to use. This overrides the - default specified in the configuration file. The pre-defined options are - listed in the User Interfaces section. The interface name is case insensitive. - +The command line options are described by issueing `offlineimap --help`. +Details on their use can be found either in the sample offlineimap.conf file or +in the user docs at `http://docs.offlineimap.org`_. User Interfaces =============== diff --git a/docs/dev-doc-src/offlineimap.rst b/docs/dev-doc-src/offlineimap.rst index bc98c16..37d78dc 100644 --- a/docs/dev-doc-src/offlineimap.rst +++ b/docs/dev-doc-src/offlineimap.rst @@ -6,6 +6,15 @@ Offlineimap is invoked with the following pattern: `offlineimap [args...]`. Where [args...] are as follows: Options: + --dry-run This mode protects us from performing any actual action. + It will not precisely give the exact information what + will happen. If e.g. it would need to create a folder, + it merely outputs "Would create folder X", but not how + many and which mails it would transfer. + --info Output information on the configured email + repositories. Useful for debugging and bug reporting. + Use in conjunction with the -a option to limit the + output to a single account. --version show program's version number and exit -h, --help show this help message and exit -1 Disable all multithreading operations and use solely a diff --git a/offlineimap/init.py b/offlineimap/init.py index d381a65..8668cc1 100644 --- a/offlineimap/init.py +++ b/offlineimap/init.py @@ -57,7 +57,19 @@ class OfflineImap: default=False, help="Do not actually modify any store but check and print " "what synchronization actions would be taken if a sync would be" - " performed.") + " performed. It will not precisely give the exact information w" + "hat will happen. If e.g. we need to create a folder, it merely" + " outputs 'Would create folder X', but not how many and which m" + "ails it would transfer.") + + parser.add_option("--info", + action="store_true", dest="diagnostics", + default=False, + help="Output information on the configured email repositories" + ". Useful for debugging and bug reporting. Use in conjunction wit" + "h the -a option to limit the output to a single account. This mo" + "de will prevent any actual sync to occur and exits after it outp" + "ut the debug information.") parser.add_option("-1", action="store_true", dest="singlethreading", @@ -80,11 +92,11 @@ class OfflineImap: "implies the -1 option.") parser.add_option("-a", dest="accounts", metavar="ACCOUNTS", - help="""Overrides the accounts section in the config file. - Lets you specify a particular account or set of - accounts to sync without having to edit the config - file. You might use this to exclude certain accounts, - or to sync some accounts that you normally prefer not to.""") + help="Overrides the accounts section in the config file. " + "Lets you specify a particular account or set of " + "accounts to sync without having to edit the config " + "file. You might use this to exclude certain accounts, " + "or to sync some accounts that you normally prefer not to.") parser.add_option("-c", dest="configfile", metavar="FILE", default="~/.offlineimaprc", @@ -92,18 +104,18 @@ class OfflineImap: "%default.") parser.add_option("-d", dest="debugtype", metavar="type1,[type2...]", - help="""Enables debugging for OfflineIMAP. This is useful - if you are to track down a malfunction or figure out what is - going on under the hood. This option requires one or more - debugtypes, separated by commas. These define what exactly - will be debugged, and so far include two options: imap, thread, - maildir or ALL. The imap option will enable IMAP protocol - stream and parsing debugging. Note that the output may contain - passwords, so take care to remove that from the debugging - output before sending it to anyone else. The maildir option - will enable debugging for certain Maildir operations. - The use of any debug option (unless 'thread' is included), - implies the single-thread option -1.""") + help="Enables debugging for OfflineIMAP. This is useful " + "if you are to track down a malfunction or figure out what is " + "going on under the hood. This option requires one or more " + "debugtypes, separated by commas. These define what exactly " + "will be debugged, and so far include two options: imap, thread, " + "maildir or ALL. The imap option will enable IMAP protocol " + "stream and parsing debugging. Note that the output may contain " + "passwords, so take care to remove that from the debugging " + "output before sending it to anyone else. The maildir option " + "will enable debugging for certain Maildir operations. " + "The use of any debug option (unless 'thread' is included), " + "implies the single-thread option -1.") parser.add_option("-l", dest="logfile", metavar="FILE", help="Log to FILE") @@ -149,13 +161,6 @@ class OfflineImap: "not usable. Possible interface choices are: %s " % ", ".join(UI_LIST.keys())) - parser.add_option("--info", - action="store_true", dest="diagnostics", - default=False, - help="Output information on the configured email repositories" - ". Useful for debugging and bug reporting. Use in conjunction wit" - "h the -a option to limit the output to a single account") - (options, args) = parser.parse_args() #read in configuration file From 40bc1f50e7b0605522feb4ac86daebb9f785eb88 Mon Sep 17 00:00:00 2001 From: Sebastian Spaeth Date: Fri, 17 Feb 2012 13:22:05 +0100 Subject: [PATCH 41/58] tests: Use only 1 IMAP connection by default We don't want to hammmer IMAP servers for the test series too much to avoid being locked out. We will need a few tests to test concurrent connections, but by default one connection should be fine. Signed-off-by: Sebastian Spaeth --- test/OLItest/globals.py | 2 ++ 1 file changed, 2 insertions(+) diff --git a/test/OLItest/globals.py b/test/OLItest/globals.py index 5d1f122..88806f2 100644 --- a/test/OLItest/globals.py +++ b/test/OLItest/globals.py @@ -33,5 +33,7 @@ localfolders = [Repository IMAP] type=IMAP +# Don't hammer the server with too many connection attempts: +maxconnections=1 folderfilter= lambda f: f.startswith('INBOX.OLItest') """) From d0723fb8a210d5c9eb412fa44438796ac74605ae Mon Sep 17 00:00:00 2001 From: Sebastian Spaeth Date: Fri, 17 Feb 2012 14:08:05 +0100 Subject: [PATCH 42/58] python3: Fix import in tests to work with python3 DOH Signed-off-by: Sebastian Spaeth --- test/OLItest/__init__.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/test/OLItest/__init__.py b/test/OLItest/__init__.py index 2f85210..6fcd52f 100644 --- a/test/OLItest/__init__.py +++ b/test/OLItest/__init__.py @@ -30,5 +30,5 @@ banner = """%(__productname__)s %(__version__)s import unittest from unittest import TestLoader, TextTestRunner -from globals import default_conf +from .globals import default_conf from TestRunner import OLITestLib From d1e6e1f09e5fe5d492a3db677c9e811af85b2658 Mon Sep 17 00:00:00 2001 From: Sebastian Spaeth Date: Fri, 17 Feb 2012 14:57:11 +0100 Subject: [PATCH 43/58] tests: make tests (nearly) work with python3 Tests work now with python 3 with the exception of the deletion of remote testfolders which fails for some reasons. Signed-off-by: Sebastian Spaeth --- test/OLItest/TestRunner.py | 28 ++++++++++++++++------------ test/OLItest/__init__.py | 2 +- test/OLItest/globals.py | 5 ++++- test/tests/test_01_basic.py | 2 +- 4 files changed, 22 insertions(+), 15 deletions(-) diff --git a/test/OLItest/TestRunner.py b/test/OLItest/TestRunner.py index e6277f2..7a2bb51 100644 --- a/test/OLItest/TestRunner.py +++ b/test/OLItest/TestRunner.py @@ -22,7 +22,10 @@ import sys import shutil import subprocess import tempfile -from ConfigParser import SafeConfigParser +try: + from configparser import SafeConfigParser +except ImportError: # python 2 + from ConfigParser import SafeConfigParser from . import default_conf class OLITestLib(): @@ -90,7 +93,7 @@ class OLITestLib(): config = cls.get_default_config() localfolders = os.path.join(cls.testdir, 'mail') config.set("Repository Maildir", "localfolders", localfolders) - with open(os.path.join(cls.testdir, 'offlineimap.conf'), "wa") as f: + with open(os.path.join(cls.testdir, 'offlineimap.conf'), "wt") as f: config.write(f) @classmethod @@ -105,7 +108,7 @@ class OLITestLib(): def run_OLI(cls): """Runs OfflineImap - :returns: (rescode, stdout) + :returns: (rescode, stdout (as unicode)) """ try: output = subprocess.check_output( @@ -113,8 +116,8 @@ class OLITestLib(): "-c%s" % os.path.join(cls.testdir, 'offlineimap.conf')], shell=False) except subprocess.CalledProcessError as e: - return (e.returncode, e.output) - return (0, output) + return (e.returncode, e.output.decode('utf-8')) + return (0, output.decode('utf-8')) @classmethod def delete_remote_testfolders(cls, reponame=None): @@ -128,7 +131,7 @@ class OLITestLib(): sections = [r for r in config.sections() \ if r.startswith('Repository')] sections = filter(lambda s: \ - config.get(s, 'Type', None).lower() == 'imap', + config.get(s, 'Type').lower() == 'imap', sections) for sec in sections: # Connect to each IMAP repo and delete all folders @@ -144,21 +147,22 @@ class OLITestLib(): assert res_t == 'OK' dirs = [] for d in data: - m = re.search(r''' # Find last quote + m = re.search(br''' # Find last quote "((?: # Non-tripple quoted can contain... [^"] | # a non-quote \\" # a backslashded quote )*)" # closing quote [^"]*$ # followed by no more quotes ''', d, flags=re.VERBOSE) - folder = m.group(1) - folder = folder.replace(r'\"', '"') # remove quoting + folder = bytearray(m.group(1)) + folder = folder.replace(br'\"', b'"') # remove quoting dirs.append(folder) # 2) filter out those not starting with INBOX.OLItest and del... - dirs = [d for d in dirs if d.startswith('INBOX.OLItest')] + dirs = [d for d in dirs if d.startswith(b'INBOX.OLItest')] for folder in dirs: - res_t, data = imapobj.delete(folder) - assert res_t == 'OK' + res_t, data = imapobj.delete(str(folder)) + assert res_t == 'OK', "Folder deletion of {} failed with error"\ + ":\n{} {}".format(folder.decode('utf-8'), res_t, data) imapobj.logout() @classmethod diff --git a/test/OLItest/__init__.py b/test/OLItest/__init__.py index 6fcd52f..ca6ef61 100644 --- a/test/OLItest/__init__.py +++ b/test/OLItest/__init__.py @@ -31,4 +31,4 @@ banner = """%(__productname__)s %(__version__)s import unittest from unittest import TestLoader, TextTestRunner from .globals import default_conf -from TestRunner import OLITestLib +from .TestRunner import OLITestLib diff --git a/test/OLItest/globals.py b/test/OLItest/globals.py index 88806f2..8e69ee8 100644 --- a/test/OLItest/globals.py +++ b/test/OLItest/globals.py @@ -14,7 +14,10 @@ # You should have received a copy of the GNU General Public License # along with this program; if not, write to the Free Software # Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA -from cStringIO import StringIO +try: + from cStringIO import StringIO +except ImportError: #python3 + from io import StringIO default_conf=StringIO("""[general] #will be set automatically diff --git a/test/tests/test_01_basic.py b/test/tests/test_01_basic.py index 0967d9d..6cda54e 100644 --- a/test/tests/test_01_basic.py +++ b/test/tests/test_01_basic.py @@ -65,7 +65,7 @@ class TestBasicFunctions(unittest.TestCase): code, res = OLITestLib.run_OLI() self.assertEqual(res, "") boxes, mails = OLITestLib.count_maildir_mails('') - self.assertTrue((boxes, mails)==(0,0), msg="Expected 0 folders and 0" + self.assertTrue((boxes, mails)==(0,0), msg="Expected 0 folders and 0 " "mails, but sync led to {} folders and {} mails".format( boxes, mails)) From bc73c11239124aa668321b45ab5d4b3a94ca8054 Mon Sep 17 00:00:00 2001 From: Sebastian Spaeth Date: Fri, 24 Feb 2012 08:31:31 +0100 Subject: [PATCH 44/58] Revert "Don't CHECK imapserver after each APPEND" This reverts commit 47390e03d6a07b2ab73b65b74b668b7ce0663f57. It is one of two potential candidates for the APPENDUID regression that John Wiegley reported. We need to examine this carefully before reintroducing this patch. Resolved Changelog.draft.rst conflict. --- Changelog.draft.rst | 2 ++ offlineimap/folder/IMAP.py | 9 ++++----- 2 files changed, 6 insertions(+), 5 deletions(-) diff --git a/Changelog.draft.rst b/Changelog.draft.rst index cd252b3..61dbe35 100644 --- a/Changelog.draft.rst +++ b/Changelog.draft.rst @@ -30,6 +30,8 @@ Changes we would not propagate local folders to the remote repository. (now tested in test03) +* Revert "* Slight performance enhancement uploading mails to an IMAP + server in the common case." It might have led to instabilities. Bug Fixes --------- diff --git a/offlineimap/folder/IMAP.py b/offlineimap/folder/IMAP.py index f783d22..64770ef 100644 --- a/offlineimap/folder/IMAP.py +++ b/offlineimap/folder/IMAP.py @@ -568,6 +568,10 @@ class IMAPFolder(BaseFolder): "failed (error). Server reponded: %s\nMessage content was: " "%s" % (self, self.getrepository(), str(e), dbg_output), OfflineImapError.ERROR.MESSAGE) + # Checkpoint. Let it write out stuff, etc. Eg searches for + # just uploaded messages won't work if we don't do this. + typ, dat = imapobj.check() + assert(typ == 'OK') # get the new UID, default to 0 (=unknown) uid = 0 @@ -587,11 +591,6 @@ class IMAPFolder(BaseFolder): "'%s'" % str(resp)) else: # Don't support UIDPLUS - # Checkpoint. Let it write out stuff, etc. Eg searches for - # just uploaded messages won't work if we don't do this. - typ, dat = imapobj.check() - assert(typ == 'OK') - uid = self.savemessage_searchforheader(imapobj, headername, headervalue) # If everything failed up to here, search the message From 0e6b4ae798e5eb5ef0c5e1b4f64a59a5933f762d Mon Sep 17 00:00:00 2001 From: Sebastian Spaeth Date: Fri, 24 Feb 2012 08:35:59 +0100 Subject: [PATCH 45/58] Revert "Clean up and improve APPENDUID handling" This reverts commit 4d47f7bf3c7e0af56e0bc1f74c3afe6c762beb3e. This is one of two candidates for introducing the instabilities that John Wiegley observed. We need to reintroduce with careful testing only. The original patch has been mostly reverted. --- offlineimap/folder/IMAP.py | 38 +++++++++++++++++++------------------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/offlineimap/folder/IMAP.py b/offlineimap/folder/IMAP.py index 64770ef..6bdcc71 100644 --- a/offlineimap/folder/IMAP.py +++ b/offlineimap/folder/IMAP.py @@ -539,10 +539,9 @@ class IMAPFolder(BaseFolder): self.ui.msgtoreadonly(self, uid, content, flags) return uid - # Clean out existing APPENDUID responses and do APPEND + #Do the APPEND try: - imapobj.response('APPENDUID') # flush APPENDUID responses - typ, dat = imapobj.append(self.getfullname(), + (typ, dat) = imapobj.append(self.getfullname(), imaputil.flagsmaildir2imap(flags), date, content) retry_left = 0 # Mark as success @@ -570,33 +569,34 @@ class IMAPFolder(BaseFolder): OfflineImapError.ERROR.MESSAGE) # Checkpoint. Let it write out stuff, etc. Eg searches for # just uploaded messages won't work if we don't do this. - typ, dat = imapobj.check() + (typ,dat) = imapobj.check() assert(typ == 'OK') - # get the new UID, default to 0 (=unknown) - uid = 0 - if use_uidplus: + # get the new UID. Test for APPENDUID response even if the + # server claims to not support it, as e.g. Gmail does :-( + if use_uidplus or imapobj._get_untagged_response('APPENDUID', True): # get new UID from the APPENDUID response, it could look # like OK [APPENDUID 38505 3955] APPEND completed with - # 38505 being folder UIDvalidity and 3955 the new UID. - typ, resp = imapobj.response('APPENDUID') - if resp == [None] or resp == None: + # 38505 bein folder UIDvalidity and 3955 the new UID. + # note: we would want to use .response() here but that + # often seems to return [None], even though we have + # data. TODO + resp = imapobj._get_untagged_response('APPENDUID') + if resp == [None]: self.ui.warn("Server supports UIDPLUS but got no APPENDUID " "appending a message.") - else: - uid = long(resp[-1].split(' ')[1]) - if uid == 0: - self.ui.warn("savemessage: Server supports UIDPLUS, but" + return 0 + uid = long(resp[-1].split(' ')[1]) + if uid == 0: + self.ui.warn("savemessage: Server supports UIDPLUS, but" " we got no usable uid back. APPENDUID reponse was " "'%s'" % str(resp)) else: - # Don't support UIDPLUS + # we don't support UIDPLUS uid = self.savemessage_searchforheader(imapobj, headername, headervalue) - # If everything failed up to here, search the message - # manually TODO: rather than inserting and searching for our - # custom header, we should be searching the Message-ID and - # compare the message size... + # See docs for savemessage in Base.py for explanation + # of this and other return values if uid == 0: self.ui.debug('imap', 'savemessage: attempt to get new UID ' 'UID failed. Search headers manually.') From 2800a71a28362cd2ec73fa3c8a2bae56a3ce09d5 Mon Sep 17 00:00:00 2001 From: Sebastian Spaeth Date: Fri, 24 Feb 2012 09:39:39 +0100 Subject: [PATCH 46/58] tests: Add "create email test" This is the first test that actually creates a (local) email and syncs. We check the result of the sync operation, to see if the server has actually been assigning a proper UID to the email and bail out if not. This test therefore excercises our ability to properly detect the new UID of an APPENDED email. Obviously we still need some IMAP<->IMAP tests too, but since this is the same codepath being used for APPENDs in that case, it could also help to detect instabilities there. In order to get this test in, the OLITestLib got a few new helper functions: - delete_maildir - create_mail - get_maildir_uids The test passes here. I invoke it via: python -m unittest test.tests.test_01_basic.TestBasicFunctions.test_04_createmail or run python setup.py test, to run the whole suite. Signed-off-by: Sebastian Spaeth --- test/OLItest/TestRunner.py | 52 +++++++++++++++++++++++++++++++++++++ test/tests/test_01_basic.py | 26 ++++++++++++++++++- 2 files changed, 77 insertions(+), 1 deletion(-) diff --git a/test/OLItest/TestRunner.py b/test/OLItest/TestRunner.py index 7a2bb51..1ce3b5f 100644 --- a/test/OLItest/TestRunner.py +++ b/test/OLItest/TestRunner.py @@ -22,12 +22,15 @@ import sys import shutil import subprocess import tempfile +import random +random.seed() try: from configparser import SafeConfigParser except ImportError: # python 2 from ConfigParser import SafeConfigParser from . import default_conf + class OLITestLib(): cred_file = None testdir = None @@ -179,6 +182,36 @@ class OLITestLib(): if e.errno != 17: # 'already exists' is ok. raise + @classmethod + def delete_maildir(cls, folder): + """Delete maildir 'folder' in our test maildir + + Does not fail if not existing""" + assert cls.testdir != None + maildir = os.path.join(cls.testdir, 'mail', folder) + shutil.rmtree(maildir, ignore_errors=True) + + @classmethod + def create_mail(cls, folder, mailfile=None, content=None): + """Create a mail in maildir 'folder'/new + + Use default mailfilename if not given. + Use some default content if not given""" + assert cls.testdir != None + while True: # Loop till we found a unique filename + mailfile = '{}:2,'.format(random.randint(0,999999999)) + mailfilepath = os.path.join(cls.testdir, 'mail', + folder, 'new', mailfile) + if not os.path.isfile(mailfilepath): + break + with open(mailfilepath,"wb") as mailf: + mailf.write(b'''From: test +Subject: Boo +Date: 1 Jan 1980 +To: test@offlineimap.org + +Content here.''') + @classmethod def count_maildir_mails(cls, folder): """Returns the number of mails in maildir 'folder' @@ -196,3 +229,22 @@ class OLITestLib(): if dirpath.endswith(('/cur', '/new')): mails += len(files) return boxes, mails + + # find UID in a maildir filename + re_uidmatch = re.compile(',U=(\d+)') + + @classmethod + def get_maildir_uids(cls, folder): + """Returns a list of maildir mail uids, 'None' if no valid uid""" + assert cls.testdir != None + mailfilepath = os.path.join(cls.testdir, 'mail', folder) + assert os.path.isdir(mailfilepath) + ret = [] + for dirpath, dirs, files in os.walk(mailfilepath): + if not dirpath.endswith((os.path.sep + 'new', os.path.sep + 'cur')): + continue # only /new /cur are interesting + for file in files: + m = cls.re_uidmatch.search(file) + uid = m.group(1) if m else None + ret.append(uid) + return ret diff --git a/test/tests/test_01_basic.py b/test/tests/test_01_basic.py index 6cda54e..aadec72 100644 --- a/test/tests/test_01_basic.py +++ b/test/tests/test_01_basic.py @@ -31,6 +31,7 @@ def setUpModule(): def tearDownModule(): logging.info("Tear Down test module") + # comment out next line to keep testdir after test runs. TODO: make nicer OLITestLib.delete_test_dir() #Stuff that can be used @@ -80,7 +81,7 @@ class TestBasicFunctions(unittest.TestCase): #logging.warn("%s %s "% (code, res)) self.assertEqual(res, "") boxes, mails = OLITestLib.count_maildir_mails('') - self.assertTrue((boxes, mails)==(2,0), msg="Expected 2 folders and 0" + self.assertTrue((boxes, mails)==(2,0), msg="Expected 2 folders and 0 " "mails, but sync led to {} folders and {} mails".format( boxes, mails)) @@ -101,4 +102,27 @@ class TestBasicFunctions(unittest.TestCase): self.assertEqual(mismatch, True, msg="Mismatching nametrans rules did " "NOT trigger an 'infinite folder generation' error. Output was:\n" "{}".format(res)) + # Write out default config file again + OLITestLib.write_config_file() + def test_04_createmail(self): + """Create mail in OLItest 1, sync, wipe folder sync + + Currently, this will mean the folder will be recreated + locally. At some point when remote folder deletion is + implemented, this behavior will change.""" + OLITestLib.delete_remote_testfolders() + OLITestLib.create_maildir('INBOX.OLItest') + OLITestLib.create_mail('INBOX.OLItest') + code, res = OLITestLib.run_OLI() + #logging.warn("%s %s "% (code, res)) + self.assertEqual(res, "") + boxes, mails = OLITestLib.count_maildir_mails('') + self.assertTrue((boxes, mails)==(1,1), msg="Expected 1 folders and 1 " + "mails, but sync led to {} folders and {} mails".format( + boxes, mails)) + # The local Mail should have been assigned a proper UID now, check! + uids = OLITestLib.get_maildir_uids('INBOX.OLItest') + self.assertFalse (None in uids, msg = "All mails should have been "+ \ + "assigned the IMAP's UID number, but {} messages had no valid ID "\ + .format(len([None for x in uids if x==None]))) From 74b133c500ef1d8954b5d402fd428a2cc062aa42 Mon Sep 17 00:00:00 2001 From: Sebastian Spaeth Date: Fri, 24 Feb 2012 11:13:27 +0100 Subject: [PATCH 47/58] Revamped documentation structure and some doc fixes `make` in the `docs` dir or `make doc` in the root dir will now create the 1) man page and 2) the user documentation using sphinx (requiring python-doctools, and sphinx). The resulting user docs are in `docs/html`. You can also only create the man pages with `make man` in the `docs` dir. Also fixed all .rst conversion errors as requested by Gentoo downstream. Signed-off-by: Sebastian Spaeth --- .gitignore | 3 +- Changelog.draft.rst | 6 + Makefile | 1 - README.rst | 120 +++++------------- docs/HACKING.rst | 3 +- docs/MANUAL.rst | 19 ++- docs/Makefile | 10 +- docs/dev-doc-src/FAQ.rst | 1 - docs/{dev-doc-src => doc-src}/API.rst | 0 docs/{ => doc-src}/FAQ.rst | 15 ++- docs/{dev-doc-src => doc-src}/INSTALL.rst | 0 docs/{dev-doc-src => doc-src}/MANUAL.rst | 0 docs/{dev-doc-src => doc-src}/conf.py | 0 docs/doc-src/features.rst | 66 ++++++++++ docs/{dev-doc-src => doc-src}/index.rst | 2 + docs/{dev-doc-src => doc-src}/nametrans.rst | 12 +- docs/{dev-doc-src => doc-src}/offlineimap.rst | 0 docs/{dev-doc-src => doc-src}/repository.rst | 0 docs/{dev-doc-src => doc-src}/ui.rst | 0 19 files changed, 140 insertions(+), 118 deletions(-) delete mode 120000 docs/dev-doc-src/FAQ.rst rename docs/{dev-doc-src => doc-src}/API.rst (100%) rename docs/{ => doc-src}/FAQ.rst (98%) rename docs/{dev-doc-src => doc-src}/INSTALL.rst (100%) rename docs/{dev-doc-src => doc-src}/MANUAL.rst (100%) rename docs/{dev-doc-src => doc-src}/conf.py (100%) create mode 100644 docs/doc-src/features.rst rename docs/{dev-doc-src => doc-src}/index.rst (97%) rename docs/{dev-doc-src => doc-src}/nametrans.rst (98%) rename docs/{dev-doc-src => doc-src}/offlineimap.rst (100%) rename docs/{dev-doc-src => doc-src}/repository.rst (100%) rename docs/{dev-doc-src => doc-src}/ui.rst (100%) diff --git a/.gitignore b/.gitignore index 9307862..620e7e4 100644 --- a/.gitignore +++ b/.gitignore @@ -1,9 +1,10 @@ # Generated files -/docs/dev-doc/ +/docs/html/ /build/ *.pyc offlineimap.1 # backups .*.swp .*.swo +*.html *~ diff --git a/Changelog.draft.rst b/Changelog.draft.rst index 61dbe35..f29e325 100644 --- a/Changelog.draft.rst +++ b/Changelog.draft.rst @@ -33,5 +33,11 @@ Changes * Revert "* Slight performance enhancement uploading mails to an IMAP server in the common case." It might have led to instabilities. +* Revamped documentation structure. `make` in the `docs` dir or `make + doc` in the root dir will now create the 1) man page and 2) the user + documentation using sphinx (requiring python-doctools, and + sphinx). The resulting user docs are in `docs/html`. You can also + only create the man pages with `make man` in the `docs` dir. + Bug Fixes --------- diff --git a/Makefile b/Makefile index 69532d4..d014388 100644 --- a/Makefile +++ b/Makefile @@ -46,7 +46,6 @@ man: doc: @$(MAKE) -C docs $(RST2HTML) README.rst readme.html - $(RST2HTML) SubmittingPatches.rst SubmittingPatches.html $(RST2HTML) Changelog.rst Changelog.html targz: ../$(TARGZ) diff --git a/README.rst b/README.rst index b4bdccc..f7cc456 100644 --- a/README.rst +++ b/README.rst @@ -1,26 +1,13 @@ .. -*- coding: utf-8 -*- - .. _mailing list: http://lists.alioth.debian.org/mailman/listinfo/offlineimap-project ====== README ====== -.. contents:: -.. sectnum:: - - Description =========== -Welcome to the official OfflineIMAP project. - -*NOTICE:* this software was written by John Goerzen, who retired from -maintaining. It is now maintained by Nicolas Sebrecht at -https://github.com/nicolas33/offlineimap. Thanks to John for his great job and -to have share this project with us. - - OfflineIMAP is a tool to simplify your e-mail reading. With OfflineIMAP, you can read the same mailbox from multiple computers. You get a current copy of your messages on each computer, and changes you make one place will be visible on all @@ -29,75 +16,42 @@ it will appear deleted on your work computer as well. OfflineIMAP is also useful if you want to use a mail reader that does not have IMAP support, has poor IMAP support, or does not provide disconnected operation. -OfflineIMAP works on pretty much any POSIX operating system, such as Linux, BSD -operating systems, MacOS X, Solaris, etc. +OfflineIMAP does not require additional python dependencies (although python-sqlite is strongly recommended) OfflineIMAP is a Free Software project licensed under the GNU General Public License. You can download it for free, and you can modify it. In fact, you are encouraged to contribute to OfflineIMAP, and doing so is fast and easy. +Documentation +============= -OfflineIMAP is FAST; it synchronizes my two accounts with over 50 folders in 3 -seconds. Other similar tools might take over a minute, and achieve a -less-reliable result. Some mail readers can take over 10 minutes to do the same -thing, and some don't even support it at all. Unlike other mail tools, -OfflineIMAP features a multi-threaded synchronization algorithm that can -dramatically speed up performance in many situations by synchronizing several -different things simultaneously. +The documentation (in .rst format) is included in the `docs` +directory. Read it directly or generate nicer html (python-sphinx +needed) or the man page (python-docutils needed) via:: -OfflineIMAP is FLEXIBLE; you can customize which folders are synced via regular -expressions, lists, or Python expressions; a versatile and comprehensive -configuration file is used to control behavior; two user interfaces are -built-in; fine-tuning of synchronization performance is possible; internal or -external automation is supported; SSL and PREAUTH tunnels are both supported; -offline (or "unplugged") reading is supported; and esoteric IMAP features are -supported to ensure compatibility with the widest variety of IMAP servers. + 'make doc' (user docs), 'make man' (man page only) or 'make' (both) -OfflineIMAP is SAFE; it uses an algorithm designed to prevent mail loss at all -costs. Because of the design of this algorithm, even programming errors should -not result in loss of mail. I am so confident in the algorithm that I use my -own personal and work accounts for testing of OfflineIMAP pre-release, -development, and beta releases. Of course, legally speaking, OfflineIMAP comes -with no warranty, so I am not responsible if this turns out to be wrong. - - -Method of Operation -=================== - -OfflineIMAP traditionally operates by maintaining a hierarchy of mail folders in -Maildir format locally. Your own mail reader will read mail from this tree, and -need never know that the mail comes from IMAP. OfflineIMAP will detect changes -to the mail folders on your IMAP server and your own computer and -bi-directionally synchronize them, copying, marking, and deleting messages as -necessary. - -With OfflineIMAP 4.0, a powerful new ability has been introduced ― the program -can now synchronize two IMAP servers with each other, with no need to have a -Maildir layer in-between. Many people use this if they use a mail reader on -their local machine that does not support Maildirs. People may install an IMAP -server on their local machine, and point both OfflineIMAP and their mail reader -of choice at it. This is often preferable to the mail reader's own IMAP support -since OfflineIMAP supports many features (offline reading, for one) that most -IMAP-aware readers don't. However, this feature is not as time-tested as -traditional syncing, so my advice is to stick with normal methods of operation -for the time being. + (`make html` will simply create html versions of all *.rst files in /docs) +The resulting user documentation will be in `docs/html`. The full user +docs are also at: ``_. Please see there for +detailed information on how to install and configure OfflineImap. Quick Start =========== -If you have already installed OfflineIMAP system-wide, or your system -administrator has done that for you, your task for setting up OfflineIMAP for -the first time is quite simple. You just need to set up your configuration -file, make your folder directory, and run it! +First, install OfflineIMAP. See docs/INSTALL.rst or read +``_. +(hint: `sudo python setup.py install`) -You can quickly set up your configuration file. The distribution includes a -file offlineimap.conf.minimal (Debian users may find this at -``/usr/share/doc/offlineimap/examples/offlineimap.conf.minimal``) that is a -basic example of setting of OfflineIMAP. You can simply copy this file into -your home directory and name it ``.offlineimaprc`` (note the leading period). A -command such as ``cp offlineimap.conf.minimal ~/.offlineimaprc`` will do it. -Or, if you prefer, you can just copy this text to ``~/.offlineimaprc``:: +Second, set up your configuration file and run it! The distribution +includes offlineimap.conf.minimal (Debian users may find this at +``/usr/share/doc/offlineimap/examples/offlineimap.conf.minimal``) that +provides you with the bare minimum of setting up OfflineIMAP. You can +simply copy this file into your home directory and name it +``.offlineimaprc``. A command such as ``cp offlineimap.conf.minimal +~/.offlineimaprc`` will do it. Or, if you prefer, you can just copy +this text to ``~/.offlineimaprc``:: [general] accounts = Test @@ -121,30 +75,23 @@ to do is specify a directory for your folders to be in (on the localfolders line), the host name of your IMAP server (on the remotehost line), and your login name on the remote (on the remoteuser line). That's it! -To run OfflineIMAP, you just have to say offlineimap ― it will fire up, ask you -for a login password if necessary, synchronize your folders, and exit. See? +To run OfflineIMAP, you just have to say `offlineimap` ― it will fire +up, ask you for a login password if necessary, synchronize your +folders, and exit. See? -You can just throw away the rest of this finely-crafted, perfectly-honed manual! -Of course, if you want to see how you can make OfflineIMAP FIVE TIMES FASTER FOR -JUST $19.95 (err, well, $0), you have to read on! - - -Documentation -============= - -If you are reading this file on github, you can find more documentations in the -`docs` directory. - -Using your git repository, you can generate documentation with:: - - $ make doc +You can just throw away the rest of the finely-crafted, +perfectly-honed user manual! Of course, if you want to see how you can +make OfflineIMAP FIVE TIMES FASTER FOR JUST $19.95 (err, well, $0), +you have to read on our full user documentation and peruse the sample +offlineimap.conf (which includes all available options) for further +tweaks! Mailing list ============ The user discussion, development and all exciting stuff take place in the -`mailing list`_. You're *NOT* supposed to subscribe to send emails. +`mailing list`_. You do *NOT* need to subscribe to send emails. Reporting bugs and contributions @@ -154,9 +101,6 @@ Bugs ---- Bugs, issues and contributions should be reported to the `mailing list`_. -**Please, don't use the github features (messages, pull requests, etc) at all. -It would most likely be discarded or ignored.** - ======== Examples diff --git a/docs/HACKING.rst b/docs/HACKING.rst index 71ec112..bdd9a44 100644 --- a/docs/HACKING.rst +++ b/docs/HACKING.rst @@ -183,6 +183,5 @@ branch. ,-) API === -API is documented in the dev-doc-src directory using the sphinx tools (also used -for python itself). This is a WIP. Contributions in this area would be very +The API is documented in the user documentation in the docs/ directory and browsable at ``_. This is a WIP. Contributions in this area would be very appreciated. diff --git a/docs/MANUAL.rst b/docs/MANUAL.rst index 9715cb8..96d5d91 100644 --- a/docs/MANUAL.rst +++ b/docs/MANUAL.rst @@ -2,17 +2,14 @@ OfflineIMAP Manual ==================== +.. _OfflineIMAP: http://offlineimap.org + -------------------------------------------------------- Powerful IMAP/Maildir synchronization and reader support -------------------------------------------------------- :Author: John Goerzen & contributors -:Date: 2011-01-15 -:Copyright: GPL v2 -:Manual section: 1 - -.. TODO: :Manual group: - +:Date: 2012-02-23 DESCRIPTION =========== @@ -45,7 +42,7 @@ OfflineImap is well suited to be frequently invoked by cron jobs, or can run in The documentation is included in the git repository and can be created by issueing `make dev-doc` in the `doc` folder (python-sphinx required), or it can -be viewed online at `http://docs.offlineimap.org`_. +be viewed online at http://docs.offlineimap.org. .. _configuration: @@ -72,7 +69,7 @@ OPTIONS The command line options are described by issueing `offlineimap --help`. Details on their use can be found either in the sample offlineimap.conf file or -in the user docs at `http://docs.offlineimap.org`_. +in the user docs at http://docs.offlineimap.org. User Interfaces =============== @@ -306,6 +303,8 @@ as Man-In-The-Middle attacks which cause you to connect to the wrong server and pretend to be your mail server. DO NOT RELY ON STARTTLS AS A SAFE CONNECTION GUARANTEEING THE AUTHENTICITY OF YOUR IMAP SERVER! +.. _UNIX signals: + UNIX Signals ============ @@ -445,7 +444,7 @@ and Sent which should keep the same name:: Synchronizing 2 IMAP accounts to local Maildirs that are "next to each other", so that mutt can work on both. Full email setup described by -Thomas Kahle at `http://dev.gentoo.org/~tomka/mail.html`_ +Thomas Kahle at ``_ offlineimap.conf:: @@ -507,7 +506,7 @@ purposes: Fetching passwords from the gnome-keyring and translating folder names on the server to local foldernames. An example implementation of get_username and get_password showing how to query gnome-keyring is contained in -`http://dev.gentoo.org/~tomka/mail-setup.tar.bz2`_ The folderfilter is +``_ The folderfilter is a lambda term that, well, filters which folders to get. The function `oimaptransfolder_acc2` translates remote folders into local folders with a very simple logic. The `INBOX` folder will have the same name diff --git a/docs/Makefile b/docs/Makefile index 8fd880d..cd688f7 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -9,7 +9,7 @@ RST2HTML=`type rst2html >/dev/null 2>&1 && echo rst2html || echo rst2html.py` RST2MAN=`type rst2man >/dev/null 2>&1 && echo rst2man || echo rst2man.py` SPHINXBUILD = sphinx-build -all: html dev-doc +all: man doc html: $(HTML_TARGETS) @@ -22,12 +22,12 @@ offlineimap.1: MANUAL.rst $(RST2MAN) MANUAL.rst offlineimap.1 cp -f offlineimap.1 .. -dev-doc: - $(SPHINXBUILD) -b html -d dev-doc/doctrees dev-doc-src dev-doc/html +doc: + $(SPHINXBUILD) -b html -d html/doctrees doc-src html clean: $(RM) -f $(HTML_TARGETS) $(RM) -f offlineimap.1 ../offlineimap.1 - $(RM) -rf dev-doc/* + $(RM) -rf html/* -.PHONY: dev-doc +.PHONY: clean doc diff --git a/docs/dev-doc-src/FAQ.rst b/docs/dev-doc-src/FAQ.rst deleted file mode 120000 index e3ca8b5..0000000 --- a/docs/dev-doc-src/FAQ.rst +++ /dev/null @@ -1 +0,0 @@ -../FAQ.rst \ No newline at end of file diff --git a/docs/dev-doc-src/API.rst b/docs/doc-src/API.rst similarity index 100% rename from docs/dev-doc-src/API.rst rename to docs/doc-src/API.rst diff --git a/docs/FAQ.rst b/docs/doc-src/FAQ.rst similarity index 98% rename from docs/FAQ.rst rename to docs/doc-src/FAQ.rst index 8381681..1d49c3d 100644 --- a/docs/FAQ.rst +++ b/docs/doc-src/FAQ.rst @@ -203,9 +203,10 @@ How is OfflineIMAP conformance? Can I force OfflineIMAP to sync a folder right now? --------------------------------------------------- -Yes, - 1) if you use the `Blinkenlights` UI. That UI shows the active accounts -as follows:: +Yes: + +1) if you use the `Blinkenlights` UI. That UI shows the active +accounts as follows:: 4: [active] *Control: . 3: [ 4:36] personal: @@ -216,8 +217,9 @@ as follows:: resync that account immediately. This will be ignored if a resync is already in progress for that account. - 2) while in sleep mode, you can also send a SIGUSR1. See the `Signals - on UNIX`_ section in the MANUAL for details. +2) while in sleep mode, you can also send a SIGUSR1. See the :ref:`UNIX + signals` section in the MANUAL for details. + I get a "Mailbox already exists" error -------------------------------------- @@ -291,14 +293,17 @@ certificates chain) in PEM format. (See the documentation of `ssl.wrap_socket`_'s `certfile` parameter for the gory details.) You can use either openssl or gnutls to create a certificate file in the required format. #. via openssl:: + openssl s_client -CApath /etc/ssl/certs -connect ${hostname}:imaps -showcerts \ | perl -ne 'print if /BEGIN/../END/; print STDERR if /return/' > $sslcacertfile ^D + #. via gnutls:: gnutls-cli --print-cert -p imaps ${host} $sslcacertfile + The path `/etc/ssl/certs` is not standardized; your system may store SSL certificates elsewhere. (On some systems it may be in `/usr/local/share/certs/`.) diff --git a/docs/dev-doc-src/INSTALL.rst b/docs/doc-src/INSTALL.rst similarity index 100% rename from docs/dev-doc-src/INSTALL.rst rename to docs/doc-src/INSTALL.rst diff --git a/docs/dev-doc-src/MANUAL.rst b/docs/doc-src/MANUAL.rst similarity index 100% rename from docs/dev-doc-src/MANUAL.rst rename to docs/doc-src/MANUAL.rst diff --git a/docs/dev-doc-src/conf.py b/docs/doc-src/conf.py similarity index 100% rename from docs/dev-doc-src/conf.py rename to docs/doc-src/conf.py diff --git a/docs/doc-src/features.rst b/docs/doc-src/features.rst new file mode 100644 index 0000000..e9272d1 --- /dev/null +++ b/docs/doc-src/features.rst @@ -0,0 +1,66 @@ +Description +=========== + +OfflineIMAP is a tool to simplify your e-mail reading. With OfflineIMAP, you can +read the same mailbox from multiple computers. You get a current copy of your +messages on each computer, and changes you make one place will be visible on all +other systems. For instance, you can delete a message on your home computer, and +it will appear deleted on your work computer as well. OfflineIMAP is also useful +if you want to use a mail reader that does not have IMAP support, has poor IMAP +support, or does not provide disconnected operation. + +OfflineIMAP works on pretty much any POSIX operating system, such as Linux, BSD +operating systems, MacOS X, Solaris, etc. + +OfflineIMAP is a Free Software project licensed under the GNU General Public +License. You can download it for free, and you can modify it. In fact, you are +encouraged to contribute to OfflineIMAP, and doing so is fast and easy. + +OfflineIMAP is FAST; it synchronizes my two accounts with over 50 folders in 3 +seconds. Other similar tools might take over a minute, and achieve a +less-reliable result. Some mail readers can take over 10 minutes to do the same +thing, and some don't even support it at all. Unlike other mail tools, +OfflineIMAP features a multi-threaded synchronization algorithm that can +dramatically speed up performance in many situations by synchronizing several +different things simultaneously. + +OfflineIMAP is FLEXIBLE; you can customize which folders are synced via regular +expressions, lists, or Python expressions; a versatile and comprehensive +configuration file is used to control behavior; two user interfaces are +built-in; fine-tuning of synchronization performance is possible; internal or +external automation is supported; SSL and PREAUTH tunnels are both supported; +offline (or "unplugged") reading is supported; and esoteric IMAP features are +supported to ensure compatibility with the widest variety of IMAP servers. + +OfflineIMAP is SAFE; it uses an algorithm designed to prevent mail loss at all +costs. Because of the design of this algorithm, even programming errors should +not result in loss of mail. I am so confident in the algorithm that I use my +own personal and work accounts for testing of OfflineIMAP pre-release, +development, and beta releases. Of course, legally speaking, OfflineIMAP comes +with no warranty, so I am not responsible if this turns out to be wrong. + +.. note: OfflineImap was written by John Goerzen, who retired from + maintaining. It is now maintained by Nicolas Sebrecht & Sebastian + Spaeth at https://github.com/spaetz/offlineimap. Thanks to John + for his great job and to have share this project with us. + +Method of Operation +=================== + +OfflineIMAP traditionally operates by maintaining a hierarchy of mail folders in +Maildir format locally. Your own mail reader will read mail from this tree, and +need never know that the mail comes from IMAP. OfflineIMAP will detect changes +to the mail folders on your IMAP server and your own computer and +bi-directionally synchronize them, copying, marking, and deleting messages as +necessary. + +With OfflineIMAP 4.0, a powerful new ability has been introduced ― the program +can now synchronize two IMAP servers with each other, with no need to have a +Maildir layer in-between. Many people use this if they use a mail reader on +their local machine that does not support Maildirs. People may install an IMAP +server on their local machine, and point both OfflineIMAP and their mail reader +of choice at it. This is often preferable to the mail reader's own IMAP support +since OfflineIMAP supports many features (offline reading, for one) that most +IMAP-aware readers don't. However, this feature is not as time-tested as +traditional syncing, so my advice is to stick with normal methods of operation +for the time being. diff --git a/docs/dev-doc-src/index.rst b/docs/doc-src/index.rst similarity index 97% rename from docs/dev-doc-src/index.rst rename to docs/doc-src/index.rst index d6aa939..6645948 100644 --- a/docs/dev-doc-src/index.rst +++ b/docs/doc-src/index.rst @@ -15,6 +15,7 @@ If you just want to get started with minimal fuzz, have a look at our `online qu More information on specific topics can be found on the following pages: **User documentation** + * :doc:`Overview and features ` * :doc:`installation/uninstall ` * :doc:`user manual/Configuration ` * :doc:`Folder filtering & name transformation guide ` @@ -28,6 +29,7 @@ More information on specific topics can be found on the following pages: .. toctree:: :hidden: + features INSTALL MANUAL nametrans diff --git a/docs/dev-doc-src/nametrans.rst b/docs/doc-src/nametrans.rst similarity index 98% rename from docs/dev-doc-src/nametrans.rst rename to docs/doc-src/nametrans.rst index fabf7a4..ca25345 100644 --- a/docs/dev-doc-src/nametrans.rst +++ b/docs/doc-src/nametrans.rst @@ -48,7 +48,7 @@ at the end when required by Python syntax) For instance:: Usually it suffices to put a `folderfilter`_ setting in the remote repository section. You might want to put a folderfilter option on the local repository if you want to prevent some folders on the local repository to be created on the remote one. (Even in this case, folder filters on the remote repository will prevent that) folderincludes -^^^^^^^^^^^^^^ +-------------- You can specify `folderincludes`_ to manually include additional folders to be synced, even if they had been filtered out by a folderfilter setting. `folderincludes`_ should return a Python list. @@ -92,8 +92,9 @@ locally? Try this:: this rule will result in undefined behavior. See also *Sharing a maildir with multiple IMAP servers* in the :ref:`pitfalls` section. + Reverse nametrans -^^^^^^^^^^^^^^^^^^ ++++++++++++++++++ Since 6.4.0, OfflineImap supports the creation of folders on the remote repository and that complicates things. Previously, only one nametrans setting on the remote repository was needed and that transformed a remote to a local name. However, nametrans transformations are one-way, and OfflineImap has no way using those rules on the remote repository to back local names to remote names. @@ -161,9 +162,10 @@ What folder separators do I need to use in nametrans rules? Maildir using the default folder separator '.' which do I need to use in nametrans rules?:: - nametrans = lambda f: "INBOX/" + f -or:: - nametrans = lambda f: "INBOX." + f + nametrans = lambda f: "INBOX/" + f + + or:: + nametrans = lambda f: "INBOX." + f **A:** Generally use the folder separator as defined in the repository you write the nametrans rule for. That is, use '/' in the above diff --git a/docs/dev-doc-src/offlineimap.rst b/docs/doc-src/offlineimap.rst similarity index 100% rename from docs/dev-doc-src/offlineimap.rst rename to docs/doc-src/offlineimap.rst diff --git a/docs/dev-doc-src/repository.rst b/docs/doc-src/repository.rst similarity index 100% rename from docs/dev-doc-src/repository.rst rename to docs/doc-src/repository.rst diff --git a/docs/dev-doc-src/ui.rst b/docs/doc-src/ui.rst similarity index 100% rename from docs/dev-doc-src/ui.rst rename to docs/doc-src/ui.rst From b7a72b742d53f546ec7d30818a218e05a6661c2d Mon Sep 17 00:00:00 2001 From: Sebastian Spaeth Date: Fri, 24 Feb 2012 11:17:34 +0100 Subject: [PATCH 48/58] Fix up Changelog .rst->.html compile errors Signed-off-by: Sebastian Spaeth --- Changelog.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/Changelog.rst b/Changelog.rst index c0fd517..2b41ff1 100644 --- a/Changelog.rst +++ b/Changelog.rst @@ -514,9 +514,8 @@ I'd like to thank reporters who involved in this cycle: - Pan Tsu - Vincent Beffara - Will Styler - (my apologies if I forget somebody) - -...and all active developers, of course! + +(my apologies if I forget somebody) ...and all active developers, of course! The imaplib2 migration looks to go the right way to be definetly released but still needs more tests. So, here we go... @@ -595,9 +594,10 @@ OfflineIMAP v6.3.2 (2010-02-21) Notes ----- -First of all I'm really happy to announce our new official `website`_. Most of -the work started from the impulse of Philippe LeCavalier with the help of -Sebastian Spaeth and other contributors. Thanks to everybody. +First of all I'm really happy to announce our new official `website +`_. Most of the work started from the impulse +of Philippe LeCavalier with the help of Sebastian Spaeth and other +contributors. Thanks to everybody. In this release, we are still touched by the "SSL3 write pending" but I think time was long enough to try to fix it. We have our first entry in the "KNOWN From 925538f02d7473429f6c846e3168deed034cefe7 Mon Sep 17 00:00:00 2001 From: Sebastian Spaeth Date: Fri, 24 Feb 2012 11:20:22 +0100 Subject: [PATCH 49/58] docs: Fix docstrings to proper .rst syntax Prevents compile errors when creating the user documentation. Signed-off-by: Sebastian Spaeth --- offlineimap/folder/Base.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/offlineimap/folder/Base.py b/offlineimap/folder/Base.py index 77cc8ad..6f6f364 100644 --- a/offlineimap/folder/Base.py +++ b/offlineimap/folder/Base.py @@ -114,7 +114,7 @@ class BaseFolder(object): concurrent threads. :returns: Boolean indicating the match. Returns True in case it - implicitely saved the UIDVALIDITY.""" + implicitely saved the UIDVALIDITY.""" if self.get_saveduidvalidity() != None: return self.get_saveduidvalidity() == self.get_uidvalidity() @@ -273,6 +273,7 @@ class BaseFolder(object): """Change the message from existing uid to new_uid If the backend supports it (IMAP does not). + :param new_uid: (optional) If given, the old UID will be changed to a new UID. This allows backends efficient renaming of messages if the UID has changed.""" From d4c7a7bf17c7962cba3f5b52ed17b719876df010 Mon Sep 17 00:00:00 2001 From: Sebastian Spaeth Date: Fri, 24 Feb 2012 11:21:11 +0100 Subject: [PATCH 50/58] Delete UPGRADE.rst This is the upgrade instruction from before 4.0 and long obsolete. Delete it. Signed-off-by: Sebastian Spaeth --- docs/UPGRADE.rst | 26 -------------------------- 1 file changed, 26 deletions(-) delete mode 100644 docs/UPGRADE.rst diff --git a/docs/UPGRADE.rst b/docs/UPGRADE.rst deleted file mode 100644 index 169ce36..0000000 --- a/docs/UPGRADE.rst +++ /dev/null @@ -1,26 +0,0 @@ - - -Upgrading to 4.0 ----------------- - -If you are upgrading from a version of OfflineIMAP prior to 3.99.12, you will -find that you will get errors when OfflineIMAP starts up (relating to -ConfigParser or AccountHashGenerator) and the configuration file. This is -because the config file format had to change to accommodate new features in 4.0. -Fortunately, it's not difficult to adjust it to suit. - - -First thing you need to do is stop any running OfflineIMAP instance, making sure -first that it's synced all your mail. Then, modify your `~/.offlineimaprc` file. -You'll need to split up each account section (make sure that it now starts with -"Account ") into two Repository sections (one for the local side and another for -the remote side.) See the files offlineimap.conf.minimal and offlineimap.conf -in the distribution if you need more assistance. - - -OfflineIMAP's status directory area has also changed. Therefore, you should -delete everything in `~/.offlineimap` as well as your local mail folders. - - -When you start up OfflineIMAP 4.0, it will re-download all your mail from the -server and then you can continue using it like normal. From ae85b666d404bba08eeee088c1e706eafecc1f52 Mon Sep 17 00:00:00 2001 From: Sebastian Spaeth Date: Fri, 24 Feb 2012 11:30:45 +0100 Subject: [PATCH 51/58] Declutter root dir: COPYRIGHT --> COPYING No need to keep a COPYING (GPL v2 license) AND a file COPYRIGHT in the root. All files have the boilerplate anyway. Add the relevant part on top of the COPYING file and do away with COPYRIGHT. Signed-off-by: Sebastian Spaeth --- COPYING | 10 ++++++++++ COPYRIGHT | 17 ----------------- 2 files changed, 10 insertions(+), 17 deletions(-) delete mode 100644 COPYRIGHT diff --git a/COPYING b/COPYING index e70efd4..5f3f605 100644 --- a/COPYING +++ b/COPYING @@ -1,3 +1,13 @@ +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. + GNU GENERAL PUBLIC LICENSE Version 2, June 1991 diff --git a/COPYRIGHT b/COPYRIGHT deleted file mode 100644 index 4a11bce..0000000 --- a/COPYRIGHT +++ /dev/null @@ -1,17 +0,0 @@ -offlineimap Mail syncing software -Copyright (C) 2002 - 2009 John Goerzen - - This program is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation; either version 2 of the License, or - (at your option) any later version. - - This program is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with this program; if not, write to the Free Software - Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA - From 8bbdaa8c66d88c2f3f67bb9431b4e83df605bf89 Mon Sep 17 00:00:00 2001 From: Sebastian Spaeth Date: Fri, 24 Feb 2012 12:03:56 +0100 Subject: [PATCH 52/58] docs: Integrate SubmittingPatches.rst into HACKING.rst Signed-off-by: Sebastian Spaeth --- docs/HACKING.rst | 187 -------------- docs/doc-src/API.rst | 6 +- .../doc-src/HACKING.rst | 240 +++++++++++++++--- docs/doc-src/index.rst | 2 + 4 files changed, 216 insertions(+), 219 deletions(-) delete mode 100644 docs/HACKING.rst rename SubmittingPatches.rst => docs/doc-src/HACKING.rst (77%) diff --git a/docs/HACKING.rst b/docs/HACKING.rst deleted file mode 100644 index bdd9a44..0000000 --- a/docs/HACKING.rst +++ /dev/null @@ -1,187 +0,0 @@ -.. -*- coding: utf-8 -*- - -.. _OfflineIMAP: https://github.com/nicolas33/offlineimap - -=================== -Hacking OfflineIMAP -=================== - -Welcome to the `OfflineIMAP`_ project. You'll find here all the information you -need to start hacking OfflineIMAP. Be aware there are a lot of very usefull tips -in the mailing list. You may want to subscribe if you didn't, yet. This is -where you'll get help. - -.. contents:: -.. sectnum:: - - -================================= -Git: Branching Model And Workflow -================================= - -Introduction -============ - -In order to involve into OfflineIMAP you need some knowledges about Git and our -workflow. Don't be afraid if you don't know much, we would be pleased to help -you. - -You can find the API docs autogenerated on http://docs.offlineimap.org. - -Release cycles -============== - -We use a classical cycle based workflow: - -1. A stable release is out. - -2. Feature topics are sent, discussed and merged. - -3. When enough work was merged, we start the freeze cycle: the first release - candidate is out. - -4. During the freeze cycle, no more features are merged. It's time to test - OfflineIMAP. New candidates version are released. The more we are late in -rc - releases the less patches are merged but bug fixes. - -5. When we think a release is stable enough, we restart from step 1. - - -Branching model -=============== - -The branching model with use in OfflineIMAP is very near from the Git project. -We use a topic oriented workflow. A topic may be one or more patches. - -The branches you'll find in the official repository are: - -* gh-pages -* master -* next -* pu -* maint - -gh-pages --------- - -This comes from a feature offered by Github. We maintain the online home github -page using this branch. - -master ------- - -If you're not sure what branch you should use, this one is for you. This is the -mainline. Simple users should use this branch to follow OfflineIMAP's evolution. - -Usually, patches submitted to the mailing list should start off of this branch. - -next ----- - -Patches recently merged are good candidates for this branch. The content of next -is merged into the mainline (master) at release time for both stable and -rc -releases. - -When patches are sent to the mailing list, contributors discuss about them. Once -done and when patches looks ready for mainline, patches are first merged into -next. Advanced users and testers use this branch to test last merged patches -before they hit the mainline. This helps not introducing strong breackages -directly in master. - -pu --- - -pu stands for "proposed updates". If a topic is not ready for master nor next, -it may be merged into pu. This branch only help developers to work on someone -else topic or an earlier pending topic. - -This branch is **not intended to be checkouted**; never. Even developers don't -do that. Due to the way pu is built you can't expect content there to work in -any way... unless you clearly want to run into troubles. - -Developers can extract a topic from this branch to work on it. See the following -section "Extract a topic from pu" in this documentation. - -maint ------ - -This is the maintenance branch. It gets its own releases starting from an old -stable release. It helps both users having troubles with last stable releases -and users not wanting latest features or so to still benefit from strong bug -fixes and security fixes. - - -Working with Git -================ - -Extract a topic from pu ------------------------ - -pu is built this way:: - - git checkout pu - git reset --keep next - git merge --no-ff -X theirs topic1 - git merge --no-ff -X theirs topic2 - git merge --no-ff -X theirs blue - git merge --no-ff -X theirs orange - ... - -As a consequence: - -1. Each topic merged uses a merge commit. A merge commit is a commit having 2 - ancestors. Actually, Git allows more than 2 parents but we don't use this - feature. It's intended. - -2. Paths in pu may mix up multiple versions if all the topics don't use the same - base commit. This is very often the case as topics aren't rebased: it guarantees - each topic is strictly identical to the last version sent to the mailing list. - No surprise. - - -What you need to extract a particular topic is the sha1 of the tip of that -branch (the last commit of the topic). Assume you want the branch of the topic -called 'blue'. First, look at the log given by this command:: - - git log --reverse --merges --parents origin/next..origin/pu - -With this command you ask for the log: - -* from next to pu -* in reverse order (older first) -* merge commits only -* with the sha1 of the ancestors - -In this list, find the topic you're looking for, basing you search on the lines -like:: - - Merge branch 'topic/name' into pu - -By convention, it has the form /. When you're at -it, pick the topic ancestor sha1. It's always the last sha1 in the line starting -by 'commit'. For you to know: - -* the first is the sha1 of the commit you see: the merge commit -* the following sha1 is the ancestor of the branch checkouted at merge time - (always the previous merged topic or the ancien next in our case) -* last is the branch merged - -Giving:: - - commit sha1_of_merge_commit sha1_of_ancient_pu sha1_of_topic_blue - -Then, you only have to checkout the topic from there:: - - git checkout -b blue sha1_of_topic_blue - -and you're done! You've just created a new branch called "blue" with the blue -content. Be aware this topic is almostly not updated against current next -branch. ,-) - - -=== -API -=== - -The API is documented in the user documentation in the docs/ directory and browsable at ``_. This is a WIP. Contributions in this area would be very -appreciated. diff --git a/docs/doc-src/API.rst b/docs/doc-src/API.rst index 20f3d1f..38df996 100644 --- a/docs/doc-src/API.rst +++ b/docs/doc-src/API.rst @@ -2,8 +2,10 @@ .. currentmodule:: offlineimap -Welcome to :mod:`offlineimaps`'s documentation -============================================== +.. _API docs: + +:mod:`offlineimap's` API documentation +====================================== Within :mod:`offlineimap`, the classes :class:`OfflineImap` provides the high-level functionality. The rest of the classes should usually not needed to be touched by the user. Email repositories are represented by a :class:`offlineimap.repository.Base.BaseRepository` or derivatives (see :mod:`offlineimap.repository` for details). A folder within a repository is represented by a :class:`offlineimap.folder.Base.BaseFolder` or any derivative from :mod:`offlineimap.folder`. diff --git a/SubmittingPatches.rst b/docs/doc-src/HACKING.rst similarity index 77% rename from SubmittingPatches.rst rename to docs/doc-src/HACKING.rst index 5161519..9192458 100644 --- a/SubmittingPatches.rst +++ b/docs/doc-src/HACKING.rst @@ -1,14 +1,134 @@ .. -*- coding: utf-8 -*- - -.. _mailing list: http://lists.alioth.debian.org/mailman/listinfo/offlineimap-project +.. _OfflineIMAP: http://offlineimap.org .. _commits mailing list: http://lists.offlineimap.org/listinfo.cgi/commits-offlineimap.org +.. _mailing list: http://lists.alioth.debian.org/mailman/listinfo/offlineimap-project -================================================= -Checklist (and a short version for the impatient) -================================================= +Hacking OfflineIMAP +=================== -Commits -======= +In this section you'll find all the information you need to start +hacking `OfflineIMAP`_. Be aware there are a lot of very usefull tips +in the mailing list. You may want to subscribe if you didn't, +yet. This is where you will get help. + +.. contents:: :depth: 2 + +API +--- + +:ref:`OfflineImap's API ` documentation is included in the user +documentation (next section) and online browsable at +``_. It is mostly auto-generated from the +source code and is a work in progress. Contributions in this area +would be very appreciated. + +Following new commits +--------------------- + +You can follow upstream commits on + - `CIA.vc `, + - `Ohloh `, + - `GitHub `, + - or on the `commits mailing list`_. + + + +Git: OfflineImap's branching Model And Workflow +=============================================== + +Introduction +------------ + +This optional section provides you with information on how we use git +branches and do releases. You will need to know very little about git +to get started. + +For the impatient, see the :ref:`contribution checklist` below. + +Git Branching model +-------------------- + +OfflineIMAP uses the following branches: + + * master + * next + * maint + * (pu) + * & several topic oriented feature branches. A topic may consist of + one or more patches. + +master +++++++ + +If you're not sure what branch you should use, this one is for you. +This is the mainline. Simple users should use this branch to follow +OfflineIMAP's evolution. + +Usually, patches submitted to the mailing list should start off of +this branch. + +next +++++ + +Patches recently merged are good candidates for this branch. The content of next +is merged into the mainline (master) at release time for both stable and -rc +releases. + +When patches are sent to the mailing list, contributors discuss about them. Once +done and when patches looks ready for mainline, patches are first merged into +next. Advanced users and testers use this branch to test last merged patches +before they hit the mainline. This helps not introducing strong breackages +directly in master. + +pu ++++ + +pu stands for "proposed updates". If a topic is not ready for master nor next, +it may be merged into pu. This branch only help developers to work on someone +else topic or an earlier pending topic. + +This branch is **not intended to be checkouted**; never. Even developers don't +do that. Due to the way pu is built you can't expect content there to work in +any way... unless you clearly want to run into troubles. + +Developers can extract a topic from this branch to work on it. See the following +section "Extract a topic from pu" in this documentation. + +maint ++++++ + +This is the maintenance branch. It gets its own releases starting from an old +stable release. It helps both users having troubles with last stable releases +and users not wanting latest features or so to still benefit from strong bug +fixes and security fixes. + +Release cycles +-------------- + +A typical release cycle works like this: + +1. A stable release is out. + +2. Feature topics are sent, discussed and merged. + +3. When enough work was merged, we start the freeze cycle: the first release + candidate is out. + +4. During the freeze cycle, no more features are merged. It's time to test + OfflineIMAP. New candidates version are released. The more we are late in -rc + releases the less patches are merged but bug fixes. + +5. When we think a release is stable enough, we restart from step 1. + + +.. _contribution checklist: + + +Contribution Checklist (and a short version for the impatient) +=============================================================== + +Create commits +-------------- * make commits of logical units * check for unnecessary whitespace with ``git diff --check`` @@ -28,8 +148,9 @@ Commits * make sure that you have tests for the bug you are fixing * make sure that the test suite passes after your commit -Patch -===== + +Export commits as patches +------------------------- * use ``git format-patch -M`` to create the patch * do not PGP sign your patch @@ -52,9 +173,9 @@ Patch * see below for instructions specific to your mailer -============ + Long version -============ +------------ I started reading over the SubmittingPatches document for Git, primarily because I wanted to have a document similar to it for OfflineIMAP to make sure people @@ -64,8 +185,8 @@ But the patch submission requirements are a lot more relaxed here on the technical/contents front, because the OfflineIMAP is a lot smaller ;-). So here is only the relevant bits. -Decide what to base your work on -================================ +Decide what branch to base your work on ++++++++++++++++++++++++++++++++++++++++ In general, always base your work on the oldest branch that your change is relevant to. @@ -92,13 +213,12 @@ master..pu`` and look for the merge commit. The second parent of this commit is the tip of the topic branch. Make separate commits for logically separate changes -==================================================== +++++++++++++++++++++++++++++++++++++++++++++++++++++ -Unless your patch is really trivial, you should not be sending -out a patch that was generated between your working tree and -your commit head. Instead, always make a commit with complete -commit message and generate a series of patches from your -repository. It is a good discipline. +Unless your patch is really trivial, you should not be sending your +changes in a single patch. Instead, always make a commit with +complete commit message and generate a series of small patches from +your repository. Describe the technical detail of the change(s). @@ -115,7 +235,7 @@ but for code. Generate your patch using git tools out of your commits -------------------------------------------------------- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ git based diff tools (git, Cogito, and StGIT included) generate unidiff which is the preferred format. @@ -133,7 +253,7 @@ that is fine, but please mark it as such. Sending your patches -==================== +++++++++++++++++++++ People on the mailing list need to be able to read and comment on the changes you are submitting. It is important for @@ -205,7 +325,7 @@ necessary. Sign your work -============== +++++++++++++++ To improve tracking of who did what, we've borrowed the "sign-off" procedure from the Linux kernel project on patches @@ -218,7 +338,7 @@ the right to pass it on as a open-source patch**. The rules are pretty simple: if you can certify the below: **Developer's Certificate of Origin 1.1** ------------------------------------------ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ By making a contribution to this project, I certify that: @@ -320,13 +440,7 @@ Know the status of your patch after submission of the branch in which your patch has been merged (i.e. it will not tell you if your patch is merged in pu if you rebase on top of master). - -* You can follow upstream commits on -`CIA.vc `, -`Ohloh `, -`GitHub `, -or on the `commits mailing list`_. - + .. * Read the git mailing list, the maintainer regularly posts messages entitled "What's cooking in git.git" and "What's in git.git" giving the status of various proposed changes. @@ -601,3 +715,69 @@ Just make sure to disable line wrapping in the email client (GMail web interface will line wrap no matter what, so you need to use a real IMAP client). +Working with Git +================ + +Extract a topic from pu +----------------------- + +pu is built this way:: + + git checkout pu + git reset --keep next + git merge --no-ff -X theirs topic1 + git merge --no-ff -X theirs topic2 + git merge --no-ff -X theirs blue + git merge --no-ff -X theirs orange + ... + +As a consequence: + +1. Each topic merged uses a merge commit. A merge commit is a commit having 2 + ancestors. Actually, Git allows more than 2 parents but we don't use this + feature. It's intended. + +2. Paths in pu may mix up multiple versions if all the topics don't use the same + base commit. This is very often the case as topics aren't rebased: it guarantees + each topic is strictly identical to the last version sent to the mailing list. + No surprise. + + +What you need to extract a particular topic is the sha1 of the tip of that +branch (the last commit of the topic). Assume you want the branch of the topic +called 'blue'. First, look at the log given by this command:: + + git log --reverse --merges --parents origin/next..origin/pu + +With this command you ask for the log: + +* from next to pu +* in reverse order (older first) +* merge commits only +* with the sha1 of the ancestors + +In this list, find the topic you're looking for, basing you search on the lines +like:: + + Merge branch 'topic/name' into pu + +By convention, it has the form /. When you're at +it, pick the topic ancestor sha1. It's always the last sha1 in the line starting +by 'commit'. For you to know: + +* the first is the sha1 of the commit you see: the merge commit +* the following sha1 is the ancestor of the branch checkouted at merge time + (always the previous merged topic or the ancien next in our case) +* last is the branch merged + +Giving:: + + commit sha1_of_merge_commit sha1_of_ancient_pu sha1_of_topic_blue + +Then, you only have to checkout the topic from there:: + + git checkout -b blue sha1_of_topic_blue + +and you're done! You've just created a new branch called "blue" with the blue +content. Be aware this topic is almostly not updated against current next +branch. ,-) diff --git a/docs/doc-src/index.rst b/docs/doc-src/index.rst index 6645948..771269e 100644 --- a/docs/doc-src/index.rst +++ b/docs/doc-src/index.rst @@ -23,6 +23,7 @@ More information on specific topics can be found on the following pages: * :doc:`Frequently Asked Questions ` **Developer documentation** + * :doc:`HACKING HowTo & git workflows ` * :doc:`API documentation ` for internal details on the :mod:`offlineimap` module @@ -36,6 +37,7 @@ More information on specific topics can be found on the following pages: offlineimap FAQ + HACKING API repository ui From bfb7a79d6bd2bc9e3d6846814a923de3c4bbeccd Mon Sep 17 00:00:00 2001 From: Sebastian Spaeth Date: Fri, 24 Feb 2012 14:46:14 +0100 Subject: [PATCH 53/58] documentation: Make top-level README a plain text file. It makes direct reading much simpler. Signed-off-by: Sebastian Spaeth --- Makefile | 1 - README.rst => README | 88 +++++++++++++++----------------------------- 2 files changed, 30 insertions(+), 59 deletions(-) rename README.rst => README (73%) diff --git a/Makefile b/Makefile index d014388..c355583 100644 --- a/Makefile +++ b/Makefile @@ -45,7 +45,6 @@ man: doc: @$(MAKE) -C docs - $(RST2HTML) README.rst readme.html $(RST2HTML) Changelog.rst Changelog.html targz: ../$(TARGZ) diff --git a/README.rst b/README similarity index 73% rename from README.rst rename to README index f7cc456..dc95198 100644 --- a/README.rst +++ b/README @@ -1,12 +1,8 @@ -.. -*- coding: utf-8 -*- -.. _mailing list: http://lists.alioth.debian.org/mailman/listinfo/offlineimap-project - -====== -README -====== +OfflineImap README +================== Description -=========== +----------- OfflineIMAP is a tool to simplify your e-mail reading. With OfflineIMAP, you can read the same mailbox from multiple computers. You get a current copy of your @@ -14,34 +10,35 @@ messages on each computer, and changes you make one place will be visible on all other systems. For instance, you can delete a message on your home computer, and it will appear deleted on your work computer as well. OfflineIMAP is also useful if you want to use a mail reader that does not have IMAP support, has poor IMAP -support, or does not provide disconnected operation. +support, or does not provide disconnected operation. It's homepage at http://offlineimap.org contains more information, source code, and online documentation. -OfflineIMAP does not require additional python dependencies (although python-sqlite is strongly recommended) +OfflineIMAP does not require additional python dependencies beyond python >=2.6 +(although python-sqlite is strongly recommended). OfflineIMAP is a Free Software project licensed under the GNU General Public -License. You can download it for free, and you can modify it. In fact, you are -encouraged to contribute to OfflineIMAP, and doing so is fast and easy. +License version 2 (or later). You can download it for free, and you can modify +it. In fact, you are encouraged to contribute to OfflineIMAP. Documentation -============= +------------- -The documentation (in .rst format) is included in the `docs` -directory. Read it directly or generate nicer html (python-sphinx -needed) or the man page (python-docutils needed) via:: +The documentation is included (in .rst format) in the `docs` directory. +Read it directly or generate nice html docs (python-sphinx needed) and/or +the man page (python-docutils needed) while being in the `docs` dir via:: 'make doc' (user docs), 'make man' (man page only) or 'make' (both) (`make html` will simply create html versions of all *.rst files in /docs) The resulting user documentation will be in `docs/html`. The full user -docs are also at: ``_. Please see there for +docs are also at: http://docs.offlineimap.org. Please see there for detailed information on how to install and configure OfflineImap. Quick Start =========== First, install OfflineIMAP. See docs/INSTALL.rst or read -``_. +http://docs.offlineimap.org/en/latest/INSTALL.html. (hint: `sudo python setup.py install`) Second, set up your configuration file and run it! The distribution @@ -76,42 +73,33 @@ line), the host name of your IMAP server (on the remotehost line), and your login name on the remote (on the remoteuser line). That's it! To run OfflineIMAP, you just have to say `offlineimap` ― it will fire -up, ask you for a login password if necessary, synchronize your -folders, and exit. See? +up, ask you for a login password if necessary, synchronize your folders, +and exit. See? -You can just throw away the rest of the finely-crafted, -perfectly-honed user manual! Of course, if you want to see how you can -make OfflineIMAP FIVE TIMES FASTER FOR JUST $19.95 (err, well, $0), -you have to read on our full user documentation and peruse the sample -offlineimap.conf (which includes all available options) for further -tweaks! +You can just throw away the rest of the finely-crafted, perfectly-honed user +manual! Of course, if you want to see how you can make OfflineIMAP +FIVE TIMES FASTER FOR JUST $19.95 (err, well, $0), you have to read on our +full user documentation and peruse the sample offlineimap.conf (which +includes all available options) for further tweaks! -Mailing list -============ +Mailing list & bug reporting +---------------------------- The user discussion, development and all exciting stuff take place in the -`mailing list`_. You do *NOT* need to subscribe to send emails. +OfflineImap mailing list at http://lists.alioth.debian.org/mailman/listinfo/offlineimap-project. You do not need to subscribe to send emails. +Bugs, issues and contributions should be reported to the mailing list. Bugs can also be reported in the issue tracker at https://github.com/spaetz/offlineimap/issues. -Reporting bugs and contributions -================================ - -Bugs ----- - -Bugs, issues and contributions should be reported to the `mailing list`_. - -======== -Examples -======== +Configuration Examples +====================== Here are some example configurations for various situations. Please e-mail any other examples you have that may be useful to me. Multiple Accounts with Mutt -=========================== +--------------------------- This example shows you how to set up OfflineIMAP to synchronize multiple accounts with the mutt mail reader. @@ -145,7 +133,7 @@ That's it! UW-IMAPD and References -======================= +----------------------- Some users with a UW-IMAPD server need to use OfflineIMAP's "reference" feature to get at their mailboxes, specifying a reference of ``~/Mail`` or ``#mh/`` @@ -183,7 +171,7 @@ folders synced to just three:: pythonfile Configuration File Option -==================================== +------------------------------------- You can have OfflineIMAP load up a Python file before evaluating the configuration file options that are Python expressions. This example is based @@ -222,19 +210,3 @@ Then, the ~/.offlineimap.py file will contain:: This code snippet illustrates how the foldersort option can be customized with a Python function from the pythonfile to always synchronize certain folders first. - - -Signals -======= - -OfflineIMAP writes its current PID into ``~/.offlineimap/pid`` when it is -running. It is not guaranteed that this file will not exist when OfflineIMAP is -not running. - - From 3c481d9ce5ab34f9d539f815a6d3b89e57ab47cb Mon Sep 17 00:00:00 2001 From: Sebastian Spaeth Date: Fri, 24 Feb 2012 14:52:30 +0100 Subject: [PATCH 54/58] -f command line option only works on the untranslated remote names Previously folderfilters had to match both the local AND remote name which caused unwanted behavior in combination with nametrans rules. Make it operate on the untranslated remote names now and clarify in the command line option help text. Signed-off-by: Sebastian Spaeth --- Changelog.draft.rst | 5 +++++ offlineimap/init.py | 20 ++++++++------------ 2 files changed, 13 insertions(+), 12 deletions(-) diff --git a/Changelog.draft.rst b/Changelog.draft.rst index f29e325..d9c8aa1 100644 --- a/Changelog.draft.rst +++ b/Changelog.draft.rst @@ -39,5 +39,10 @@ Changes sphinx). The resulting user docs are in `docs/html`. You can also only create the man pages with `make man` in the `docs` dir. +* -f command line option only works on the untranslated remote + repository folder names now. Previously folderfilters had to match + both the local AND remote name which caused unwanted behavior in + combination with nametrans rules. Clarify in the help text. + Bug Fixes --------- diff --git a/offlineimap/init.py b/offlineimap/init.py index 8668cc1..24d6c1a 100644 --- a/offlineimap/init.py +++ b/offlineimap/init.py @@ -121,12 +121,10 @@ class OfflineImap: help="Log to FILE") parser.add_option("-f", dest="folders", metavar="folder1,[folder2...]", - help= - "Only sync the specified folders. The folder names " - "are the *untranslated* foldernames. This " - "command-line option overrides any 'folderfilter' " - "and 'folderincludes' options in the configuration " - "file.") + help="Only sync the specified folders. The folder names " + "are the *untranslated* foldernames of the remote repository. " + "This command-line option overrides any 'folderfilter' " + "and 'folderincludes' options in the configuration file.") parser.add_option("-k", dest="configoverride", action="append", @@ -269,12 +267,10 @@ class OfflineImap: for accountname in accounts.getaccountlist(config): account_section = 'Account ' + accountname remote_repo_section = 'Repository ' + \ - config.get(account_section, 'remoterepository') - local_repo_section = 'Repository ' + \ - config.get(account_section, 'localrepository') - for section in [remote_repo_section, local_repo_section]: - config.set(section, "folderfilter", folderfilter) - config.set(section, "folderincludes", folderincludes) + config.get(account_section, 'remoterepository') + config.set(remote_repo_section, "folderfilter", folderfilter) + config.set(remote_repo_section, "folderincludes", + folderincludes) if options.logfile: sys.stderr = self.ui.logfile From d6da65b18f87725868bcc28cffaba7e3b4876c28 Mon Sep 17 00:00:00 2001 From: Sebastian Spaeth Date: Mon, 27 Feb 2012 16:35:17 +0100 Subject: [PATCH 55/58] tests: Fix test #4 1) Fix test #4 by deleting all local mailfolders remaining from previous tests, the mailfolder count will be off, otherwise. 2) Make folder deletion work in python3, it weirdly enough needs to be quoted like this to work in python3 (I found a python bug about this somewhere). Signed-off-by: Sebastian Spaeth --- test/OLItest/TestRunner.py | 4 ++-- test/tests/test_01_basic.py | 1 + 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/test/OLItest/TestRunner.py b/test/OLItest/TestRunner.py index 1ce3b5f..fc06a87 100644 --- a/test/OLItest/TestRunner.py +++ b/test/OLItest/TestRunner.py @@ -158,12 +158,12 @@ class OLITestLib(): [^"]*$ # followed by no more quotes ''', d, flags=re.VERBOSE) folder = bytearray(m.group(1)) - folder = folder.replace(br'\"', b'"') # remove quoting + #folder = folder.replace(br'\"', b'"') # remove quoting dirs.append(folder) # 2) filter out those not starting with INBOX.OLItest and del... dirs = [d for d in dirs if d.startswith(b'INBOX.OLItest')] for folder in dirs: - res_t, data = imapobj.delete(str(folder)) + res_t, data = imapobj.delete(b'\"'+folder+b'\"') assert res_t == 'OK', "Folder deletion of {} failed with error"\ ":\n{} {}".format(folder.decode('utf-8'), res_t, data) imapobj.logout() diff --git a/test/tests/test_01_basic.py b/test/tests/test_01_basic.py index aadec72..f5a0ea1 100644 --- a/test/tests/test_01_basic.py +++ b/test/tests/test_01_basic.py @@ -112,6 +112,7 @@ class TestBasicFunctions(unittest.TestCase): locally. At some point when remote folder deletion is implemented, this behavior will change.""" OLITestLib.delete_remote_testfolders() + OLITestLib.delete_maildir('') #Delete all local maildir folders OLITestLib.create_maildir('INBOX.OLItest') OLITestLib.create_mail('INBOX.OLItest') code, res = OLITestLib.run_OLI() From 29ba2fc523eede41faa1693157d703e5cf93f949 Mon Sep 17 00:00:00 2001 From: Sebastian Spaeth Date: Mon, 2 Apr 2012 23:26:59 +0200 Subject: [PATCH 56/58] Warn about nonsensical config option 'sep' for IMAP repositories We autodetect the folder separator on IMAP servers and ignore any 'sep' setting in the repository section for IMAP servers. Detect if there is such a setting and warn the user about it. Signed-off-by: Sebastian Spaeth --- Changelog.draft.rst | 2 ++ offlineimap/repository/IMAP.py | 3 +++ 2 files changed, 5 insertions(+) diff --git a/Changelog.draft.rst b/Changelog.draft.rst index d9c8aa1..5fdacac 100644 --- a/Changelog.draft.rst +++ b/Changelog.draft.rst @@ -44,5 +44,7 @@ Changes both the local AND remote name which caused unwanted behavior in combination with nametrans rules. Clarify in the help text. +* Some better output when using nonsensical configuration settings + Bug Fixes --------- diff --git a/offlineimap/repository/IMAP.py b/offlineimap/repository/IMAP.py index 28e73b7..5ad787a 100644 --- a/offlineimap/repository/IMAP.py +++ b/offlineimap/repository/IMAP.py @@ -33,6 +33,9 @@ class IMAPRepository(BaseRepository): self._host = None self.imapserver = imapserver.IMAPServer(self) self.folders = None + if self.getconf('sep', None): + self.ui.info("The 'sep' setting is being ignored for IMAP " + "repository '%s' (it's autodetected)" % self) def startkeepalive(self): keepalivetime = self.getkeepalive() From 2f88b0296a8715263f22f6342a58ec4db3d33fd2 Mon Sep 17 00:00:00 2001 From: Eygene Ryabinkin Date: Sun, 19 Feb 2012 20:55:06 +0400 Subject: [PATCH 57/58] Fix Curses interface for Python 2.6 In 2.6 all logging classes are not the new-style ones, so they have no mro() method and, thus, we can't use super() for them. Since CursesLogHanler is singly-inherited method, there will be no problems in usage of the explicit superclass name. Signed-off-by: Eygene Ryabinkin Signed-off-by: Sebastian Spaeth --- Changelog.draft.rst | 2 ++ offlineimap/ui/Curses.py | 2 +- 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/Changelog.draft.rst b/Changelog.draft.rst index 5fdacac..c2b7dbc 100644 --- a/Changelog.draft.rst +++ b/Changelog.draft.rst @@ -48,3 +48,5 @@ Changes Bug Fixes --------- + +* Improve compatability of the curses UI with python 2.6 diff --git a/offlineimap/ui/Curses.py b/offlineimap/ui/Curses.py index 365be60..7463a6a 100644 --- a/offlineimap/ui/Curses.py +++ b/offlineimap/ui/Curses.py @@ -281,7 +281,7 @@ class CursesLogHandler(logging.StreamHandler): """self.ui has been set to the UI class before anything is invoked""" def emit(self, record): - log_str = super(CursesLogHandler, self).format(record) + log_str = logging.StreamHandler.format(self, record) color = self.ui.gettf().curses_color # We must acquire both locks. Otherwise, deadlock can result. # This can happen if one thread calls _msg (locking curses, then From d3427a664ece1f3a5a5480adc41e5c96b8f4eb9a Mon Sep 17 00:00:00 2001 From: Sebastian Spaeth Date: Mon, 2 Apr 2012 23:47:32 +0200 Subject: [PATCH 58/58] v6.5.3 release see changelog Signed-off-by: Sebastian Spaeth --- .gitignore | 2 +- Changelog.draft.rst | 52 ----------------------------------------- Changelog.rst | 51 ++++++++++++++++++++++++++++++++++++---- offlineimap/__init__.py | 2 +- 4 files changed, 48 insertions(+), 59 deletions(-) delete mode 100644 Changelog.draft.rst diff --git a/.gitignore b/.gitignore index 620e7e4..c5af353 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,5 @@ # Generated files -/docs/html/ +/docs/dev-doc/ /build/ *.pyc offlineimap.1 diff --git a/Changelog.draft.rst b/Changelog.draft.rst deleted file mode 100644 index c2b7dbc..0000000 --- a/Changelog.draft.rst +++ /dev/null @@ -1,52 +0,0 @@ -========= -ChangeLog -========= - -Users should ignore this content: **it is draft**. - -Contributors should add entries here in the following section, on top of the -others. - -`WIP (coming releases)` -======================= - -New Features ------------- - -* --dry-run mode protects us from performing any actual action. - It will not precisely give the exact information what will - happen. If e.g. it would need to create a folder, it merely - outputs "Would create folder X", but not how many and which mails - it would transfer. - -Changes -------- - -* internal code changes to prepare for Python3 - -* Improve user documentation of nametrans/folderfilter - -* Fixed some cases where invalid nametrans rules were not caught and - we would not propagate local folders to the remote repository. - (now tested in test03) - -* Revert "* Slight performance enhancement uploading mails to an IMAP - server in the common case." It might have led to instabilities. - -* Revamped documentation structure. `make` in the `docs` dir or `make - doc` in the root dir will now create the 1) man page and 2) the user - documentation using sphinx (requiring python-doctools, and - sphinx). The resulting user docs are in `docs/html`. You can also - only create the man pages with `make man` in the `docs` dir. - -* -f command line option only works on the untranslated remote - repository folder names now. Previously folderfilters had to match - both the local AND remote name which caused unwanted behavior in - combination with nametrans rules. Clarify in the help text. - -* Some better output when using nonsensical configuration settings - -Bug Fixes ---------- - -* Improve compatability of the curses UI with python 2.6 diff --git a/Changelog.rst b/Changelog.rst index 2b41ff1..f8bdfaa 100644 --- a/Changelog.rst +++ b/Changelog.rst @@ -5,11 +5,52 @@ ChangeLog :website: http://offlineimap.org -**NOTE FROM THE MAINTAINER:** - Contributors should use the `WIP` section in Changelog.draft.rst in order to - add changes they are working on. I will use it to make the new changelog entry - on releases. And because I'm lazy, it will also be used as a draft for the - releases announces. +WIP (add new stuff for the next release) +======================================== + +New Features +------------ + +Changes +------- + +Bug Fixes +--------- + + +OfflineIMAP v6.5.3 (2012-04-02) +=============================== + +* --dry-run mode protects us from performing any actual action. It will + not precisely give the exact information what will happen. If e.g. it + would need to create a folder, it merely outputs "Would create folder + X", but not how many and which mails it would transfer. + +* internal code changes to prepare for Python3 + +* Improve user documentation of nametrans/folderfilter + +* Fixed some cases where invalid nametrans rules were not caught and + we would not propagate local folders to the remote repository. + (now tested in test03) + +* Revert "* Slight performance enhancement uploading mails to an IMAP + server in the common case." It might have led to instabilities. + +* Revamped documentation structure. `make` in the `docs` dir or `make + doc` in the root dir will now create the 1) man page and 2) the user + documentation using sphinx (requiring python-doctools, and + sphinx). The resulting user docs are in `docs/html`. You can also + only create the man pages with `make man` in the `docs` dir. + +* -f command line option only works on the untranslated remote + repository folder names now. Previously folderfilters had to match + both the local AND remote name which caused unwanted behavior in + combination with nametrans rules. Clarify in the help text. + +* Some better output when using nonsensical configuration settings + +* Improve compatability of the curses UI with python 2.6 OfflineIMAP v6.5.2.1 (2012-04-04) ===================================== diff --git a/offlineimap/__init__.py b/offlineimap/__init__.py index 0dc0943..5673a89 100644 --- a/offlineimap/__init__.py +++ b/offlineimap/__init__.py @@ -1,7 +1,7 @@ __all__ = ['OfflineImap'] __productname__ = 'OfflineIMAP' -__version__ = "6.5.2.1" +__version__ = "6.5.3" __copyright__ = "Copyright 2002-2012 John Goerzen & contributors" __author__ = "John Goerzen" __author_email__= "john@complete.org"