Skip to content

Versions

Constants and utilities for working with EnergyPlus version numbers. idfkit bundles schemas for every release from v8.9 through v25.2.

EnergyPlus version registry.

Defines all supported EnergyPlus versions since v8.9 (the first to publish epJSON schema) and provides utilities for version manipulation.

find_closest_version(version)

Find the closest supported version that is <= the given version.

This is useful when a file specifies a patch version that doesn't exactly match a supported version (e.g. 9.0.0 -> 9.0.1).

Returns:

Type Description
tuple[int, int, int] | None

The closest supported version, or None if no suitable version exists.

Examples:

>>> find_closest_version((24, 1, 5))
(24, 1, 0)
>>> find_closest_version((9, 0, 0))
(8, 9, 0)
>>> find_closest_version((1, 0, 0)) is None
True
Source code in src/idfkit/versions.py 
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
def find_closest_version(version: tuple[int, int, int]) -> tuple[int, int, int] | None:
    """
    Find the closest supported version that is <= the given version.

    This is useful when a file specifies a patch version that doesn't
    exactly match a supported version (e.g. 9.0.0 -> 9.0.1).

    Returns:
        The closest supported version, or None if no suitable version exists.

    Examples:
        >>> find_closest_version((24, 1, 5))
        (24, 1, 0)
        >>> find_closest_version((9, 0, 0))
        (8, 9, 0)
        >>> find_closest_version((1, 0, 0)) is None
        True
    """
    best: tuple[int, int, int] | None = None
    for v in ENERGYPLUS_VERSIONS:
        if v <= version:
            best = v
    return best

github_release_tag(version)

Return the GitHub release tag for a version.

Examples:

>>> github_release_tag((24, 1, 0))
'v24.1.0'
>>> github_release_tag((9, 2, 0))
'v9.2.0'
Source code in src/idfkit/versions.py 
112
113
114
115
116
117
118
119
120
121
def github_release_tag(version: tuple[int, int, int]) -> str:
    """Return the GitHub release tag for a version.

    Examples:
        >>> github_release_tag((24, 1, 0))
        'v24.1.0'
        >>> github_release_tag((9, 2, 0))
        'v9.2.0'
    """
    return f"v{version[0]}.{version[1]}.{version[2]}"

is_supported_version(version)

Check if a version is in the supported set.

Examples:

>>> is_supported_version((24, 1, 0))
True
>>> is_supported_version((99, 0, 0))
False
>>> is_supported_version(MINIMUM_VERSION)
True
Source code in src/idfkit/versions.py 
49
50
51
52
53
54
55
56
57
58
59
60
def is_supported_version(version: tuple[int, int, int]) -> bool:
    """Check if a version is in the supported set.

    Examples:
        >>> is_supported_version((24, 1, 0))
        True
        >>> is_supported_version((99, 0, 0))
        False
        >>> is_supported_version(MINIMUM_VERSION)
        True
    """
    return version in _VERSION_SET

version_dirname(version)

Return the schema directory name for a version.

Examples:

>>> version_dirname((24, 1, 0))
'V24-1-0'
>>> version_dirname((9, 6, 0))
'V9-6-0'
Source code in src/idfkit/versions.py 
75
76
77
78
79
80
81
82
83
84
def version_dirname(version: tuple[int, int, int]) -> str:
    """Return the schema directory name for a version.

    Examples:
        >>> version_dirname((24, 1, 0))
        'V24-1-0'
        >>> version_dirname((9, 6, 0))
        'V9-6-0'
    """
    return f"V{version[0]}-{version[1]}-{version[2]}"

version_string(version)

Format a version tuple as a human-readable string.

Examples:

>>> version_string((24, 1, 0))
'24.1.0'
>>> version_string((9, 6, 0))
'9.6.0'
Source code in src/idfkit/versions.py 
63
64
65
66
67
68
69
70
71
72
def version_string(version: tuple[int, int, int]) -> str:
    """Format a version tuple as a human-readable string.

    Examples:
        >>> version_string((24, 1, 0))
        '24.1.0'
        >>> version_string((9, 6, 0))
        '9.6.0'
    """
    return f"{version[0]}.{version[1]}.{version[2]}"