docs: Improves `IntoPyObject` documentation in the guides by Cheukting · Pull Request #5835 · PyO3/pyo3

Cheukting · 2026-02-22T00:46:11Z

closes #5709

…tomization.

…tructs and tuples.

… and `#[derive(IntoPyObjectRef)]`.

…readability and consistency.

…ation.

Icxolu

Thank you for working on this! I spotted a few things and left comments below.

guide/src/conversions/traits.md

Icxolu · 2026-02-22T22:27:24Z

guide/src/conversions/traits.md

+You can also use `#[pyo3(from_item_all)]` on a struct to convert every field to be used with `get_item` method.
+In this case, you don't need to use `#[pyo3(item)]` on each field.


from_item_all has no functionality for IntoPyObject since it exclusively uses set_item. It is just accepted for compatibility with FromPyObject. (Same is true for for other attributes as well, for example attribute or default)

Icxolu · 2026-02-22T22:28:59Z

guide/src/conversions/traits.md

 For `enum`s each variant is converted according to the rules for `struct`s above.

-```rust,no_run
+```rust


It only makes sense to run these if there is main which does something, otherwise it is better to leave these as no_run for a faster test suite.

Icxolu · 2026-02-22T22:31:44Z

guide/src/conversions/traits.md

+- `pyo3(default)`, `pyo3(default = ...)`
+  - if the argument is set, uses the given default value.
+  - in this case, the argument must be a Rust expression returning a value of the desired Rust type.
+  - if the argument is not set, [`Default::default`](https://doc.rust-lang.org/std/default/trait.Default.html#tymethod.default) is used.
+  - note that the default value is only used if the field is not set.
+    If the field is set and the conversion function from Rust to Python fails, an exception is raised and the default value is not used.
+  - this attribute is only supported on named fields.
+


This one has no effect for IntoPyObject and we should not document it.

Icxolu · 2026-02-22T22:32:34Z

guide/src/conversions/traits.md

+
 #### `#[derive(IntoPyObject)]`/`#[derive(IntoPyObjectRef)]` Field Attributes

+- `pyo3(item)`, `pyo3(item("key"))`


pyo3(item) is actually the default and only pyo3(item("key")) has the effect to use a different key

…er field attributes in `IntoPyObject` traits.

Cheukting · 2026-02-23T18:25:40Z

It is updated considering all your feedback and suggestions @Icxolu please feel free to check again

…r clarity

Icxolu · 2026-02-24T18:16:06Z

guide/src/conversions/traits.md

  - fields with an explicit renaming via `attribute(...)`/`item(...)` are not affected
+- `#[pyo3(from_item_all)]`
+  - extract every field with `get_item` method.
+  - can't use `#[pyo3(attribute)]` or barely use `#[pyo3(item)]` on any field after.


not quite sure what you mean here

Icxolu · 2026-02-24T18:21:31Z

guide/src/conversions/traits.md

+struct RustyStruct {
+    #[pyo3(item("key"))]
+    string_in_mapping: String,
+    #[pyo3(attribute("name"))] // no effect on this field


Given that this has no effect here, I would not put it in an example. I think this is just confusing to people. What I think we can do is to write a sentence somewhere that FromPyObject and IntoPyObject for convenience (technical) reasons accept each other arguments, but that not all of them are supported by both of them equally, then linking to the sections with the list of supported attributes of each.

Icxolu · 2026-02-24T18:22:38Z

guide/src/conversions/traits.md

+
+- `pyo3(transparent)`
+  - convert the field directly to the object instead of `set_item()`
+  - Newtype structs and tuple-variants are treated as transparent per default.


Suggested change

- Newtype structs and tuple-variants are treated as transparent per default.

- Newtype tuple structs and tuple-variants are treated as transparent per default.

Icxolu · 2026-02-24T18:26:58Z

guide/src/conversions/traits.md

+- `#[pyo3(from_item_all)]`
+  - Added for avoid erroring when `FromPyObject` is dervived together
+  - It will be a no-op attribute for `#[derive(IntoPyObject)]`/`#[derive(IntoPyObjectRef)]`


As mentioned here, I think we should not list the ones that don't do anything, instead writing a more generic paragraph and maybe link to it from here. IMO this just clutters up the list without bringing too much valuable info to a user who is looking to customize IntoPyObject, but maybe other have different opinions here.

ngoldbaum · 2026-02-25T20:46:49Z

guide/src/conversions/traits.md

    ```

+- `pyo3(default)`, `pyo3(default = ...)`
+  - Added for avoid erroring when `FromPyObject` is dervived together


I'm not sure what this means. Together with what?

I think @Icxolu has explained that, it is common practice to derviced IntoPyObject and FromPyObject together and this option is available to avoid errors. I think it is obvious to people who are using this feature but I can add more explanation once we have decided on the format.

I think I was just having trouble with the grammar. Maybe instead:

"Used to avoid errors when deriving both FromPyObject and IntoPyObject"

ngoldbaum · 2026-02-25T20:48:50Z

guide/src/conversions/traits.md

  - Possible values are: "camelCase", "kebab-case", "lowercase", "PascalCase", "SCREAMING-KEBAB-CASE", "SCREAMING_SNAKE_CASE", "snake_case", "UPPERCASE".
  - fields with an explicit renaming via `attribute(...)`/`item(...)` are not affected
+- `#[pyo3(from_item_all)]`
+  - extract every field with `get_item` method.


Not sure what this means either.

There is an explanation above, this is just a list of organising them together in one place. Please read the paragraph above

davidhewitt · 2026-02-26T09:59:30Z

guide/src/conversions/traits.md

 ### `#[derive(FromPyObject)]` Container Attributes

 - `pyo3(transparent)`
  - extract the field directly from the object as `obj.extract()` instead of `get_item()` or


Observation: this is currently in a list. Some of these macros have the options documented as a table, e.g. https://pyo3.rs/v0.28.2/class.html#customizing-the-class

I think we're probably quite inconsistent across the documentation, maybe we should create a new issue to decide on preferred style (table or list) and convert them all?

I do like the table format better, we can tie the effect of the attribution for FromPyObject and IntoPyObject together. I can work on that this weekend if it looks better

Cheukting · 2026-02-26T21:06:38Z

In my opinion, we need a list or table to list out the behaviour of each option, including the no-op ones because:

The original issue was saying that they are not documented even though it is allowed
If not list out users will assume those not show are not allowed.

If a table is clearer and easier to explain I don't mind moving all items in the lists into tables. But I do believe they need to be explicitly documentated.

Icxolu · 2026-02-26T21:25:09Z

Hmm, the reason I don't think we should list them is that I would not consider these "public" API. You should not use the options if you only implementing IntoPyObject, these are FromPyObject specific options. We only have to accept them here for technical reasons. I would argue that these are basically #[doc(hidden)] options and thus should only be documented where we "officially" support them, which here is FromPyObject.

Alternatively, I think we could follow serde's example and just create list (or table) of all supported by both. They for example don't specify that deserialize_with is Deserialize only and Serialize does not care. Listing these unsupported options directly under the IntoPyObject heading just feels plain wrong to me.

Cheukting · 2026-03-01T17:55:04Z

Let's follow serde's example then, I also think it looks neater by not having two lists.

Cheukting added 8 commits February 21, 2026 16:38

Document advanced IntoPyObject field customization with examples.

14d1d19

Clarify get_item usage and update examples for field conversion cus…

5a0cde6

…tomization.

Add doc tests

0891f56

Simplify and clarify field conversion trait documentation.

b06044d

Add doc test for #[pyo3(transparent)] usage in IntoPyObject for s…

ef76c25

…tructs and tuples.

Document container and field attributes for #[derive(IntoPyObject)]…

88fe9f4

… and `#[derive(IntoPyObjectRef)]`.

Clarify and format documentation for #[pyo3] attributes, improving …

329cbe4

…readability and consistency.

Fix formatting for pyo3(default) in field conversion trait document…

e6030c1

…ation.

Cheukting changed the title ~~docs: Improves IntoPyObject documentation in the guides [WIP]~~ docs: Improves IntoPyObject documentation in the guides Feb 22, 2026

Icxolu requested changes Feb 22, 2026

View reviewed changes

Update and clarify documentation for #[pyo3(from_item_all)] and oth…

eb52512

…er field attributes in `IntoPyObject` traits.

Improve documentation formatting and add no_run to code examples fo…

6f57ad6

…r clarity

Cheukting force-pushed the doc-5709 branch from 98360a0 to 6f57ad6 Compare February 23, 2026 18:33

Cheukting added 2 commits February 23, 2026 18:45

one missing no_run

2af35cc

Fix doc test

fac1cc1

Icxolu reviewed Feb 24, 2026

View reviewed changes

ngoldbaum reviewed Feb 25, 2026

View reviewed changes

davidhewitt reviewed Feb 26, 2026

View reviewed changes

		You can also use `#[pyo3(from_item_all)]` on a struct to convert every field to be used with `get_item` method.
		In this case, you don't need to use `#[pyo3(item)]` on each field.


		#### `#[derive(IntoPyObject)]`/`#[derive(IntoPyObjectRef)]` Field Attributes

		- `pyo3(item)`, `pyo3(item("key"))`

	- Newtype structs and tuple-variants are treated as transparent per default.
	- Newtype tuple structs and tuple-variants are treated as transparent per default.

Conversation

Cheukting commented Feb 22, 2026

Uh oh!

Icxolu left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Cheukting commented Feb 23, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Cheukting Feb 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Cheukting commented Feb 26, 2026

Uh oh!

Icxolu commented Feb 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Cheukting commented Mar 1, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Cheukting Feb 26, 2026 •

edited

Loading

Icxolu commented Feb 26, 2026 •

edited

Loading