Skip to content

gitversioned.versioning.generation

Format and generate output version strings.

Provides utilities to format versions under standards like PEP 440 and SemVer 2, render version templates using Git repository metadata, and execute strategies to inject version strings into files or output streams.

FormattedVersion

Bases: Version

Version subclass providing custom string formatting.

Wraps a packaging Version to custom-format string output for PEP 440 and SemVer 2 standards based on the resolved version type.

Example

from packaging.version import Version ver = FormattedVersion(Version("1.0.0.post1"), "post", "semver2") str(ver) '1.0.0-post1'

Source code in src/gitversioned/versioning/generation.py 
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
class FormattedVersion(Version):
    """Version subclass providing custom string formatting.

    Wraps a packaging Version to custom-format string output for PEP 440 and
    SemVer 2 standards based on the resolved version type.

    Example:
        >>> from packaging.version import Version
        >>> ver = FormattedVersion(Version("1.0.0.post1"), "post", "semver2")
        >>> str(ver)
        '1.0.0-post1'
    """

    def __init__(
        self,
        version: Version,
        version_type: VersionType,
        version_standard: str = "pep440",
    ) -> None:
        """Initialize the formatted version wrapper.

        :param version: The base packaging Version object.
        :param version_type: The type of version being represented.
        :param version_standard: The target version standard ("pep440" or "semver2").
        """
        super().__init__(str(version))
        self._version_type = version_type
        self._version_standard = version_standard

    def __str__(self) -> str:
        """Return the version formatted according to the standard.

        :return: The formatted version string.
        :raises ValueError: If the version standard is unsupported.
        """
        if self._version_standard == "pep440":
            return super().__str__()

        if self._version_standard == "semver2":
            formatted = ".".join(map(str, (list(self.release) + [0, 0])[:3]))
            if self._version_type == "post":
                post_value = self.post or 0
                formatted += f"-post{post_value}"
            elif self._version_type in ("pre", "alpha", "nightly"):
                pre_parts = self.pre or ("a", 0)
                formatted += f"{pre_parts[0]}{pre_parts[1]}"
            elif self._version_type == "dev":
                dev_value = self.dev or 0
                formatted += f"-dev{dev_value}"
            if self.local is not None:
                formatted += f"+{self.local}"
            return formatted

        raise ValueError(f"Unsupported version standard: {self._version_standard}")

    def __repr__(self) -> str:
        """Return the developer-friendly string representation of the formatted version.

        :return: The string representation.
        """
        return repr(self.__str__())

__init__(version, version_type, version_standard='pep440')

Initialize the formatted version wrapper.

:param version: The base packaging Version object. :param version_type: The type of version being represented. :param version_standard: The target version standard ("pep440" or "semver2").

Source code in src/gitversioned/versioning/generation.py 
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
def __init__(
    self,
    version: Version,
    version_type: VersionType,
    version_standard: str = "pep440",
) -> None:
    """Initialize the formatted version wrapper.

    :param version: The base packaging Version object.
    :param version_type: The type of version being represented.
    :param version_standard: The target version standard ("pep440" or "semver2").
    """
    super().__init__(str(version))
    self._version_type = version_type
    self._version_standard = version_standard

__repr__()

Return the developer-friendly string representation of the formatted version.

:return: The string representation.

Source code in src/gitversioned/versioning/generation.py 
87
88
89
90
91
92
def __repr__(self) -> str:
    """Return the developer-friendly string representation of the formatted version.

    :return: The string representation.
    """
    return repr(self.__str__())

__str__()

Return the version formatted according to the standard.

:return: The formatted version string. :raises ValueError: If the version standard is unsupported.

Source code in src/gitversioned/versioning/generation.py 
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
def __str__(self) -> str:
    """Return the version formatted according to the standard.

    :return: The formatted version string.
    :raises ValueError: If the version standard is unsupported.
    """
    if self._version_standard == "pep440":
        return super().__str__()

    if self._version_standard == "semver2":
        formatted = ".".join(map(str, (list(self.release) + [0, 0])[:3]))
        if self._version_type == "post":
            post_value = self.post or 0
            formatted += f"-post{post_value}"
        elif self._version_type in ("pre", "alpha", "nightly"):
            pre_parts = self.pre or ("a", 0)
            formatted += f"{pre_parts[0]}{pre_parts[1]}"
        elif self._version_type == "dev":
            dev_value = self.dev or 0
            formatted += f"-dev{dev_value}"
        if self.local is not None:
            formatted += f"+{self.local}"
        return formatted

    raise ValueError(f"Unsupported version standard: {self._version_standard}")

generate_from_template(pattern, version, reference, settings, repository, environment)

Render a template pattern using version and git repository metadata.

Example

from gitversioned.settings import Settings from gitversioned.utils import BuildEnvironment, GitReference, GitRepository from packaging.version import Version generate_from_template( ... "v{version}-{ref.short_sha}", ... Version("1.0.0"), ... GitReference(short_sha="abc1234"), ... Settings(), ... GitRepository(), ... BuildEnvironment() ... ) 'v1.0.0-abc1234'

