doc/client_api_versions.txt
author Shawn Walker <srw@sun.com>
Thu, 23 Jul 2009 14:17:08 -0500
changeset 1254 28871b08d49c
parent 1141 a74d6815a7fc
child 1255 13914487fd06
permissions -rw-r--r--
8463 missing key file error message says certificate is missing

Version 16:
Compatible with clients using version 15.
Changes:
   The following exceptions were added to pkg.client.api_errors:
    
    class NoSuchKey(CertificateError):
        """Used to indicate that a key could not be found."""

Version 15:
Incompatible with clients using versions 1-14.
Changes:
    The unfound_fmris variable in the
    pkg.client.api_errors.PlanCreationException class is now called 
    unmatched_fmris.

Version 14:
Compatible with clients using versions 12-14.
Changes:
    The following methods were added to pkg.client.publisher.Publisher:

        def create_meta_root(self):
                """Create the publisher's meta_root."""

        def remove_meta_root(self):
                """Removes the publisher's meta_root."""

Version 13:
Compatible with clients using version 12.
Changes:
    By default, publisher repositories will be checked for new metadata no more
    than once every four hours unless otherwise requested.  Each time a
    publisher's selected repository is checked for updates, the client will
    store a timestamp (in UTC) marking when the refresh was performed.

    ImageInterface.refresh() has changed as follows:
        * Changed 'full_refresh' to an optional keyword argument that defaults
          to False.

        * Added optional boolean keyword 'immediate' that allows the client to
          request that a publisher be checked for updates even if a check is
          not yet needed.

        * Changed to properly use progress tracker for refreshing of publisher
          metadata.

        * Now only refreshes publisher metadata based on the update interval
          specified by the refresh_seconds property on the publisher's
          selected_repository.

    ImageInterface.update_publisher() has changed as follows:
        * When updating a publisher with 'refresh_allowed' set to False, its
          catalog will no longer be removed.  Instead, it is marked as needing
          refresh, and the next time the client can do so, it will.

    pkg.client.publisher.Publisher has changed as follows:
        * New property 'last_refreshed':
                A datetime object representing the time (in UTC) the
                publisher's selected repository was last refreshed for new
                metadata (such as catalog updates).  'None' if the publisher
                hasn't been refreshed yet or the time is not available.

          The above property will be automatically set by the api as needed
          although api consumers are free to retrieve its value.  Manually
          setting this value is not recommended.

        * New property 'meta_root':
                The absolute pathname of the directory where the publisher's
                metadata should be written to and read from.

          The above property will be automatically set by the api as needed
          although api consumers are free to retrieve its value.  Manually
          setting this value is not recommended.

        * New property 'needs_refresh':
                A boolean value indicating whether the publisher's metadata for
                the currently selected repository needs to be refreshed.

Version 12:
Incompatible with clients using versions 1-12
Changes:
    This versions adds local_search and remote_search to the api and removes
    those functions from pkg.client.image.

Version 11:
Incompatible with clients using versions 1-10
Changes:
   This version changes all parameter names and property names from 'authority'
   to 'publisher'.  For example, parameters named 'auths' were changed to
   'pubs'; parameters named 'authent' were changed to 'pubent' and so forth.

   In addition, the following new api functions were added to ImageInterface:
        def add_publisher(self, pub, refresh_allowed=True):
                """Add the provided publisher object to the image
                configuration."""

        def get_preferred_publisher(self):
                """Returns the preferred publisher object for the image."""

        def get_publisher(self, prefix=None, alias=None, duplicate=False):
                """Retrieves a publisher object matching the provided prefix
                (name) or alias.

                'duplicate' is an optional boolean value indicating whether
                a copy of the publisher object should be returned instead
                of the original.
                """

        def get_publishers(self, duplicate=False):
                """Returns a list of the publisher objects for the current
                image.

                'duplicate' is an optional boolean value indicating whether
                copies of the publisher objects should be returned instead
                of the originals.
                """

        def get_publisher_last_update_time(self, prefix=None, alias=None):
                """Returns a datetime object representing the last time the
                catalog for a publisher was modified or None."""

        def has_publisher(self, prefix=None, alias=None):
                """Retrieves a publisher object matching the provided prefix
                (name) or alias."""

        def remove_publisher(self, prefix=None, alias=None):
                """Removes a publisher object matching the provided prefix
                (name) or alias."""

        def set_preferred_publisher(self, prefix=None, alias=None):
                """Sets the preferred publisher for the image."""

        def update_publisher(self, pub, refresh_allowed=True):
                """Replaces an existing publisher object with the provided one
                using the _source_object_id identifier set during copy."""

        def update_publisher(self, pub, refresh_allowed=True):
                """Replaces an existing publisher object with the provided one
                using the _source_object_id identifier set during copy.

                'refresh_allowed' is an optional boolean value indicating
                whether a refresh of publisher metadata (such as its catalog)
                should be performed if transport information is changed for a
                repository, mirror, or origin.  If False, no attempt will be
                made to retrieve publisher metadata."""


        def log_operation_end(self, error=None, result=None):
                """Marks the end of an operation to be recorded in image
                history.

                'result' should be a pkg.client.history constant value
                representing the outcome of an operation.  If not provided,
                and 'error' is provided, the final result of the operation will
                be based on the class of 'error' and 'error' will be recorded
                for the current operation.  If 'result' and 'error' is not
                provided, success is assumed."""

        def log_operation_error(self, error):
                """Adds an error to the list of errors to be recorded in image
                history for the current opreation."""

        def log_operation_start(self, name):
                """Marks the start of an operation to be recorded in image
                history."""
 
        def parse_p5i(self, fileobj=None, location=None):
                """Reads the pkg(5) publisher json formatted data at 'location'
                or from the provided file-like object 'fileobj' and returns a
                list of tuples of the format (publisher object, pkg_names).
                pkg_names is a list of strings representing package names or
                FMRIs.  If any pkg_names not specific to a publisher were
                provided, the last tuple returned will be of the format (None,
                pkg_names).

                'fileobj' is an optional file-like object that must support a
                'read' method for retrieving data.

                'location' is an optional string value that should either start
                with a leading slash and be pathname of a file or a URI string.

                'fileobj' or 'location' must be provided."""

        def write_p5i(self, fileobj, pkg_names=None, pubs=None):
                """Writes the publisher, repository, and provided package names
                to the provided file-like object 'fileobj' in json p5i format.

                'fileobj' is only required to have a 'write' method that accepts
                data to be written as a parameter.

                'pkg_names' is a dict of lists, tuples, or sets indexed by
                publisher prefix that contain package names, FMRI strings, or
                package info objects.  A prefix of "" can be used for packages
                that are not specific to a publisher.

                'pubs' is an optional list of publisher prefixes or Publisher
                objects.  If not provided, the information for all publishers
                (excluding those disabled) will be output."""

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 replaces them with a set of options to allow
    the caller control over which information is retrieved.

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 publisher 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):