Skip to content

Commit 49c1d22

Browse files
davidhewittdavidhewitt
committed
docs: for #2234 
1 parent 5cc3ce9 commit 49c1d22

File tree

4 files changed

+51
-55
lines changed

4 files changed

+51
-55
lines changed

‎CHANGELOG.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
88

99
## [Unreleased]
1010

11+
### Changed
12+
13+
- Allow `#[pyo3(crate = "...", text_signature = "...")]` options to be used directly in `#[pyclass(crate = "...", text_signature = "...")]`. [#2234](https://github.com/PyO3/pyo3/pull/2234)
14+
1115
### Fixed
1216

1317
- Considered `PYTHONFRAMEWORK` when cross compiling in order that on macos cross compiling against a [Framework bundle](https://developer.apple.com/library/archive/documentation/MacOSX/Conceptual/BPFrameworks/Concepts/FrameworkAnatomy.html) is considered shared. [#2233](https://github.com/PyO3/pyo3/pull/2233)

‎guide/src/class.md

Lines changed: 12 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -195,22 +195,16 @@ Python::with_gil(|py|{
195195

196196
## Customizing the class
197197

198-
The `#[pyclass]` macro accepts the following parameters:
199-
200-
* `name="XXX"` - Set the class name shown in Python code. By default, the struct name is used as the class name.
201-
* `freelist=XXX` - The `freelist` parameter adds support of free allocation list to custom class.
202-
The performance improvement applies to types that are often created and deleted in a row,
203-
so that they can benefit from a freelist. `XXX` is a number of items for the free list.
204-
* `gc` - Classes with the `gc` parameter participate in Python garbage collection.
205-
If a custom class contains references to other Python objects that can be collected, the [`PyGCProtocol`]({{#PYO3_DOCS_URL}}/pyo3/class/gc/trait.PyGCProtocol.html) trait has to be implemented.
206-
* `weakref` - Adds support for Python weak references.
207-
* `extends=BaseType` - Use a custom base class. The base `BaseType` must implement `PyTypeInfo`. `enum` pyclasses can't use a custom base class.
208-
* `subclass` - Allows Python classes to inherit from this class. `enum` pyclasses can't be inherited from.
209-
* `dict` - Adds `__dict__` support, so that the instances of this type have a dictionary containing arbitrary instance variables.
210-
* `unsendable` - Making it safe to expose `!Send` structs to Python, where all object can be accessed
211-
by multiple threads. A class marked with `unsendable` panics when accessed by another thread.
212-
* `module="XXX"` - Set the name of the module the class will be shown as defined in. If not given, the class
213-
will be a virtual member of the `builtins` module.
198+
{{#include ../../pyo3-macros/docs/pyclass_parameters.md}}
199+
200+
[params-1]: {{#PYO3_DOCS_URL}}/pyo3/prelude/struct.PyAny.html
201+
[params-2]: https://en.wikipedia.org/wiki/Free_list
202+
[params-3]: https://doc.rust-lang.org/stable/std/marker/trait.Send.html
203+
[params-4]: https://doc.rust-lang.org/stable/std/rc/struct.Rc.html
204+
[params-5]: https://doc.rust-lang.org/stable/std/sync/struct.Rc.html
205+
[params-6]: https://docs.python.org/3/library/weakref.html
206+
207+
These parameters are covered in various sections of this guide.
214208

215209
### Return type
216210

@@ -716,16 +710,15 @@ num=-1
716710

717711
## Making class method signatures available to Python
718712

719-
The [`#[pyo3(text_signature = "...")]`](./function.md#text_signature) option for `#[pyfunction]` also works for classes and methods:
713+
The [`text_signature = "..."`](./function.md#text_signature) option for `#[pyfunction]` also works for classes and methods:
720714

721715
```rust
722716
# #![allow(dead_code)]
723717
use pyo3::prelude::*;
724718
use pyo3::types::PyType;
725719

726720
// it works even if the item is not documented:
727-
#[pyclass]
728-
#[pyo3(text_signature = "(c, d, /)")]
721+
#[pyclass(text_signature = "(c, d, /)")]
729722
struct MyClass {}
730723

731724
#[pymethods]

‎pyo3-macros/docs/pyclass_parameters.md

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
`#[pyclass]` can be used with the following parameters:
2+
3+
| Parameter | Description |
4+
| :- | :- |
5+
| <span style="white-space: pre">`crate = "some::path"`</span> | Path to import the `pyo3` crate, if it's not accessible at `::pyo3`. |
6+
| `dict` | Gives instances of this class an empty `__dict__` to store custom attributes. |
7+
| <span style="white-space: pre">`extends = BaseType`</span> | Use a custom baseclass. Defaults to [`PyAny`][params-1] |
8+
| <span style="white-space: pre">`freelist = N`</span> | Implements a [free list][params-2] of size N. This can improve performance for types that are often created and deleted in quick succession. Profile your code to see whether `freelist` is right for you. |
9+
| <span style="white-space: pre">`module = "module_name"`</span> | Python code will see the class as being defined in this module. Defaults to `builtins`. |
10+
| <span style="white-space: pre">`name = "python_name"`</span> | Sets the name that Python sees this class as. Defaults to the name of the Rust struct. |
11+
| <span style="white-space: pre">`text_signature = "(arg1, arg2, ...)"`</span> | Sets the text signature for the Python class' `__new__` method. |
12+
| `subclass` | Allows other Python classes and `#[pyclass]` to inherit from this class. Enums cannot be subclassed. |
13+
| `unsendable` | Required if your struct is not [`Send`][params-3]. Rather than using `unsendable`, consider implementing your struct in a threadsafe way by e.g. substituting [`Rc`][params-4] with [`Arc`][params-5]. By using `unsendable`, your class will panic when accessed by another thread.|
14+
| `weakref` | Allows this class to be [weakly referenceable][params-6]. |
15+
16+
All of these parameters can either be passed directly on the `#[pyclass(...)]` annotation, or as one or
17+
more accompanying `#[pyo3(...)]` annotations, e.g.:
18+
19+
```rust,ignore
20+
// Argument supplied directly to the `#[pyclass]` annotation.
21+
#[pyclass(name = "SomeName", subclass)]
22+
struct MyClass { }
23+
24+
// Argument supplied as a separate annotation.
25+
#[pyclass]
26+
#[pyo3(name = "SomeName", subclass)]
27+
struct MyClass { }
28+
```

‎pyo3-macros/src/lib.rs

Lines changed: 7 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -81,47 +81,18 @@ pub fn pyproto(_: TokenStream, input: TokenStream) -> TokenStream {
8181

8282
/// A proc macro used to expose Rust structs and fieldless enums as Python objects.
8383
///
84-
/// `#[pyclass]` can be used the following [parameters][2]:
85-
///
86-
/// | Parameter | Description |
87-
/// | :- | :- |
88-
/// | <span style="white-space: pre">`crate = "some::path"`</span> | Path to import the `pyo3` crate, if it's not accessible at `::pyo3`. |
89-
/// | `dict` | Gives instances of this class an empty `__dict__` to store custom attributes. |
90-
/// | <span style="white-space: pre">`extends = BaseType`</span> | Use a custom baseclass. Defaults to [`PyAny`][4] |
91-
/// | <span style="white-space: pre">`freelist = N`</span> | Implements a [free list][9] of size N. This can improve performance for types that are often created and deleted in quick succession. Profile your code to see whether `freelist` is right for you. |
92-
/// | <span style="white-space: pre">`module = "module_name"`</span> | Python code will see the class as being defined in this module. Defaults to `builtins`. |
93-
/// | <span style="white-space: pre">`name = "python_name"`</span> | Sets the name that Python sees this class as. Defaults to the name of the Rust struct. |
94-
/// | <span style="white-space: pre">`text_signature = "(arg1, arg2, ...)"`</span> | Sets the text signature for the Python class' `__new__` method. |
95-
/// | `subclass` | Allows other Python classes and `#[pyclass]` to inherit from this class. Enums cannot be subclassed. |
96-
/// | `unsendable` | Required if your struct is not [`Send`][3]. Rather than using `unsendable`, consider implementing your struct in a threadsafe way by e.g. substituting [`Rc`][7] with [`Arc`][8]. By using `unsendable`, your class will panic when accessed by another thread.|
97-
/// | `weakref` | Allows this class to be [weakly referenceable][6]. |
98-
///
99-
/// All of these parameters can either be passed directly on the `#[pyclass(...)]` annotation, or as one or
100-
/// more accompanying `#[pyo3(...)]` annotations, e.g.:
101-
///
102-
/// ```rust,ignore
103-
/// // Argument supplied directly to the `#[pyclass]` annotation.
104-
/// #[pyclass(name = "SomeName", subclass)]
105-
/// struct MyClass { }
106-
///
107-
/// // Argument supplied as a separate annotation.
108-
/// #[pyclass]
109-
/// #[pyo3(name = "SomeName", subclass)]
110-
/// struct MyClass { }
111-
/// ```
84+
#[cfg_attr(docsrs, cfg_attr(docsrs, doc = include_str!("../docs/pyclass_parameters.md")))]
11285
///
11386
/// For more on creating Python classes,
11487
/// see the [class section of the guide][1].
11588
///
11689
/// [1]: https://pyo3.rs/latest/class.html
117-
/// [2]: https://pyo3.rs/latest/class.html#customizing-the-class
118-
/// [3]: std::marker::Send
119-
/// [4]: ../prelude/struct.PyAny.html
120-
/// [5]: https://pyo3.rs/latest/class/protocols.html#garbage-collector-integration
121-
/// [6]: https://docs.python.org/3/library/weakref.html
122-
/// [7]: std::rc::Rc
123-
/// [8]: std::sync::Arc
124-
/// [9]: https://en.wikipedia.org/wiki/Free_list
90+
/// [params-1]: ../prelude/struct.PyAny.html
91+
/// [params-2]: https://en.wikipedia.org/wiki/Free_list
92+
/// [params-3]: std::marker::Send
93+
/// [params-4]: std::rc::Rc
94+
/// [params-5]: std::sync::Arc
95+
/// [params-6]: https://docs.python.org/3/library/weakref.html
12596
#[proc_macro_attribute]
12697
pub fn pyclass(attr: TokenStream, input: TokenStream) -> TokenStream {
12798
use syn::Item;

0 commit comments

Comments
 (0)