Refactored serialization

- Moved serialization from VersionConfig to version.serialization

bumpversion/version_part.py

@@ -1,17 +1,13 @@
 """Module for managing Versions and their internal parts."""
 import re
-import string
-from copy import copy
 from typing import Any, Dict, List, MutableMapping, Optional, Tuple
 
 from click import UsageError
-from versioning.models import VersionComponentConfig
 
-from bumpversion.exceptions import FormattingError, MissingValueError
 from bumpversion.ui import get_indented_logger
 from bumpversion.utils import labels_for_format
-from bumpversion.versioning.models import Version, VersionComponent, VersionSpec
-from bumpversion.versioning.serialization import parse_version
+from bumpversion.versioning.models import Version, VersionComponentConfig, VersionSpec
+from bumpversion.versioning.serialization import parse_version, serialize
 
 logger = get_indented_logger(__name__)
 
@@ -85,117 +81,6 @@ def parse(self, version_string: Optional[str] = None) -> Optional[Version]:
         version.original = version_string
         return version
 
-        # _parsed = {
-        #     key: VersionComponent(self.part_configs[key], value)
-        #     for key, value in parsed.items()
-        #     if key in self.part_configs
-        # }
-        # return Version(_parsed, version_string)
-
-    def _serialize(
-        self, version: Version, serialize_format: str, context: MutableMapping, raise_if_incomplete: bool = False
-    ) -> str:
-        """
-        Attempts to serialize a version with the given serialization format.
-
-        Args:
-            version: The version to serialize
-            serialize_format: The serialization format to use, using Python's format string syntax
-            context: The context to use when serializing the version
-            raise_if_incomplete: Whether to raise an error if the version is incomplete
-
-        Raises:
-            FormattingError: if not serializable
-            MissingValueError: if not all parts required in the format have values
-
-        Returns:
-            The serialized version as a string
-        """
-        values = copy(context)
-        for k in version:
-            values[k] = version[k]
-
-        # TODO dump complete context on debug level
-
-        try:
-            # test whether all parts required in the format have values
-            serialized = serialize_format.format(**values)
-
-        except KeyError as e:
-            missing_key = getattr(e, "message", e.args[0])
-            raise MissingValueError(
-                f"Did not find key {missing_key!r} in {version!r} when serializing version number"
-            ) from e
-
-        keys_needing_representation = set()
-
-        keys = list(self.order)
-        for i, k in enumerate(keys):
-            v = values[k]
-
-            if not isinstance(v, VersionComponent):
-                # values coming from environment variables don't need
-                # representation
-                continue
-
-            if not v.is_optional:
-                keys_needing_representation = set(keys[: i + 1])
-
-        required_by_format = set(labels_for_format(serialize_format))
-
-        # try whether all parsed keys are represented
-        if raise_if_incomplete and not keys_needing_representation <= required_by_format:
-            missing_keys = keys_needing_representation ^ required_by_format
-            raise FormattingError(
-                f"""Could not represent '{"', '".join(missing_keys)}' in format '{serialize_format}'"""
-            )
-
-        return serialized
-
-    def _choose_serialize_format(self, version: Version, context: MutableMapping) -> str:
-        """
-        Choose a serialization format for the given version and context.
-
-        Args:
-            version: The version to serialize
-            context: The context to use when serializing the version
-
-        Returns:
-            The serialized version as a string
-
-        Raises:
-            MissingValueError: if not all parts required in the format have values
-        """
-        chosen = None
-
-        logger.debug("Evaluating serialization formats")
-        logger.indent()
-        for serialize_format in self.serialize_formats:
-            try:
-                self._serialize(version, serialize_format, context, raise_if_incomplete=True)
-                # Prefer shorter or first search expression.
-                chosen_part_count = len(list(string.Formatter().parse(chosen))) if chosen else None
-                serialize_part_count = len(list(string.Formatter().parse(serialize_format)))
-                if not chosen or chosen_part_count > serialize_part_count:
-                    chosen = serialize_format
-                    logger.debug("Found '%s' to be a usable serialization format", chosen)
-                else:
-                    logger.debug("Found '%s' usable serialization format, but it's longer", serialize_format)
-            except FormattingError:
-                # If chosen, prefer shorter
-                if not chosen:
-                    chosen = serialize_format
-            except MissingValueError as e:
-                logger.info(e.message)
-                raise e
-
-        if not chosen:
-            raise KeyError("Did not find suitable serialization format")
-        logger.dedent()
-        logger.debug("Selected serialization format '%s'", chosen)
-
-        return chosen
-
     def serialize(self, version: Version, context: MutableMapping) -> str:
         """
         Serialize a version to a string.
@@ -207,9 +92,4 @@ def serialize(self, version: Version, context: MutableMapping) -> str:
         Returns:
             The serialized version as a string
         """
