Include more detailed version ranges spec, and make Requirement.specs a

public/documented attribute.  (backport from trunk)

--HG--
branch : setuptools-0.6
extra : convert_revision : svn%3A6015fed2-1504-0410-9fe1-9d1591cc4771/sandbox/branches/setuptools-0.6%4050532

pkg_resources.txt

@@ -610,6 +610,17 @@ Requirements Parsing
     parsed using the ``parse_version()`` utility function.  Otherwise, it is
     assumed to be an already-parsed version.
 
+    The ``Requirement`` object's version specifiers (``.specs``) are internally
+    sorted into ascending version order, and used to establish what ranges of
+    versions are acceptable.  Adjacent redundant conditions are effectively
+    consolidated (e.g. ``">1, >2"`` produces the same results as ``">1"``, and
+    ``"<2,<3"`` produces the same results as``"<3"``). ``"!="`` versions are
+    excised from the ranges they fall within.  The version being tested for
+    acceptability is then checked for membership in the resulting ranges.
+    (Note that providing conflicting conditions for the same version (e.g.
+    ``"<2,>=2"`` or ``"==2,!=2"``) is meaningless and may therefore produce
+    bizarre results when compared with actual version number(s).)
+
 ``__eq__(other_requirement)``
     A requirement compares equal to another requirement if they have
     case-insensitively equal project names, version specifiers, and "extras".
@@ -634,6 +645,14 @@ Requirements Parsing
     function, so they may not exactly equal the extras the requirement was
     created with.)
 
+``specs``
+    A list of ``(op,version)`` tuples, sorted in ascending parsed-version
+    order.  The `op` in each tuple is a comparison operator, represented as
+    a string.  The `version` is the (unparsed) version number.  The relative
+    order of tuples containing the same version numbers is undefined, since
+    having more than one operator for a given version is either redundant or
+    self-contradictory.
+
 
 Entry Points
 ============

setuptools.txt

@@ -514,6 +514,15 @@ specifiers.  A version specifier is one of the operators ``<``, ``>``, ``<=``,
 separated by whitespace, but any whitespace or nonstandard characters within a
 project name or version identifier must be replaced with ``-``.
 
+Version specifiers for a given project are internally sorted into ascending
+version order, and used to establish what ranges of versions are acceptable.
+Adjacent redundant conditions are also consolidated (e.g. ``">1, >2"`` becomes
+``">1"``, and ``"<2,<3"`` becomes ``"<3"``). ``"!="`` versions are excised from
+the ranges they fall within.  A project's version is then checked for
+membership in the resulting ranges. (Note that providing conflicting conditions
+for the same version (e.g. "<2,>=2" or "==2,!=2") is meaningless and may
+therefore produce bizarre results.)
+
 Here are some example requirement specifiers::
 
     docutils >= 0.3