FIX: select the native extension by interpreter architecture on Windows by Om-singhaI · Pull Request #727 · microsoft/mssql-python · GitHub

PR title: FIX: select the native extension by interpreter architecture on Windows

Branch: fix/loader-interpreter-architecture (local only, not pushed)

Work Item / Issue Reference

GitHub Issue: #726

AB#47600

Summary

mssql_python/ddbc_bindings.py chose which compiled extension to load from platform.machine(). On Windows that reports the host CPU, not the architecture the running interpreter was built for. With an x64 CPython on a Windows ARM64 machine (the default python.org installer is x64 and pip installs the win_amd64 wheel), the loader looked for ddbc_bindings.cp314-arm64.pyd, which the wheel never shipped. The lookup missed on every import, a Warning: Using fallback module file ... line was printed to stdout, and the module was picked by directory order through the fallback branch.

Fix

On Windows the architecture now comes from sysconfig.get_platform(), which is derived from the interpreter build and matches the wheel tag (win-amd64 to amd64, win-arm64 to arm64, win32 to win32). The token then goes through the existing normalize_architecture() mapping, so the file names are unchanged for native x64 and native ARM64 installs. macOS and Linux keep using platform.machine() as before (macOS is universal2 anyway).
The file search moved into find_module_path(), and the fallback notice is now emitted as a RuntimeWarning through warnings.warn() instead of print(), so tools that parse a script's stdout no longer receive a stray warning line. The fallback to the first matching file is kept as it was.
tests/test_000_dependencies.py built its expected file name from platform.machine() as well, so test_python_extension_exists failed on the same configuration. It now derives the raw architecture from the loader's get_interpreter_architecture().

Changes

mssql_python/ddbc_bindings.py: new get_interpreter_architecture(), get_module_architecture() and find_module_path() helpers; module level code now calls them. No change to the public driver API.
tests/test_000_dependencies.py: DependencyTester uses the loader helper; the two "conceptual" tests that re simulated the print() and the ImportError string now exercise find_module_path() against a temp directory; new tests monkeypatch sysconfig.get_platform and platform.machine to cover an x64 interpreter on an ARM64 host, a native x64 interpreter, a native ARM64 interpreter, a 32 bit interpreter, and the Linux and macOS passthrough.
CHANGELOG.md: entry under Unreleased / Fixed.

Before (loader source executed with platform.system() = Windows, platform.machine() = ARM64, sysconfig.get_platform() = win-amd64, directory containing only ddbc_bindings.cp314-amd64.pyd):

expected_module  : ddbc_bindings.cp314-arm64.pyd
module_path      : ddbc_bindings.cp314-amd64.pyd   (via fallback)
stdout captured  : 'Warning: Using fallback module file ddbc_bindings.cp314-amd64.pyd instead of ddbc_bindings.cp314-arm64.pyd\n'

After (same inputs):

architecture     : amd64
module_path      : ddbc_bindings.cp314-amd64.pyd   (exact match)
stdout captured  : ''
warnings raised  : []

Validation

python -m pytest tests/test_000_dependencies.py: 26 passed, 3 skipped on main; 33 passed, 3 skipped with this change (macOS, Python 3.14, prebuilt 1.13.0 universal2 binary placed next to the source tree). The 3 skips are the Windows only dependency tests and the Linux only distribution test.
With the source change stashed, the updated test module fails at collection (ImportError: cannot import name 'find_module_path'), and the reproduction above prints the stdout warning again.
black --check --line-length=100 mssql_python/ tests/: clean. flake8 on the two changed files reports only findings that already exist on main (one pre existing E501 went away with the replaced line).
Not verified on real Windows ARM64 hardware. The Windows behaviour is covered by monkeypatching sysconfig.get_platform and platform.machine, and by executing the loader source with those values patched. A run on a Windows ARM64 machine with an x64 interpreter would be the definitive check: python -c "import mssql_python" should print nothing.

Possible follow ups (not in this PR)

The fallback still loads module_files[0] when nothing matches exactly. Raising instead of guessing would be stricter, but it changes behaviour for anyone relying on the fallback today, so it is left for a separate decision.
The 32 bit naming was inconsistent on main: CMakeLists.txt and build.bat name the x86 binary with a win32 token, while the loader normalized win32 to x86 and looked for a file the build never produces. The second commit aligns the loader with the build (x86 becomes win32, the same way x64 becomes amd64) and the 32 bit test case expects the win32 token. No x86 wheels are published today, so shipped packages are unaffected. The fallback notice also gets stacklevel=2 so it points at the import site.

