Skip to content

Speed up import isal by not importing __future__ in the version file - #335

Merged
rhpvorderman merged 5 commits into
pycompression:developfrom
ptweezy:minimal-version-file
Nov 18, 2026
Merged

rhpvorderman merged 5 commits into
pycompression:developfrom
ptweezy:minimal-version-file

Conversation

@ptweezy

@ptweezy ptweezy commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

The default version file template of setuptools-scm 10, which isolated builds now use, starts with from __future__ import annotations. __future__ is not a frozen module, so every import isal loads it from disk unless another module already has. This PR sets version_file_template in pyproject.toml to that default template without the __future__ import. The generated file keeps version, version_tuple, commit_id and their dunder forms. It only differs from the default in that line and in the first comment, which names setuptools-scm instead of vcs-versioning.

Without the import, Python 3.11 to 3.13 evaluate annotations such as tuple[int | str, ...] when the module is imported, which works from Python 3.10 on. Python 3.14 does not evaluate them on import.

The commit_id line uses scm_version.short_node, which setuptools-scm has had since 9.2.0. With 8.x the build fails with AttributeError: 'ScmVersion' object has no attribute 'short_node', so build-system.requires now asks for setuptools-scm>=9.2. setuptools-scm 9.2.0 and 10.3.4 write the same file. _version.pyi now declares all the variables, so type checkers accept them.

Timed in the process on Linux with Python 3.14, as the median of 300 interleaved runs, import isal.isal_zlib takes 267 µs instead of 327 µs. A version file that only sets __version__ takes 262 µs, so keeping the variables costs about 5 µs. A program that has already imported __future__ saves nothing.

tests/test_version.py checks __version__ against importlib.metadata. The test suite passes on this branch on Linux with CPython 3.14.

Checklist

  • Pull request details were added to CHANGELOG.rst
  • Documentation was updated (if needed)

The default version file template of setuptools-scm 10, which isolated
builds now get, starts with "from __future__ import annotations".
__future__ is not a frozen module, so every "import isal" loaded it
from disk unless another module had done so first. isal only uses
__version__, and _version.pyi declares nothing else, so a one-line
template now replaces the default.

Under cachegrind, "import isal" runs 576K fewer instructions on Python
3.11 and 653K fewer on 3.14, about a third of what it costs on top of
interpreter startup. Timed in the process on Linux, "import
isal.isal_zlib" takes 0.13 ms less on 3.11 (776 to 646 us) and 0.21 ms
less on 3.14 (944 to 736 us). Processes that have already imported
__future__ see no change.

isal._version no longer has version, version_tuple, commit_id and their
dunder forms. Nothing in isal uses them.

@rhpvorderman rhpvorderman left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I just checked. The from __future__ import annotations is no longer needed since python 3.9. So there is no need to keep that import in there. I do like to keep the rest of the version file though.

Comment thread pyproject.toml Resolved
Comment thread tests/test_version.py Resolved
Downstream code can use version_tuple and commit_id from
isal._version, for example to check for a feature. The template is
now the default template of setuptools-scm 10 without "from
__future__ import annotations", so the version file keeps version,
version_tuple, commit_id and their dunder forms. Python 3.10 and
later can evaluate its annotations without the import, and Python
3.14 does not evaluate them on import.

The commit_id line needs scm_version.short_node, which setuptools-scm
has had since 9.2.0. Older versions fail the build with an
AttributeError, so the build now requires setuptools-scm 9.2 or
later. _version.pyi declares all the variables, so type checkers
accept them too.

Timed in the process on Python 3.14, as the median of 300 interleaved
runs, "import isal.isal_zlib" takes 267 us. It takes 327 us with the
default template, and 262 us when the version file only sets
__version__.
Testing this detail of the version file template is not needed.
@ptweezy
ptweezy force-pushed the minimal-version-file branch from ba62f86 to 2f6552f Compare November 18, 2026 01:54
@rhpvorderman
rhpvorderman merged commit a9d991e into pycompression:develop Nov 18, 2026
23 of 24 checks passed
@ptweezy
ptweezy deleted the minimal-version-file branch November 18, 2026 14:23
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants