Renamed AvailableDistributions -> Environment. Add sketch of pkg_resources

manual outline.

--HG--
branch : setuptools
extra : convert_revision : svn%3A6015fed2-1504-0410-9fe1-9d1591cc4771/sandbox/trunk/setuptools%4041184

6 files changed, 158 insertions, 17 deletions

diff --git a/pkg_resources.py b/pkg_resources.py
index ffc31319..4e46a092 100644
--- a/pkg_resources.py
+++ b/pkg_resources.py
@@ -52,7 +52,7 @@ __all__ = [
     'get_default_cache',
 
     # Primary implementation classes
-    'AvailableDistributions', 'WorkingSet', 'ResourceManager',
+    'Environment', 'WorkingSet', 'ResourceManager',
     'Distribution', 'Requirement', 'EntryPoint',
 
     # Exceptions
@@ -76,7 +76,7 @@ __all__ = [
     'fixup_namespace_packages', 'get_importer',
 
     # Deprecated/backward compatibility only
-    'run_main',
+    'run_main', 'AvailableDistributions',
 ]
 
 
@@ -453,7 +453,7 @@ class WorkingSet(object):
         """List all distributions needed to (recursively) meet `requirements`
 
         `requirements` must be a sequence of ``Requirement`` objects.  `env`,
-        if supplied, should be an ``AvailableDistributions`` instance.  If
+        if supplied, should be an ``Environment`` instance.  If
         not supplied, it defaults to all distributions available within any
         entry or distribution in the working set.  `installer`, if supplied,
         will be invoked with each requirement that cannot be met by an
@@ -476,7 +476,7 @@ class WorkingSet(object):
             if dist is None:
                 # Find the best distribution and add it to the map
                 if env is None:
-                    env = AvailableDistributions(self.entries)
+                    env = Environment(self.entries)
                 dist = best[req.key] = env.best_match(req, self, installer)
                 if dist is None:
                     raise DistributionNotFound(req)  # XXX put more info here
@@ -531,7 +531,7 @@ class WorkingSet(object):
 
 
 
-class AvailableDistributions(object):
+class Environment(object):
     """Searchable snapshot of distributions on a search path"""
 
     def __init__(self,search_path=None,platform=get_platform(),python=PY_MAJOR):
@@ -645,7 +645,6 @@ class AvailableDistributions(object):
 
         return self.obtain(req, installer) # try and download/install
 
-
     def obtain(self, requirement, installer=None):
         """Obtain a distro that matches requirement (e.g. via download)"""
         if installer is not None:
@@ -653,6 +652,7 @@ class AvailableDistributions(object):
 
     def __len__(self): return len(self._distmap)
 
+AvailableDistributions = Environment    # XXX backward compatibility
 
 class ResourceManager:
     """Manage resource extraction and packages"""
diff --git a/pkg_resources.txt b/pkg_resources.txt
new file mode 100755
index 00000000..f7a17bd6
--- /dev/null
+++ b/pkg_resources.txt
@@ -0,0 +1,133 @@
+=============================================================
+Package Discovery and Resource Access using ``pkg_resources``
+=============================================================
+
+The ``pkg_resources`` module, distributed with ``setuptools``, provides
+features for Python libraries to access resource files, and for extensible
+applications and frameworks to automatically discover plugins.  It also
+provides runtime support for using C extensions that are inside zipfile
+eggs, support for merging packages that have separately-distributed modules or
+subpackages, and APIs for managing Python's current "working set" of active
+packages.
+
+
+.. contents:: **Table of Contents**
+
+
+--------
+Overview
+--------
+
+XXX
+
+
+-----------------
+Developer's Guide
+-----------------
+
+    Accessing Resources
+    Finding and Activating Package Distributions
+        get_provider()
+        require()
+        WorkingSet
+        iter_distributions
+    Running Scripts
+    Configuration
+    Namespace Packages
+    Extensible Applications and Frameworks
+        Locating entry points
+        Activation listeners
+        Metadata access
+        Extended Discovery and Installation
+    Supporting Custom PEP 302 Implementations
+
+
+-------------
+API Reference
+-------------
+
+
+``WorkingSet`` Objects
+======================
+
+Listeners
+
+
+``Environment`` Objects
+=======================
+
+XXX
+
+
+``EntryPoint`` Objects
+======================
+
+XXX
+
+
+``Requirement`` Objects
+=======================
+
+XXX Syntax, parse_requirments, Requirement.parse, etc.
+
+
+``Distribution`` Objects
+========================
+
+XXX
+
+
+``ResourceManager`` Objects
+===========================
+
+XXX
+
+
+Exceptions
+==========
+
+XXX ResolutionError, VersionConflict, DistributionNotFound, UnknownExtra
+
+
+Utility Functions
+=================
+
+
+Parsing Utilities
+-----------------
+
+yield_lines
+    XXX
+
+split_sections
+    XXX
+
+parse_version
+    XXX
+
+safe_name
+    XXX
+
+safe_version
+    XXX
+
+
+Platform Utilities
+------------------
+
+get_platform
+    XXX
+
+compatible_platforms
+    XXX
+
+
+File/Path Utilities
+-------------------
+
+ensure_directory
+    XXX
+
+normalize_path
+    XXX
+
diff --git a/setuptools.txt b/setuptools.txt
index 66881d6c..1beb8327 100755
--- a/setuptools.txt
+++ b/setuptools.txt
@@ -51,6 +51,12 @@ Feature Highlights:
 * Deploy your project in "development mode", such that it's available on
   ``sys.path``, yet can still be edited directly from its source checkout.
 
+* Easily extend the distutils with new commands or ``setup()`` arguments, and
+  distribute/reuse your extensions for multiple projects, without copying code.
+
+* Create extensible applications and frameworks that automatically discover
+  extensions, using simple "entry points" declared in a project's setup script.
+
 
 .. contents:: **Table of Contents**
 
@@ -1846,7 +1852,9 @@ Release Notes/Change History
      that tells it to only yield distributions whose location is the passed-in
      path.  (It defaults to False, so that the default behavior is unchanged.)
 
-   * The ``resolve()`` method of ``AvailableDistributions`` is now a method of
+   * ``AvailableDistributions`` is now called ``Environment``
+
+   * The ``resolve()`` method of ``Environment`` is now a method of
      ``WorkingSet`` instead, and the ``best_match()`` method now uses a working
      set instead of a path list as its second argument.
 
diff --git a/setuptools/command/easy_install.py b/setuptools/command/easy_install.py
index 8c1a3110..63260350 100755
--- a/setuptools/command/easy_install.py
+++ b/setuptools/command/easy_install.py
@@ -181,7 +181,7 @@ class easy_install(Command):
             self.package_index = self.create_index(
                 self.index_url, search_path = self.shadow_path
             )
-        self.local_index = AvailableDistributions(self.shadow_path)
+        self.local_index = Environment(self.shadow_path)
 
         if self.find_links is not None:
             if isinstance(self.find_links, basestring):
@@ -805,7 +805,7 @@ See the setuptools documentation for the "develop" command for more info.
         try:
             args.append(dist_dir)
             self.run_setup(setup_script, setup_base, args)
-            all_eggs = AvailableDistributions([dist_dir])
+            all_eggs = Environment([dist_dir])
             eggs = []
             for key in all_eggs:
                 for dist in all_eggs[key]:
@@ -1064,14 +1064,14 @@ def parse_requirement_arg(spec):
 
 
 
-class PthDistributions(AvailableDistributions):
+class PthDistributions(Environment):
     """A .pth file with Distribution paths in it"""
 
     dirty = False
 
     def __init__(self, filename):
         self.filename = filename; self._load()
-        AvailableDistributions.__init__(
+        Environment.__init__(
             self, list(yield_lines(self.paths)), None, None
         )
 
@@ -1109,13 +1109,13 @@ class PthDistributions(AvailableDistributions):
         """Add `dist` to the distribution map"""
         if dist.location not in self.paths:
             self.paths.append(dist.location); self.dirty = True
-        AvailableDistributions.add(self,dist)
+        Environment.add(self,dist)
 
     def remove(self,dist):
         """Remove `dist` from the distribution map"""
         while dist.location in self.paths:
             self.paths.remove(dist.location); self.dirty = True
-        AvailableDistributions.remove(self,dist)
+        Environment.remove(self,dist)
 
 
 def main(argv, **kw):
diff --git a/setuptools/package_index.py b/setuptools/package_index.py
index d5013795..6ef185f0 100755
--- a/setuptools/package_index.py
+++ b/setuptools/package_index.py
@@ -121,11 +121,11 @@ def interpret_distro_name(location, basename, metadata,
 
 
 
-class PackageIndex(AvailableDistributions):
+class PackageIndex(Environment):
     """A distribution index that scans web pages for download URLs"""
 
     def __init__(self,index_url="http://www.python.org/pypi",*args,**kw):
-        AvailableDistributions.__init__(self,*args,**kw)
+        Environment.__init__(self,*args,**kw)
         self.index_url = index_url + "/"[:not index_url.endswith('/')]
         self.scanned_urls = {}
         self.fetched_urls = {}
diff --git a/setuptools/tests/test_resources.py b/setuptools/tests/test_resources.py
index 865065c2..7ec9b980 100644
--- a/setuptools/tests/test_resources.py
+++ b/setuptools/tests/test_resources.py
@@ -23,7 +23,7 @@ class DistroTests(TestCase):
 
     def testCollection(self):
         # empty path should produce no distributions
-        ad = AvailableDistributions([], python=None)
+        ad = Environment([], python=None)
         self.assertEqual(list(ad), [])
         self.assertEqual(len(ad),0)
         self.assertEqual(ad.get('FooPkg'),None)
@@ -122,7 +122,7 @@ class DistroTests(TestCase):
 
 
     def testResolve(self):
-        ad = AvailableDistributions([]); ws = WorkingSet([])
+        ad = Environment([]); ws = WorkingSet([])
 
         # Resolving no requirements -> nothing to install
         self.assertEqual( list(ws.resolve([],ad)), [] )