Addons: sorting algorithm for versions customizable on flyout

Allow users to choose one of the pre-defined algorithms:

- Lexicographically
- SemVer (Read the Docs)
- CalVer
- Custom pattern

The sorting algorithm is implemented in the backend. So, the list returned under
`addons.flyout.versions` will be sorted acordingly the algorithm the user chose.
There is no need to do anything extra in the front-end.

The algorithm follows the next general rule: _"all the versions that don't match the
pattern defined, are considered invalid and sorted lexicographically between
them and added to the end of the list"_. That means that valid versions will
appear always first in the list and sorted together with other _valid versions_.

There is one _key feature_ here and is that the user can define any pattern
supported by `bumpver`, which is the module we use behind the scenes to perform
the sorting. See https://github.com/mbarkhau/bumpver#pattern-examples

On the other hand, `SemVer (Read the Docs)` is implemented used the exact same
code we were using for the old flyout implementation. This is mainly to keep
backward compatibility, but its usage is not recommended since it's pretty hard
to explain to users and hide non-clear/weird behavior.

Closes readthedocs/addons#222

Author: humitos

readthedocs/projects/constants.py

@@ -431,3 +431,23 @@
         _("Single version without translations (/<filename>)"),
     ),
 )
+
+
+ADDONS_FLYOUT_SORTING_LEXICOGRAPHYCALLY = "lexicographically"
+# Compatibility to keep the behavior of the old flyout.
+# This isn't a good algorithm, but it's a way to keep the old behavior in case we need it.
+ADDONS_FLYOUT_SORTING_SEMVER_READTHEDOCS_COMPATIBLE = "semver-readthedocs-compatible"
+# https://pypi.org/project/packaging/
+ADDONS_FLYOUT_SORTING_PYTHON_PACKAGING = "python-packaging"
+ADDONS_FLYOUT_SORTING_CALVER = "calver"
+# Let the user to define a custom pattern and use BumpVer to parse and sort the versions.
+# https://github.com/mbarkhau/bumpver#pattern-examples
+ADDONS_FLYOUT_SORTING_CUSTOM_PATTERN = "custom-pattern"
+
+ADDONS_FLYOUT_SORTING_CHOICES = (
+    (ADDONS_FLYOUT_SORTING_LEXICOGRAPHYCALLY, "Lexicographically"),
+    (ADDONS_FLYOUT_SORTING_SEMVER_READTHEDOCS_COMPATIBLE, "SemVer (Read the Docs)"),
+    (ADDONS_FLYOUT_SORTING_PYTHON_PACKAGING, "Python Packaging (PEP 440 and PEP 425)"),
+    (ADDONS_FLYOUT_SORTING_CALVER, "CalVer (YYYY.0M.0M)"),
+    (ADDONS_FLYOUT_SORTING_CUSTOM_PATTERN, "Define your own pattern"),
+)

readthedocs/projects/forms.py

@@ -18,6 +18,7 @@
 from readthedocs.integrations.models import Integration
 from readthedocs.invitations.models import Invitation
 from readthedocs.oauth.models import RemoteRepository
+from readthedocs.projects.constants import ADDONS_FLYOUT_SORTING_CUSTOM_PATTERN
 from readthedocs.projects.models import (
     AddonsConfig,
     Domain,
@@ -498,6 +499,8 @@ class Meta:
             "doc_diff_enabled",
             "external_version_warning_enabled",
             "flyout_enabled",
+            "flyout_sorting",
+            "flyout_sorting_custom_pattern",
             "hotkeys_enabled",
             "search_enabled",
             "stable_latest_version_warning_enabled",
@@ -522,6 +525,18 @@ def __init__(self, *args, **kwargs):
         kwargs["instance"] = addons
         super().__init__(*args, **kwargs)
 
+    def clean(self):
+        if (
+            self.cleaned_data["flyout_sorting"] == ADDONS_FLYOUT_SORTING_CUSTOM_PATTERN
+            and not self.cleaned_data["flyout_sorting_custom_pattern"]
+        ):
+            raise forms.ValidationError(
+                _(
+                    "The flyout sorting custom pattern is required when selecting a custom pattern."
+                ),
+            )
+        return super().clean()
+
     def clean_project(self):
         return self.project
 

readthedocs/projects/migrations/0114_addons_flyout_sorting.py

@@ -0,0 +1,37 @@
+# Generated by Django 4.2.9 on 2024-01-26 12:08
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("projects", "0113_disable_analytics_addons"),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name="addonsconfig",
+            name="flyout_sorting_custom_pattern",
+            field=models.CharField(
+                blank=True,
+                default=None,
+                help_text="Sorting pattern supported by BumpVer",
+                max_length=32,
+                null=True,
+            ),
+        ),
+        migrations.AlterField(
+            model_name="addonsconfig",
+            name="flyout_sorting",
+            field=models.CharField(
+                choices=[
+                    ("lexicographically", "Lexicographically"),
+                    ("semver-readthedocs-compatible", "SemVer (Read the Docs)"),
+                    ("python-packaging", "Python Packaging (PEP 440 and PEP 425)"),
+                    ("calver", "CalVer (YYYY.0M.0M)"),
+                    ("custom-pattern", "Define your own pattern"),
+                ],
+                default="lexicographically",
+            ),
+        ),
+    ]

