Merge pull request #1384 from gregmuellegger/issue/1017

Using packaging.version for version number parsing, beeing PEP-440 compliant

Author: ericholscher

docs/versions.rst

@@ -22,13 +22,24 @@ You should push a **tag** for each version of your project.
 These tags should be numbered in a way that is consistent with `semantic versioning <http://semver.org/>`_.
 This will map to your ``stable`` branch by default.
 
+.. note::
+    We in fact are parsing your tag names against the rules given by
+    `PEP 440`_. This spec allows "normal" version numbers like ``1.4.2`` as
+    well as pre-releases. A alpha version or a release candidate are examples
+    of pre-releases and they look like this: ``2.0a1``.
+
+    We only consider non pre-releases for the ``stable`` version of your
+    documentation.
+
 If you have documentation changes on a **long-lived branch**,
 you can build those too.
 This will allow you to see how the new docs will be built in this branch of the code.
 Generally you won't have more than 1 active branch over a long period of time.
 The main exception here would be **release branches**,
 which are branches that are maintained over time for a specific release number.
 
+.. _PEP 440: https://www.python.org/dev/peps/pep-0440/
+
 Redirects on root URLs
 ----------------------
 

readthedocs/api/base.py

@@ -16,7 +16,8 @@
 from builds.models import Build, Version
 from core.utils import trigger_build
 from projects.models import Project, ImportedFile
-from projects.utils import highest_version, mkversion
+from projects.version_handling import highest_version
+from projects.version_handling import parse_version_failsafe
 from djangome import views as djangome
 
 from .utils import SearchMixin, PostAuthentication
@@ -141,25 +142,28 @@ def get_object_list(self, request):
 
     def version_compare(self, request, **kwargs):
         project = get_object_or_404(Project, slug=kwargs['project_slug'])
-        highest = highest_version(project.versions.filter(active=True))
+        highest_version_obj, highest_version_comparable = highest_version(
+            project.versions.filter(active=True))
         base = kwargs.get('base', None)
         ret_val = {
-            'project': highest[0],
-            'version': highest[1],
+            'project': highest_version_obj,
+            'version': highest_version_comparable,
             'is_highest': True,
         }
-        if highest[0]:
-            ret_val['url'] = highest[0].get_absolute_url()
-            ret_val['slug'] = highest[0].slug,
+        if highest_version_obj:
+            ret_val['url'] = highest_version_obj.get_absolute_url()
+            ret_val['slug'] = highest_version_obj.slug,
         if base and base != LATEST:
             try:
-                ver_obj = project.versions.get(slug=base)
-                base_ver = mkversion(ver_obj)
-                if base_ver:
+                base_version_obj = project.versions.get(slug=base)
+                base_version_comparable = parse_version_failsafe(
+                    base_version_obj.verbose_name)
+                if base_version_comparable:
                     # This is only place where is_highest can get set.  All
                     # error cases will be set to True, for non- standard
                     # versions.
-                    ret_val['is_highest'] = base_ver >= highest[1]
+                    ret_val['is_highest'] = (
+                        base_version_comparable >= highest_version_comparable)
                 else:
                     ret_val['is_highest'] = True
             except (Version.DoesNotExist, TypeError):

readthedocs/betterversion/__init__.py

@@ -3,7 +3,6 @@
 import os
 from urlparse import urlparse
 
-from distlib.version import UnsupportedVersionError
 from django.conf import settings
 from django.contrib.auth.models import User
 from django.core.urlresolvers import reverse
@@ -13,16 +12,17 @@
 
 from guardian.shortcuts import assign
 
-from betterversion.better import version_windows, VersionIdentifier
 from builds.constants import LATEST
 from builds.constants import LATEST_VERBOSE_NAME
+from builds.constants import STABLE
 from oauth import utils as oauth_utils
 from privacy.loader import RelatedProjectManager, ProjectManager
 from projects import constants
 from projects.exceptions import ProjectImportError
 from projects.templatetags.projects_tags import sort_version_aware
-from projects.utils import (highest_version as _highest, make_api_version,
-                            symlink, update_static_metadata)
+from projects.utils import make_api_version, symlink, update_static_metadata
+from projects.version_handling import determine_stable_version
+from projects.version_handling import version_windows
 from taggit.managers import TaggableManager
 from tastyapi.slum import api
 
@@ -248,7 +248,7 @@ def subdomain(self):
         return "%s.%s" % (subdomain_slug, prod_domain)
 
     def sync_supported_versions(self):
-        supported = self.supported_versions(flat=True)
+        supported = self.supported_versions()
         if supported:
             self.versions.filter(
                 verbose_name__in=supported).update(supported=True)
@@ -590,10 +590,6 @@ def conf_dir(self, version=LATEST):
         if conf_file:
             return conf_file.replace('/conf.py', '')
 
-    @property
-    def highest_version(self):
-        return _highest(self.api_versions())
-
     @property
     def is_imported(self):
         return bool(self.repo)
@@ -697,37 +693,59 @@ def all_active_versions(self):
         """
         return self.versions.filter(active=True)
 
-    def supported_versions(self, flat=True):
+    def supported_versions(self):
         """
         Get the list of supported versions.
         Returns a list of version strings.
         """
         if not self.num_major or not self.num_minor or not self.num_point:
-            return None
-        version_identifiers = []
-        for version in self.versions.all():
-            try:
-                version_identifiers.append(VersionIdentifier(version.verbose_name))
-            except UnsupportedVersionError:
-                # Probably a branch
-                pass
-        active_versions = version_windows(
+            return []
+        version_identifiers = self.versions.values_list('verbose_name', flat=True)
+        return version_windows(
             version_identifiers,
             major=self.num_major,
             minor=self.num_minor,
             point=self.num_point,
-            flat=flat,
         )
-        version_strings = [v._string for v in active_versions]
-        return version_strings
+
+    def get_stable_version(self):
+        return self.versions.filter(slug=STABLE).first()
+
+    def update_stable_version(self):
+        """
+        Returns the version that was promoited to be the new stable version.
+        It will return ``None`` if no update was mode or if there is no
+        version on the project that can be considered stable.
+        """
+        versions = self.versions.all()
+        new_stable = determine_stable_version(versions)
+        if new_stable:
+            current_stable = self.get_stable_version()
+            if current_stable:
+                identifier_updated = (
+                    new_stable.identifier != current_stable.identifier)
+                if identifier_updated and current_stable.machine:
+                    log.info(
+                        "Update stable version: {project}:{version}".format(
+                            project=self.slug,
+                            version=new_stable.identifier))
+                    current_stable.identifier = new_stable.identifier
+                    current_stable.save()
+                    return new_stable
+            else:
+                log.info(
+                    "Creating new stable version: {project}:{version}".format(
+                        project=self.slug,
+                        version=new_stable.identifier))
+                current_stable = self.versions.create_stable(
+                    type=new_stable.type,
+                    identifier=new_stable.identifier)
+                return new_stable
 
     def version_from_branch_name(self, branch):
+        versions = self.versions_from_branch_name(branch)
         try:
-            return (
-                self.versions.filter(identifier=branch) |
-                self.versions.filter(identifier=('remotes/origin/%s' % branch)) |
-                self.versions.filter(identifier=('origin/%s' % branch))
-            )[0]
+            return versions[0]
         except IndexError:
             return None
 

readthedocs/betterversion/better.py

@@ -1,34 +1,20 @@
 from django import template
 
-from distutils2.version import NormalizedVersion
-from projects.utils import mkversion
-from builds.constants import LATEST
-from builds.constants import STABLE
-
-register = template.Library()
+from projects.version_handling import comparable_version
 
 
-def make_version(version):
-    ver = mkversion(version)
-    if not ver:
-        if version.slug == LATEST:
-            return NormalizedVersion('99999.0', error_on_huge_major_num=False)
-        elif version.slug == STABLE:
-            return NormalizedVersion('9999.0', error_on_huge_major_num=False)
-        else:
-            return NormalizedVersion('999.0', error_on_huge_major_num=False)
-    return ver
+register = template.Library()
 
 
 @register.filter
 def sort_version_aware(versions):
     """
     Takes a list of versions objects and sort them caring about version schemes
     """
-    sorted_verisons = sorted(versions,
-                             key=make_version,
-                             reverse=True)
-    return sorted_verisons
+    return sorted(
+        versions,
+        key=lambda version: comparable_version(version.verbose_name),
+        reverse=True)
 
 
 @register.filter

readthedocs/projects/models.py

@@ -9,7 +9,6 @@
 from httplib2 import Http
 
 from django.conf import settings
-from distutils2.version import NormalizedVersion, suggest_normalized_version
 import redis
 
 from builds.constants import LATEST
@@ -114,37 +113,6 @@ def safe_write(filename, contents):
         fh.close()
 
 
-def mkversion(version_obj):
-    try:
-        if hasattr(version_obj, 'slug'):
-            ver = NormalizedVersion(
-                suggest_normalized_version(version_obj.slug)
-            )
-        else:
-            ver = NormalizedVersion(
-                suggest_normalized_version(version_obj['slug'])
-            )
-        return ver
-    except TypeError:
-        return None
-
-
-def highest_version(version_list):
-    highest = [None, None]
-    for version in version_list:
-        ver = mkversion(version)
-        if not ver:
-            continue
-        elif highest[1] and ver:
-            # If there's a highest, and no version, we don't need to set
-            # anything
-            if ver > highest[1]:
-                highest = [version, ver]
-        else:
-            highest = [version, ver]
-    return highest
-
-
 def purge_version(version, mainsite=False, subdomain=False, cname=False):
     varnish_servers = getattr(settings, 'VARNISH_SERVERS', None)
     h = Http()