Dwave-cloud-client

Upgrade Notes

- `dwave.cloud.utils` module has been split into the following submodules: `dwave.cloud.utils.cli`, `dwave.cloud.utils.coders`, `dwave.cloud.utils.decorators`, `dwave.cloud.utils.dist`, `dwave.cloud.utils.exception`, `dwave.cloud.utils.http`, `dwave.cloud.utils.logging`, `dwave.cloud.utils.qubo`, and `dwave.cloud.utils.time`.

First reason for doing this was code clean-up (including adding type annotations), but a more important reason is that this will enable import time optimization in the future. And that's why we break backwards compatibility by not importing everything back into the top-level utils namespace.

The utils module is considered Ocean-internal as is, so this move shouldn't affect user's code.

<!-- -->

- Positional arguments in `dwave.cloud.Client` constructor, deprecated in 0.10.0, are removed in 0.12.0. Use keyword arguments instead.

<!-- -->

- Alias keys `samples` and `occurrences` (for `solutions` and `num_occurrences`) in the results dict of `dwave.cloud.computation.Future.result()`, deprecated in 0.8.0, are now finally removed in 0.12.0. We'll try to keep the result dict as close to raw data returned by SAPI as possible. Postprocessed data is instead available via `dwave.cloud.computation.Future` properties.

New Features

- Add support for `binary-ref` answer encoding format, where answer data is not immediately present in the answer, but on an URI referenced in the answer response.

<!-- -->

- Add `dwave.cloud.computation.Future.answer_data` property to hold the answer data of a resolved future. A call to `.answer_data` will block until computation future is resolved.

<!-- -->

- Add `dwave.cloud.api.models.UnstructuredProblemAnswerBinaryRef` model, a subclass of `ProblemAnswer` for `binary-ref` answers, and a method for downloading answer data (resolving binary-ref), `dwave.cloud.api.resources.Problems.get_answer_data`.

<!-- -->

- Add support for nonlinear unstructured solvers with `dwave.cloud.solver.NLSolver`.

<!-- -->

- Add request/response logging to `AuthFlow`/`OAuth2Session`.

<!-- -->

- Add basic support for structured logs (JSON output).

<!-- -->

- Enable log format control with `DWAVE_LOG_FORMAT` env variable (set to `"json"` for structured output.

Bug Fixes

- Fix a possible race condition when multiple threads try to resolve remote computation results. A special case of this occurs on binary answer download from a reference link. See [\624](https://github.com/dwavesystems/dwave-cloud-client/issues/624).

<!-- -->

- Log failing request/response details in the low-level API client.

<!-- -->

- Suppress logging output from the cloud-client by default (as recommended for libraries).

<!-- -->

- Format log record date/time according to ISO 8601.

New Features

- Add support for `binary-ref` answer encoding format, where answer data is not immediately present in the answer, but on an URI referenced in the answer response.

<!-- -->

- Add `dwave.cloud.computation.Future.answer_data` property to hold the answer data of a resolved future. A call to `.answer_data` will block until computation future is resolved.

<!-- -->

- Add `dwave.cloud.api.models.UnstructuredProblemAnswerBinaryRef` model, a subclass of `ProblemAnswer` for `binary-ref` answers, and a method for downloading answer data (resolving binary-ref), `dwave.cloud.api.resources.Problems.get_answer_data`.

<!-- -->

- Add support for nonlinear unstructured solvers with `dwave.cloud.solver.NLSolver`.

<!-- -->

- Add request/response logging to `AuthFlow`/`OAuth2Session`.

<!-- -->

- Add basic support for structured logs (JSON output).

<!-- -->

- Enable log format control with `DWAVE_LOG_FORMAT` env variable (set to `"json"` for structured output.

Bug Fixes

- Fix a possible race condition when multiple threads try to resolve remote computation results. A special case of this occurs on binary answer download from a reference link. See [\624](https://github.com/dwavesystems/dwave-cloud-client/issues/624).

<!-- -->

- Log failing request/response details in the low-level API client.

<!-- -->

- Suppress logging output from the cloud-client by default (as recommended for libraries).

<!-- -->

- Format log record date/time according to ISO 8601.

New Features

- Add `revoke_token` method to `dwave.cloud.auth.flow.AuthFlow` to enable revocation of OAuth 2.0 refresh/access tokens. See [\600](https://github.com/dwavesystems/dwave-cloud-client/issues/600).

- Add `dwave auth revoke` CLI command to enable revocation of OAuth 2.0 refresh/access tokens from command line. See [\600](https://github.com/dwavesystems/dwave-cloud-client/issues/600).

Bug Fixes

- Set correct lower bounds for requests/urllib3, and preemptively set upper bounds on other dependencies to prevent future breaks. See [\612](https://github.com/dwavesystems/dwave-cloud-client/pull/612).

Bug Fixes

- Use fixed authorization success URL, without any authorization query parameters appended (to minimize exposure), as they are not needed on the authorization server's success page.

<!-- -->

- Improve CSRF protection on localhost redirect URI during authorization code exchange. Previously, `state` was verified only if supplied. Now it's mandatory. Please note this is an additional CSRF protection on top of the PKCE, just in case PKCE is not supported (or properly implemented) server-side.

<!-- -->

- Fix PKCE support in `dwave.cloud.auth.flow.AuthFlow` by properly including `code_verifier` in fetch token (code exchange) requests. See [\605](https://github.com/dwavesystems/dwave-cloud-client/issues/605).

<!-- -->

- Remove circular references in `dwave.cloud.computation.Future` to enable easier garbage collection and lower memory footprint. See [\601](https://github.com/dwavesystems/dwave-cloud-client/issues/601).

<!-- -->

- Use a consistent `User-Agent` value for all API and non-API requests made by `Client`, `api.Client` and `auth.flow` client.

<!-- -->

- Speed-up `User-Agent` string construction significantly (10ms to 5us).

New Features

- Add Python 3.12 support.

- Add `dwave.cloud.utils.get_distribution` as a replacement for `pkg_resources.get_distribution` unavailable in Python 3.12.

New Features

- Add optional Leap authorization step to `dwave setup` CLI. During setup, we now install optional contributed packages, authorize Ocean to access Leap (`--auth` and `--oob` flags), and finally create the configuration file, optionally retrieving SAPI token from Leap API (if authorized) for the currently active Leap project, or project specified with `--project` option. See [\591](https://github.com/dwavesystems/dwave-cloud-client/issues/591).

<!-- -->

- Add `--skip-valid` option to `dwave auth login` CLI. When used, authorization flow will be skipped if Leap access token is valid or if it can be refreshed.

<!-- -->

- Prefer QPU solvers in `dwave ping`, unless overridden by user/config. See [\592](https://github.com/dwavesystems/dwave-cloud-client/issues/592)

<!-- -->

- Redirect user back to a Leap info page when auth redirect flow successfully completes. Similarly, redirect user to a Leap error page in case of an auth error.