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

public/documented attribute.


git-svn-id: http://svn.python.org/projects/sandbox/trunk/setuptools@50531 6015fed2-1504-0410-9fe1-9d1591cc4771

2 files changed, 31 insertions, 3 deletions

diff --git a/pkg_resources.txt b/pkg_resources.txt
index 5fd0eb2..6a733e5 100755
--- a/pkg_resources.txt
+++ b/pkg_resources.txt
@@ -616,6 +616,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".
@@ -640,6 +651,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
 ============
diff --git a/setuptools.txt b/setuptools.txt
index 9f7d3ea..ef3e90f 100755
--- a/setuptools.txt
+++ b/setuptools.txt
@@ -349,7 +349,7 @@ unless you need the associated ``setuptools`` feature.
     has an ``additional_tests()`` function, it is called and the results are
     added to the tests to be run.  If the named suite is a package, any
     submodules and subpackages are recursively added to the overall test suite.
-    
+
     Specifying this argument enables use of the `test`_ command to run the
     specified test suite, e.g. via ``setup.py test``.  See the section on the
     `test`_ command below for more details.
@@ -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
@@ -1041,7 +1050,7 @@ command; see the section on the `develop`_ command below for more details.
 
 Note that you can also apply setuptools commands to non-setuptools projects,
 using commands like this::
- 
+
    python -c "import setuptools; execfile('setup.py')" develop
 
 That is, you can simply list the normal setup commands and options following
@@ -2432,7 +2441,7 @@ A few important points for writing revision control file finders:
   with the absence of needed programs (i.e., ones belonging to the revision
   control system itself.  It *may*, however, use ``distutils.log.warn()`` to
   inform the user of the missing program(s).
-  
+
 
 Subclassing ``Command``
 -----------------------