The loader in mssql_python/ddbc_bindings.py derived the architecture token of the compiled module from platform.machine(). On Windows that call reports the host CPU, not the architecture the interpreter was built for. An x64 CPython running on a Windows ARM64 machine, which is what the default python.org installer gives you, therefore looked for the arm64 .pyd while the installed win_amd64 wheel only ships the amd64 .pyd. The lookup missed on every import, a warning was printed to stdout, and the module was picked by directory order through the fallback branch. On Windows the architecture now comes from sysconfig.get_platform(), which is derived from the interpreter build and matches the wheel tag. Its platform string is reduced to the amd64, arm64 or win32 token and fed through the existing normalize_architecture() mapping, so the resulting file names are unchanged for native x64 and ARM64 installs. macOS and Linux keep using platform.machine() as before. The module search moved into find_module_path() and the fallback notice is now a RuntimeWarning instead of a print() call, so scripts whose stdout is parsed by other tools no longer receive a stray warning line. The fallback to the first matching file is kept as it was. tests/test_000_dependencies.py built its expected file name from platform.machine() as well, which made test_python_extension_exists fail on the same configuration. It now uses the loader's helper. New tests cover the x64 interpreter on an ARM64 host, the native ARM64 and x64 interpreters, the 32 bit interpreter, the non Windows passthrough, and the exact match, fallback warning and no match branches of find_module_path(). Refs microsoft#726

Azure Pipelines:
There may be pipelines that require an authorized user to comment /azp run to run.

Pull request overview

This PR fixes Windows native-extension selection in mssql_python/ddbc_bindings.py by deriving architecture from the running interpreter (via sysconfig.get_platform()) instead of the host CPU (platform.machine()), preventing unnecessary fallback loading (and stdout noise) when x64 Python runs on Windows ARM64.

Changes:

Add loader helpers (get_interpreter_architecture, get_module_architecture, find_module_path) and move module file resolution into find_module_path().
Replace the stdout print() fallback notice with a RuntimeWarning via warnings.warn().
Update tests/test_000_dependencies.py to align expected extension naming with the loader and add targeted tests for Windows interpreter-vs-host architecture behavior.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File	Description
mssql_python/ddbc_bindings.py	Uses interpreter-derived Windows architecture and refactors module discovery into find_module_path() with warning-based fallback reporting.
tests/test_000_dependencies.py	Aligns dependency expectations with the loader and adds regression tests covering Windows ARM64 host + x64 interpreter and other architecture cases.
CHANGELOG.md	Documents the GH-726 loader fix and warning behavior change under Unreleased/Fixed.

Suppressed comments (1)

mssql_python/ddbc_bindings.py:164

The fallback warning is emitted from inside the loader, so without a stacklevel it will point at ddbc_bindings.py rather than the caller’s import site. Setting stacklevel=2 makes the warning actionable for users (it will report the line that imported/triggered the loader).

    warnings.warn(
        f"Using fallback module file {module_files[0]} instead of {expected_module}",
        RuntimeWarning,
    )

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

…ension The build names the 32 bit Windows artifact with the win32 token (pybind/build.bat and pybind/CMakeLists.txt both map x86 to win32), while the loader normalized the interpreter architecture to x86 and so looked for a file that is never produced. get_module_architecture now renames x86 to win32 the same way it already renames x64 to amd64, and the test for a 32 bit interpreter expects the token the build actually writes. The fallback notice is emitted with stacklevel 2 so the warning points at the import site rather than at the loader itself. Raised in review.

/azp run

Azure Pipelines:
Successfully started running 1 pipeline(s).

Code Coverage Report

Diff coverage	Overall coverage	Lines covered
100%	82%	7783 of 9455

Files needing attention

mssql_python.pybind.logger_bridge.cpp: 59.2%
mssql_python.pybind.ddbc_bindings.h: 61.5%
mssql_python.pybind.logger_bridge.hpp: 70.8%
mssql_python.pybind.ddbc_bindings.cpp: 75.5%
mssql_python.__init__.py: 77.6%
mssql_python.row.py: 77.6%
mssql_python.pybind.connection.connection_pool.cpp: 81.4%
mssql_python.pybind.connection.connection.cpp: 84.3%
mssql_python.logging.py: 85.5%
mssql_python.connection.py: 85.9%

View Azure DevOps build

Reviewed the PR for correctness, security, reliability, performance, test coverage, repository conventions, and applicable architecture and design specifications. No actionable issues were identified. The implementation is consistent with repository standards and the applicable approved design requirements.

Notes (non-blocking, no change required):

The fallback path in find_module_path() still returns module_files[0] when no exact-arch binary exists, so it can hand back a wrong-architecture .pyd. This is pre-existing behavior intentionally preserved here and noted as a follow-up - flagging only for awareness.
The Windows ARM64 / x64-interpreter path is covered by monkeypatched tests but not verified on real ARM64 hardware; a one-time python -c "import mssql_python" on that config would be the definitive check.

The fallback accepted any ddbc_bindings file with the right extension, so a binary built for another CPython version could be handed to importlib, which fails there with a confusing DLL or symbol error instead of a clean ImportError. The cpXY tags are version specific, so only files carrying this interpreter's tag are considered now, sorted so the pick is deterministic. A different architecture stays eligible, which keeps the case microsoftGH-726 cares about working.

…e' into fix/loader-interpreter-architecture

You are right, and it bit me while verifying: this Mac has only a cp314 build, and on a cp310 interpreter the old fallback handed it over and import died inside dlopen with a missing symbol, exactly the confusing failure you describe. The fallback now only considers files carrying this interpreter's version tag, sorted so the pick is deterministic, while a different architecture stays eligible so the GH-726 case keeps working.

