resync to latest version of patches submitted to sugar upstream on github

6 files changed, 144 insertions, 189 deletions

diff --git a/src/jarabe/journal/palettes.py b/src/jarabe/journal/palettes.py
index 5ba959e..cc604dc 100644
--- a/src/jarabe/journal/palettes.py
+++ b/src/jarabe/journal/palettes.py
@@ -39,7 +39,7 @@ from jarabe.model import mimeregistry
 from jarabe.journal import misc
 from jarabe.journal import model
 from jarabe.journal import journalwindow
-from jarabe.web import accountsmanager as oam
+from jarabe.web import accountsmanager
 
 
 class ObjectPalette(Palette):
@@ -252,7 +252,7 @@ class CopyMenu(Gtk.Menu):
             self.append(volume_menu)
             volume_menu.show()
 
-        for account in oam.get_configured_accounts():
+        for account in accountsmanager.get_configured_accounts():
             menu = account.get_share_menu(metadata)
             self.append(menu)
 
diff --git a/src/jarabe/web/__init__.py b/src/jarabe/web/__init__.py
index e69de29..85f6a24 100644
--- a/src/jarabe/web/__init__.py
+++ b/src/jarabe/web/__init__.py
@@ -0,0 +1,15 @@
+# Copyright (C) 2006-2007, Red Hat, Inc.
+#
+# 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
diff --git a/src/jarabe/web/account.py b/src/jarabe/web/account.py
index f9be23e..2e55f25 100644
--- a/src/jarabe/web/account.py
+++ b/src/jarabe/web/account.py
@@ -25,54 +25,119 @@ from sugar3.graphics.toolbutton import ToolButton
 
 class Account():
     ''' Account is a prototype class for online accounts. It provides
-    stubs for five public methods that are used by online services:
-
-    get_description returns a brief description of the online service
-    used in palette menuitems and on the webservices control panel.
-
-    is_configured returns True if the service has been configured for
-    use, e.g., an access token has been acquired.
-
-    is_active returns True if the service is currently available,
-    e.g., the access token has not expired.
-
-    get_share_menu returns a menu item used on the Copy To palette in
-    the Journal and on the Journal detail view toolbar.
-
-    get_refresh_menu returns a menu item used on the Journal detail
-    view toolbar.
+    stubs for five public methods that are used by online services
     '''
 
     def get_description(self):
+        ''' get_description returns a brief description of the online
+        service. The description is used in palette menuitems and on
+        the webservices control panel.
+
+        :returns: online-account name
+        :rtype: string
+        '''
         raise NotImplementedError
 
     def is_configured(self):
+        ''' is_configured returns True if the service has been
+        configured for use, e.g., an access token has been acquired.
+
+        :returns: configuration status
+        :rtype: bool
+        '''
         raise NotImplementedError
 
     def is_active(self):
+        ''' is_active returns True if the service is currently
+        available, e.g., the access token has not expired.
+
+        :returns: active status
+        :rtype: bool
+        '''
         raise NotImplementedError
 
     def get_share_menu(self):
+        ''' get_share_menu returns a menu item used on the Copy To
+        palette in the Journal and on the Journal detail-view toolbar.
+
+        :param: journal_entry_metadata
+        :type: dict
+        :returns: MenuItem
+        :rtype: MenuItem
+        '''
         raise NotImplementedError
 
     def get_refresh_menu(self):
+        ''' get_refresh_menu returns a menu item used on the Journal
+        detail-view toolbar.
+
+        :param: journal_entry_metadata
+        :type: dict
+        :returns: MenuItem
+        :rtype: MenuItem
+        '''
         raise NotImplementedError
 
 
 class MenuItem(MenuItem):
+    ''' This is a subclass of sugar3.graphics.menuitem.MenuItem
+
+    The transfer signals are used to update progress of data transfer
+    between Sugar and the online service. Signal handlers in the
+    journaltoolbox manage a Notification Alert of this progress.
+
+    'transfer-started' is emitted at the beginning of a transfer.
+
+    'transfer-progress' is emitted periodically to indicate progress.
+
+    :emits: total data to transfer
+    :type: float
+    :emits: quantity of data transfered
+    :type: float
+    :emits: message string
+    :type: string
+
+    'transfer-completed' is emitted at the successful completion of a
+    transfer.
+
+    :emits: message string
+    :type: string
+
+    'transfer-failed' is emitted at if the transfer fails.
+
+    :emits: message string
+    :type: string
+
+    'transfer-state-changed' is emitted when the account manager wants
+    to indicate a change in state.
+
+    :emits: message string
+    :type: string
+
+    The comments-changed signal is emitted by the online service if
+    changes to the 'comments' metadata have been made. The
+    expandedentry of the Journal detail view displays these comments.
+
+    :emits: metadata['comments']
+    :type: string
+    '''
     __gsignals__ = {
-        'transfer-started': (GObject.SignalFlags.RUN_FIRST, None,
-                             ([int, int])),
+        'transfer-started': (GObject.SignalFlags.RUN_FIRST, None, ([])),
         'transfer-progress': (GObject.SignalFlags.RUN_FIRST, None,
-                              ([int, int, float])),
-        'transfer-completed': (GObject.SignalFlags.RUN_FIRST, None,
-                               ([int, int])),
-        'transfer-failed': (GObject.SignalFlags.RUN_FIRST, None,
-                            ([int, int, str])),
+                              ([int, int, str])),
+        'transfer-completed': (GObject.SignalFlags.RUN_FIRST, None, ([str])),
+        'transfer-failed': (GObject.SignalFlags.RUN_FIRST, None, ([str])),
         'transfer-state-changed': (GObject.SignalFlags.RUN_FIRST, None,
                                    ([str])),
