[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