Skip to content

Commit f930199

Browse files
davidhewittdavidhewitt
authored
docs: additional detail in migration guide for 0.29 (#6123)
* docs: additional detail in migration guide for 0.29 * fmt
1 parent 91ab0d1 commit f930199

1 file changed

Lines changed: 46 additions & 6 deletions

File tree

‎guide/src/migration.md‎

Lines changed: 46 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,9 @@ For a detailed list of all changes, see the [CHANGELOG](changelog.md).
77

88
### Removed implementations of `From<str::Utf8Error>`, `From<string::FromUtf16Error>`, and `From<char::DecodeUtf16Error>` for `PyErr`
99

10+
<details open>
11+
<summary><small>Click to expand</small></summary>
12+
1013
Previously the implementations of `From<string::FromUtf8Error>`, `From<ffi::IntoStringError>`, `From<str::Utf8Error>`, `From<string::FromUtf16Error>`, and `From<char::DecodeUtf16Error>` failed to construct the correct Python exception class, as reported in <https://github.com/PyO3/pyo3/issues/5651>.
1114
The implementations for `string::FromUtf8Error` and `ffi::IntoStringError` were fixed in this release.
1215

@@ -36,8 +39,13 @@ fn bytes_to_str<'a>(py: Python<'_>, bytes: &'a [u8]) -> PyResult<&'a str> {
3639
For `string::FromUtf16Error` and `char::DecodeUtf16Error` the Rust error types do not contain any of the information required to construct a `UnicodeDecodeError`.
3740
To raise a Python `UnicodeDecodeError` a new error should be manually constructed by calling `PyUnicodeDecodeError::new_err(...)`.
3841

42+
</details>
43+
3944
### `pyo3_build_config` APIs now require a direct dependency on `pyo3` or `pyo3-ffi`
4045

46+
<details open>
47+
<summary><small>Click to expand</small></summary>
48+
4149
Prior to PyO3 0.29, `pyo3-build-config` would inline part of the build configuration into the crate in its own build script.
4250
This worked for simple builds but not for cross-compiling; `pyo3-ffi`'s build script would need to re-implement a lot of the same machinery to correctly configure the build for cross-compilation.
4351
There were also edge cases where `pyo3-build-config` would use this inlined configuration incorrectly and misconfigure the build - e.g. [when cross compiling with `buck` or `bazel` build systems](https://github.com/PyO3/pyo3/issues/4579).
@@ -93,11 +101,43 @@ impl Sub {
93101
}
94102
```
95103

104+
</details>
105+
106+
### Minor API breaks for soundness reasons
107+
108+
<details open>
109+
<summary><small>Click to expand</small></summary>
110+
111+
Recent development in LLM-assisted security analysis has enhanced the ability to detect flaws, both for maintainers and attackers.
112+
Such security analysis of PyO3 flagged some APIs with edge cases that could lead to unsoundness.
113+
The PyO3 maintainers took the decision to make small breaking changes to eliminate these edge cases.
114+
Users should not be affected by these changes unless they were inadvertently relying on unsound behavior.
115+
116+
The changes were:
117+
118+
- `PyCapsule::new_with_destructor` now requires the destructor to be `'static` to prevent possible use-after-free issues.
119+
- `PyCFunction::new_closure` now requires the closure to be `Sync` to prevent possible thread unsafety. ⚠️ A security advisory will be issued for this, as the thread unsafety could easily go undetected in testing and lead to exploitable issues downstream in production. ⚠️
120+
- `PyClassGuardMap` has been split into `PyClassGuardMap` and `PyClassGuardMapMut` to prevent possible lifetime variance issues.
121+
- `PyClassGuardMut::as_super` now returns `PyClassGuardMutSuper` instead of `&mut PyClassGuardMut<SuperType>` to prevent possible type confusion issues.
122+
123+
</details>
124+
125+
### PyO3 now uses `raw-dylib` linking on Windows
126+
127+
<details open>
128+
<summary><small>Click to expand</small></summary>
129+
130+
The `raw-dylib` linking mode allows PyO3 to no longer need to have link libraries present when building for Windows targets.
131+
This removes the need for the `generate-import-lib` feature (which is now a no-op) and generally simplifies building for Windows.
132+
This is not expected to have negative impact on users, please report if there are issues.
133+
134+
</details>
135+
96136
## from 0.27.* to 0.28
97137

98138
### Default to supporting free-threaded Python
99139

100-
<details open>
140+
<details>
101141
<summary><small>Click to expand</small></summary>
102142

103143
When PyO3 0.23 added support for free-threaded Python, this was as an opt-in feature for modules by annotating with `#[pymodule(gil_used = false)]`.
@@ -108,7 +148,7 @@ Modules now automatically allow use on free-threaded Python, unless they directl
108148

109149
### Deprecation of automatic `FromPyObject` for `#[pyclass]` types which implement `Clone`
110150

111-
<details open>
151+
<details>
112152
<summary><small>Click to expand</small></summary>
113153

114154
`#[pyclass]` types which implement `Clone` used to also implement `FromPyObject` automatically.
@@ -151,7 +191,7 @@ The `#[pyclass(skip_from_py_object)]` option will eventually be deprecated and r
151191

152192
### Deprecation of `Py<T>` constructors from raw pointer
153193

154-
<details open>
194+
<details>
155195
<summary><small>Click to expand</small></summary>
156196

157197
The constructors `Py::from_owned_ptr`, `Py::from_owned_ptr_or_opt`, and `Py::from_owned_ptr_or_err` (and similar "borrowed" variants) perform an unchecked cast to the `Py<T>` target type `T`.
@@ -193,7 +233,7 @@ let _: Bound<'_, PyNone> = unsafe { Bound::from_owned_ptr(py, raw_ptr).cast_into
193233

194234
### Removal of `From<Bound<'_, T>` and `From<Py<T>> for PyClassInitializer<T>`
195235

196-
<details open>
236+
<details>
197237
<summary><small>Click to expand</small></summary>
198238

199239
As part of refactoring the initialization code these impls were removed and its functionality was moved into the generated code for `#[new]`.
@@ -227,7 +267,7 @@ let obj_2 = existing_bound.clone();
227267

228268
### Untyped buffer API moved to PyUntypedBuffer
229269

230-
<details open>
270+
<details>
231271
<summary><small>Click to expand</small></summary>
232272

233273
`PyBuffer<T>` now is a typed wrapper around `PyUntypedBuffer`.
@@ -238,7 +278,7 @@ Users may need to update references to the moved functions.
238278

239279
### Internal change to use multi-phase initialization
240280

241-
<details open>
281+
<details>
242282
<summary><small>Click to expand</small></summary>
243283

244284
[PEP 489](https://peps.python.org/pep-0489/) introduced "multi-phase initialization" for extension modules which provides ways to allocate and clean up per-module state.

0 commit comments

Comments
 (0)