-        logger.debug("Serializing version '%s'", version)
-        logger.indent()
-        serialized = self._serialize(version, self._choose_serialize_format(version, context), context)
-        logger.debug("Serialized to '%s'", serialized)
-        logger.dedent()
-        return serialized
+        return serialize(version, list(self.serialize_formats), context)

bumpversion/versioning/serialization.py

@@ -1,10 +1,13 @@
 """Functions for serializing and deserializing version objects."""
 import re
-from typing import Dict
+from copy import copy
+from operator import itemgetter
+from typing import Dict, List, MutableMapping
 
-from bumpversion.exceptions import BumpVersionError
+from bumpversion.exceptions import BumpVersionError, FormattingError
 from bumpversion.ui import get_indented_logger
-from bumpversion.utils import key_val_string
+from bumpversion.utils import key_val_string, labels_for_format
+from bumpversion.versioning.models import Version
 
 logger = get_indented_logger(__name__)
 
@@ -54,3 +57,81 @@ def parse_version(version_string: str, parse_pattern: str) -> Dict[str, str]:
     logger.dedent()
 
     return parsed
+
+
+def multisort(xs: list, specs: tuple) -> list:
+    """
+    Sort a list of dictionaries by multiple keys.
+
+    From https://docs.python.org/3/howto/sorting.html#sort-stability-and-complex-sorts
+
+    Args:
+        xs: The list of dictionaries to sort
+        specs: A tuple of (key, reverse) pairs
+
+    Returns:
+        The sorted list
+    """
+    for key, reverse in reversed(specs):
+        xs.sort(key=itemgetter(key), reverse=reverse)
+    return xs
+
+
+def serialize(version: Version, serialize_patterns: List[str], context: MutableMapping) -> str:
+    """
+    Attempts to serialize a version with the given serialization format.
+
+    - valid serialization patterns are those that are renderable with the given context
+    - formats that contain all required components are preferred
+    - the shortest valid serialization pattern is used
+    - if two patterns are equally short, the first one is used
+    - if no valid serialization pattern is found, an error is raised
+
+    Args:
+        version: The version to serialize
+        serialize_patterns: The serialization format to use, using Python's format string syntax
+        context: The context to use when serializing the version
+
+    Raises:
+        FormattingError: if a serialization pattern
+
+    Returns:
+        The serialized version as a string
+    """
+    logger.debug("Serializing version '%s'", version)
+    logger.indent()
+
+    local_context = copy(context)
+    local_context.update(version.values())
+    local_context_keys = set(local_context.keys())
+    required_component_labels = set(version.required_components())
+
+    patterns = []
+    for index, pattern in enumerate(serialize_patterns):
+        labels = set(labels_for_format(pattern))
+        patterns.append(
+            {
+                "pattern": pattern,
+                "labels": labels,
+                "order": index,
+                "num_labels": len(labels),
+                "renderable": local_context_keys >= labels,
+                "has_required_components": required_component_labels <= labels,
+            }
+        )
+
+    valid_patterns = filter(itemgetter("renderable"), patterns)
+    sorted_patterns = multisort(
+        list(valid_patterns), (("has_required_components", True), ("num_labels", False), ("order", False))
+    )
+
+    if not sorted_patterns:
+        raise FormattingError(f"Could not find a valid serialization format in {serialize_patterns!r} for {version!r}")
+
+    chosen_pattern = sorted_patterns[0]["pattern"]
+    logger.debug("Using serialization format '%s'", chosen_pattern)
+    serialized = chosen_pattern.format(**local_context)
+    logger.debug("Serialized to '%s'", serialized)
+    logger.dedent()
+
+    return serialized

