Version semantic

git –> setuptools-scm –> kitting (howto.txt / igor.py / Makefile) –> semantic versioning

See also

packaging.version.Version [docs]

Release phases

Without SETUPTOOLS_SCM_PRETEND_VERSION_FOR_DRAIN_SWAMP environmental variable locals are included in version

e.g. “0.1.1.dev0+g4b33a80.d20240129” local is “g4b33a80.d20240129”

When releasing this is not what is wanted, so use SETUPTOOLS_SCM_PRETEND_VERSION_FOR_DRAIN_SWAMP with the version

  • Current version

    PYTHONWARNINGS="ignore" python setup.py --version

  • Release by tag aka final

    PYTHONWARNINGS="ignore" SETUPTOOLS_SCM_PRETEND_VERSION_FOR_DRAIN_SWAMP="$(git describe --tag)" python setup.py --version
SETUPTOOLS_SCM_PRETEND_VERSION_FOR_DRAIN_SWAMP="$(git describe --tag)" python -m build

  • alpha: a, beta: b, or candidate: rc

    PYTHONWARNINGS="ignore" SETUPTOOLS_SCM_PRETEND_VERSION_FOR_DRAIN_SWAMP="0.1.1a1" python setup.py --version
SETUPTOOLS_SCM_PRETEND_VERSION_FOR_DRAIN_SWAMP="0.1.1a1" python -m build

  • dev

    PYTHONWARNINGS="ignore" SETUPTOOLS_SCM_PRETEND_VERSION_FOR_DRAIN_SWAMP="0.1.1a1.dev1" python setup.py --version
SETUPTOOLS_SCM_PRETEND_VERSION_FOR_DRAIN_SWAMP="0.1.1a1.dev1" python -m build

Move the tag past post commits

  • post

    PYTHONWARNINGS="ignore" SETUPTOOLS_SCM_PRETEND_VERSION_FOR_DRAIN_SWAMP="0.1.1.post1" python setup.py --version
SETUPTOOLS_SCM_PRETEND_VERSION_FOR_DRAIN_SWAMP="0.1.1.post1" python -m build
drain_swamp.version_semantic.__all__: tuple[str, str, str] = ("SemVersion", "sanitize_tag", "get_version")

Module exports

drain_swamp.version_semantic._map_release: types.MappingProxyType[str, str] = types.MappingProxyType({"alpha": "a", "beta": "b", "candidate": "rc"})

Mapping of release levels. So can gracefully go back and forth

Read only mapping. key is long name. value is abbreviation. Long names will be converted into the abbreviations

drain_swamp.version_semantic._logger: logging.Logger

Module level logger

class drain_swamp.version_semantic.SemVersion(path=None, is_use_final=False)

Translates git version ‣ Python semantic version. Intended use cases:

  • kitting (building sdist and whl)

  • not hardcoding the package str within Python packages

CURRENT_ALIAS_DEFAULT: str = "current"

Preferred default that is used within code. Indicates to get the current git version

CURRENT_ALIASES: tuple[str, str] = ("current", "now")

Aliases which means current (version)

KINDS: tuple[str, str, str] = ("tag", "current", "now")

All the acceptable kinds besides a version str

tag – get the latest tagged version

current or now – get the current version from git. Most likely development version

Variables:

  • path (pathlib.Path | None) – Default None. If None, assumes path is current working directory, otherwise provide the absolute path to the package base folder

  • is_use_final (Any | None) –

    Default False. final is not normally valid within a semantic version string. The use of final may be used to indicate intention of creating a tagged release version. If all the stars are aligned and its G’ds Will. If not, post release version(s) would occur and final would be incorrect.

    Don’t create invalid semantic version strings cuz its convenient. Don’t use this feature!

Raises:
anchor()

Full semantic version for display. xyz separated by hyphens.

Returns:

None when parse_var has not been called otherwise version for display

Return type:

str | None

static as_tuple(version_str)

version tuple as written to _version.py file.

Parameters:

version_str (str) – raw version str

Returns:

version tuple

Return type:

tuple[int | str, …]

property dev

Development version number.

Returns:

dev version number. None is valid. If a dev starts from 0. Also None, if not call parse_var beforehand

Return type:

int | None

property is_use_final

Within a semantic version str “final” is not a valid token. However in scripts it might be used to indicate about to create a tagged version

Use of final is discouraged

Returns:

True if final can be within a semantic version str otherwise False

Return type:

bool

property major

major version. If breaking change, in API, should be incremented.

Returns:

None if not called parse_ver beforehand. Otherwise will be an int

Return type:

int | None

property micro

micro version. For all the other possible categories of changes which are not exceptionally notable

Returns:

None if not called parse_ver beforehand. Otherwise will be an int

Return type:

int | None

property minor

minor version. Incremented if a new feature or a fix occurred.

Returns:

None if not called parse_ver beforehand. Otherwise will be an int

Return type:

int | None

parse_ver(ver, local=None)

Safely parses the semantic version str. The epoch and local will be removed.

Parameters:

  • ver (str) – version str. Best to preprocess this using sanitize_tag

  • local (str | None) – Default None. local format +g[commit].d[YYYYMMDD]. Format wrong if there isn’t minimum one tagged version

Raises:

  • ValueError – Invalid version string. git requires one commit. setupttools-scm requires one tagged commit

property path_cwd

Getter for absolute Path to current working directory.

Returns:

Absolute Path to current working directory

Return type:

pathlib.Path

readthedocs_url(package_name, is_latest=False)

Get readthedocs.io URL. Call parse_ver first.

Parameters:

  • package_name – Differences from app name, contains hyphens rather than underscores

  • is_latest (bool | None) – Default False. If True get latest url otherwise get version specific url

Returns:

url to readthedocs.io for a semantic version of the docs, not necessarily the latest

Return type:

str

property release

Components of the release segment of the version.

Does not include epoch or any pre-release / development / post-release suffixes

Returns:

tuple of major, minor, micro

Return type:

tuple[int, int, int]

property releaselevel

Get long form: alpha, beta, candidate, post. Abbreviations (a, b, and rc) are converted into long forms:

Pre-releases: alpha, beta, candidate, a, b, or rc

Post release: post

Does not indicate whether a development release or not

Returns:

pre-release (beta alpha) or release candidate (rc). None, if not call parse_var beforehand

Return type:

str | None

property releaselevel_abbr

Short form: a, b, rc, post.

Returns:

Short form. Valid in semantic version str

Return type:

str

classmethod sanitize_kind(kind)

Allow kind to be a version str, ‘current’, ‘tag’.

Parameters:

kind (str | None) – Default None. If None, assumes "tag". Type of desired version str. Most reliable to pass in a version str if making a tagged version or want the tagged version. “current” will most likely get a development version

Returns:

kind (“current” or “tag”) or a version str

Return type:

str

property serial

Whether is a post release or not. Cannot be both a post and a pre release.

Returns:

1 indicates post release otherwise 0. None, if not call parse_var beforehand

Return type:

int | None

version_clean(kind)

Gets cleaned version str from either git or version_file.

  • “current” or “now” Gets current version thru setuptools-scm

  • “tag” Gets version from version file. Greatly depends on the pyproject.toml being valid and well configured.

    If pyproject.toml doesn’t exist or malformed will raise a AssertionError. For any other reason, will issue a warning and return None.

    Prefer to fallback to the current version rather than not be able to return a version str at all. Convert the warning –> strerr, so have a chance to correct the problem without sacrificing usability

  • a version str Uses that version str. Use this to create prerelease, post release, and tagged versions

Parameters:

kind (str) – a known kind or a version str

Returns:

cleaned version str

Return type:

str

Raises:
version_xyz()

Get xyz version. Call parse_ver first.

Returns:

xyz version str. Only None if parse_ver not called beforehand

Return type:

str | None

drain_swamp.version_semantic._arbritary_version(next_version, path=None)

From the version file get semantic version str. This depends heavily on pyproject.toml being well-formed

Parameters:

  • next_version (str) – Default empty string. If not provided, tagged version

  • path (pathlib.Path | None) – Default None. If None assumes path is current working directory, otherwise provide the path to the package base folder

Returns:

tagged version or current version str. None rather than empty string

Return type:

str | None

Warning

This command writes to src/[package name]/_version.py Use unittest.mock.patch() to avoid the actual call

drain_swamp.version_semantic._current_tag(path=None)

Tagged version as known by git. If there is no tagged version, make one!

Until a tagged version exists, the version string will not be a valid semantic version.

The git version is authoritative, not some hardcoded version str in a module within a Python package

Runs git describe --tag

Parameters:

path (pathlib.Path | None) – Default None. If None assumes path is current working directory, otherwise provide the path to the package base folder

Returns:

None indicates there are no tagged versions otherwise the latest tagged version

Return type:

str | None

Raises:

  • AssertionError – git executable not found. git must not be installed

drain_swamp.version_semantic._current_version(path=None)

setuptools_scm get the current version. Which more often than not is a development version

Parameters:

path (pathlib.Path | None) – Default None. If None assumes path is current working directory, otherwise provide the path to the package base folder

Returns:

Current version as known by setuptools-scm. Avoid returning an empty string

Return type:

str | None

Note

To update src/[app name]/_version.py, use command, python setup.py --version

drain_swamp.version_semantic._is_ver_ok(str_v)

Check version str ok.

Parameters:

str_v (str) – raw version str

Returns:

True if semantic version str is valid otherwise False

Return type:

bool

drain_swamp.version_semantic._path_or_cwd(val)

Frequently used and annoying to test multiple times.

Should be a Path. If anything else return cwd

Parameters:

path (Any | None) – Should be a Path

Returns:

Path or cwd Path

Return type:

pathlib.Path

drain_swamp.version_semantic._pre_split(_v)

Force short prerelease.

short: a, b, or rc long: alpha, beta, candidate

Parameters:

_v (packaging.version.Version) – packaging module Version class

Returns:

short prerelease string and prerelease number

Return type:

tuple[str, int, str] | None

drain_swamp.version_semantic._remove_v(ver)

Remove prepended v. e.g. From 0!v1.0.1.a1dev1+g4b33a80.d20240129

Will not work on an initial untagged version, 0.1.dev0.d20240213

Parameters:

ver (str) – Non-initial untagged version

Returns:

original str without the v. Includes epoch and local

Return type:

str

drain_swamp.version_semantic._scm_key(dist_name)

Environment variable offer by setuptools-scm to set a specific version. Acts as an normal behavior override.

This is needed when wanting to create a:

  • tagged version

  • post-release version

  • pre-release version

Parameters:

prog_name (str) – package name. Will upper case and replace hyphens with underscores

Returns:

environment variable to affect setuptools-scm behavior

Return type:

str

drain_swamp.version_semantic._strip_epoch(ver)

Strip epoch.

Parameters:

ver (str) – May contain epoch, v, and local

Returns:

epoch and remaining str including v and local

Return type:

tuple[str | None, str]

drain_swamp.version_semantic._strip_local(ver)

Strip local from end of version string.

From 0!v1.0.1.a1dev1+g4b33a80.d20240129

local: g4b33a80.d20240129

remaining: 0!v1.0.1.a1dev1

Parameters:

ver (str) – full version str from git. May include epoch and local

Returns:

local and remaining

Return type:

tuple[str | None, str]

drain_swamp.version_semantic._tag_version(next_version='', path=None)

Previously meant latest git tagged version, but there is no situation where this is desirable.

If tag version, take from: version_file, or fallback If version provided, update version file

Parameters:

  • next_version (str | None) – Default empty string. If not provided, tagged version

  • path (pathlib.Path | None) – Default None. If None assumes path is current working directory, otherwise provide the path to the package base folder

Returns:

tagged version or current version str

Return type:

str | None

Raises:
drain_swamp.version_semantic.get_package_name(path)

Get package name, unmodified, from pyproject.toml.

Parameters:

path (pathlib.Path) – absolute path to either package base folder or pyproject.toml

Returns:

package name. [project].name is a required field, so can assume exists. None if issue with pyproject.toml

Return type:

str | None

drain_swamp.version_semantic.get_version(ver, is_use_final=False)

Semantic version string broken into parts.

Parameters:

  • ver (str) – A semantic version string

  • is_use_final (bool) –

    Default False. final is not normally valid within a semantic version string. The use of final may be used to indicate intention of creating a tagged release version. If all the stars are aligned and its G’ds Will. If not, post release version(s) would occur and final would be incorrect.

    Don’t create invalid semantic version strings cuz its convenient. Don’t use this feature!

Returns:

Semantic version broken into parts: major, minor, micro, release level, serial. And _dev

Return type:

tuple[tuple[int, int, int, str, int], int | None]

Raises:

  • ValueError – Invalid version string. git requires one commit. setupttools-scm requires one tagged commit

drain_swamp.version_semantic.outlier_sanitize(ver)

Deal with particularly bad version str, 0.1.dev0.d20240213.

Explain the regex

0 <escape .> 1 <escape .> dev <digits> (1 or more)
escape . d (once) <digits>*8
Parameters:

ver (str) – Raw version str

Returns:

If this case applies, fixes otherwise leave as is

Return type:

str

drain_swamp.version_semantic.sanitize_tag(ver)

Avoid reinventing the wheel, leverage Version.

final is invalid.

Parameters:

ver (str) – raw semantic version

Returns:

Sanitized semantic version str

Return type:

tuple[str, str | None]

Raises: