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

Martin Sivak msivak at redhat.com
Wed Aug 8 14:03:59 UTC 2012


Yes, the object was moved to different file to avoid circular import.

Martin

----- Original Message -----
> 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
> 
> _______________________________________________
> anaconda-patches mailing list
> anaconda-patches at lists.fedorahosted.org
> https://lists.fedorahosted.org/mailman/listinfo/anaconda-patches
> 


More information about the anaconda-patches mailing list