Trees       Indices       Help   
Module UIRegistrar
[hide private]
[frames] | no frames]

Module UIRegistrar

source code

Defines the registrar functions responsible for managing an on-disk repository of User Interface Elements (UIEs) that define the Perks, Devices, Choosers, and Monitors available to the user and the system. Defines a helper class UIESet that is used internally by the registrar to represent collections of UIEs that are to be loaded when LSR starts, when any Tier starts, or when a particular Tier starts for a particular user.

Functions to install, uninstall, associate, disassociate, and list UIEs are primarily of interest to third-party UIE developers and expert users. These methods allow extensions to be added to LSR and associated with profiles so they are loaded automatically at startup or when Tiers are created. The AEMain script defines a command line interface for accessing these methods. See the documentation in that module or the LSR man page for details.

Functions to load UIEs are of interest to LSR developers. Given a UIE name, the loadOne method will import the Python module containing the named UIE and return an instance of the class in that module of the same name (if the UIE module is properly installed). Given a UIE kind and name along with the name of a , the loadAssociated method will import all Python modules containing the UIEs to be loaded and return a list of UIE objects sorted in the desired load order. Objects, not classes, are returned by this method implying any initialization requiring data from an external source must be done outside the constructor.

Author: Peter Parente

Organization: IBM Corporation

Copyright: Copyright (c) 2005, 2007 IBM Corporation

License: The BSD License

All rights reserved. This program and the accompanying materials are made available under the terms of the BSD license which accompanies this distribution, and is available at http://www.opensource.org/licenses/bsd-license.php

Classes [hide private]
  Metadata
Bag class for specifying UIE metadata.
  UIESet
Associates the names of installed UIEs with times when they should be automatically loaded by LSR under a particular user profile.
Functions [hide private]
Metadata
_ensureUIEValid(real_path)
Ensures the UIE module at the given path contains a class matching the stated name.		 source code
Metadata
_parseUIEMetadata(name, path, text)
Gets the metadata from a UIE module without importing it.		 source code
object
_getUIEInstance(name)
Gets an instance of the UIE class having the same name as the module indicated by the given name.		 source code
module
_getUIEModule(name)
Loads the UIE module of the given name.		 source code
 
install(real_path, local=True, overwrite=False)
Installs a new UIE module in either the local or global repository.		 source code
 
uninstall(name, local=True)
Removes a UIE module from the global or local repository.		 source code
list of string
associate(name, profiles=None, tier=None, all_tiers=False, index=None)
Associates an installed UIE of the given name with a profile so that it is loaded automatically by LSR.		 source code
list of string
disassociate(name, profiles=None, tier=None, all_tiers=False)
Disassociates an installed UIE of the given name from a profile so that it is no longer loaded automatically by LSR.		 source code
list of string
listInstalled(kind=None)
Gets a list of all installed UIEs of the given kind, both local and global.		 source code
boolean
hasTierAssociated(kind, profile, tier)
Gets if at least one UIE of the given kind is associated with the given Tier in the profile.		 source code
dictionary of string : list
listAssociatedMap(kind, profile)
Gets a map associating Tier names with UIEs of the given kind in this profile.		 source code
list of string
listAssociatedAny(kind, profile)
Gets a list of UIEs of the given kind associated with any Tier in this profile.		 source code
list of string or 2-tuple
listAssociated(kind, profile, tier=None)
Gets a list of the names of all UIEs of the given kind associated with the given profile.		 source code
string
getPath(name)
Gets the absolute path where an installed UIE is located on disk.		 source code
object
loadOne(name)
Gets the class representing the installed UIE of the given kind and name.		 source code
list of object
loadAssociated(kind, profile, tier=None)
Gets all UIE classes in the given profile to be loaded at the given time.		 source code
Variables [hide private]
  log = logging.getLogger('UIRegistrar')