tests/test_versioning/test_serialization.py

@@ -1,7 +1,8 @@
 """Tests for the serialization of versioned objects."""
-from bumpversion.versioning.serialization import parse_version
-from bumpversion.versioning.models import SEMVER_PATTERN
-from bumpversion.exceptions import BumpVersionError
+from bumpversion.versioning.serialization import parse_version, serialize
+from bumpversion.versioning.conventions import semver_spec, SEMVER_PATTERN
+from bumpversion.versioning.models import Version
+from bumpversion.exceptions import BumpVersionError, FormattingError, MissingValueError
 
 import pytest
 from pytest import param
@@ -60,3 +61,68 @@ def test_invalid_parse_pattern_raises_error(self):
         """If the parse pattern is not a valid regular expression, a ValueError should be raised."""
         with pytest.raises(BumpVersionError):
             parse_version("1.2.3", r"v(?P<major>\d+\.(?P<minor>\d+)\.(?P<patch>\d+)")
+
+    def test_parse_pattern_with_newlines(self):
+        """A parse pattern with newlines should be parsed correctly."""
+        pattern = r"MAJOR=(?P<major>\d+)\nMINOR=(?P<minor>\d+)\nPATCH=(?P<patch>\d+)\n"
+        assert parse_version("MAJOR=31\nMINOR=0\nPATCH=3\n", pattern) == {"major": "31", "minor": "0", "patch": "3"}
+
+
+class TestSerialize:
+    """Test the serialize function."""
+
+    @pytest.mark.parametrize(
+        ["version", "expected"],
+        [
+            param(
+                semver_spec().create_version({"major": "1", "minor": "2", "patch": "3"}),
+                "1.2.3",
+                id="major-minor-patch",
+            ),
+            param(
+                semver_spec().create_version({"major": "1", "minor": "2", "patch": "0"}),
+                "1.2",
+                id="major-minor-patch-zero",
+            ),
+            param(
+                semver_spec().create_version({"major": "1", "minor": "0", "patch": "0"}),
+                "1",
+                id="major-minor-zero-patch-zero",
+            ),
+        ],
+    )
+    def test_picks_string_with_least_labels(self, version: Version, expected: str):
+        patterns = ["{major}.{minor}.{patch}", "{major}.{minor}", "{major}"]
+        assert serialize(version, serialize_patterns=patterns, context=version.values()) == expected
+
+    def test_renders_a_format_with_newlines(self):
+        """A serialization format with newlines should be rendered correctly."""
+        version = semver_spec().create_version({"major": "31", "minor": "0", "patch": "3"})
+        assert (
+            serialize(
+                version, serialize_patterns=["MAJOR={major}\nMINOR={minor}\nPATCH={patch}\n"], context=version.values()
+            )
+            == "MAJOR=31\nMINOR=0\nPATCH=3\n"
+        )
+
+    def test_renders_a_format_with_additional_context(self):
+        """A serialization format with additional context should be rendered correctly."""
+        version = semver_spec().create_version({"major": "1", "minor": "2", "patch": "3"})
+        assert (
+            serialize(
+                version,
+                serialize_patterns=["{major}.{minor}.{patch}+{$BUILDMETADATA}"],
+                context={"$BUILDMETADATA": "build.1", "major": "1", "minor": "2", "patch": "3"},
+            )
+            == "1.2.3+build.1"
+        )
+
+    def test_raises_error_if_context_is_missing_values(self):
+        """An error is raised if not all parts required in the format have values."""
+        version = semver_spec().create_version({"major": "1", "minor": "2"})
+        with pytest.raises(FormattingError):
+            serialize(
+                version,
+                serialize_patterns=["{major}.{minor}.{patch}+{$BUILDMETADATA}"],
+                context={"major": "1", "minor": "2", "patch": "0"},
+            )