Version management examples

Python packages, libraries and frameworks use various processes to manage the version setting and increments of the software

Version management may differ for software likely to be distributed via packaged installations from PyPi / pip, conda, or from source installs from source archives (GitLab/ GitHub)

The main repos checked to inform version settings were:

• pip, pytest, black
• datashader, xarray, scikit-learn,
• numpy, pandas
• iris, matplotlib
• dash, dvc

---

Summary

• Packages reviewed and checked last: Jan 2023 (12 packages checked)
• setuptools-scm will be used to give automatic version numbering from git tags
• versioneer was a similar package, but it no longer maintained
• setuptools-scm used by: 7 / 12
• versioneer used by: 2/ 12
• other version management: 3 / 12

Packages by version method

• setutools-scm: pip, pytest, black, xarray, iris, matplotlib, dvc
• versioneer: numpy, pandas,
• param: datashader,
• other: scikit-learn, dash

---

Pip

• https://github.com/pypa/pip
• setuptools-scm
• SemVer
• https://github.com/pypa/pip/blob/main/src/pip/_vendor/platformdirs/version.py
• custom "get_version" function in setup.py
• variable version in init.py file
  • reads version from init file "src/pip/init.py"
  • https://github.com/pypa/pip/blob/main/src/pip/__init__.py
  • https://github.com/pytest-dev/pytest/blob/main/setup.cfg
• use examples
  • from pip import version

Pytest

• setuptools-scm to manage version
• SemVer
• key files
  • https://github.com/pytest-dev/pytest/blob/main/pyproject.toml
  • https://github.com/pytest-dev/pytest/blob/main/src/_pytest/__init__.py
  • https://github.com/pytest-dev/pytest/blob/main/pyproject.toml
  • https://github.com/pytest-dev/pytest/blob/main/doc/en/conf.py
  • https://github.com/pytest-dev/pytest/blob/main/.gitignore
• use examples
  • import pytest
  • pytest.version_tuple # (7, 0, 0)

Black

• setuptools-scm to manage version
• SemVer
• set to ignore locally in repo, and added to init
• https://github.com/psf/black/blob/master/.gitignore
• https://github.com/psf/black/blob/main/pyproject.toml

---

Datashader

• https://github.com/holoviz/datashader
• SemVer
• uses the "param" package to extract version during setup
• version=param.version.get_setup_version(file,"datashader",archive_commit="$Format:%h$"),
• https://param.holoviz.org/Reference_Manual/param.html
• https://param.holoviz.org/reference.html?highlight=version#param.version.Version

Xarray

• setuptools-scm to manage version
• CalVer
• uses scm version flag in setup.py
• setup(use_scm_version={"fallback_version": "999"})
• set in pyproject.toml
• https://github.com/pydata/xarray/blob/main/pyproject.toml
• https://github.com/pydata/xarray/blob/main/.github/workflows/configure-testpypi-version.py

Scikit-learn

• set in init.py
• SemVer
• Version is used from this local import and used to set the version in setup.py
• https://github.com/scikit-learn/scikit-learn/blob/main/sklearn/__init__.py

Numpy

• SemVer
• uses versioneer.py for version management
• versionner.py at root
• [versioneer] section in setup.cfg

Pandas

• uses versioneer.py for version management
• SemVer
• versionner.py at root
• [versioneer] section in setup.cfg
• https://github.com/pandas-dev/pandas/blob/main/scripts/generate_version.py
• https://github.com/pandas-dev/pandas/blob/main/pandas/_version.py
• https://github.com/pandas-dev/pandas/blob/main/pandas/tests/test_common.py#L160
• https://github.com/pandas-dev/pandas/blob/main/doc/source/conf.py

---

Iris

• setuptools-scm
• SemVer
• https://github.com/SciTools/iris/blob/main/pyproject.toml#L11
• https://github.com/SciTools/iris/blob/main/.gitignore
• https://github.com/SciTools/iris/blob/main/lib/iris/__init__.py

Matplotlib

• setuptools-scm
• SemVer

---

Dash

• "Dash is a productive Python framework for building web analytic applications"
• direct edit of file
• Semver
• https://github.com/plotly/dash
• version.py file holds the version number, e.g. __version__ = "1.19.0"
• This is read in by setup.py at installation
• https://github.com/plotly/dash/blob/master/setup.py
• https://github.com/plotly/dash/blob/master/dash/__init__.py
• https://github.com/plotly/dash/blob/master/dash/version.py

DVC

• "An open-source tool for data science and machine learning projects"
• setuptools-scm
• SemVer
• https://github.com/iterative/dvc/blob/main/dvc/version.py
• https://github.com/iterative/dvc/blob/main/.github/workflows/packages.yaml
• https://github.com/iterative/dvc/blob/main/pyproject.toml