Add partially-written API

pep-0262.txt

@@ -98,6 +98,72 @@ Database Contents
     INSTALLDB directory.
 
 
+API Description
+
+    There's a single fundamental class, InstallationDatabase.  The
+    code for it lives in distutils/install_db.py.  (XXX any
+    suggestions for alternate locations in the standard library, or an
+    alternate module name?)
+
+    The InstallationDatabase returns instances of Package that contain
+    all the information about an installed package.
+
+    XXX Several of the fields in Package are duplicates of ones in
+    distutils.dist.Distribution.  Probably they should be factored out
+    into the Package class proposed here, but can this be done in a
+    backward-compatible way?
+    
+    InstallationDatabase has the following interface:
+
+class InstallationDatabase:
+    def __init__ (self, path=None):
+        """InstallationDatabase(path:string)
+        Read the installation database rooted at the specified path.
+        If path is None, INSTALLDB is used as the default.    
+        """
+
+    def get_package (self, package_name):
+        """get_package(package_name:string) : Package
+        Get the object corresponding to a single package.
+        """
+
+    def list_packages (self):
+        """list_packages() : [Package]
+        Return a list of all packages installed on the system, 
+        enumerated in no particular order.
+        """
+
+class Package:
+    """Instance attributes:
+    name : string
+      Package name
+    files : {string : (size:int, perms:int, owner:string, group:string,
+                       digest:string)}
+       Dictionary mapping the path of a file installed by this package 
+       to information about the file.
+
+    The following fields all come from PEP 241.
+
+    version : distutils.version.Version
+      Version of this package
+    platform : [string]
+    summary : string
+    description : string
+    keywords : string
+    home_page : string    
+    author : string
+    author_email : string
+    license : string
+    """
+
+    def add_file (self, path):
+        """add_file(path:string):None
+        Record the size, ownership, &c., information for an installed file.
+        XXX as written, this would stat() the file.  Should the size/perms/
+        checksum all be provided as parameters to this method instead?
+        """
+
+
 Deliverables
 
     A description of the database API, to be added to this PEP.