Configuration

configuration parameters

Configuration parameters can be configured in pyproject.toml or setup.py. Callables or other Python objects have to be passed in setup.py (via the use_scm_version keyword argument).

root : Path | PathLike[str]

Relative path to the SCM root, defaults to . and is relative to the file path passed in relative_to

version_scheme : str | Callable[[ScmVersion], str]

Configures how the version number is constructed; either an entrypoint name or a callable. See Version number construction for predefined implementations.

local_scheme : str | Callable[[ScmVersion], str]

Configures how the local component of the version (the optional part after the +) is constructed; either an entrypoint name or a callable. See Version number construction for predefined implementations.

version_file: Path | PathLike[str] | None = None

A path to a file that gets replaced with a file containing the current version. It is ideal for creating a _version.py file within the package, typically used to avoid using importlib.metadata (which adds some overhead).

Only files with .py and .txt extensions have builtin templates, for other file types it is necessary to provide version_file_template.

version_file_template: str | None = None

A new-style format string taking version, scm_version and version_tuple as parameters. version is the generated next_version as string, version_tuple is a tuple of split numbers/strings and scm_version is the ScmVersion instance the current version was rendered from

write_to: Pathlike[str] | Path | None = None

(deprecated) legacy option to create a version file relative to the scm root it's broken for usage from a sdist and fixing it would be a fatal breaking change, use version_file instead.

relative_to: Path|Pathlike[str] = "pyproject.toml"

A file/directory from which the root can be resolved. Typically called by a script or module that is not in the root of the repository to point setuptools_scm at the root of the repository by supplying __file__.

tag_regex: str|Pattern[str]

A Python regex string to extract the version part from any SCM tag. The regex needs to contain either a single match group, or a group named version, that captures the actual version information.

Defaults to the value of setuptools_scm._config.DEFAULT_TAG_REGEX

parentdir_prefix_version: str|None = None

If the normal methods for detecting the version (SCM version, sdist metadata) fail, and the parent directory name starts with parentdir_prefix_version, then this prefix is stripped and the rest of the parent directory name is matched with tag_regex to get a version string. If this parameter is unset (the default), then this fallback is not used.

This was intended to cover GitHub's "release tarballs", which extract into directories named projectname-tag/ (in which case parentdir_prefix_version can be set e.g. to projectname-).

fallback_version: str | None = None

A version string that will be used if no other method for detecting the version worked (e.g., when using a tarball with no metadata). If this is unset (the default), setuptools-scm will error if it fails to detect the version.

parse: Callable[[Path, Config], ScmVersion] | None = None

A function that will be used instead of the discovered SCM for parsing the version. Use with caution, this is a function for advanced use and you should be familiar with the setuptools-scm internals to use it.

git_describe_command

This command will be used instead the default git describe --long command.

Defaults to the value set by setuptools_scm.git.DEFAULT_DESCRIBE

normalize

A boolean flag indicating if the version string should be normalized. Defaults to True. Setting this to False is equivalent to setting version_cls to setuptools_scm.NonNormalizedVersion

version_cls: type|str = packaging.version.Version

An optional class used to parse, verify and possibly normalize the version string. Its constructor should receive a single string argument, and its str should return the normalized version string to use. This option can also receive a class qualified name as a string.

The setuptools_scm.NonNormalizedVersion convenience class is provided to disable the normalization step done by packaging.version.Version. If this is used while setuptools-scm is integrated in a setuptools packaging process, the non-normalized version number will appear in all files (see version_file note).

normalization still applies to artifact filenames

Setuptools will still normalize it to create the final distribution, so as to stay compliant with the python packaging standards.

environment variables

SETUPTOOLS_SCM_PRETEND_VERSION

used as the primary source for the version number in which case it will be an unparsed string

it is strongly recommended to use distribution-specific pretend versions (see below).

SETUPTOOLS_SCM_PRETEND_VERSION_FOR_${NORMALIZED_DIST_NAME}

used as the primary source for the version number, in which case it will be an unparsed string. Specifying distribution-specific pretend versions will avoid possible collisions with third party distributions also using setuptools-scm

the dist name normalization follows adapted PEP 503 semantics, with one or more of ".-_" being replaced by a single "_", and the name being upper-cased

this will take precedence over SETUPTOOLS_SCM_PRETEND_VERSION

SETUPTOOLS_SCM_DEBUG

enable the debug logging

SOURCE_DATE_EPOCH

