feat(merge): Add force_version argument

docs/changelog.rst

@@ -1,6 +1,14 @@
 Changelog
 =========
 
+1.1.12 (2024-05-07)
+-------------------
+
+Added
+~~~~~
+
+-  :meth:`ocdskit.combine.merge` accepts a ``force_version`` argument.
+
 1.1.11 (2024-05-01)
 -------------------
 

docs/conf.py

@@ -26,7 +26,7 @@
 author = "Open Contracting Partnership"
 
 # The short X.Y version
-version = "1.1.11"
+version = "1.1.12"
 # The full version, including alpha/beta/rc tags
 release = version
 

ocdskit/combine.py

@@ -1,4 +1,5 @@
 import warnings
+from typing import Union
 
 from ocdsextensionregistry import ProfileBuilder
 from ocdsmerge import Merger
@@ -135,14 +136,15 @@ def combine_release_packages(packages, uri='', publisher=None, published_date=''
 def merge(
     data,
     uri: str = '',
-    publisher: dict = None,
+    publisher: Union[dict, None] = None,
     published_date: str = '',
     version: str = DEFAULT_VERSION,
-    schema: dict = None,
+    schema: Union[dict, None] = None,
     return_versioned_release: bool = False,
     return_package: bool = False,
     use_linked_releases: bool = False,
     streaming: bool = False,
+    force_version: bool = False,
     ignore_version: bool = False,
 ):
     """
@@ -168,12 +170,13 @@ def merge(
         package; otherwise, yield versioned releases instead of compiled releases
     :param streaming: if ``return_package`` is ``True``, set the package's records to a generator (this only works
         if the calling code exhausts the generator before ``merge`` returns)
-    :param ignore_version: do not raise an error if the versions are inconsistent across packages to merge
-    :raises InconsistentVersionError: if the versions are inconsistent across packages to merge
+    :param force_version: version to use instead of the version of the first release package or individual release
+    :param ignore_version: do not raise an error if the versions are inconsistent across items to merge
+    :raises InconsistentVersionError: if the versions are inconsistent across items to merge
     :raises MissingOcidKeyError: if the release is missing an ``ocid`` field
     :raises UnknownVersionError: if the OCDS version is not recognized
     """
-    with Packager(ignore_version=ignore_version) as packager:
+    with Packager(force_version=force_version, ignore_version=ignore_version) as packager:
         packager.add(data)
 
         if not schema and packager.version:

ocdskit/packager.py

@@ -4,6 +4,7 @@
 from abc import ABC, abstractmethod
 from collections import defaultdict
 from tempfile import NamedTemporaryFile
+from typing import Union
 
 from ocdskit.exceptions import InconsistentVersionError, MissingOcidKeyError
 from ocdskit.util import (
@@ -49,9 +50,13 @@ class Packager:
     same version of OCDS.
     """
 
-    def __init__(self, ignore_version=False):
+    def __init__(self, force_version: Union[str, None] = None, ignore_version: bool = False):
+        """
+        :param force_version: version to use instead of the version of the first release package or individual release
+        :param ignore_version: do not raise an error if the versions are inconsistent across items to merge
+        """
         self.package = _empty_record_package()
-        self.version = None
+        self.version = force_version
         self.ignore_version = ignore_version
 
         if USING_SQLITE:
@@ -70,7 +75,7 @@ def add(self, data):
         Adds release packages and/or individual releases to be merged.
 
         :param data: an iterable of release packages and individual releases
-        :raises InconsistentVersionError: if the versions are inconsistent across packages to merge
+        :raises InconsistentVersionError: if the versions are inconsistent across items to merge
         """
         for i, item in enumerate(data):
             version = get_ocds_minor_version(item)

setup.cfg

@@ -1,6 +1,6 @@
 [metadata]
 name = ocdskit
-version = 1.1.11
+version = 1.1.12
 author = Open Contracting Partnership
 author_email = data@open-contracting.org
 license = BSD

tests/test_combine.py

@@ -5,7 +5,7 @@
 from ocdsmerge.exceptions import DuplicateIdValueWarning
 
 from ocdskit.combine import compile_release_packages, merge, package_records
-from ocdskit.exceptions import InconsistentVersionError
+from ocdskit.exceptions import InconsistentVersionError, UnknownVersionError
 from tests import read
 
 
@@ -54,6 +54,21 @@ def test_merge_warning():
     ]
 
 
+def test_merge_unknown_version(capsys, monkeypatch, caplog):
+    def data():
+        yield json.loads(read('release-package_unknown-version.json'))
+
+    with pytest.raises(UnknownVersionError):
+        list(merge(data()))
+
+
+def test_merge_unknown_version_force_version(capsys, monkeypatch, caplog):
+    def data():
+        yield json.loads(read('release-package_unknown-version.json'))
+
+    list(merge(data(), force_version='1.1', ignore_version=True))  # no error
+
+
 def test_merge_version_mismatch():
     def data():
         yield json.loads(read('realdata/release-package_1.1-1.json'))