Utility functions for handling version compatibility.
This module contains functions that help managing the versions of different Fed-BioMed components.
See https://fedbiomed.org/latest/user-guide/deployment/versions for more information
Instructions for developers
If you make a change that changes the format/metadata/structure of one of the components below, you must update the version.
Components concerned by versioning:
- config files (researcher and node)
- messaging protocol (i.e. structure of Message classes)
- breakpoints
Instructions for updating the version
- bump the version in common/constants.py: if your change breaks backward compatibility you must increase the major version, else the minor version. Micro versions are supported but their use is currently discouraged.
- Update the Changelog page with a short description of your change, ideally including instructions on how to manually migrate from the previous version.
Attributes
FBM_Component_Version module-attribute
FBM_Component_Version = Version
The Type of objects representing version numbers in Fed-BioMed
Classes
Functions
raise_for_version_compatibility
raise_for_version_compatibility(their_version, our_version, error_msg=None)
Check version compatibility and behave accordingly.
Raises an exception if the versions are incompatible, otherwise outputs a warning or info message.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
their_version | Union[FBM_Component_Version, str] | the version that we detected in the component | required |
our_version | Union[FBM_Component_Version, str] | the version of the component within the current runtime | required |
error_msg | Optional[str] | an optional error message. It may contain two %s placeholders which will be substituted with the values of their_version and our_version. | None |
Raises:
| Type | Description |
|---|---|
FedbiomedVersionError | if the versions are incompatible |
Source code in fedbiomed/common/utils/_versions.py
def raise_for_version_compatibility(their_version: Union[FBM_Component_Version, str],
our_version: Union[FBM_Component_Version, str],
error_msg: Optional[str] = None) -> None:
"""Check version compatibility and behave accordingly.
Raises an exception if the versions are incompatible, otherwise outputs a warning or info message.
Args:
their_version: the version that we detected in the component
our_version: the version of the component within the current runtime
error_msg: an optional error message. It may contain two %s placeholders which will be substituted with
the values of their_version and our_version.
Raises:
FedbiomedVersionError: if the versions are incompatible
"""
if isinstance(our_version, str):
our_version = FBM_Component_Version(our_version)
if isinstance(their_version, str):
their_version = FBM_Component_Version(their_version)
if not isinstance(our_version, FBM_Component_Version):
msg = f"{ErrorNumbers.FB625.value}: Component version has incorrect type `our_version` type={str(type(our_version))} value={our_version}"
logger.critical(msg)
raise FedbiomedVersionError(msg)
if not isinstance(their_version, FBM_Component_Version):
msg = f"{ErrorNumbers.FB625.value}: Component version has incorrect type `their_version` type={str(type(their_version))} value={their_version}"
logger.critical(msg)
raise FedbiomedVersionError(msg)
if our_version != their_version:
# note: the checks below rely on the short-circuiting behaviour of the or operator
# (e.g. when checking our_version.minor < their_version.minor we have the guarantee that
# our_version.major == their_version.major
if our_version.major != their_version.major or \
our_version.minor < their_version.minor or \
(our_version.minor == their_version.minor and our_version.micro < their_version.micro):
msg = _create_msg_for_version_check(
f"{ErrorNumbers.FB625.value}: Found incompatible version %s, expected version %s" if error_msg is None else error_msg,
their_version,
our_version
)
logger.critical(msg)
raise FedbiomedVersionError(msg)
else:
msg = _create_msg_for_version_check(
"Found version %s, expected version %s",
their_version,
our_version
)
logger.warning(msg)