6902 api.info needs a "fast" flag or a way to pass a set of the information required
Version 10:
Incompatible with clients using versions 1-9:
Changes:
This version changes the interface to info. It removes the action info
and licenses flag and
Version 9:
Compatible with clients using versions 1-8
Changes:
This version adds an optional argument to plan_update_all to allow the
specification of a name for the clone of the BE which is made. It also
exposes check_be_name as part of the api.
Version 8:
Compatible with clients using versions 1-7
Changes:
This version introduces InvalidDepotResponseException. The
exception is thrown when operations that refresh the catalog
discover that the server is not a pkg depot. Clients of the api
should catch this exception and respond appropriately.
Version 7:
Compatible with clients using versions 1-6
Changes:
Ignore the pkg_client_name parameter passed to api.ImageInterface() if
pkg.client.global_settings.client_name isn't None. This latter object
is now the preferred way to set the client name, and the
pkg_client_name parameter may be ignored or removed in the future.
Version 6:
Compatible with clients using versions 1-5
Changes:
Adds a new field to PackageInfo, category_info_list, which is a list of
PackageCategory objects. These objects contain the scheme and category
information for packages.
Version 5:
Compatible with clients using versions 1-4 as long as they have a generic
APIException. This is the case for PackageManager and UpdateManaget.
Changes:
plan_install and plan_update_all can now raise PermissionsException.
Version 4:
Compatible with clients using versions 1, 2, and 3
Changes:
Modifies where certain progress tracking calls were made, calling
evaluate_start much sooner.
Adds refresh tracking to progress.py. This allows for active feedback when
the catalogs of authorities are being refreshed.
Version 3:
Compatible with clients using Versions 1 and 2
Changes:
Adds an optional argument to info which determines whether detailed information
about actions will be returned
Adds the following new fields to PackageInfo objects: links, hardlinks,
files, dirs, dependencies
Version 2:
Compatible with clients using Version 1
Changes:
Adds the optional argument update_index to plan_install, plan_uninstall, and
plan_update_all. When the argument is false, no automatic update to the
index occurs. By default, the argument is true.
Version 1:
Incompatible with clients using Version 0
Changes:
plan_install now returns a tuple of whether there is anything to do and
a catalog refresh exception, if one was caught. In this, it mirrors the
first and third return values from plan_update_all.
Version 0:
def __init__(self, img_path, version_id, progesstracker,
cancel_state_callable, pkg_client_name):
"""Constructs an ImageInterface. img_path should point to an
existing image. version_id indicates the version of the api
the client is expecting to use. progesstracker is the
progresstracker the client wants the api to use for UI
callbacks. cancel_state_callable is a function which the client
wishes to have called each time whether the operation can be
canceled changes. It can raise VersionException and
ImageNotFoundException."""
def plan_install(self, pkg_list, filters, refresh_catalogs=True,
noexecute=False, verbose=False):
"""Contructs a plan to install the packages provided in
pkg_list. pkg_list is a list of packages to install. filters
is a list of filters to apply to the actions of the installed
packages. refresh_catalogs controls whether the catalogs will
automatically be refreshed. noexecute determines whether the
history will be recorded after planning is finished. verbose
controls whether verbose debugging output will be printed to the
terminal. Its existence is temporary. If there are things to do
to complete the install, it returns True, otherwise it returns
False. It can raise InvalidCertException, PlanCreationException,
NetworkUnavailableException, and InventoryException. The
noexecute argument is included for compatibility with
operational history. The hope is it can be removed in the
future."""
def plan_uninstall(self, pkg_list, recursive_removal, noexecute=False,
verbose=False):
"""Contructs a plan to uninstall the packages provided in
pkg_list. pkg_list is a list of packages to install.
recursive_removal controls whether recursive removal is
allowed. noexecute determines whether the history will be
recorded after planning is finished. verbose controls whether
verbose debugging output will be printed to the terminal. Its
existence is temporary. If there are things to do to complete
the uninstall, it returns True, otherwise it returns False. It
can raise NonLeafPackageException and PlanCreationException."""
def plan_update_all(self, actual_cmd, refresh_catalogs=True,
noexecute=False, force=False, pkgs_must_be_up_to_date=None,
verbose=False):
"""Creates a plan to update all packages on the system to the
latest known versions. actual_cmd is the command used to start
the client. It is used to determine the image to check whether
SUNWipkg is up to date. refresh_catalogs controls whether the
catalogs will automatically be refreshed. noexecute determines
whether the history will be recorded after planning is finished.
force controls whether update should proceed even if ipkg is not
up to date. verbose controls whether verbose debugging output
will be printed to the terminal. Its existence is temporary. It
returns a tuple of three things. The first is a boolean which
tells the client whether there is anything to do. The second
tells whether the image is an opensolaris image. The third is
either None, or an exception which indicates partial success.
This is currently used to indicate a failure in refreshing
catalogs. It can raise CatalogRefreshException,
IpkgOutOfDateException, NetworkUnavailableException, and
PlanCreationException."""
def describe(self):
"""Returns None if no plan is ready yet, otherwise returns
a PlanDescription"""
def prepare(self):
"""Takes care of things which must be done before the plan
can be executed. This includes downloading the packages to
disk and preparing the indexes to be updated during
execution. It can raise ProblematicPermissionsIndexException,
and PlanMissingException. Should only be called once a
plan_X method has been called."""
def execute_plan(self, be_name=None):
"""Executes the plan. This is uncancelable one it begins. It
can raise CorruptedIndexException,
ProblematicPermissionsIndexException, ImageplanStateException,
ImageUpdateOnLiveImageException, and PlanMissingException.
Should only be called after the prepare method has been
called."""
def refresh(self, full_refresh, auths=None):
"""Refreshes the catalogs. full_refresh controls whether to do
a full retrieval of the catalog from the authority or only
update the existing catalog. auths is a list of authorities to
refresh. Passing an empty list or using the default value means
all known authorities will be refreshed. While it currently
returns an image object, this is an expedient for allowing
existing code to work while the rest of the API is put into
place."""
def info(self, fmri_strings, local, get_licenses):
"""Gathers information about fmris. fmri_strings is a list
of fmri_names for which information is desired. local
determines whether to retrieve the information locally.
get_licenses determines whether to retrieve the text of
the licenses. It returns a dictionary of lists. The keys
for the dictionary are the constants specified in the class
definition. The values are lists of PackageInfo objects or
strings."""
def can_be_canceled(self):
"""Returns true if the API is in a cancelable state."""
def reset(self):
"""Resets the API back the the initial state. Note:
this does not necessarily return the disk to its initial state
since the indexes or download cache may have been changed by
the prepare method."""
def cancel(self):
"""Used for asynchronous cancelation. It returns the API
to the state it was in prior to the current method being
invoked. Canceling during a plan phase returns the API to
its initial state. Canceling during prepare puts the API
into the state it was in just after planning had completed.
Plan execution cannot be canceled. A call to this method blocks
until the canelation has happened. Note: this does not
necessarily return the disk to its initial state since the
indexes or download cache may have been changed by the
prepare method."""
class PlanDescription(object):
"""A class which describes the changes the plan will make. It
provides a list of tuples of PackageInfo's. The first item in the
tuple is the package that is being changed. The second item in the
tuple is the package that will be in the image after the change."""
def get_changes(self):
class LicenseInfo(object):
"""A class representing the license information a package
provides."""
def get_text(self):
class PackageInfo(object):
"""A class capturing the information about packages that a client
could need. The fmri is guaranteed to be set. All other values may
be None, depending on how the PackageInfo instance was created."""
# Possible package installation states
INSTALLED = 1
NOT_INSTALLED = 2
self.pkg_stem
self.summary
self.state
self.authority
self.preferred_authority
self.version
self.build_release
self.branch
self.packaging_date
self.size
self.fmri
self.licenses
def __str__(self):