Merge branch 'avar/pr404' into next

Signed-off-by: Nicolas Sebrecht <nicolas.s-dev@laposte.net>

offlineimap.conf

@@ -1259,13 +1259,20 @@ remoteuser = username
 # Only "remoteuser" (or "remoteusereval" ) is mandatory.  Default values for
 # other parameters are OK, and you should not need fiddle with those.
 #
-# The Gmail repository will use hard-coded values for "remotehost",
+# The Gmail repository provides default values for "remotehost",
-# "remoteport", "tunnel" and "ssl".  Any attempt to set those parameters will be
+# "remoteport", "tunnel" and "ssl". For the defaults we use, see:
-# silently ignored. For details, see
 #
 #  http://mail.google.com/support/bin/answer.py?answer=78799&topic=12814
 #
-# This means ssl is enabled and must be configured correcly.
+# This means ssl is enabled and must be configured correcly when connecting to
+# Gmail.
+#
+# In addition we provide defaults for "oauth2_request_url",
+# "trashfolder" and "spamfolder".
+#
+# All of the defaults we provide can be overriden. E.g. you can
+# override "remotehost"/"remoteport"/"ssl" if you'd like to connect to
+# imap.gmail.com via a local stunnel instead of directly.
 #
 # To enable GMail labels synchronisation, set the option "synclabels" in the
 # corresponding "Account" section.

offlineimap/repository/Gmail.py

@@ -22,55 +22,67 @@ from offlineimap import folder, OfflineImapError
 class GmailRepository(IMAPRepository):
     """Gmail IMAP repository.
 
-    Falls back to hard-coded gmail host name and port, if none were specified:
+    This class just has default settings for GMail's IMAP service. So
+    you can do 'type = Gmail' instead of 'type = IMAP' and skip
+    specifying the hostname, port etc. See
     http://mail.google.com/support/bin/answer.py?answer=78799&topic=12814
-    """
+    for the values we use."""
-
-    OAUTH2_URL = 'https://accounts.google.com/o/oauth2/token'
-    # Gmail IMAP server hostname
-    HOSTNAME = "imap.gmail.com"
-    # Gmail IMAP server port
-    PORT = 993
-
     def __init__(self, reposname, account):
         """Initialize a GmailRepository object."""
-        # Enforce SSL usage
-        account.getconfig().set('Repository ' + reposname,
-                                'ssl', 'yes')
         IMAPRepository.__init__(self, reposname, account)
 
-
     def gethost(self):
         """Return the server name to connect to.
 
-        Gmail implementation first checks for the usual IMAP settings
+        We first check the usual IMAP settings, and then fall back to
-        and falls back to imap.gmail.com if not specified."""
+        imap.gmail.com if nothing is specified."""
         try:
             return super(GmailRepository, self).gethost()
         except OfflineImapError:
-            # Nothing was configured, cache and return hardcoded one.
+            # Nothing was configured, cache and return hardcoded
-            self._host = GmailRepository.HOSTNAME
+            # one. See the parent class (IMAPRepository) for how this
+            # cache is used.
+            self._host = "imap.gmail.com"
             return self._host
 
     def getoauth2_request_url(self):
-        """Return the server name to connect to.
+        """Return the OAuth URL to request tokens from.
 
-        Gmail implementation first checks for the usual IMAP settings
+        We first check the usual OAuth settings, and then fall back to
-        and falls back to imap.gmail.com if not specified."""
+        https://accounts.google.com/o/oauth2/token if nothing is
+        specified."""
 
         url = super(GmailRepository, self).getoauth2_request_url()
         if url is None:
             # Nothing was configured, cache and return hardcoded one.
-            self.setoauth2_request_url(GmailRepository.OAUTH2_URL)
+            self.setoauth2_request_url("https://accounts.google.com/o/oauth2/token")
         else:
             self.setoauth2_request_url(url)
         return self.oauth2_request_url
 
     def getport(self):
-        return GmailRepository.PORT
+        """Return the port number to connect to.
+
+        This Gmail implementation first checks for the usual IMAP settings
+        and falls back to 993 if nothing is specified."""
+
+        port = super(GmailRepository, self).getport()
+
+        if port is None:
+            return 993
+        else:
+            return port
 
     def getssl(self):
+        ssl = self.getconfboolean('ssl', None)
+
+        if ssl is None:
+            # Nothing was configured, return our default setting for
+            # GMail. Maybe this should look more similar to gethost &
+            # we could just rely on the global "ssl = yes" default.
             return True
+        else:
+            return ssl
 
     def getpreauthtunnel(self):
         return None
@@ -87,5 +99,8 @@ class GmailRepository(IMAPRepository):
         return self.getconf('trashfolder', '[Gmail]/Trash')
 
     def getspamfolder(self):
-        #: Gmail also deletes messages upon EXPUNGE in the Spam folder
+        # Depending on the IMAP settings (Settings -> Forwarding and
+        # POP/IMAP -> IMAP Access -> "When I mark a message in IMAP as
+        # deleted") GMail might also deletes messages upon EXPUNGE in
+        # the Spam folder.
         return self.getconf('spamfolder', '[Gmail]/Spam')