:param pattern: The template string pattern to render. :param version: The target Version object. :param reference: The active Git reference metadata. :param settings: Active application configuration. :param repository: The Git repository context helper. :param environment: The environment build variables context. :return: The rendered string, or an empty string if pattern is empty.

Source code in src/gitversioned/versioning/generation.py 
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
@autolog
def generate_from_template(
    pattern: str | None,
    version: Version,
    reference: GitReference,
    settings: Settings,
    repository: GitRepository,
    environment: BuildEnvironment,
) -> str:
    """Render a template pattern using version and git repository metadata.

    Example:
        >>> from gitversioned.settings import Settings
        >>> from gitversioned.utils import BuildEnvironment, GitReference, GitRepository
        >>> from packaging.version import Version
        >>> generate_from_template(
        ...     "v{version}-{ref.short_sha}",
        ...     Version("1.0.0"),
        ...     GitReference(short_sha="abc1234"),
        ...     Settings(),
        ...     GitRepository(),
        ...     BuildEnvironment()
        ... )
        'v1.0.0-abc1234'

    :param pattern: The template string pattern to render.
    :param version: The target Version object.
    :param reference: The active Git reference metadata.
    :param settings: Active application configuration.
    :param repository: The Git repository context helper.
    :param environment: The environment build variables context.
    :return: The rendered string, or an empty string if pattern is empty.
    """
    if not pattern:
        return ""

    context = {
        "version": version,
        "repo": repository,
        "config": settings,
        "env": environment,
        "ref": reference,
    }

    return str(render(generate_template(pattern, context, use_eval=True)))

generate_output_from_strategies(version, version_type, reference, settings, repository, environment)

Resolve the configuration output strategy to generate formatted version content.

Example

from packaging.version import Version from gitversioned.settings import Settings, TemplateStrStrategy from gitversioned.utils import BuildEnvironment, GitReference, GitRepository settings = Settings( ... output_strategies=TemplateStrStrategy( ... content="version = '{version}'" ... ) ... ) generate_output_from_strategies( ... Version("1.0.0"), ... "release", ... GitReference(), ... settings, ... GitRepository(), ... BuildEnvironment(), ... ) "version = '1.0.0'"

:param version: The target Version object. :param version_type: The category of version being built. :param reference: The current Git reference metadata. :param settings: Active application configuration. :param repository: The Git repository context helper. :param environment: The environment build variables context. :return: The generated version string content. :raises ValueError: If the active strategy is unsupported or cannot be resolved.

Source code in src/gitversioned/versioning/generation.py 
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
@autolog
def generate_output_from_strategies(
    version: Version,
    version_type: VersionType,
    reference: GitReference,
    settings: Settings,
    repository: GitRepository,
    environment: BuildEnvironment,
) -> str:
    """Resolve the configuration output strategy to generate formatted version content.

    Example:
        >>> from packaging.version import Version
        >>> from gitversioned.settings import Settings, TemplateStrStrategy
        >>> from gitversioned.utils import BuildEnvironment, GitReference, GitRepository
        >>> settings = Settings(
        ...     output_strategies=TemplateStrStrategy(
        ...         content="__version__ = '{version}'"
        ...     )
        ... )
        >>> generate_output_from_strategies(
        ...     Version("1.0.0"),
        ...     "release",
        ...     GitReference(),
        ...     settings,
        ...     GitRepository(),
        ...     BuildEnvironment(),
        ... )
        "__version__ = '1.0.0'"

    :param version: The target Version object.
    :param version_type: The category of version being built.
    :param reference: The current Git reference metadata.
    :param settings: Active application configuration.
    :param repository: The Git repository context helper.
    :param environment: The environment build variables context.
    :return: The generated version string content.
    :raises ValueError: If the active strategy is unsupported or cannot be resolved.
    """
    if isinstance(
        settings.output_strategies,
        (TemplatePathStrategy, TemplateStrStrategy, RegexStrategy),
    ):
        strategy = settings.output_strategies
    elif isinstance(settings.output_strategies, dict):
        if len(settings.output_strategies) == 1:
            strategy = list(settings.output_strategies.values())[0]
        elif version_type in settings.output_strategies:
            strategy = settings.output_strategies[version_type]
        elif "release" in settings.output_strategies:
            strategy = settings.output_strategies["release"]
        else:
            raise ValueError("Could not determine output strategy.")
    else:
        raise ValueError("Could not determine output strategy.")

    if isinstance(strategy, (TemplateStrStrategy, TemplatePathStrategy)):
        return _generate_output_from_template_strategy(
            strategy,
            version,
            version_type,
            reference,
            settings,
            repository,
            environment,
        )

    if isinstance(strategy, RegexStrategy):
        return _generate_output_from_regex_strategy(
            strategy,
            version,
            version_type,
            reference,
            settings,
            repository,
            environment,
        )

    raise ValueError(f"Unsupported strategy type: {type(strategy)}")