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

1 files changed, 19 insertions, 0 deletions

diff --git a/pkg_resources.txt b/pkg_resources.txt
index 4be14dfa..a502411c 100755
--- a/pkg_resources.txt
+++ b/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
 ============