Took your test as suggested, plus one pinning the deterministic pick. The old fallback test asserted that a cp39 file satisfied a cp310 request, so it now uses a same version different architecture pair instead. Both new tests fail on the previous commit; the file is 35 passed with the change.

Corrections look good to me! Approving the PR

Thanks Jahnvi Thakkar (@jahnvi480)! The Python Linting failure was black asking for the fallback condition on a single line since it fits within the line length. Pushed the reformat in aa85a27, no logic changes.

/azp run

Azure Pipelines:
Successfully started running 1 pipeline(s).

Thanks Jahnvi Thakkar (Jahnvi Thakkar (@jahnvi480))! The Python Linting failure was black asking for the fallback condition on a single line since it fits within the line length. Pushed the reformat in aa85a27, no logic changes.

Yes

/azp run

Azure Pipelines:
Successfully started running 1 pipeline(s).

Copilot AI lite review requested due to automatic review settings August 22, 2026 07:02

Copilot started reviewing on behalf of om singhal (Om-singhaI) August 22, 2026 07:02 View session

Copilot AI reviewed Aug 22, 2026

View reviewed changes

Comment thread mssql_python/ddbc_bindings.py Outdated

Comment thread tests/test_000_dependencies.py Outdated

Merge branch 'main' into fix/loader-interpreter-architecture

2005f38

Jahnvi Thakkar (jahnvi480) requested changes Aug 26, 2026

View reviewed changes

Comment thread mssql_python/ddbc_bindings.py Outdated

Comment thread tests/test_000_dependencies.py

Sumit Sarabhai (sumitmsft) previously approved these changes Aug 26, 2026

View reviewed changes

om singhal (Om-singhaI) added 2 commits August 26, 2026 08:30

Merge remote-tracking branch 'fork/fix/loader-interpreter-architectur…

153e8a7

…e' into fix/loader-interpreter-architecture

om singhal (Om-singhaI) dismissed Sumit Sarabhai (sumitmsft)’s stale review via 153e8a7 August 26, 2026 12:36

Jahnvi Thakkar (jahnvi480) previously approved these changes Aug 27, 2026

View reviewed changes

Apply black formatting to the fallback filter

aa85a27

om singhal (Om-singhaI) dismissed Jahnvi Thakkar (jahnvi480)’s stale review via aa85a27 August 27, 2026 03:39

Jahnvi Thakkar (jahnvi480) added 2 commits August 27, 2026 09:45

Merge branch 'main' into fix/loader-interpreter-architecture

0eedf14

Merge branch 'main' into fix/loader-interpreter-architecture

fcc2c5f

Jahnvi Thakkar (jahnvi480) approved these changes Aug 27, 2026

View reviewed changes

Jahnvi Thakkar (jahnvi480) requested a review from Sumit Sarabhai (sumitmsft) August 27, 2026 05:21

gargsaumya approved these changes Aug 27, 2026

View reviewed changes

Subrata (subrata-ms) approved these changes Aug 27, 2026

View reviewed changes

Sumit Sarabhai (sumitmsft) approved these changes Aug 27, 2026

View reviewed changes

Jahnvi Thakkar (jahnvi480) merged commit 53600d4 into microsoft:main Aug 27, 2026
26 of 27 checks passed

Subrata (subrata-ms) mentioned this pull request Aug 27, 2026

RELEASE:1.14.0 #731

Open

FIX: select the native extension by interpreter architecture on Windows by Om-singhaI · Pull Request #727 · microsoft/mssql-python · GitHub

Uh oh!

FIX: select the native extension by interpreter architecture on Windows - #727

Conversation

om singhal (Om-singhaI) commented Aug 22, 2026 • edited by jahnvi480 Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Work Item / Issue Reference

Summary

Uh oh!

azure-pipelines Bot commented Aug 22, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

David Levy (dlevy-msft-sql) commented Aug 22, 2026

Uh oh!

azure-pipelines Bot commented Aug 22, 2026

Uh oh!

github-actions Bot commented Aug 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Code Coverage Report

Files needing attention

Uh oh!

Uh oh!

Uh oh!

Sumit Sarabhai (sumitmsft) left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

om singhal (Om-singhaI) commented Aug 26, 2026

Uh oh!

Jahnvi Thakkar (jahnvi480) commented Aug 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

om singhal (Om-singhaI) commented Aug 27, 2026

Uh oh!

Jahnvi Thakkar (jahnvi480) commented Aug 27, 2026

Uh oh!

azure-pipelines Bot commented Aug 27, 2026

Uh oh!

Jahnvi Thakkar (jahnvi480) commented Aug 27, 2026

Uh oh!

Jahnvi Thakkar (jahnvi480) commented Aug 27, 2026

Uh oh!

azure-pipelines Bot commented Aug 27, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

om singhal (Om-singhaI) commented Aug 22, 2026 •
edited by jahnvi480
Loading

github-actions Bot commented Aug 22, 2026 •
edited
Loading

Sumit Sarabhai (sumitmsft) left a comment •
edited
Loading

Jahnvi Thakkar (jahnvi480) commented Aug 27, 2026 •
edited
Loading