python / python/typing

Annotations for `__eq__`

Open
#1,536 0 comments 2 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

topic: documentation topic: typing spec
Dominant language
Python
Stars
1.8k
Forks
302
Avg merge
23h
Merged PRs (30d)
8

Description

It would be useful to have more guidance on how __eq__ methods should be annotated.

A few considerations:

  • Enable type checkers to warn on non-overlapping equality comparisons. The type annotations should ideally allow type checkers to look at a check like A() == B() and verify whether it can ever return True.
  • Some level of support for __eq__ returning a non-boolean (classic example: numpy arrays)
  • How to think about __eq__ methods that return NotImplemented on unrecognized types versus those that throw an error

See also https://discuss.python.org/t/make-type-hints-for-eq-of-primitives-less-strict/34240

Covering this in the typing spec is important because it affects how library authors should annotate __eq__ methods in their libraries if they want all type checkers to understand these methods.

Contributor guide

No contributing guide indexed for this repository

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 typing specification and the linked discuss.python.org thread to understand the existing treatment of eq. The work is complete when the specification gives agreed guidance for non-overlapping comparisons, non-boolean returns, NotImplemented, and errors, with library authors able to apply it consistently.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.