PyO3 / PyO3/pyo3

`#[pyclass]` trait ergonomics

Open
#4,207 9 comments 3 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Rust
Stars
16.2k
Forks
1k
Avg merge
2d 6h
Merged PRs (30d)
66

Description

Following up to #4202 and #4206 I wanted to write down something I've been thinking about for a while. It looks like we're moving ahead with accepting those options so I'll assume that at least the design choice to have these options is accepted.

In summary, I think there are at least five convenience options to add to #[pyclass] to automatically expose Python magic methods based on Rust trait implementations:

  • #[pyclass(eq)] for equality based off PartialEq - #4210
  • #[pyclass(ord)] for ordering operators based off PartialOrd - #4202
  • #[pyclass(hash)] for hash based off Hash - #4206
  • #[pyclass(str)] for __str__ based off Display. I think we could also have #[pyclass(str = "<format>")] to specify a format-args-compatible string concisely.
  • #[pyclass(repr)] for __repr__ based off Debug. Similarly to the above I think we could have #[pyclass(repr = "<format>")].

Based off the recent PRs I think the basic implementation of these is more or less agreed upon, possibly excluding the extra argument on the string formatting options.

As we proceed with / make progress on the above, I think there are two further steps which make sense to explore:

  1. Simple enums currently generate eq and repr automatically. I think we should be deprecating the automatic generation and start requiring opt-in to the new behaviour, to be consistent with everything else. I think it's relatively easy to do this as we just need to emit the deprecation warning if the eq or repr arguments weren't passed.
  2. I think a future extension would be to have #[pyclass(init)] to automatically generate a constructor (like we already do for complex enums) and then #[pyclass(dataclass)] which does some or all of the above conveniences (maybe depending on whether the class is frozen).

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reading the related issues #4202, #4206, and #4210 to understand the accepted #[pyclass] option design. The remaining proposal concerns repr, deprecating automatic enum behavior, and possible init/dataclass extensions; work is done only after the scope and unresolved formatting choices are agreed.

Written by the indexing model from the issue text.

Assessment

Tech stack
python, rust
Domain
backend-api-design
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.