refactor: version handling with new Version class

- Added `bughog/version_control/version.py` with the `Version` class.
- Refactored `ExperimentResult` and `Executable` to use `Version` objects.
- Updated `MongoDB` to handle `Version` serialization and deserialization.
- Added the `packaging` library as a dependency in `pyproject.toml`.
- Added tests for the `Version` class and updated existing tests.

Author: GJFR

bughog/database/mongo/mongodb.py

@@ -11,6 +11,7 @@
 from pymongo.errors import ServerSelectionTimeoutError
 
 from bughog.evaluation.experiment_result import ExperimentResult
+from bughog.version_control.version import Version
 from bughog.parameters import (
     DatabaseParameters,
     EvaluationParameters,
@@ -147,7 +148,7 @@ def store_result(self, params: ExperimentParameters, result: ExperimentResult):
         subject_config = params.subject_configuration
         collection = self.__get_data_collection(subject_config)
         query = {
-            'subject_version': result.executable_version,
+            'subject_version': str(result.executable_version) if result.executable_version else None,
             'executable_origin': result.executable_origin,
             'padded_subject_version': result.padded_subject_version,
             'subject_config': subject_config.subject_setting,
@@ -183,7 +184,7 @@ def get_result(self, params: ExperimentParameters) -> Optional[ExperimentResult]
         doc = collection.find_one(query)
         if doc:
             return ExperimentResult(
-                doc['subject_version'],
+                Version(doc['subject_version']),
                 doc['executable_origin'],
                 doc['state'],
                 doc['result']['raw'],

bughog/evaluation/experiment_result.py

@@ -1,12 +1,12 @@
-import re
 from dataclasses import dataclass
-from typing import Optional
+
+from bughog.version_control.version import Version
 
 
 @dataclass(frozen=True)
 class ExperimentResult:
-    executable_version: Optional[str]
-    executable_origin: Optional[str]
+    executable_version: Version | None
+    executable_origin: str | None
     state: dict
     raw_results: dict
     result_variables: set[tuple[str, str]]
@@ -17,7 +17,7 @@ def is_reproduced(self) -> bool:
         return self.poc_is_reproduced(self.result_variables)
 
     @staticmethod
-    def poc_is_reproduced(result_variables: Optional[set[tuple[str, str]]]) -> bool:
+    def poc_is_reproduced(result_variables: set[tuple[str, str]] | None) -> bool:
         if result_variables is None:
             return False
         for key, value in result_variables:
@@ -26,7 +26,7 @@ def poc_is_reproduced(result_variables: Optional[set[tuple[str, str]]]) -> bool:
         return False
 
     @staticmethod
-    def poc_passed_sanity_check(result_variables: Optional[set[tuple[str, str]]]) -> bool:
+    def poc_passed_sanity_check(result_variables: set[tuple[str, str]] | None) -> bool:
         if result_variables is None:
             return False
         for key, value in result_variables:
@@ -35,7 +35,7 @@ def poc_passed_sanity_check(result_variables: Optional[set[tuple[str, str]]]) ->
         return False
 
     @staticmethod
-    def poc_is_dirty(result_variables: Optional[set[tuple[str, str]]]) -> bool:
+    def poc_is_dirty(result_variables: set[tuple[str, str]] | None) -> bool:
         """
         Returns whether the poc is dirty: it is not reproduced and the sanity check did not succeed.
         """
@@ -48,32 +48,14 @@ def padded_subject_version(self) -> str:
         """
         Returns a zero-padded version string derived from the executable's version,
         suitable for lexicographic comparison.
-
-        Each dot-separated numeric segment is left-padded with zeros to 4 digits.
-        A trailing build-metadata suffix (e.g. the '-<hash>' in '0.0.1-abc123f')
-        is stripped from the last segment before padding and then re-attached, so
-        both 'M.m.p' and 'M.m.p-hash' version formats are handled uniformly.
-        The result for '0.0.1-abc123f' would be '0000.0000.0001-abc123f'.
-
-        Raises ValueError if executable_version is None or does not match the
-        expected format (1-4 digit dot-separated segments with an optional
-        trailing '-<suffix>').
         """
-        if self.executable_version is None or not re.fullmatch(r'\d{1,4}(\.\d{1,4})*(-\w+)?', self.executable_version):
-            raise ValueError(f"Unsupported version format: '{self.executable_version}'")
-        padding_target = 4
-        padded_version = []
-        for sub in self.executable_version.split('.'):
-            numeric, _, suffix = sub.partition('-')
-            padded = '0' * (padding_target - len(numeric)) + numeric
-            if suffix:
-                padded += '-' + suffix
-            padded_version.append(padded)
-        return '.'.join(padded_version)
+        if self.executable_version is None:
+            raise ValueError('executable_version is None')
+        return self.executable_version.padded()
 
     def to_dict(self) -> dict:
         return {
-            'executable_version': self.executable_version,
+            'executable_version': str(self.executable_version) if self.executable_version else None,
             'executable_origin': self.executable_origin,
             'state': self.state,
             'raw_results': self.raw_results,

bughog/subject/executable.py

@@ -6,13 +6,13 @@
 import time
 from abc import ABC, abstractmethod
 from enum import Enum, auto, unique
-from typing import Optional
 
 from bughog import util
 from bughog.evaluation.collectors.logs import LogCollector
 from bughog.evaluation.file_structure import Folder
 from bughog.parameters import SubjectConfiguration
 from bughog.version_control.state.base import State
+from bughog.version_control.version import Version
 
 logger = logging.getLogger(__name__)
 
@@ -32,7 +32,7 @@ def __init__(self, config: SubjectConfiguration, state: State) -> None:
         self._runtime_env_vars = {}
         self._runtime_args = []
         self.__version = None
-        self.__process: Optional[subprocess.Popen] = None
+        self.__process: subprocess.Popen | None = None
 
     # #
     # TO BE IMPLEMENT BY EVERY EVALUATION SUBJECT EXECUTABLE
@@ -147,10 +147,11 @@ def is_ready_for_use(self) -> bool:
         return os.path.isfile(self.executable_path) and self.version is not None
 
     @property
-    def version(self) -> Optional[str]:
+    def version(self) -> Version | None:
         if self.__version is None:
             try:
-                self.__version = self._get_version()
+                version_str = self._get_version()
+                self.__version = Version(version_str)
             except Exception:
                 logger.error(f'Could not retrieve version for {self.state}', exc_info=True)
                 return None
@@ -212,7 +213,7 @@ def unstage(self):
         elif os.path.isdir(self.staging_folder):
             shutil.rmtree(self.staging_folder)
 
-    def run(self, experiment_specific_params: list[str], cwd: Optional[Folder] = None):
+    def run(self, experiment_specific_params: list[str], cwd: Folder | None = None):
         """
         Runs the executable with the given arguments, and kills it after the given timeout.
         """

bughog/version_control/version.py

@@ -0,0 +1,87 @@
+from functools import total_ordering
+from typing import Any
+
+from packaging.version import parse
+
+
+@total_ordering
+class Version:
+    """
+    A wrapper around packaging.version.Version to provide BugHog-specific
+    logic like 'selectable_version' and consistent padding.
+    """
+
+    def __init__(self, version_str: str):
+        self._original_str = version_str
+        # Handle formats like "0.0.1-<hash>" (Servo).
+        # PEP 440 local versions use '+' (e.g. 0.0.1+hash).
+        parsed_str = version_str
+        if '-' in version_str:
+            base, suffix = version_str.split('-', 1)
+            parsed_str = f'{base}+{suffix}'
+
+        self._v = parse(parsed_str)
+
+    @property
+    def major(self) -> int:
+        return self._v.major
+
+    @property
+    def minor(self) -> int:
+        return self._v.minor
+
+    @property
+    def patch(self) -> int:
+        return self._v.micro
+
+    @property
+    def is_pre_release(self) -> bool:
+        return self.major == 0
+
+    @property
+    def selectable_version(self) -> str:
+        """
+        Returns the version string that should be used for selection in the UI/API.
+        - For major versions >= 1, returns the major version (e.g. "100").
+        - For major versions == 0 and minor >= 1, returns major.minor (e.g. "0.1").
+        - For major versions == 0 and minor == 0, returns major.minor.patch (e.g. "0.0.1").
+        """
+        if self.major >= 1:
+            return str(self.major)
+        if self.minor >= 1:
+            return f'{self.major}.{self.minor}'
+        return f'{self.major}.{self.minor}.{self.patch}'
+
+    def padded(self, segment_length: int = 4) -> str:
+        """
+        Returns a zero-padded version string suitable for lexicographic comparison.
+        Matches the logic in ExperimentResult.padded_subject_version.
+        """
+        padded_segments = []
+        for s in self._v.release:
+            s_str = str(s)
+            if len(s_str) > segment_length:
+                raise ValueError(f"Version segment '{s_str}' exceeds maximum length of {segment_length}")
+            padded_segments.append(s_str.zfill(segment_length))
+
+        padded_base = '.'.join(padded_segments)
+
+        if self._v.local:
+            return f'{padded_base}-{self._v.local}'
+        return padded_base
+
+    def __eq__(self, other: Any) -> bool:
+        if not isinstance(other, Version):
+            return NotImplemented
+        return self._v == other._v
+
+    def __lt__(self, other: Any) -> bool:
+        if not isinstance(other, Version):
+            return NotImplemented
+        return self._v < other._v
+
+    def __repr__(self) -> str:
+        return f"Version('{self._original_str}')"
+
+    def __str__(self) -> str:
+        return self._original_str

pyproject.toml

@@ -8,6 +8,7 @@ dependencies = [
     "flask-sock==0.7.0",
     "flatten-dict==0.4.2",
     "gunicorn==25.1.0",
+    "packaging>=26.0",
     "pillow==12.1.1",
     "pyautogui==0.9.54",
     "pydantic>=2.12.5",

test/states/test_experiment_result.py

@@ -1,11 +1,12 @@
 import pytest
 
 from bughog.evaluation.experiment_result import ExperimentResult
+from bughog.version_control.version import Version
 
 
 def _make_result(result_variables, executable_version='100.0.1.1'):
     return ExperimentResult(
-        executable_version=executable_version,
+        executable_version=Version(executable_version) if executable_version else None,
         executable_origin='public',
         state={'type': 'commit', 'commit_nb': 1},
         raw_results={},

test/states/test_version.py

@@ -0,0 +1,57 @@
+import pytest
+from bughog.version_control.version import Version
+
+
+def test_version_parsing():
+    v = Version('100.0.5')
+    assert v.major == 100
+    assert v.minor == 0
+    assert v.patch == 5
+    assert not v.is_pre_release
+
+
+def test_version_pre_release():
+    v = Version('0.1.2')
+    assert v.major == 0
+    assert v.minor == 1
+    assert v.patch == 2
+    assert v.is_pre_release
+
+
+def test_servo_version():
+    v = Version('0.0.1-abc123f')
+    assert v.major == 0
+    assert v.minor == 0
+    assert v.patch == 1
+    # packaging.version local segment will contain the hash
+    assert str(v) == '0.0.1-abc123f'
+
+
+def test_selectable_version_major():
+    assert Version('100.0.5').selectable_version == '100'
+    assert Version('1.2.3').selectable_version == '1'
+
+
+def test_selectable_version_pre_release():
+    assert Version('0.1.2').selectable_version == '0.1'
+    # Now includes patch when minor is also 0
+    assert Version('0.0.1').selectable_version == '0.0.1'
+
+
+def test_version_comparison():
+    assert Version('100.0.0') > Version('99.0.0')
+    assert Version('0.1.2') > Version('0.1.1')
+    assert Version('0.1.2') < Version('1.0.0')
+    assert Version('100.0.1') == Version('100.0.1')
+
+
+def test_padded_version():
+    assert Version('100.0.5').padded() == '0100.0000.0005'
+    assert Version('0.1.2').padded() == '0000.0001.0002'
+    # Servo style
+    assert Version('0.0.1-abc123f').padded() == '0000.0000.0001-abc123f'
+
+
+def test_invalid_version():
+    with pytest.raises(Exception):
+        Version('not-a-version')