Improved documentation

CHANGELOG.md

@@ -5,6 +5,14 @@ PyO3 versions, please see the [migration guide](https://pyo3.rs/master/migration
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+### Added
+- Add support for building for CPython limited API. This required a few minor changes to runtime behaviour of of pyo3 `#[pyclass]` types. See the migration guide for full details. [#1152](https://github.com/PyO3/pyo3/pull/1152)
+
+### Changed
+- Change return type `PyType::name()` from `Cow<str>` to `PyResult<&str>`. [#1152](https://github.com/PyO3/pyo3/pull/1152)
+- `#[pyclass(subclass)]` is now required for subclassing from Rust (was previously just required for subclassing from Python). [#1152](https://github.com/PyO3/pyo3/pull/1152)
+
 ## [Unreleased]
 ### Added
 - Add support for keyword-only arguments without default values in `#[pyfunction]`. [#1209](https://github.com/PyO3/pyo3/pull/1209)

guide/src/migration.md

@@ -3,6 +3,18 @@
 This guide can help you upgrade code through breaking changes from one PyO3 version to the next.
 For a detailed list of all changes, see the [CHANGELOG](changelog.md).
 
+## from 0.12.* to 0.13
+
+### Runtime changes to support the CPython limited API
+
+In PyO3 `0.13` support was added for compiling against the CPython limited API. This had a number of implications for _all_ PyO3 users, described here.
+
+The largest of these is that all types created from PyO3 are what CPython calls "heap" types. The specific implications of this are:
+
+- If you wish to subclass one of these types _from Rust_ you must mark it `#[pyclass(subclass)]`, as you would if you wished to allow subclassing it from Python code.
+- Type objects are now mutable - Python code can set attributes on them.
+- `__module__` on types without `#[pyclass(module="mymodule")]` no longer returns `builtins`, it now raises `AttributeError`.
+
 ## from 0.11.* to 0.12
 
 ### `PyErr` has been reworked

src/marshal.rs

@@ -1,4 +1,6 @@
 #![cfg(not(Py_LIMITED_API))]
+//! Support for the Python `marshal` format. Not supported in limited API
+//! builds.
 
 use crate::ffi;
 use crate::types::{PyAny, PyBytes};

src/pyclass.rs

@@ -258,7 +258,7 @@ fn tp_init_additional<T: PyClass>(type_object: *mut ffi::PyTypeObject) {
     // except for that it does and we have tests.
 
     // Running this causes PyPy to segfault.
-    #[cfg(not(PyPy))]
+    #[cfg(all(not(PyPy), not(Py_3_10)))]
     if T::DESCRIPTION != "\0" {
         unsafe {
             // Until CPython 3.10, tp_doc was treated specially for heap-types,