string LOCAL_PATH = os.path.join(HOME_USER, os.path.basename(sys.argv...
Location of the set of installed UIEs for this user
string GLOBAL_PATH = os.path.join(HOME_DIR, 'global.installed')
Location of the set of installed UIEs for all users of the system
string PERK = 'perk'
Kind of UIE responsible for registering Tasks that handle AEEvents and AEInput.Gestures
string DEVICE = 'device'
Kind of UIE responsible for managing a method of input (e.g keyboard), managing a method of output (e.g speech), or both (e.g.
string CHOOSER = 'chooser'
Kind of UIE responsible for interacting with the user via more than the usual LSR key combos (e.g.
string MONITOR = 'monitor'
Kind of UIE responsible for creating a human-readable representation (e.g.
list ALL_KINDS = [DEVICE, CHOOSER, MONITOR, PERK]
List of all known kinds of UIEs
list STARTUP_KINDS = [DEVICE, MONITOR]
Subset of ALL_KINDS that should be loaded at startup
  InstallCache = InstallCache()
Function Details [hide private]

_ensureUIEValid(real_path)

source code 

Ensures the UIE module at the given path contains a class matching the stated name. Ensure Metadata is specified in the UIE to aid in installation and association. Returns the UIE metadata.

Parameters:
  • real_path (string) - Real path to the UIE module located on disk
Returns: Metadata
Metadata from the UIE
Raises:
  • AttributeError - When __uie__ dictionary is missing from the UIE
  • IOError - When the UIE module cannot be read

Note: No longer checks if a class fits the definition of the given kind of UIE. This validation is difficult when the module imports dependencies and actually provides little useful information about whether or not the UIE is implemented correctly. It can only tell us if it provides the proper interface. We have gracefully degredation at runtime, so why bother "almost ensuring" it's valid at install time?

_parseUIEMetadata(name, path, text)

source code 

Gets the metadata from a UIE module without importing it.

Parameters:
  • name (string) - Name of the installed UIE to fetch metadata from
  • text (string) - Pre-fetched contents of the UIE
Returns: Metadata
Metadata from the UIE
Raises:
  • AttributeError - When __uie__ dictionary is missing from the UIE
  • KeyError - When the named UIE is not installed
  • IOError - When the UIE module cannot be read

_getUIEInstance(name)

source code 

Gets an instance of the UIE class having the same name as the module indicated by the given name.

Parameters:
  • name (string) - Name of the UIE, unique across all UIEs of the same kind
Returns: object
UIE instance
Raises:
  • KeyError - When the UIE is not installed globally or locally
  • AttributeError - When the module is missing a class of the given name
  • ImportError - When the UIE module cannot be imported
  • IOError - When the UIE module cannot be read

_getUIEModule(name)

source code 

Loads the UIE module of the given name. Returns a reference to the module for use by _getUIEInstance by querying the InstallCache.

Parameters:
  • name (string) - Name of the UIE, unique across all UIEs
Returns: module
Reference to the UIE module
Raises:
  • KeyError - When the UIE is not installed globally or locally
  • IOError - When the UIE module cannot be read
  • ImportError - When the UIE module cannot be imported

install(real_path, local=True, overwrite=False)

source code 

Installs a new UIE module in either the local or global repository. Installing in the global repository requires write permissions on the LSR home directory at its install location. Checks if the UIE to be installed is valid as determined by _ensureUIEValid and retrieves its metadata.

Parameters:
  • real_path (string) - Relative or absolute location of the UIE module on disk
  • local (boolean) - Install this UIE for the current user only (True) or for all users (False)?
  • overwrite (boolean) - Ignore errors if a UIE is already installed and overwrite?
Raises:
  • AttributeError - When __uie__ dictionary is missing from the UIE
  • KeyError - When the named UIE is already installed
  • IOError - When the UIE module cannot be read

uninstall(name, local=True)

source code 

Removes a UIE module from the global or local repository. Removes all references to a UIE uninstalled from the local repository from existing profiles.

Parameters:
  • name (string) - Name of the UIE, unique across all UIEs
  • local (boolean) - Uninstall this UIE for the current user only (True) or for all users (False)?
Raises:
  • AttributeError - When __uie__ dictionary is missing from the UIE
  • KeyError - When the UIE is not already installed
  • IOError - When the local on-disk cache cannot be updated

associate(name, profiles=None, tier=None, all_tiers=False, index=None)

source code 

Associates an installed UIE of the given name with a profile so that it is loaded automatically by LSR.

Parameters:
  • name (string) - Name of the UIE, unique across all UIEs
  • profiles (list of string) - Names of the profiles in which UIE of the given name will be loaded automatically. Defaults to None meaning BUILTIN_PROFILES will be used.
  • tier (string) - Name of the Tier which will cause the loading of the given UIE. Defaults to None.
  • all_tiers (boolean) - Load this UIE on all Tiers?
  • index (integer) - Load order of the UIE when multiple UIEs are to be loaded at the given time. Defaults to None meaning after all other associated UIEs of the same kind.
Returns: list of string
Names of profiles with which the UIE was associated
Raises:
  • KeyError - When the UIE is not already installed

disassociate(name, profiles=None, tier=None, all_tiers=False)

source code 

Disassociates an installed UIE of the given name from a profile so that it is no longer loaded automatically by LSR.

Parameters:
  • name (string) - Name of the UIE, unique across all UIEs
  • profiles (list of string) - Names of the profiles in which UIE of the given name will no longer be loaded automatically. Defaults to None meaning BUILTIN_PROFILES will be used.
  • tier (string) - Name of the Tier which will no longer cause the loading of the given UIE. Defaults to None.
  • all_tiers (boolean) - Disassociate this UIE from loading in all Tiers?
Returns: list of string
Names of profiles from which the UIE was disassociated

listInstalled(kind=None)

source code 

Gets a list of all installed UIEs of the given kind, both local and global.

Parameters:
  • kind (string) - Kind of UIE, one of ALL_KINDS or None to indicate all kinds
Returns: list of string
Names of installed UIEs

hasTierAssociated(kind, profile, tier)

source code 

Gets if at least one UIE of the given kind is associated with the given Tier in the profile.

Parameters:
  • kind (string) - Kind of UIE, one of ALL_KINDS
  • profile (string) - Name of the profile
  • tier (string) - Name of the Tier potentially associated with UIEs
Returns: boolean
At least one Tier specific UIE?
Raises:
  • ValueError - When the named profile does not exist

listAssociatedMap(kind, profile)

source code 

Gets a map associating Tier names with UIEs of the given kind in this profile.

Parameters:
  • kind (string) - Kind of UIE, one of ALL_KINDS
  • profile (string) - Name of the profile
Returns: dictionary of string : list
Dictionary mapping Tier names to lists of UIE names
Raises:
  • ValueError - When the named profile does not exist

listAssociatedAny(kind, profile)

source code 

Gets a list of UIEs of the given kind associated with any Tier in this profile.

Parameters:
  • kind (string) - Kind of UIE, one of ALL_KINDS
  • profile (string) - Name of the profile
Returns: list of string
List of UIEs that load on any Tier
Raises:
  • ValueError - When the named profile does not exist

listAssociated(kind, profile, tier=None)

source code 

Gets a list of the names of all UIEs of the given kind associated with the given profile. The tier may be specified for PERKs. If it is, only UIEs associated with that Tier are returned.

Parameters:
  • kind (string) - Kind of UIE, one of ALL_KINDS
  • profile (string) - Name of the profile
  • tier (string) - Name of the Tier associated with the UIEs. If None, fetches UIE names for all Tiers.
Returns: list of string or 2-tuple
Names of the UIEs
Raises:
  • ValueError - When the named profile does not exist

getPath(name)

source code 

Gets the absolute path where an installed UIE is located on disk. Does not include the filename of the UIE.

Parameters:
  • name (string) - Name of the UIE, unique across all UIEs
Returns: string
Absolute parent directory of the UIE module on disk
Raises:
  • KeyError - When a UIE with the given name is not installed

loadOne(name)

source code 

Gets the class representing the installed UIE of the given kind and name. Checks if the UIE is installed. Fails to load the UIE if any of the dependencies are missing.

Parameters:
  • name (string) - Name of the UIE, unique across all UIEs of the same kind
Returns: object
Instantiated UIE object or None if the object could not be loaded

loadAssociated(kind, profile, tier=None)

source code 

Gets all UIE classes in the given profile to be loaded at the given time.

Parameters:
  • kind (string) - Kind of UIE, one of ALL_KINDS
  • profile (string) - Name of the profile
  • tier (string) - Name of the Tier which causes the loading of the listed UIEs
Returns: list of object
All UIE instances to be loaded sorted in proper load order

Variables Details [hide private]

LOCAL_PATH

Location of the set of installed UIEs for this user
Type:
string
Value:
os.path.join(HOME_USER, os.path.basename(sys.argv [0])+ '.installed')

DEVICE

Kind of UIE responsible for managing a method of input (e.g keyboard), managing a method of output (e.g speech), or both (e.g. Braille device)
Type:
string
Value:
'device'

CHOOSER

Kind of UIE responsible for interacting with the user via more than the usual LSR key combos (e.g. configuration, help, search)
Type:
string
Value:
'chooser'

MONITOR

Kind of UIE responsible for creating a human-readable representation (e.g. GUI dialog, log file) of some AccessEngine data (e.g. input, output, events) for the purposes of development and debugging
Type:
string
Value:
'monitor'

   Trees       Indices       Help   
Generated by Epydoc 3.0beta1 on Mon Jun 4 15:33:15 2007 http://epydoc.sourceforge.net