-        'comments-changed': (GObject.SignalFlags.RUN_FIRST, None, ([str])),
-    }
+        'comments-changed': (GObject.SignalFlags.RUN_FIRST, None, ([str]))
+        }
 
     def set_metadata(self, metadata):
+        ''' The online account uses this method to set metadata in the
+        Sugar journal and provide a means of updating menuitem status,
+        e.g., enabling the refresh menu after a successful transfer.
+
+        :param: journal_entry_metadata
+        :type: dict
+        '''
         raise NotImplementedError
diff --git a/src/jarabe/web/accountsmanager.py b/src/jarabe/web/accountsmanager.py
index be083c0..cd1da83 100644
--- a/src/jarabe/web/accountsmanager.py
+++ b/src/jarabe/web/accountsmanager.py
@@ -22,38 +22,45 @@ from gi.repository import Gtk
 
 from jarabe import config
 
+_accounts = []
+
 
 def get_all_accounts():
-    accounts = []
+    ''' Returns a list of all installed online account managers '''
+    global _accounts  # No need to do this every time.
+    if len(_accounts) > 0:
+        return _accounts
 
     web_path = os.path.join(config.ext_path, 'web')
-    if os.path.exists(web_path):
-        for d in os.listdir(web_path):
-            dir_path = os.path.join(web_path, d)
-            module = _load_module(dir_path)
-            if module is not None:
-                accounts.append(module)
-                _load_icon_path(dir_path)
+    try:
+        web_path_dirs = os.listdir(web_path)
+    except OSError, e:
+        web_path_dirs = []
+        logging.warning('listdir: %s: %s' % (web_path, e))
+
+    for d in web_path_dirs:
+        dir_path = os.path.join(web_path, d)
+        module = _load_module(dir_path)
+        if module is not None:
+            _accounts.append(module)
+            _extend_icon_theme_search_path(dir_path)
 
-    return accounts
+    return _accounts
 
 
 def _load_module(dir_path):
     module = None
     if os.path.isdir(dir_path):
         for f in os.listdir(dir_path):
-            if f.endswith('.py') and not f.startswith('__'):
+            if f == 'account.py':
                 module_name = f[:-3]
                 logging.debug('OnlineAccountsManager loading %s' % (
                         module_name))
-
+                module_path = 'web.%s.%s' % (os.path.basename(dir_path),
+                                             module_name)
                 try:
-                    mod = __import__(
-                        'web.' + os.path.basename(dir_path) + '.' + \
-                            module_name,
-                        globals(),
-                        locals(),
-                        [module_name])
+                    mod = __import__(module_path, globals(), locals(),
+                                     [module_name])
                     if hasattr(mod, 'get_account'):
                         module = mod.get_account()
 
@@ -64,17 +71,22 @@ def _load_module(dir_path):
     return module
 
 
-def _load_icon_path(dir_path):
+def _extend_icon_theme_search_path(dir_path):
     icon_theme = Gtk.IconTheme.get_default()
     icon_search_path = icon_theme.get_search_path()
 
-    if os.path.isdir(dir_path):
-        for f in os.listdir(dir_path):
-            if f == 'icons':
-                icon_path = os.path.join(dir_path, f)
-                if os.path.isdir(icon_path) and \
-                        icon_path not in icon_search_path:
-                    icon_theme.append_search_path(icon_path)
+    try:
+        icon_path_dirs = os.listdir(dir_path)
+    except OSError, e:
+        icon_path_dirs = []
+        logging.warning('listdir: %s: %s' % (dir_path, e))
+
+    for f in icon_path_dirs:
+        if f == 'icons':
+            icon_path = os.path.join(dir_path, f)
+            if os.path.isdir(icon_path) and \
+                    icon_path not in icon_search_path:
+                icon_theme.append_search_path(icon_path)
 
 
 def get_configured_accounts():
diff --git a/src/jarabe/web/online_account.py b/src/jarabe/web/online_account.py
deleted file mode 100644
index d0b7a67..0000000
--- a/src/jarabe/web/online_account.py
+++ /dev/null
@@ -1,60 +0,0 @@
-#!/usr/bin/env python
-#
-# Copyright (c) 2013 Walter Bender, Raul Gutierrez Segales
-#
-# This library is free software; you can redistribute it and/or
-# modify it under the terms of the GNU Lesser General Public
-# License as published by the Free Software Foundation; either
-# version 2 of the License, or (at your option) any later version.
-#
-# This library 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
-# Lesser General Public License for more details.
-#
-# You should have received a copy of the GNU Lesser General Public
-# License along with this library; if not, write to the
-# Free Software Foundation, Inc., 59 Temple Place - Suite 330,
-# Boston, MA 02111-1307, USA.
-
-import logging
-
-from gi.repository import GObject
-
-from sugar3.graphics.menuitem import MenuItem
-from sugar3.graphics.toolbutton import ToolButton
-
-
-class OnlineAccount(GObject.GObject):
-    def get_description(self):
-        raise Exception("Not defined")
-
-    def is_configured(self):
-        raise Exception("Not defined")
-
-    def is_active(self):
-        raise Exception("Not defined")
-
-    def get_share_menu(self):
-        raise Exception("Not defined")
-
-    def get_refresh_button(self):
-        raise Exception("Not defined")
-
-
-class OnlineMenu(MenuItem):
-    __gsignals__ = {
-        'transfer-started': (GObject.SignalFlags.RUN_FIRST, None, ([int, int])),
-        'transfer-progress': (GObject.SignalFlags.RUN_FIRST, None, ([int, int, float])),
-        'transfer-completed': (GObject.SignalFlags.RUN_FIRST, None, ([int, int])),
-        'transfer-failed': (GObject.SignalFlags.RUN_FIRST, None, ([int, int, str])),
-        'transfer-state-changed': (GObject.SignalFlags.RUN_FIRST, None, ([str])),
-        'comments-changed': (GObject.SignalFlags.RUN_FIRST, None, ([str])),
-    }
-
-    def _transfer_state_changed_cb(self, transfer_object, state):
-        logging.debug('_transfer_state_changed_cb')
-        self.emit('transfer-state-changed', state)
-
-    def set_metadata(self, metadata):
-        raise Exception("Not defined")
diff --git a/src/jarabe/web/online_accounts_manager.py b/src/jarabe/web/online_accounts_manager.py
deleted file mode 100644
index d2c26c9..0000000
--- a/src/jarabe/web/online_accounts_manager.py
+++ /dev/null
@@ -1,77 +0,0 @@
-#!/usr/bin/env python
-#
-# Copyright (c) 2013 Walter Bender
-#
-# This library is free software; you can redistribute it and/or
-# modify it under the terms of the GNU Lesser General Public
-# License as published by the Free Software Foundation; either
-# version 2 of the License, or (at your option) any later version.
-#
-# This library 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
-# Lesser General Public License for more details.
-#
-# You should have received a copy of the GNU Lesser General Public
-# License along with this library; if not, write to the
-# Free Software Foundation, Inc., 59 Temple Place - Suite 330,
-# Boston, MA 02111-1307, USA.
-
-from gi.repository import Gtk
-from gi.repository import GObject
-import logging
-import os
-
-from jarabe import config
-
-
-class OnlineAccountsManager(GObject.GObject):
-    @classmethod
-    def all_accounts(cls):
-        accounts = []
-
-        icon_theme = Gtk.IconTheme.get_default()
-        icon_search_path = icon_theme.get_search_path()
-
-        web_paths = [os.path.join(config.ext_path, 'web'),
-                     os.path.join(os.path.expanduser('~'),
-                                  '.sugar', 'extensions', 'web')]
-
-        for web_path in web_paths:
-            if os.path.exists(web_path):
-                for d in os.listdir(web_path):
-                    dir_path = os.path.join(web_path, d)
-                    if os.path.isdir(dir_path):
-                        for f in os.listdir(dir_path):
-                            if f.endswith('.py') and not f.startswith('__'):
-                                module_name = f[:-3]
-                                logging.debug(
-                                    'OnlineAccountsManager loading %s' % \
-                                                  (module_name))
-                                try:
-                                    mod = __import__(
-                                        'web.' + d + '.' + module_name,
-                                        globals(),
-                                        locals(),
-                                        [module_name])
-                                    if hasattr(mod, 'get_account'):
-                                        accounts.append(mod.get_account())
-                                except Exception as e:
-                                    logging.exception(
-                                        'Exception while loading %s: %s' % \
-                                            (module_name, str(e)))
-                            elif f == 'icons':
-                                icon_path = os.path.join(dir_path, f)
-                                if os.path.isdir(icon_path) and \
-                                        icon_path not in icon_search_path:
-                                    icon_theme.append_search_path(icon_path)
-
-        return accounts
-
-    @classmethod
-    def configured_accounts(cls):
-        return [a for a in cls.all_accounts() if a.is_configured()]
-
-    @classmethod
-    def active_accounts(cls):
-        return [a for a in cls.all_accounts() if a.is_active()]