readthedocs/projects/models.py

@@ -61,6 +61,8 @@
 from readthedocs.vcs_support.backends import backend_cls
 
 from .constants import (
+    ADDONS_FLYOUT_SORTING_CHOICES,
+    ADDONS_FLYOUT_SORTING_LEXICOGRAPHYCALLY,
     DOWNLOADABLE_MEDIA_TYPES,
     MEDIA_TYPES,
     MULTIPLE_VERSIONS_WITH_TRANSLATIONS,
@@ -179,6 +181,17 @@ class AddonsConfig(TimeStampedModel):
 
     # Flyout
     flyout_enabled = models.BooleanField(default=True)
+    flyout_sorting = models.CharField(
+        choices=ADDONS_FLYOUT_SORTING_CHOICES,
+        default=ADDONS_FLYOUT_SORTING_LEXICOGRAPHYCALLY,
+    )
+    flyout_sorting_custom_pattern = models.CharField(
+        max_length=32,
+        default=None,
+        null=True,
+        blank=True,
+        help_text="Sorting pattern supported by BumpVer",
+    )
 
     # Hotkeys
     hotkeys_enabled = models.BooleanField(default=True)

readthedocs/projects/version_handling.py

@@ -1,7 +1,10 @@
 """Project version handling."""
+import operator
 import unicodedata
 
-from packaging.version import InvalidVersion, Version
+from bumpver.v2version import parse_version_info
+from bumpver.version import PatternError
+from packaging.version import InvalidVersion, Version, parse
 
 from readthedocs.builds.constants import LATEST_VERBOSE_NAME, STABLE_VERBOSE_NAME, TAG
 from readthedocs.vcs_support.backends import backend_cls
@@ -158,3 +161,86 @@ def determine_stable_version(version_list):
         version_obj, comparable = versions[0]
         return version_obj
     return None
+
+
+def sort_versions_python_packaging(version_list):
+    """
+    Sort Read the Docs versions list using ``packaging`` algorithm.
+
+    All the invalid version (raise ``InvalidVersion``) are added at the end
+    sorted lexicographically.
+
+    https://pypi.org/project/packaging/
+    https://packaging.python.org/en/latest/specifications/version-specifiers/
+    """
+    lexicographically_sorted_version_list = sorted(
+        version_list,
+        key=operator.attrgetter("slug"),
+    )
+
+    valid_versions = []
+    invalid_versions = []
+    for i, version in enumerate(lexicographically_sorted_version_list):
+        try:
+            valid_versions.append((version, Version(version.slug)))
+        except InvalidVersion:
+            # When the version is invalid, we put it at the end while keeping
+            # the lexicographically sorting between the invalid ones.
+            invalid_versions.append((version, parse(str(100000 + i))))
+
+    return [
+        item[0]
+        for item in sorted(valid_versions, key=operator.itemgetter(1))
+        + invalid_versions
+    ]
+
+
+def sort_versions_calver(version_list):
+    """
+    Sort Read the Docs versions using CalVer pattern: ``YYYY.0M.0M``.
+
+    All the invalid version are added at the end sorted lexicographically.
+    """
+    raw_pattern = "YYYY.0M.0D"
+    return sort_versions_custom_pattern(version_list, raw_pattern)
+
+
+def sort_versions_custom_pattern(version_list, raw_pattern):
+    """
+    Sort Read the Docs versions using a custom pattern.
+
+    All the invalid version (raise ``PatternError``) are added at the end
+    sorted lexicographically.
+
+    It uses ``Bumpver`` behinds the scenes for the parsing and sorting.
+    https://github.com/mbarkhau/bumpver
+    """
+    raw_pattern = "YYYY.0M.0D"
+    lexicographically_sorted_version_list = sorted(
+        version_list,
+        key=operator.attrgetter("slug"),
+    )
+
+    valid_versions = []
+    invalid_versions = []
+    for i, version in enumerate(lexicographically_sorted_version_list):
+        try:
+            valid_versions.append(
+                (
+                    version,
+                    parse_version_info(
+                        version.slug,
+                        raw_pattern=raw_pattern,
+                    ),
+                )
+            )
+        except PatternError:
+            # When the version is invalid, we put it at the end while keeping
+            # the lexicographically sorting between the invalid ones.
+            invalid_versions.append((version, parse(str(100000 + i))))
+
+    return [
+        item[0]
+        for item in sorted(valid_versions, key=operator.itemgetter(1))
+        + invalid_versions
+    ]

readthedocs/proxito/views/hosting.py

@@ -23,7 +23,19 @@
 from readthedocs.core.resolver import Resolver
 from readthedocs.core.unresolver import UnresolverError, unresolver
 from readthedocs.core.utils.extend import SettingsOverrideObject
+from readthedocs.projects.constants import (
+    ADDONS_FLYOUT_SORTING_CALVER,
+    ADDONS_FLYOUT_SORTING_CUSTOM_PATTERN,
+    ADDONS_FLYOUT_SORTING_PYTHON_PACKAGING,
+    ADDONS_FLYOUT_SORTING_SEMVER_READTHEDOCS_COMPATIBLE,
+)
 from readthedocs.projects.models import AddonsConfig, Project
+from readthedocs.projects.version_handling import (
+    comparable_version,
+    sort_versions_calver,
+    sort_versions_custom_pattern,
+    sort_versions_python_packaging,
+)
 
 log = structlog.get_logger(__name__)  # noqa
 
@@ -265,6 +277,32 @@ def _v0(self, project, version, build, filename, url, user):
                 .only("slug", "type")
                 .order_by("slug")
             )
+            if (
+                project.addons.flyout_sorting
+                == ADDONS_FLYOUT_SORTING_SEMVER_READTHEDOCS_COMPATIBLE
+            ):
+                versions_active_built_not_hidden = sorted(
+                    versions_active_built_not_hidden,
+                    key=lambda version: comparable_version(
+                        version.verbose_name,
+                        repo_type=project.repo_type,
+                    ),
+                )
+            elif (
+                project.addons.flyout_sorting == ADDONS_FLYOUT_SORTING_PYTHON_PACKAGING
+            ):
+                versions_active_built_not_hidden = sort_versions_python_packaging(
+                    versions_active_built_not_hidden
+                )
+            elif project.addons.flyout_sorting == ADDONS_FLYOUT_SORTING_CALVER:
+                versions_active_built_not_hidden = sort_versions_calver(
+                    versions_active_built_not_hidden
+                )
+            elif project.addons.flyout_sorting == ADDONS_FLYOUT_SORTING_CUSTOM_PATTERN:
+                versions_active_built_not_hidden = sort_versions_custom_pattern(
+                    versions_active_built_not_hidden,
+                    project.addons.flyout_sorting_custom_pattern,
+                )
 
         if version:
             version_downloads = version.get_downloads(pretty=True).items()
@@ -332,9 +370,9 @@ def _v0(self, project, version, build, filename, url, user):
                     # NOTE: I think we are moving away from these selectors
                     # since we are doing floating noticications now.
                     # "query_selector": "[role=main]",
-                    "versions": list(
-                        versions_active_built_not_hidden.values_list("slug", flat=True)
-                    ),
+                    "versions": [
+                        version_.slug for version_ in versions_active_built_not_hidden
+                    ],
                 },
                 "flyout": {
                     "enabled": project.addons.flyout_enabled,

requirements/pip.in

@@ -176,3 +176,6 @@ dparse
 gunicorn
 
 django-cacheops
+
+# Used by Addons for sorting patterns
+bumpver