Addons: sorting algorithm for versions customizable on flyout

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