lsst.base 23.0.0-2-gc17f1a8+f3d053c481
LSST Data Management Base Package
Public Member Functions | Static Public Attributes | List of all members
lsst.base.packages.Packages Class Reference

Public Member Functions

def __init__ (self, packages)
 
def fromSystem (cls)
 
def fromBytes (cls, data, format)
 
def read (cls, filename)
 
def toBytes (self, format)
 
def write (self, filename)
 
def __len__ (self)
 
def __str__ (self)
 
def __repr__ (self)
 
def __contains__ (self, pkg)
 
def __iter__ (self)
 
def __eq__ (self, other)
 
def update (self, other)
 
def extra (self, other)
 
def missing (self, other)
 
def difference (self, other)
 

Static Public Attributes

dictionary formats
 

Detailed Description

A table of packages and their versions.

There are a few different types of packages, and their versions are
collected in different ways:

1. Run-time libraries (e.g., cfitsio, fftw): we get their version from
   interrogating the dynamic library
2. Python modules (e.g., afw, numpy; galsim is also in this group even
   though we only use it through the library, because no version
   information is currently provided through the library): we get their
   version from the ``__version__`` module variable. Note that this means
   that we're only aware of modules that have already been imported.
3. Other packages provide no run-time accessible version information (e.g.,
   astrometry_net): we get their version from interrogating the
   environment.  Currently, that means EUPS; if EUPS is replaced or dropped
   then we'll need to consider an alternative means of getting this version
   information.
4. Local versions of packages (a non-installed EUPS package, selected with
   ``setup -r /path/to/package``): we identify these through the
   environment (EUPS again) and use as a version the path supplemented with
   the ``git`` SHA and, if the git repo isn't clean, an MD5 of the diff.

These package versions are collected and stored in a Packages object, which
provides useful comparison and persistence features.

Example usage:

.. code-block:: python

    from lsst.base import Packages
    pkgs = Packages.fromSystem()
    print("Current packages:", pkgs)
    old = Packages.read("/path/to/packages.pickle")
    print("Old packages:", old)
    print("Missing packages compared to before:", pkgs.missing(old))
    print("Extra packages compared to before:", pkgs.extra(old))
    print("Different packages: ", pkgs.difference(old))
    old.update(pkgs)  # Include any new packages in the old
    old.write("/path/to/packages.pickle")

Parameters
----------
packages : `dict`
    A mapping {package: version} where both keys and values are type `str`.

Notes
-----
This is essentially a wrapper around a dict with some conveniences.

Definition at line 262 of file packages.py.

Constructor & Destructor Documentation

◆ __init__()

def lsst.base.packages.Packages.__init__ (   self,
  packages 
)

Definition at line 317 of file packages.py.

Member Function Documentation

◆ __contains__()

def lsst.base.packages.Packages.__contains__ (   self,
  pkg 
)

Definition at line 438 of file packages.py.

◆ __eq__()

def lsst.base.packages.Packages.__eq__ (   self,
  other 
)

Definition at line 444 of file packages.py.

◆ __iter__()

def lsst.base.packages.Packages.__iter__ (   self)

Definition at line 441 of file packages.py.

◆ __len__()

def lsst.base.packages.Packages.__len__ (   self)

Definition at line 424 of file packages.py.

◆ __repr__()

def lsst.base.packages.Packages.__repr__ (   self)

Definition at line 435 of file packages.py.

◆ __str__()

def lsst.base.packages.Packages.__str__ (   self)

Definition at line 427 of file packages.py.

◆ difference()

def lsst.base.packages.Packages.difference (   self,
  other 
)
Get packages in symmetric difference of self and another `Packages`
object.

Parameters
----------
other : `Packages`
    Other packages to compare against.

Returns
-------
difference : `dict`
    Packages in symmetric difference.  Keys (type `str`) are package
    names; values (type `str`) are their versions.

Definition at line 497 of file packages.py.

◆ extra()

def lsst.base.packages.Packages.extra (   self,
  other 
)
Get packages in self but not in another `Packages` object.

Parameters
----------
other : `Packages`
    Other packages to compare against.

Returns
-------
extra : `dict`
    Extra packages. Keys (type `str`) are package names; values
    (type `str`) are their versions.

Definition at line 465 of file packages.py.

◆ fromBytes()

def lsst.base.packages.Packages.fromBytes (   cls,
  data,
  format 
)
Construct the object from a byte representation.

Parameters
----------
data : `bytes`
    The serialized form of this object in bytes.
format : `str`
    The format of those bytes. Can be ``yaml`` or ``pickle``.

Definition at line 341 of file packages.py.

◆ fromSystem()

def lsst.base.packages.Packages.fromSystem (   cls)
Construct a `Packages` by examining the system.

Determine packages by examining python's `sys.modules`, runtime
libraries and EUPS.

Returns
-------
packages : `Packages`

Definition at line 323 of file packages.py.

◆ missing()

def lsst.base.packages.Packages.missing (   self,
  other 
)
Get packages in another `Packages` object but missing from self.

Parameters
----------
other : `Packages`
    Other packages to compare against.

Returns
-------
missing : `dict`
    Missing packages. Keys (type `str`) are package names; values
    (type `str`) are their versions.

Definition at line 481 of file packages.py.

◆ read()

def lsst.base.packages.Packages.read (   cls,
  filename 
)
Read packages from filename.

Parameters
----------
filename : `str`
    Filename from which to read. The format is determined from the
    file extension.  Currently support ``.pickle``, ``.pkl``
    and ``.yaml``.

Returns
-------
packages : `Packages`

Definition at line 362 of file packages.py.

◆ toBytes()

def lsst.base.packages.Packages.toBytes (   self,
  format 
)
Convert the object to a serialized bytes form using the
specified format.

Parameters
----------
format : `str`
    Format to use when serializing. Can be ``yaml`` or ``pickle``.

Returns
-------
data : `bytes`
    Byte string representing the serialized object.

Definition at line 385 of file packages.py.

◆ update()

def lsst.base.packages.Packages.update (   self,
  other 
)
Update packages with contents of another set of packages.

Parameters
----------
other : `Packages`
    Other packages to merge with self.

Notes
-----
No check is made to see if we're clobbering anything.

Definition at line 450 of file packages.py.

◆ write()

def lsst.base.packages.Packages.write (   self,
  filename 
)
Write to file.

Parameters
----------
filename : `str`
    Filename to which to write. The format of the data file
    is determined from the file extension. Currently supports
    ``.pickle`` and ``.yaml``

Definition at line 406 of file packages.py.

Member Data Documentation

◆ formats

dictionary lsst.base.packages.Packages.formats
static
Initial value:
= {".pkl": "pickle",
".pickle": "pickle",
".yaml": "yaml"}

Definition at line 313 of file packages.py.


The documentation for this class was generated from the following file: