boltz2-python-client v0.5.2.post1 - clean-install fix (lazy-import pandas)

[nil16]

PEP 440 post-release patch on top of #34 (v0.5.2). Tagged on gitlab-master as v0.5.2.post1. No public API changes; fixes a long-standing packaging defect.

TL;DR

Three files, +56/-6. Defers an import pandas as pd from module top into the four methods that actually use it, so pip install boltz2-python-client followed by import boltz2_client works on a clean env. pandas is not a runtime dependency (it's [dev]-only) — that's the root cause.

Why

Caught during TestPyPI clean-install validation of v0.5.2. The bug actually existed in 0.5.0 and 0.5.1 already published on PyPI:

$ python3 -m venv /tmp/cleanenv
$ /tmp/cleanenv/bin/pip install boltz2-python-client==0.5.2
$ /tmp/cleanenv/bin/python -c "import boltz2_client"
Traceback (most recent call last):
  ...
  File ".../boltz2_client/virtual_screening.py", line 19, in <module>
    import pandas as pd
ModuleNotFoundError: No module named 'pandas'

The CLI (including the boltz2 --version flag added in v0.5.2) was equally unreachable on a clean install. We never noticed because almost everyone has pandas pre-installed in their data-science env.

What changed

boltz2_client/virtual_screening.py

• Removed module-top import pandas as pd.
• Added from __future__ import annotations so the pd.DataFrame return-type annotations on the affected methods are evaluated lazily and do not require pandas at import time.
• Added a TYPE_CHECKING: import pandas as pd block so static type checkers and IDEs can still resolve those annotations.
• Inserted import pandas as pd inside the four methods that actually use pandas:
  • CompoundLibrary.from_csv
  • VirtualScreeningResult.to_dataframe
  • VirtualScreeningResult.get_top_hits
  • VirtualScreeningResult.get_statistics_by_group

Calling any of those methods still requires pandas (unchanged); importing the package, running the CLI, and every other code path no longer does.

boltz2_client/__init__.py

• __version__ 0.5.2 -> 0.5.2.post1.

CHANGELOG.md

• New [0.5.2.post1] - 2026-02-24 entry placed above [0.5.2] documenting the packaging fix and rationale.

Verification

• 134/134 unit tests pass on the post1 commit (no regression from the lazy-import refactor).
• twine check PASSED for both wheel and sdist of 0.5.2.post1.
• PEP 625-compliant filenames: boltz2_python_client-0.5.2.post1-py3-none-any.whl and boltz2_python_client-0.5.2.post1.tar.gz.
• Diff in this PR is byte-for-byte identical to the gitlab-master v0.5.2..v0.5.2.post1 patch (modulo the examples/nims/boltz-2/ prefix). Verified by automated comparison.
• End-to-end clean-install verification:

  python3 -m venv /tmp/cleanenv
  /tmp/cleanenv/bin/pip install boltz2_python_client-0.5.2.post1-py3-none-any.whl
  # pandas is NOT installed
  /tmp/cleanenv/bin/python -c "import boltz2_client; print(boltz2_client.__version__)"
  # -> 0.5.2.post1
  /tmp/cleanenv/bin/boltz2 --version
  # -> boltz2 0.5.2.post1
  

  All three of these previously raised ModuleNotFoundError.

Test plan

git checkout boltz2-v0.5.2.post1
cd examples/nims/boltz-2
pip install -e .
boltz2 --version          # -> "boltz2 0.5.2.post1"
pytest tests -q --ignore=tests/test_live_endpoints.py
# expect: 134 passed

To reproduce the clean-install fix:

python3 -m venv /tmp/cleanenv
/tmp/cleanenv/bin/pip install ./examples/nims/boltz-2  # NO [dev]
/tmp/cleanenv/bin/python -c "import boltz2_client; print(boltz2_client.__version__)"
# Before this PR: ModuleNotFoundError: No module named 'pandas'
# After  this PR: 0.5.2.post1

Note on PyPI plan

Once this PR is merged, 0.5.2.post1 will be uploaded to TestPyPI first (clean-install validated) and then the same bytes to PyPI. pip install boltz2-python-client will resolve to 0.5.2.post1 for users on pip>=20.3. The 0.5.2 slot on TestPyPI is permanently sealed with the broken artifact (PyPI's policy); the 0.5.2 slot on PyPI will remain unused.

Made with Cursor