Hi everyone,
Here's a draft of the API that's been discussed previously. Please let
me know if there are capabilities not provided that the packamanger
needs that can't easily be handled by extending the progresstracker
class. The plan is to get the CLI working using the API and take the
feedback with the goal of having a fairly firm API in 3-4 weeks in the
gate that the GUI can integrate with. One thing that's still to come
from an API design perspective is to collect all the exceptions that
cross the API boundary together into a single module (or small number of
modules) so that they're accessible and easily tracked.
To be clear, this is a draft. Names, functionality, and nearly anything
may change. Also, this version of the API is specifically for the most
dangerous operations, ones that can harm a users system: Install,
Uninstall, Image-Update, and Refresh. Others like list, search, info,
etc... will be added to this API in the future, but the first step is to
get the GUI and the CLI passing through the same interface on the
critical actions.
The flow of control for the consumer of a PkgClient object is:
1) Create an API object. This establishes which Image the API object is
associated with and assigns a progresstracker (for simplicity)
2) Call either plan_install, plan_uninstall, plan_image_update
3) Call prepare
4) Call execute_plan
Cancel essentially sends you back one step (so if it's doing 3 and
cancel is sent, the state will return to 2).
Reset returns the state to just after step 1.
Thanks,
Brock
class PkgClient(object):
def __init__(self, img_path, version_id, progesstracker,
cancel_state_callable):
# Raises VersionException, NoImageException
def plan_install(self, pkg_list, filters):
# pkg_list: list of packages to install
# filters: filters to apply to the actions of the installed
# packages
# Returns 1 if it has things to do, 0 for nothing to be done
# Raises InvalidCertException, image.PlanCreationException,
# image.UnmatchedFmriException
def plan_uninstall(self, pkg_list, recursive_removal):
# pkg_list: list of packages to remove
# recursive_removal: whether recursive removal should be
# applied
# Returns 1 if it has things to do, 0 for nothing to be done
# Raises imageplan.NonLeafPackageException,
# image.PlanCreationException
def plan_update_all(self, actual_cmd):
# Returns a tuple of:
# whether there is anything to do,
# whether this is an opensolaris image,
# if an exception that was caught that allowed
# execution to continue, it is
# returned, otherwise None is
# returned
# raises image.CatalogRefreshException,
# IpkgOutOfDateException
# image.PlanCreationException
def describe(self):
# Returns None if no plan is ready yet, otherwise returns
# a PlanDescription
def prepare(self):
# Downloads the packages to disk.
# Prepares the indexes for updating.
# Raises search_errors.ProblematicPermissionsIndexException,
# UnknownPlanTypeException
def execute_plan(self):
# Raises search_erorrs:(InconsistentIndexException,
# PartialIndexingException,
# ProblematicPermissionsIndexException)
# Raises ImageplanStateException
def refresh(self, full_refresh, auths=None):
# full_refresh: whether to do a full retrieval of the
catalog
# from the authority or only update the existing catalog
# auths: a list of authorities to refresh. Passing an empty
# list or using the default value means to refresh all
# known authorities
def can_be_cancelled(self):
# Returns true if the API is in a cancelable state.
def reset(self):
# This resets the API object back to initial state
def cancel(self):
# Used for asynchronous cancellation
# Puts the API back into the previous state.
# Canceling during a plan phase returns the
# API to its initial state. Cancelling
# during prepare puts the API into the
# state it was in just after planning had completed.
# Plan execution cannot be canceled.
class PlanDescription(object):
def get_changes(self):
# Returns a list of (origin fmri string, destrination
fmri string) pairs
Exceptions:
class ApiVersionException(Exception)
# Provides the expected and provided version
class InvalidCertException(Exception)
# Raised when the client's certificate is not valid
class ImageplanStateException(Exception)
# Raised when plan execution did not complete
# Provides the last good state of execution
class IpkgOutOfDateException(Exception):
# Raised when the ipkg on the system is out of date
class UnknownPlanTypeException(Exception):
# Raised when plan is not recognized or known
class ImageUpdateOnLiveImageException(Exception):
# Raised when BE creation failed or was not performed and actions would
happen on the live image
class CanceledException(Exception):
# Raised when a cancel has been requested and the API has reached a
point where it can accept the cancel request
class PlanMissingException(Exception):
# Raised during execution or preparation if no plan exists.
class UnrecognizedAuthorityException(Exception):
# Raised when refresh is called with an authority the image doesn't
recognize
class NoImageException(Exception):
# Raised when no image could be found at the specified path.
# Provides the path given
class NetworkUnavailable(Exception):
# Raised when the network is unavailable and needed
_______________________________________________
pkg-discuss mailing list
[email protected]
http://mail.opensolaris.org/mailman/listinfo/pkg-discuss