used as the timestamp from which the node-and-date and node-and-timestamp local parts are derived, otherwise the current time is used (https://reproducible-builds.org/docs/source-date-epoch/)

SETUPTOOLS_SCM_IGNORE_VCS_ROOTS

a os.pathsep separated list of directory names to ignore for root finding

api reference

constants

setuptools_scm._config.DEFAULT_TAG_REGEX module-attribute

DEFAULT_TAG_REGEX = compile('^(?:[\\w-]+-)?(?P<version>[vV]?\\d+(?:\\.\\d+){0,2}[^\\+]*)(?:\\+.*)?$')

default tag regex that tries to match PEP440 style versions with prefix consisting of dashed words

setuptools_scm.git.DEFAULT_DESCRIBE module-attribute

DEFAULT_DESCRIBE = ['git', 'describe', '--dirty', '--tags', '--long', '--match', '*[0-9]*']

the configuration class

setuptools_scm.Configuration dataclass

Global configuration model

Source code in src/setuptools_scm/_config.py

@dataclasses.dataclass
class Configuration:
    """Global configuration model"""

    relative_to: _t.PathT | None = None
    root: _t.PathT = "."
    version_scheme: _t.VERSION_SCHEME = DEFAULT_VERSION_SCHEME
    local_scheme: _t.VERSION_SCHEME = DEFAULT_LOCAL_SCHEME
    tag_regex: Pattern[str] = DEFAULT_TAG_REGEX
    parentdir_prefix_version: str | None = None
    fallback_version: str | None = None
    fallback_root: _t.PathT = "."
    write_to: _t.PathT | None = None
    write_to_template: str | None = None
    version_file: _t.PathT | None = None
    version_file_template: str | None = None
    parse: ParseFunction | None = None
    git_describe_command: _t.CMD_TYPE | None = None
    dist_name: str | None = None
    version_cls: type[_VersionT] = _Version
    search_parent_directories: bool = False

    parent: _t.PathT | None = None

    @property
    def absolute_root(self) -> str:
        return _check_absolute_root(self.root, self.relative_to)

    @classmethod
    def from_file(
        cls,
        name: str | os.PathLike[str] = "pyproject.toml",
        dist_name: str | None = None,
        _require_section: bool = True,
        **kwargs: Any,
    ) -> Configuration:
        """
        Read Configuration from pyproject.toml (or similar).
        Raises exceptions when file is not found or toml is
        not installed or the file has invalid format or does
        not contain the [tool.setuptools_scm] section.
        """

        pyproject_data = _read_pyproject(Path(name), require_section=_require_section)
        args = _get_args_for_pyproject(pyproject_data, dist_name, kwargs)

        args.update(read_toml_overrides(args["dist_name"]))
        relative_to = args.pop("relative_to", name)
        return cls.from_data(relative_to=relative_to, data=args)

    @classmethod
    def from_data(
        cls, relative_to: str | os.PathLike[str], data: dict[str, Any]
    ) -> Configuration:
        """
        given configuration data
        create a config instance after validating tag regex/version class
        """
        tag_regex = _check_tag_regex(data.pop("tag_regex", None))
        version_cls = _validate_version_cls(
            data.pop("version_cls", None), data.pop("normalize", True)
        )
        return cls(
            relative_to=relative_to,
            version_cls=version_cls,
            tag_regex=tag_regex,
            **data,
        )

from_data classmethod

from_data(relative_to: str | PathLike[str], data: dict[str, Any]) -> Configuration

given configuration data create a config instance after validating tag regex/version class

Source code in src/setuptools_scm/_config.py

@classmethod
def from_data(
    cls, relative_to: str | os.PathLike[str], data: dict[str, Any]
) -> Configuration:
    """
    given configuration data
    create a config instance after validating tag regex/version class
    """
    tag_regex = _check_tag_regex(data.pop("tag_regex", None))
    version_cls = _validate_version_cls(
        data.pop("version_cls", None), data.pop("normalize", True)
    )
    return cls(
        relative_to=relative_to,
        version_cls=version_cls,
        tag_regex=tag_regex,
        **data,
    )

from_file classmethod

from_file(name: str | PathLike[str] = 'pyproject.toml', dist_name: str | None = None, _require_section: bool = True, **kwargs: Any) -> Configuration

Read Configuration from pyproject.toml (or similar). Raises exceptions when file is not found or toml is not installed or the file has invalid format or does not contain the [tool.setuptools_scm] section.

Source code in src/setuptools_scm/_config.py

@classmethod
def from_file(
    cls,
    name: str | os.PathLike[str] = "pyproject.toml",
    dist_name: str | None = None,
    _require_section: bool = True,
    **kwargs: Any,
) -> Configuration:
    """
    Read Configuration from pyproject.toml (or similar).
    Raises exceptions when file is not found or toml is
    not installed or the file has invalid format or does
    not contain the [tool.setuptools_scm] section.
    """

    pyproject_data = _read_pyproject(Path(name), require_section=_require_section)
    args = _get_args_for_pyproject(pyproject_data, dist_name, kwargs)

    args.update(read_toml_overrides(args["dist_name"]))
    relative_to = args.pop("relative_to", name)
    return cls.from_data(relative_to=relative_to, data=args)