Skip to content

setuptools_plugin

gitversioned.plugins.setuptools_plugin

Setuptools integration for GitVersioned.

This module provides entry points for Setuptools to automatically compute and inject versions resolved from Git metadata into package distribution objects.

finalize_distribution_options(distribution)

Computes the package version and updates the distribution metadata.

This is the primary entry point triggered during the Setuptools lifecycle.

Source code in src/gitversioned/plugins/setuptools_plugin.py 
 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
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
def finalize_distribution_options(distribution: Distribution) -> None:
    """
    Computes the package version and updates the distribution metadata.

    This is the primary entry point triggered during the Setuptools lifecycle.
    """

    configure_logger(LoggingSettings(enabled=True))
    logger.debug("Finalizing distribution options for GitVersioned.")

    project_root, source_root, package_name = _resolve_project_context(distribution)
    if not package_name:
        raise DistutilsSetupError("Could not determine package name.")

    # Check for an established version to avoid redundant Git resolution
    established_version = _extract_established_version(distribution, project_root)
    config_overrides = getattr(distribution, "gitversioned_config", {})

    try:
        kwargs: Any = {
            "package_name": package_name,
            "project_root": project_root,
            "src_root": source_root,
            "build_is_editable": getattr(distribution, "editable", False),
        }
        kwargs.update(config_overrides)
        settings = Settings(**kwargs)

        if established_version:
            logger.info(f"Using established version: {established_version}")
            version_string = established_version
            output_path = _find_existing_version_file(settings)
        else:
            repository = GitRepository(settings.project_root)
            environment = BuildEnvironment(project_root=settings.project_root)
            version, output_path = resolve_and_generate_version(
                settings=settings, repository=repository, environment=environment
            )
            version_string = str(version)

        # Update distribution metadata
        if hasattr(distribution, "metadata"):
            distribution.metadata.version = version_string
        distribution.version = version_string

        if output_path:
            _inject_output_into_distribution(
                distribution=distribution,
                output_path=output_path,
                source_root=source_root,
                package_name=package_name,
            )

    except Exception as error:
        if isinstance(error, DistutilsSetupError):
            raise
        logger.exception("Unexpected failure during version resolution")
        raise DistutilsSetupError(f"Failed to resolve version: {error}") from error

setup_keywords(distribution, attribute, value)

Validates and stores the GitVersioned configuration dictionary.

Parameters:

Name Type Description Default
distribution Distribution

The Setuptools distribution object.

 required
attribute str

The keyword attribute name.

 required
value Any

The configuration dictionary provided by the user.

 required
Source code in src/gitversioned/plugins/setuptools_plugin.py 
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
def setup_keywords(distribution: Distribution, attribute: str, value: Any) -> None:
    """
    Validates and stores the GitVersioned configuration dictionary.

    :param distribution: The Setuptools distribution object.
    :param attribute: The keyword attribute name.
    :param value: The configuration dictionary provided by the user.
    """
    configure_logger(LoggingSettings(enabled=True))
    logger.debug(f"setup_keywords called with attribute='{attribute}'")

    if attribute != "gitversioned":
        logger.error(f"Unknown keyword argument: {attribute}")
        raise DistutilsSetupError(f"Unknown keyword argument: {attribute}")

    if not isinstance(value, dict):
        logger.error("gitversioned keyword argument must be a dict")
        raise DistutilsSetupError("gitversioned must be a dict")

    distribution.gitversioned_config = value