Add `Version.precedence_key`.

This will be used in `sort(..., key=lambda v: v.precedence_key)`.
Remove previous comparison/ordering implementation.

The current implementation relies on a 4-tuple:
- major, minor, patch (as integers) - natural order matches precedence
  rules
- a tuple of identifiers for the prerelease component.

The identifiers for the prerelease components are based on:
- A `NumericIdentifier` class, that compares number using their natural
  order, and always compares lower than non-numeric identifiers
- A `AlphaIdentifier` class for non-numeric identifiers; it compares
  versions using ASCII ordering.
- A `MaxIdentifier` class, that compares higher to any other identifier;
  used to ensure that a non-prerelease version is greater than any of
  its prereleases.

1 files changed, 7 insertions, 0 deletions

diff --git a/docs/reference.rst b/docs/reference.rst
index 62a2b3b..3495940 100644
--- a/docs/reference.rst
+++ b/docs/reference.rst
@@ -128,6 +128,13 @@ Representing a version (the Version class)
         May be ``None`` for a :attr:`partial` version number in a ``<major>``, ``<major>.<minor>``,
         ``<major>.<minor>.<patch>`` or ``<major>.<minor>.<patch>-<prerelease>`` format.
 
+    .. attribute:: precedence_key
+
+        Read-only attribute; suited for use in ``sort(versions, key=lambda v: v.precedence_key)``.
+        The actual value of the attribute is considered an implementation detail; the only
+        guarantee is that ordering versions by their precedence_key will comply with semver precedence rules.
+
+        Note that the :attr:`~Version.build` isn't included in the precedence_key computatin.
 
     .. rubric:: Methods