Added docstrings.
diff --git a/Lib/plat-mac/pimp.py b/Lib/plat-mac/pimp.py
index e91e75b..2f6ec22 100644
--- a/Lib/plat-mac/pimp.py
+++ b/Lib/plat-mac/pimp.py
@@ -1,3 +1,17 @@
+"""Package Install Manager for Python.
+
+This is currently a MacOSX-only strawman implementation.
+Motto: "He may be shabby, but he gets you what you need" :-)
+
+Tools to allow easy installation of packages. The idea is that there is
+an online XML database per (platform, python-version) containing packages
+known to work with that combination. This module contains tools for getting
+and parsing the database, testing whether packages are installed, computing
+dependencies and installing packages.
+
+There is a minimal main program that works as a command line tool, but the
+intention is that the end user will use this through a GUI.
+"""
import sys
import os
import urllib
@@ -6,6 +20,8 @@
import distutils.util
import md5
+__all__ = ["PimpPreferences", "PimpDatabase", "PimpPackage", "main"]
+
_scriptExc_NotInstalled = "pimp._scriptExc_NotInstalled"
_scriptExc_OldInstalled = "pimp._scriptExc_OldInstalled"
_scriptExc_BadInstalled = "pimp._scriptExc_BadInstalled"
@@ -32,6 +48,9 @@
urllib.URLopener.http_error_default(self, url, fp, errcode, errmsg, headers)
class PimpPreferences:
+ """Container for per-user preferences, such as the database to use
+ and where to install packages"""
+
def __init__(self,
flavorOrder=None,
downloadDir=None,
@@ -55,6 +74,9 @@
self.pimpDatabase = pimpDatabase
def check(self):
+ """Check that the preferences make sense: directories exist and are
+ writable, the install directory is on sys.path, etc."""
+
rv = ""
RWX_OK = os.R_OK|os.W_OK|os.X_OK
if not os.path.exists(self.downloadDir):
@@ -83,6 +105,8 @@
return rv
def compareFlavors(self, left, right):
+ """Compare two flavor strings. This is part of your preferences
+ because whether the user prefers installing from source or binary is."""
if left in self.flavorOrder:
if right in self.flavorOrder:
return cmp(self.flavorOrder.index(left), self.flavorOrder.index(right))
@@ -92,6 +116,11 @@
return cmp(left, right)
class PimpDatabase:
+ """Class representing a pimp database. It can actually contain
+ information from multiple databases through inclusion, but the
+ toplevel database is considered the master, as its maintainer is
+ "responsible" for the contents"""
+
def __init__(self, prefs):
self._packages = []
self.preferences = prefs
@@ -101,6 +130,10 @@
self._description = ""
def appendURL(self, url, included=0):
+ """Append packages from the database with the given URL.
+ Only the first database should specify included=0, so the
+ global information (maintainer, description) get stored."""
+
if url in self._urllist:
return
self._urllist.append(url)
@@ -111,26 +144,39 @@
self._version = dict.get('version', '0.1')
self._maintainer = dict.get('maintainer', '')
self._description = dict.get('description', '')
- self.appendPackages(dict['packages'])
+ self._appendPackages(dict['packages'])
others = dict.get('include', [])
for url in others:
self.appendURL(url, included=1)
- def appendPackages(self, packages):
+ def _appendPackages(self, packages):
+ """Given a list of dictionaries containing package
+ descriptions create the PimpPackage objects and append them
+ to our internal storage."""
+
for p in packages:
pkg = PimpPackage(self, **dict(p))
self._packages.append(pkg)
def list(self):
+ """Return a list of all PimpPackage objects in the database."""
+
return self._packages
def listnames(self):
+ """Return a list of names of all packages in the database."""
+
rv = []
for pkg in self._packages:
rv.append(_fmtpackagename(pkg))
return rv
def dump(self, pathOrFile):
+ """Dump the contents of the database to an XML .plist file.
+
+ The file can be passed as either a file object or a pathname.
+ All data, including included databases, is dumped."""
+
packages = []
for pkg in self._packages:
packages.append(pkg.dump())
@@ -144,6 +190,13 @@
plist.write(pathOrFile)
def find(self, ident):
+ """Find a package. The package can be specified by name
+ or as a dictionary with name, version and flavor entries.
+
+ Only name is obligatory. If there are multiple matches the
+ best one (higher version number, flavors ordered according to
+ users' preference) is returned."""
+
if type(ident) == str:
# Remove ( and ) for pseudo-packages
if ident[0] == '(' and ident[-1] == ')':
@@ -175,6 +228,8 @@
return found
class PimpPackage:
+ """Class representing a single package."""
+
def __init__(self, db, name,
version=None,
flavor=None,
@@ -200,6 +255,7 @@
self._MD5Sum = MD5Sum
def dump(self):
+ """Return a dict object containing the information on the package."""
dict = {
'name': self.name,
}
@@ -226,15 +282,24 @@
return dict
def __cmp__(self, other):
+ """Compare two packages, where the "better" package sorts lower."""
+
if not isinstance(other, PimpPackage):
return cmp(id(self), id(other))
if self.name != other.name:
return cmp(self.name, other.name)
if self.version != other.version:
- return cmp(self.version, other.version)
+ return -cmp(self.version, other.version)
return self._db.preferences.compareFlavors(self.flavor, other.flavor)
def installed(self):
+ """Test wheter the package is installed.
+
+ Returns two values: a status indicator which is one of
+ "yes", "no", "old" (an older version is installed) or "bad"
+ (something went wrong during the install test) and a human
+ readable string which may contain more details."""
+
namespace = {
"NotInstalled": _scriptExc_NotInstalled,
"OldInstalled": _scriptExc_OldInstalled,
@@ -259,6 +324,14 @@
return "yes", ""
def prerequisites(self):
+ """Return a list of prerequisites for this package.
+
+ The list contains 2-tuples, of which the first item is either
+ a PimpPackage object or None, and the second is a descriptive
+ string. The first item can be None if this package depends on
+ something that isn't pimp-installable, in which case the descriptive
+ string should tell the user what to do."""
+
rv = []
if not self.downloadURL:
return [(None, "This package needs to be installed manually")]
@@ -278,6 +351,8 @@
return rv
def _cmd(self, output, dir, *cmditems):
+ """Internal routine to run a shell command in a given directory."""
+
cmd = ("cd \"%s\"; " % dir) + " ".join(cmditems)
if output:
output.write("+ %s\n" % cmd)
@@ -293,7 +368,18 @@
rv = fp.close()
return rv
- def downloadSinglePackage(self, output):
+ def downloadSinglePackage(self, output=None):
+ """Download a single package, if needed.
+
+ An MD5 signature is used to determine whether download is needed,
+ and to test that we actually downloaded what we expected.
+ If output is given it is a file-like object that will receive a log
+ of what happens.
+
+ If anything unforeseen happened the method returns an error message
+ string.
+ """
+
scheme, loc, path, query, frag = urlparse.urlsplit(self.downloadURL)
path = urllib.url2pathname(path)
filename = os.path.split(path)[1]
@@ -312,6 +398,8 @@
return "archive does not have correct MD5 checksum"
def _archiveOK(self):
+ """Test an archive. It should exist and the MD5 checksum should be correct."""
+
if not os.path.exists(self.archiveFilename):
return 0
if not self._MD5Sum:
@@ -321,7 +409,9 @@
checksum = md5.new(data).hexdigest()
return checksum == self._MD5Sum
- def unpackSinglePackage(self, output):
+ def unpackSinglePackage(self, output=None):
+ """Unpack a downloaded package archive."""
+
filename = os.path.split(self.archiveFilename)[1]
for ext, cmd in ARCHIVE_FORMATS:
if filename[-len(ext):] == ext:
@@ -337,7 +427,12 @@
if not os.path.exists(setupname) and not NO_EXECUTE:
return "no setup.py found after unpack of archive"
- def installSinglePackage(self, output):
+ def installSinglePackage(self, output=None):
+ """Download, unpack and install a single package.
+
+ If output is given it should be a file-like object and it
+ will receive a log of what happened."""
+
if not self.downloadURL:
return "%s: This package needs to be installed manually" % _fmtpackagename(self)
msg = self.downloadSinglePackage(output)
@@ -359,6 +454,9 @@
return None
class PimpInstaller:
+ """Installer engine: computes dependencies and installs
+ packages in the right order."""
+
def __init__(self, db):
self._todo = []
self._db = db
@@ -374,6 +472,12 @@
self._todo.insert(0, package)
def _prepareInstall(self, package, force=0, recursive=1):
+ """Internal routine, recursive engine for prepareInstall.
+
+ Test whether the package is installed and (if not installed
+ or if force==1) prepend it to the temporary todo list and
+ call ourselves recursively on all prerequisites."""
+
if not force:
status, message = package.installed()
if status == "yes":
@@ -391,6 +495,15 @@
self._curmessages.append("Requires: %s" % descr)
def prepareInstall(self, package, force=0, recursive=1):
+ """Prepare installation of a package.
+
+ If the package is already installed and force is false nothing
+ is done. If recursive is true prerequisites are installed first.
+
+ Returns a list of packages (to be passed to install) and a list
+ of messages of any problems encountered.
+ """
+
self._curtodo = []
self._curmessages = []
self._prepareInstall(package, force, recursive)
@@ -400,6 +513,8 @@
return rv
def install(self, packages, output):
+ """Install a list of packages."""
+
self._addPackages(packages)
status = []
for pkg in self._todo:
@@ -410,6 +525,11 @@
def _fmtpackagename(dict):
+ """Return the full name "name-version-flavor" of a package.
+
+ If the package is a pseudo-package, something that cannot be
+ installed through pimp, return the name in (parentheses)."""
+
if isinstance(dict, PimpPackage):
dict = dict.dump()
rv = dict['name']
@@ -423,6 +543,8 @@
return rv
def _run(mode, verbose, force, args):
+ """Engine for the main program"""
+
prefs = PimpPreferences()
prefs.check()
db = PimpDatabase(prefs)
@@ -495,6 +617,8 @@
print "\t", m
def main():
+ """Minimal commandline tool to drive pimp."""
+
import getopt
def _help():
print "Usage: pimp [-v] -s [package ...] List installed status"