feat: allow direct endpoint connection strategy

[jselig-rigetti]

Closes #572

I think I may have my python env wrong (using uv venv) but this is what I get from makers generate-stubs

Could not find platform independent libraries <prefix>
Could not find platform dependent libraries <exec_prefix>
Python path configuration:
  PYTHONHOME = (not set)
  PYTHONPATH = (not set)
  program name = 'python3'
  isolated = 0
  environment = 1
  user site = 1
  safe_path = 0
  import site = 1
  is in build tree = 0
  stdlib dir = '/install/lib/python3.12'
  sys._base_executable = '[...]/target/debug/stub_gen'
  sys.base_prefix = '/install'
  sys.base_exec_prefix = '/install'
  sys.platlibdir = 'lib'
  sys.executable = '[...]/target/debug/stub_gen'
  sys.prefix = '/install'
  sys.exec_prefix = '/install'
  sys.path = [
    '/install/lib/python312.zip',
    '/install/lib/python3.12',
    '/install/lib/python3.12/lib-dynload',
  ]
Fatal Python error: init_fs_encoding: failed to get the Python codec of the filesystem encoding
Python runtime state: core initialized
ModuleNotFoundError: No module named 'encodings'

Current thread 0x0000000208193080 (most recent call first):
  <no Python frame>
Error while executing command, exit code: 1

[github-actions]

PR Preview Action v1.8.1
🚀 View preview at https://rigetti.github.io/qcs-sdk-rust/pr-preview/pr-573/
Built to branch qcs-sdk-python-docs at 2026-02-27 20:00 UTC. Preview will be ready when the GitHub Pages deployment is complete.

[asaites]

I think I may have my python env wrong (using uv venv) but this is what I get from makers generate-stubs

Although I'm not exactly certain what's going wrong for you, I suspect you'll be able to resolve it by deleting and recreating your virtualenv. Assuming you have Python 3.10+ on the path, you can do that by running this from the project's crates/lib/ directory:

python3 -m venv --clear --upgrade-deps .venv && source .venv/bin/activate

You can run PYO3_PRINT_CONFIG=1 makers generate-stubs to show you which Python version its picking up. For what it's worth, that specific command shouldn't require a virtualenv, but running it while one is active should determine the config PyO3 uses without manually setting env vars or providing a config file. The resolved lib_dir, executable, and python_framework_prefix should be pointing to the same ones used by the virtual environment.

The tasks that run Python use poetry, which is configured to use that directory-local .venv environment. The install-python-deps task will create that environment for you, provided you have poetry on your path.

The other tasks related to Python bindings typically depend on the generate-stubs task, so if that task is failing, so will they. The reason the stub generation task itself doesn't bother running from the local .venv is that you must have a working Python available on the path in order to run poetry commands (or indeed to create a virtualenv), and the task itself isn't manipulating that environment. Put another way, any Python installation that works for running those other tasks should be enough for that task to succeed.

[asaites]

Overall, this looks good to me. It needs the Python stubs regenerated, and I understand you had some trouble with that. I also had some suggestions about documentation and naming, but they're not functional changes. With the stubs updated, I'm happy for it to merge.

[jselig-rigetti]

Ah @asaites thanks, got it working with the following:

PYTHONHOME=$(uv python dir)/cpython-3.12.12-macos-aarch64-none makers generate-stubs

[jselig-rigetti]

I guess this isn't being changed on knope release

[asaites]

Ah, yeah, I hadn't though about that. The actual value of __version__ is determined from CARGO_PKG_VERSION when the extension module is built, so it technically only matches the stub value if the stubs are regenerated after the package version is set. Rather than having knope regenerate the stubs, it's probably more sensible to just elide the specific value itself. That requires a little bit of type trickery, so I'll open a separate issue/PR for it, if that's alright with you.

[asaites]

• Issue: The __version__ value in type stubs should elide its value #574
• PR: fix: elide version value from python stub files #575

[windsurf-bot]

Other comments (2)

• crates/lib/src/qpu/api/python.rs (738-738) There's an inconsistency in the documentation. The parameter description mentions `ConnectionStrategy.endpoint_address()` but based on other documentation in the file, it should be `ConnectionStrategy.direct_endpoint_address()`.
• crates/lib/src/qpu/api/mod.rs (572-577) The `EndpointAddress` strategy doesn't require a quantum processor ID for connection, but it still needs one when using the target methods (`get_job_target`, `get_results_target`, `get_cancel_target`). Consider adding a validation check in these methods to ensure a quantum processor ID is provided when needed.

💡 To request another review, post a new comment with "/windsurf-review".

[asaites]

I'm very surprised this would be the case. I don't have that variable set in my environment, but since the resolution is managed by PyO3, there must be something about our environments that are different. I'm glad you found a resolution that worked for you, though.

[asaites]

LGTM