[PATCH 08/13] add documentation and comments to TUI classes

Vratislav Podzimek vpodzime at redhat.com
Wed Aug 8 11:13:48 UTC 2012


On Wed, 2012-08-08 at 10:52 +0200, Martin Sivak wrote:
> ---
>  pyanaconda/ui/tui/__init__.py        |   71 +++++++++++++++++++---------------
>  pyanaconda/ui/tui/hubs/__init__.py   |   27 +++++++++++--
>  pyanaconda/ui/tui/spokes/__init__.py |   15 ++++++-
>  pyanaconda/ui/tui/tuiobject.py       |   59 ++++++++++++++++++++++++++++
>  4 files changed, 136 insertions(+), 36 deletions(-)
>  create mode 100644 pyanaconda/ui/tui/tuiobject.py
> 
> diff --git a/pyanaconda/ui/tui/__init__.py b/pyanaconda/ui/tui/__init__.py
> index 22acf1c..5f45c57 100644
> --- a/pyanaconda/ui/tui/__init__.py
> +++ b/pyanaconda/ui/tui/__init__.py
> @@ -1,11 +1,23 @@
>  from pyanaconda import ui
>  from pyanaconda.ui import common
>  import simpleline as tui
> +from hubs.summary import SummaryHub
> +from spokes import StandaloneSpoke
>  
>  class ErrorDialog(tui.UIScreen):
> +    """Dialog screen for reporting errors to user."""
> +
>      title = u"Error"
>  
>      def __init__(self, app, message):
> +        """
> +        :param app: the running application reference
> +        :type app: instance of App class
> +
> +        :param message: the message to show to the user
> +        :type message: unicode
> +        """
> +
>          tui.UIScreen.__init__(self, app)
>          self._message = message
>  
> @@ -18,12 +30,23 @@ class ErrorDialog(tui.UIScreen):
>          return u"Press enter to exit."
>  
>      def input(self, key):
> +        """This dialog is closed by any input."""
>          self.close()
>  
>  class YesNoDialog(tui.UIScreen):
> +    """Dialog screen for Yes - No questions."""
> +
>      title = u"Question"
>  
>      def __init__(self, app, message):
> +        """
> +        :param app: the running application reference
> +        :type app: instance of App class
> +
> +        :param message: the message to show to the user
> +        :type message: unicode
> +        """
> +
>          tui.UIScreen.__init__(self, app)
>          self._message = message
>          self._response = None
> @@ -54,11 +77,27 @@ class YesNoDialog(tui.UIScreen):
>  
>      @property
>      def answer(self):
> +        """The response can be True (yes), False (no) or None (no response)."""
>          return self._response
>  
>  class TextUserInterface(ui.UserInterface):
> +    """This is the main class for Text user interface."""
>  
>      def __init__(self, storage, payload, instclass):
> +        """
> +        For detailed description of the arguments see
> +        the parent class.
> +
> +        :param storage: storage backend reference
> +        :type storage: instance of pyanaconda.Storage
> +
> +        :param payload: payload (usually yum) reference
> +        :type payload: instance of payload handler
> +
> +        :param instclass: install class reference
> +        :type instclass: instance of install class
> +        """
> +
>          ui.UserInterface.__init__(self, storage, payload, instclass)
>          self._app = None
>  
> @@ -67,14 +106,8 @@ class TextUserInterface(ui.UserInterface):
>             This method must be provided by all subclasses.
>          """
>          self._app = tui.App(u"Anaconda", yes_or_no_question = YesNoDialog)
> -
> -        from hubs.summary import SummaryHub
> -        #from hubs.progress import ProgressHub
>          self._hubs = [SummaryHub]
>  
> -
> -        from spokes import StandaloneSpoke
> -
>          # First, grab a list of all the standalone spokes.
>          path = os.path.join(os.path.dirname(__file__), "spokes")
>          actionClasses = self.getActionClasses("pyanaconda.ui.tui.spokes.%s", path, self._hubs, StandaloneSpoke)
> @@ -126,29 +159,3 @@ class TextUserInterface(ui.UserInterface):
>          question_window = YesNoDialog(self._app, message)
>          self._app.switch_window_modal(question_window)
>          return question_window.answer

Should the following change be in this patch?
> -
> -class TUIObject(tui.UIScreen, common.UIObject):
> -    title = u"Default title"
> -
> -    def __init__(self, app, data):
> -        tui.UIScreen.__init__(self, app)
> -        common.UIObject.__init__(self, data)
> -
> -    @property
> -    def showable(self):
> -        return True
> -
> -    def teardown(self):
> -        pass
> -
> -    def initialize(self):
> -        pass
> -
> -    def refresh(self, args = None):
> -        """Put everything to display into self.window list."""
> -        tui.UIScreen.refresh(self, args)
> -
> -    def retranslate(self):
> -        # do retranslation stuff
> -        # redraw
> -        self.app.switch_screen(self)
> diff --git a/pyanaconda/ui/tui/hubs/__init__.py b/pyanaconda/ui/tui/hubs/__init__.py
> index 33a122e..9d4937a 100644
> --- a/pyanaconda/ui/tui/hubs/__init__.py
> +++ b/pyanaconda/ui/tui/hubs/__init__.py
> @@ -1,21 +1,37 @@
>  from .. import simpleline as tui
> -from pyanaconda.ui.tui import TUIObject
> +from pyanaconda.ui.tui.tuiobject import TUIObject
>  from pyanaconda.ui.tui.spokes import collect_spokes
>  from pyanaconda.ui import common
>  
>  class TUIHub(TUIObject, common.Hub):
> +    """Base Hub class implementing the pyanaconda.ui.common.Hub interface.
> +    It uses text based categories to look for relevant Spokes and manages
> +    all the spokes it finds to have the proper category.
> +
> +    :param categories: list all the spoke categories to be displayed in this Hub
> +    :type categories: list of strings
> +
> +    :param title: title for this Hub
> +    :type title: unicode
> +
> +    """
> +
>      categories = []
>      title = "Default HUB title"
>  
>      def __init__(self, app, data, storage, payload, instclass):
>          TUIObject.__init__(self, app, data)
>          common.Hub.__init__(self, data, storage, payload, instclass)
> -        self._spokes = {}
> -        self._keys = {}
> +
> +        self._spokes = {}     # holds spokes referenced by their class name
> +        self._keys = {}       # holds spokes referenced by their user input key
>          self._spoke_count = 0
>  
> +        # look for spokes having category present in self.categories
>          for c in self.categories:
>              spokes = collect_spokes(c)
> +
> +            # sort them according to their priority
>              for s in sorted(spokes, key = lambda s: s.priority):
>                  spoke = s(app, data, storage, payload, instclass)
>                  spoke.initialize()
> @@ -31,12 +47,15 @@ class TUIHub(TUIObject, common.Hub):
>  
> 
>      def refresh(self, args = None):
> +        """This methods fills the self._window list by all the objects
> +        we want shown on this screen. Title and Spokes mostly."""
>          TUIObject.refresh(self, args)
>  
>          def _prep(i, w):
>              number = tui.TextWidget("%2d)" % i)
>              return tui.ColumnWidget([(3, [number]), (None, [w])], 1)
>  
> +        # split spokes to two columns
>          left = [_prep(i, w) for i,w in self._keys.iteritems() if i % 2 == 1]
>          right = [_prep(i, w) for i,w in self._keys.iteritems() if i % 2 == 0]
>  
> @@ -46,6 +65,8 @@ class TUIHub(TUIObject, common.Hub):
>          return True
>  
>      def input(self, key):
> +        """Handle user input. Numbers are used to show a spoke, the rest is passed
> +        to the higher level for processing."""
>          try:
>              number = int(key)
>              self.app.switch_screen_with_return(self._keys[number])
> diff --git a/pyanaconda/ui/tui/spokes/__init__.py b/pyanaconda/ui/tui/spokes/__init__.py
> index 153b79c..07fc3d1 100644
> --- a/pyanaconda/ui/tui/spokes/__init__.py
> +++ b/pyanaconda/ui/tui/spokes/__init__.py
> @@ -1,5 +1,5 @@
>  from .. import simpleline as tui
> -from pyanaconda.ui.tui import TUIObject
> +from pyanaconda.ui.tui.tuiobject import TUIObject
>  from pyanaconda.ui.common import Spoke, StandaloneSpoke, NormalSpoke, PersonalizationSpoke, collect
>  import os
>  
> @@ -7,6 +7,17 @@ __all__ = ["TUISpoke", "StandaloneSpoke", "NormalSpoke", "PersonalizationSpoke",
>             "collect_spokes", "collect_categories"]
>  
>  class TUISpoke(TUIObject, tui.Widget, Spoke):
> +    """Base TUI Spoke class implementing the pyanaconda.ui.common.Spoke API.
> +    It also acts as a Widget so we can easily add it to Hub, where is shows
> +    as a summary box with title, description and completed checkbox.
> +
> +    :param title: title of this spoke
> +    :type title: unicode
> +
> +    :param category: category this spoke belongs to
> +    :type category: string
> +    """
> +
>      title = u"Default spoke title"
>      category = u""
>  
> @@ -28,9 +39,11 @@ class TUISpoke(TUIObject, tui.Widget, Spoke):
>          return True
>  
>      def input(self, key):
> +        """Handle the input, the base class just forwards it to the App level."""
>          return key
>  
>      def render(self, width):
> +        """Render the summary representation for Hub to internal buffer."""
>          tui.Widget.render(self, width)
>          c = tui.CheckboxWidget(completed = self.completed, title = self.title, text = self.status)
>          c.render(width)
> diff --git a/pyanaconda/ui/tui/tuiobject.py b/pyanaconda/ui/tui/tuiobject.py
> new file mode 100644
> index 0000000..35c920f
> --- /dev/null
> +++ b/pyanaconda/ui/tui/tuiobject.py
> @@ -0,0 +1,59 @@
> +# base TUIObject for Anaconda TUI
> +#
> +# Copyright (C) 2012  Red Hat, Inc.
> +#
> +# This copyrighted material is made available to anyone wishing to use,
> +# modify, copy, or redistribute it subject to the terms and conditions of
> +# the GNU General Public License v.2, or (at your option) any later version.
> +# This program is distributed in the hope that it will be useful, but WITHOUT
> +# ANY WARRANTY expressed or implied, including the implied warranties 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 Street, Fifth Floor, Boston, MA
> +# 02110-1301, USA.  Any Red Hat trademarks that are incorporated in the
> +# source code or documentation are not subject to the GNU General Public
> +# License and may only be used or replicated with the express permission of
> +# Red Hat, Inc.
> +#
> +# Red Hat Author(s): Martin Sivak <msivak at redhat.com>
> +#
> +
> +from pyanaconda.ui import common
> +import simpleline as tui
> +
> +class TUIObject(tui.UIScreen, common.UIObject):
> +    """Base class for Anaconda specific TUI screens. Implements the
> +    common pyanaconda.ui.common.UIObject interface"""
> +
> +    title = u"Default title"
> +
> +    def __init__(self, app, data):
> +        tui.UIScreen.__init__(self, app)
> +        common.UIObject.__init__(self, data)
> +
> +    @property
> +    def showable(self):
> +        return True
> +
> +    def teardown(self):
> +        pass
> +
> +    def initialize(self):
> +        """This method gets called whenever Hub or UserInterface prepares
> +        all found objects for use. It is called only once and has no direct
> +        connection to rendering."""
> +        pass
> +
> +    def refresh(self, args = None):
> +        """Put everything to display into self.window list."""
> +        tui.UIScreen.refresh(self, args)
> +
> +    def retranslate(self):
> +        """After language is changed, this method ensures that all the
> +        texts on screen are translated. It only needs to refresh the
> +        screen in text mode, as translation will happen automatically
> +        and there is no way to change labels on previously displayed content."""
> +
> +        # redraw
> +        self.app.switch_screen(self)

-- 
Vratislav Podzimek

Anaconda Rider | Red Hat, Inc. | Brno - Czech Republic



More information about the anaconda-patches mailing list