# Common classes for user interface
#
# Copyright (C) 2012-2014 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): Chris Lumens <clumens@redhat.com>
# Martin Sivak <msivak@redhat.com>
#
import os
import imp
import inspect
import sys
import types
from abc import ABCMeta, abstractproperty
from pyanaconda.constants import ANACONDA_ENVIRON, FIRSTBOOT_ENVIRON
from pyanaconda.errors import RemovedModuleError
from pykickstart.constants import FIRSTBOOT_RECONFIG, DISPLAY_MODE_TEXT
import logging
log = logging.getLogger("anaconda")
class UIObject(object):
"""This is the base class from which all other UI classes are derived. It
thus contains only attributes and methods that are common to everything
else. It should not be directly instantiated.
"""
def __init__(self, data):
"""Create a new UIObject instance, including loading its uiFile and
all UI-related objects.
Instance attributes:
data -- An instance of a pykickstart Handler object. The Hub
never directly uses this instance. Instead, it passes
it down into Spokes when they are created and applied.
The Hub simply stores this instance so it doesn't need
to be passed by the user.
"""
if self.__class__ is UIObject:
raise TypeError("UIObject is an abstract class")
self.skipTo = None
self._data = data
def initialize(self):
"""Perform whatever actions are necessary to pre-fill the UI with
values. This method is called only once, after the object is
created. The difference between this method and __init__ is that
this method may take a long time (especially for NormalSpokes) and
thus may be run in its own thread.
"""
pass
def refresh(self):
"""Perform whatever actions are necessary to reset the UI immediately
before it is displayed. This method is called every time a screen
is shown, which could potentially be several times in the case of a
NormalSpoke. Thus, it's important to not do things like populate
stores (which could result in the store having duplicate entries) or
anything that takes a long time (as that will result in a delay
between the user's action and showing the results).
For anything potentially long-lived, use the initialize method.
"""
pass
@property
def showable(self):
"""Should this object even be shown? This method is useful for checking
some precondition before this screen is shown. If False is returned,
the screen will be skipped and the object destroyed.
"""
return True
def teardown(self):
"""Perform whatever actions are necessary to clean up after this object
is done. It's not necessary for every subclass to have an instance
of this method.
NOTE: It is important for this method to not destroy self.window if
you are making a Spoke or Hub subclass. It is assumed that once
these are instantiated, they live until the program terminates. This
is required for various status notifications.
"""
pass
@property
def data(self):
return self._data
class FirstbootSpokeMixIn(object):
"""This MixIn class marks Spokes as usable for Firstboot
and Anaconda.
"""
@classmethod
def should_run(cls, environment, data):
"""This method is responsible for beginning Spoke initialization
in the firstboot environment (even before __init__).
It should return True if the spoke is to be shown
and False if it should be skipped.
It might be called multiple times, with or without (None)
the data argument.
"""
if environment == ANACONDA_ENVIRON:
return True
elif environment == FIRSTBOOT_ENVIRON and data is None:
# cannot decide, stay in the game and let another call with data
# available (will come) decide
return True
elif environment == FIRSTBOOT_ENVIRON and \
data and data.firstboot.firstboot == FIRSTBOOT_RECONFIG:
# generally run spokes in firstboot only if doing reconfig, spokes
# that should run even if not doing reconfig should override this
# method
return True
else:
return False
class FirstbootOnlySpokeMixIn(object):
"""This MixIn class marks Spokes as usable for Firstboot."""
@classmethod
def should_run(cls, environment, data):
"""This method is responsible for beginning Spoke initialization
in the firstboot environment (even before __init__).
It should return True if the spoke is to be shown and False
if it should be skipped.
It might be called multiple times, with or without (None)
the data argument.
"""
if environment == FIRSTBOOT_ENVIRON:
# firstboot only spokes should run in firstboot by default, spokes
# that should run even if not doing reconfig should override this
# method
return True
else:
return False
class Spoke(object, metaclass=ABCMeta):
"""A Spoke is a single configuration screen. There are several different
places where a Spoke can be displayed, each of which will have its own
unique class. A Spoke is typically used when an element in the Hub is
selected but can also be displayed before a Hub or between multiple
Hubs.
What amount of the UI layout a Spoke provides depends upon where it is
to be shown. Regardless, the UI of a Spoke should be given by an
interface description file like glade as often as possible, though this
is not a strict requirement.
Class attributes:
category -- Under which SpokeCategory shall this Spoke be displayed
in the Hub? This is a reference to a Hub subclass (not an
object, but the class itself). If no category is given,
this Spoke will not be displayed. Note that category is
not required for any Spokes appearing before or after a
Hub.
icon -- The name of the icon to be displayed in the SpokeSelector
widget corresponding to this Spoke instance. If no icon
is given, the default from SpokeSelector will be used.
title -- The title to be displayed in the SpokeSelector widget
corresponding to this Spoke instance. If no title is
given, the default from SpokeSelector will be used.
"""
category = None
icon = None
title = None
def __init__(self, storage, payload, instclass):
"""Create a new Spoke instance.
The arguments this base class accepts defines the API that spokes
have to work with. A Spoke does not get free reign over everything
in the anaconda class, as that would be a big mess. Instead, a
Spoke may count on the following:
data -- An instance of a pykickstart Handler object. The
Spoke uses this to populate its UI with defaults
and to pass results back after it has run. The data
property must be implemented by classes inherting
from Spoke.
storage -- An instance of storage.Storage. This is useful for
determining what storage devices are present and how
they are configured.
payload -- An instance of a packaging.Payload subclass. This
is useful for displaying and selecting packages to
install, and in carrying out the actual installation.
instclass -- An instance of a BaseInstallClass subclass. This
is useful for determining distribution-specific
installation information like default package
selections and default partitioning.
"""
self._storage = storage
self.payload = payload
self.instclass = instclass
self.applyOnSkip = False
self.visitedSinceApplied = True
@abstractproperty
def data(self):
pass
@property
def storage(self):
return self._storage
@classmethod
def should_run(cls, environment, data):
"""This method is responsible for beginning Spoke initialization.
It should return True if the spoke is to be shown while in
<environment> and False if it should be skipped.
It might be called multiple times, with or without (None)
the data argument.
"""
return environment == ANACONDA_ENVIRON
def apply(self):
"""Apply the selections made on this Spoke to the object's preset
data object. This method must be provided by every subclass.
"""
raise NotImplementedError
@property
def changed(self):
"""Have the values on the spoke changed since the last time it was
run? If not, the apply and execute methods will be skipped. This
is to avoid the spoke doing potentially long-lived and destructive
actions that are completely unnecessary.
"""
return True
@property
def configured(self):
"""This method returns a list of textual ids that should
be written into the after-install customization status
file for the firstboot and GIE to know that the spoke was
configured and what value groups were provided."""
return ["%s.%s" % (self.__class__.__module__, self.__class__.__name__)]
@property
def completed(self):
"""Has this spoke been visited and completed? If not and the spoke is
mandatory, a special warning icon will be shown on the Hub beside the
spoke, and a highlighted message will be shown at the bottom of the
Hub. Installation will not be allowed to proceed until all mandatory
spokes are complete.
WARNING: This can be called before the spoke is finished initializing
if the spoke starts a thread. It should make sure it doesn't access
things until they are completely setup.
"""
return False
@property
def sensitive(self):
"""May the user click on this spoke's selector and be taken to the spoke?
This is different from the showable property. A spoke that is not
sensitive will still be shown on the hub, but the user may not enter it.
This is also different from the ready property. A spoke that is not
ready may not be entered, but the spoke may become ready in the future.
A spoke that is not sensitive will likely not become so.
Most spokes will not want to override this method.
"""
return True
@property
def mandatory(self):
"""Mark this spoke as mandatory. Installation will not be allowed
to proceed until all mandatory spokes are complete.
Spokes are mandatory unless marked as not being so.
"""
return True
def execute(self):
"""Cause the data object to take effect on the target system. This will
usually be as simple as calling one or more of the execute methods on
the data object. This method does not need to be provided by all
subclasses.
This method will be called in two different places: (1) Immediately
after initialize on kickstart installs. (2) Immediately after apply
in all cases.
"""
pass
@property
def status(self):
"""Given the current status of whatever this Spoke configures, return
a very brief string. The purpose of this is to display something
on the Hub under the Spoke's title so the user can tell at a glance
how things are configured.
A spoke's status line on the Hub can also be overloaded to provide
information about why a Spoke is not yet ready, or if an error has
occurred when setting it up. This can be done by calling
send_message from pyanaconda.ui.communication with the target
Spoke's class name and the message to be displayed.
If the Spoke was not yet ready when send_message was called, the
message will be overwritten with the value of this status property
when the Spoke becomes ready.
"""
raise NotImplementedError
def entry_logger(self):
"""Log immediately before this spoke is about to be displayed on the
screen. Subclasses may override this method if they want to log
more specific information, but an overridden method should finish
by calling this method so the entry will be logged.
"""
log.debug("Entered spoke: %s", self.__class__.__name__)
def exit_logger(self):
"""Log when a user leaves the spoke. Subclasses may override this
method if they want to log more specific information, but an
overridden method should finish by calling this method so the
exit will be logged.
"""
log.debug("Left spoke: %s", self.__class__.__name__)
# Inherit abstract methods from Spoke
# pylint: disable=abstract-method
class NormalSpoke(Spoke):
"""A NormalSpoke is a Spoke subclass that is displayed when the user
selects something on a Hub. This is what most Spokes in anaconda will
be based on.
From a layout perspective, a NormalSpoke takes up the entire screen
therefore hiding the Hub and its action area. The NormalSpoke also
provides some basic navigation information (where you are, what you're
installing, how to get back to the Hub) at the top of the screen.
"""
def __init__(self, storage, payload, instclass):
"""Create a NormalSpoke instance."""
Spoke.__init__(self, storage, payload, instclass)
self.selector = None
@property
def indirect(self):
"""If this property returns True, then this spoke is considered indirect.
An indirect spoke is one that can only be reached through another spoke
instead of directly through the hub. One example of this is the
custom partitioning spoke, which may only be accessed through the
install destination spoke.
Indirect spokes do not need to provide a completed or status property.
For most spokes, overriding this property is unnecessary.
"""
return False
@property
def ready(self):
"""Returns True if the Spoke has all the information required to be
displayed. Almost all spokes should keep the default value here.
Only override this method if the Spoke requires some potentially
long-lived process (like storage probing) before it's ready.
A Spoke may be marked as ready or not by calling send_ready or
send_not_ready from pyanaconda.ui.communication with the
target Spoke's class name.
While a Spoke is not ready, a progress message may be shown to
give the user some feedback. See the status property for details.
"""
return True
# Inherit abstract methods from NormalSpoke
# pylint: disable=abstract-method
class StandaloneSpoke(Spoke):
"""A StandaloneSpoke is a Spoke subclass that is displayed apart from any
Hub. It is suitable to be used as a Welcome screen.
From a layout perspective, a StandaloneSpoke provides a full screen
interface. However, it also provides navigation information at the top
and bottom of the screen that makes it look like the StandaloneSpoke
fits into some other UI element.
Class attributes:
preForHub/postForHub -- A reference to a Hub subclass this Spoke is
either a pre or post action for. Only one of
these may be set at a time. Note that all
post actions will be run for one hub before
any pre actions for the next.
priority -- This value is used to sort pre and post
actions. The lower a value, the earlier it
will be run. So a value of 0 for a post action
ensures it will run immediately after a Hub,
while a value of 0 for a pre actions means
it will run as the first thing.
"""
preForHub = None
postForHub = None
def __init__(self, storage, payload, instclass):
"""Create a StandaloneSpoke instance."""
if self.preForHub and self.postForHub:
raise AttributeError("StandaloneSpoke instance %s may not have both preForHub and postForHub set" % self)
Spoke.__init__(self, storage, payload, instclass)
# Standalone spokes are not part of a hub, and thus have no status.
# Provide a concrete implementation of status here so that subclasses
# don't need one.
@property
def status(self):
return None
class Hub(object, metaclass=ABCMeta):
"""A Hub is an overview UI screen. A Hub consists of one or more grids of
configuration options that the user may choose from. Each grid is
provided by a SpokeCategory, and each option is provided by a Spoke.
When the user dives down into a Spoke and is finished interacting with
it, they are returned to the Hub.
Some Spokes are required. The user must interact with all required
Spokes before they are allowed to proceed to the next stage of
installation.
From a layout perspective, a Hub is the entirety of the screen, though
the screen itself can be roughly divided into thirds. The top third is
some basic navigation information (where you are, what you're
installing). The middle third is the grid of Spokes. The bottom third
is an action area providing additional buttons (quit, continue) or
progress information (during package installation).
Installation may consist of multiple chained Hubs, or Hubs with
additional standalone screens either before or after them.
"""
def __init__(self, storage, payload, instclass):
"""Create a new Hub instance.
The arguments this base class accepts defines the API that Hubs
have to work with. A Hub does not get free reign over everything
in the anaconda class, as that would be a big mess. Instead, a
Hub may count on the following:
data -- An instance of a pykickstart Handler object. The
Hub uses this to populate its UI with defaults
and to pass results back after it has run. The data
property must be implemented by classes inheriting
from Hub.
storage -- An instance of storage.Storage. This is useful for
determining what storage devices are present and how
they are configured.
payload -- An instance of a packaging.Payload subclass. This
is useful for displaying and selecting packages to
install, and in carrying out the actual installation.
instclass -- An instance of a BaseInstallClass subclass. This
is useful for determining distribution-specific
installation information like default package
selections and default partitioning.
"""
self._storage = storage
self.payload = payload
self.instclass = instclass
self.paths = {}
self._spokes = {}
# spokes for which environments this hub should collect?
self._environs = [ANACONDA_ENVIRON]
@abstractproperty
def data(self):
pass
@property
def storage(self):
return self._storage
def set_path(self, path_id, paths):
"""Update the paths attribute with list of tuples in the form (module
name format string, directory name)"""
self.paths[path_id] = paths
def entry_logger(self):
"""Log immediately before this hub is about to be displayed on the
screen. Subclasses may override this method if they want to log
more specific information, but an overridden method should finish
by calling this method so the entry will be logged.
Note that due to how the GUI flows, hubs are only entered once -
when they are initially displayed. Going to a spoke from a hub
and then coming back to the hub does not count as exiting and
entering.
"""
log.debug("Entered hub: %s", self.__class__.__name__)
def _collectCategoriesAndSpokes(self):
"""This method is provided so that is can be overridden in a subclass
by a custom collect method.
One example of such usage is the Initial Setup application.
"""
return collectCategoriesAndSpokes(self.paths, self.__class__, self.data.displaymode.displayMode)
def exit_logger(self):
"""Log when a user leaves the hub. Subclasses may override this
method if they want to log more specific information, but an
overridden method should finish by calling this method so the
exit will be logged.
Note that due to how the GUI flows, hubs are not exited when the
user selects a spoke from the hub. They are only exited when the
continue or quit button is clicked on the hub.
"""
log.debug("Left hub: %s", self.__class__.__name__)
def collect(module_pattern, path, pred):
"""Traverse the directory (given by path), import all files as a module
module_pattern % filename and find all classes within that match
the given predicate. This is then returned as a list of classes.
It is suggested you use collect_categories or collect_spokes instead of
this lower-level method.
:param module_pattern: the full name pattern (pyanaconda.ui.gui.spokes.%s)
we want to assign to imported modules
:type module_pattern: string
:param path: the directory we are picking up modules from
:type path: string
:param pred: function which marks classes as good to import
:type pred: function with one argument returning True or False
"""
retval = []
try:
contents = os.listdir(path)
# when the directory "path" does not exist
except OSError:
return []
for module_file in contents:
if (not module_file.endswith(".py")) and \
(not module_file.endswith(".so")):
continue
if module_file == "__init__.py":
continue
try:
mod_name = module_file[:module_file.rindex(".")]
except ValueError:
mod_name = module_file
mod_info = None
module = None
module_path = None
try:
imp.acquire_lock()
(fo, module_path, module_flags) = imp.find_module(mod_name, [path])
module = sys.modules.get(module_pattern % mod_name)
# do not load module if any module with the same name
# is already imported
if not module:
# try importing the module the standard way first
# uses sys.path and the module's full name!
try:
__import__(module_pattern % mod_name)
module = sys.modules[module_pattern % mod_name]
# if it fails (package-less addon?) try importing single file
# and filling up the package structure voids
except ImportError:
# prepare dummy modules to prevent RuntimeWarnings
module_parts = (module_pattern % mod_name).split(".")
# remove the last name as it will be inserted by the import
module_parts.pop()
# make sure all "parent" modules are in sys.modules
for l in range(len(module_parts)):
module_part_name = ".".join(module_parts[:l+1])
if module_part_name not in sys.modules:
module_part = types.ModuleType(module_part_name)
module_part.__path__ = [path]
sys.modules[module_part_name] = module_part
# load the collected module
module = imp.load_module(module_pattern % mod_name,
fo, module_path, module_flags)
# get the filenames without the extensions so we can compare those
# with the .py[co]? equivalence in mind
# - we do not have to care about files without extension as the
# condition at the beginning of the for loop filters out those
# - module_flags[0] contains the extension of the module imp found
candidate_name = module_path[:module_path.rindex(module_flags[0])]
loaded_name, loaded_ext = module.__file__.rsplit(".", 1)
# restore the extension dot eaten by split
loaded_ext = "." + loaded_ext
# do not collect classes when the module is already imported
# from different path than we are traversing
# this condition checks the module name without file extension
if candidate_name != loaded_name:
continue
# if the candidate file is .py[co]? and the loaded is not (.so)
# skip the file as well
if module_flags[0].startswith(".py") and not loaded_ext.startswith(".py"):
continue
# if the candidate file is not .py[co]? and the loaded is
# skip the file as well
if not module_flags[0].startswith(".py") and loaded_ext.startswith(".py"):
continue
except RemovedModuleError:
# collected some removed module
continue
except ImportError as imperr:
if module_path and "pyanaconda" in module_path:
# failure when importing our own module:
raise
log.error("Failed to import module %s from path %s in collect: %s", mod_name, module_path, imperr)
continue
finally:
imp.release_lock()
if mod_info and mod_info[0]:
mod_info[0].close()
p = lambda obj: inspect.isclass(obj) and pred(obj)
# if __all__ is defined in the module, use it
if not hasattr(module, "__all__"):
members = inspect.getmembers(module, p)
else:
members = [(name, getattr(module, name))
for name in module.__all__
if p(getattr(module, name))]
for (_name, val) in members:
retval.append(val)
return retval
def collect_spokes(mask_paths, category):
"""Return a list of all spoke subclasses that should appear for a given
category. Look for them in files imported as module_path % basename(f)
:param mask_paths: list of mask, path tuples to search for classes
:type mask_paths: list of (mask, path)
:return: list of Spoke classes belonging to category
:rtype: list of Spoke classes
"""
spokes = []
for mask, path in mask_paths:
spokes.extend(collect(mask, path,
lambda obj: hasattr(obj, "category") and obj.category is not None and obj.category.__name__ == category))
return spokes
def collect_categories(mask_paths, displaymode):
"""Return a list of all category subclasses. Look for them in modules
imported as module_mask % basename(f) where f is name of all files in path.
"""
categories = []
if displaymode == DISPLAY_MODE_TEXT:
for mask, path in mask_paths:
categories.extend(collect(mask, path, lambda obj: getattr(obj, "displayOnHubTUI", None) is not None))
else:
for mask, path in mask_paths:
categories.extend(collect(mask, path, lambda obj: getattr(obj, "displayOnHubGUI", None) is not None))
return categories
def collectCategoriesAndSpokes(paths, klass, displaymode):
"""Collects categories and spokes to be displayed on this Hub
:param paths: dictionary mapping categories, spokes, and hubs to their
their respective search path(s)
:return: dictionary mapping category class to list of spoke classes
:rtype: dictionary[category class] -> [ list of spoke classes ]
"""
ret = {}
# Collect all the categories this hub displays, then collect all the
# spokes belonging to all those categories.
if displaymode == DISPLAY_MODE_TEXT:
categories = sorted(filter(lambda c: c.displayOnHubTUI == klass.__name__, collect_categories(paths["categories"], displaymode)),
key=lambda c: c.sortOrder)
else:
categories = sorted(filter(lambda c: c.displayOnHubGUI == klass.__name__, collect_categories(paths["categories"], displaymode)),
key=lambda c: c.sortOrder)
for c in categories:
ret[c] = collect_spokes(paths["spokes"], c.__name__)
return ret