Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

gh-101100: Add a table of class attributes to the "Custom classes" section of the data model docs #124480

Merged
merged 6 commits into from
Sep 25, 2024

Conversation

AlexWaygood
Copy link
Member

@AlexWaygood AlexWaygood commented Sep 25, 2024

  • Convert the attribute references in the "Custom classes" section to a list table
  • Refer to the attributes as type.__*__ rather than class.__*__; this reflects the reality at runtime
  • Make sure all attribute references for custom classes are referenceable from other files
  • Add references for attributes that were not previously documented (such as __qualname__), and move some references from library/stdtypes.rst to the datamodel docs so that references for all class attributes can be found in a single location
  • Update and improve references to class attributes from other files so that they properly link to the canonical entries in the table
  • Fix 21 or so Sphinx nitpicks in the process

📚 Documentation preview 📚: https://cpython-previews--124480.org.readthedocs.build/

@bedevere-app bedevere-app bot added docs Documentation in the Doc dir skip news labels Sep 25, 2024
@AlexWaygood AlexWaygood added needs backport to 3.12 bug and security fixes needs backport to 3.13 bugs and security fixes labels Sep 25, 2024
Doc/faq/programming.rst Show resolved Hide resolved
Doc/whatsnew/2.2.rst Outdated Show resolved Hide resolved
Copy link
Contributor

@willingc willingc left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good @AlexWaygood. Thanks for doing this table.

As an FYI, it's much faster to review when the nitpick fixes are a separate PR. Makes it a little easier to grok what the new addition contains. No worries for this PR.

@AlexWaygood
Copy link
Member Author

As an FYI, it's much faster to review when the nitpick fixes are a separate PR. Makes it a little easier to grok what the new addition contains. No worries for this PR.

Thanks -- I'll separate it out into two PRs next time!

@AlexWaygood AlexWaygood enabled auto-merge (squash) September 25, 2024 18:51
@AlexWaygood AlexWaygood merged commit 0d9d56c into python:main Sep 25, 2024
23 checks passed
@AlexWaygood AlexWaygood deleted the class-attrs-docs branch September 25, 2024 19:29
@miss-islington-app
Copy link

Thanks @AlexWaygood for the PR 🌮🎉.. I'm working now to backport this PR to: 3.12, 3.13.
🐍🍒⛏🤖

@miss-islington-app
Copy link

Sorry, @AlexWaygood, I could not cleanly backport this to 3.13 due to a conflict.
Please backport using cherry_picker on command line.

cherry_picker 0d9d56c4e4246495f506f7fb319548fb105b535b 3.13

@miss-islington-app
Copy link

Sorry, @AlexWaygood, I could not cleanly backport this to 3.12 due to a conflict.
Please backport using cherry_picker on command line.

cherry_picker 0d9d56c4e4246495f506f7fb319548fb105b535b 3.12

AlexWaygood added a commit to AlexWaygood/cpython that referenced this pull request Sep 25, 2024
@bedevere-app
Copy link

bedevere-app bot commented Sep 25, 2024

GH-124556 is a backport of this pull request to the 3.13 branch.

@bedevere-app bedevere-app bot removed the needs backport to 3.13 bugs and security fixes label Sep 25, 2024
AlexWaygood added a commit to AlexWaygood/cpython that referenced this pull request Sep 25, 2024
@bedevere-app
Copy link

bedevere-app bot commented Sep 25, 2024

GH-124558 is a backport of this pull request to the 3.12 branch.

@bedevere-app bedevere-app bot removed the needs backport to 3.12 bug and security fixes label Sep 25, 2024
AlexWaygood added a commit that referenced this pull request Sep 25, 2024
emilyemorehouse added a commit to lysnikolaou/cpython that referenced this pull request Sep 26, 2024
* main: (69 commits)
  Add "annotate" SET_FUNCTION_ATTRIBUTE bit to dis. (python#124566)
  pythongh-124412: Add helpers for converting annotations to source format (python#124551)
  pythongh-119180: Disallow instantiation of ConstEvaluator objects (python#124561)
  For-else deserves its own section in the tutorial (python#123946)
  Add 3.13 as a version option to the crash issue template (python#124560)
  pythongh-123242: Note that type.__annotations__ may not exist (python#124557)
  pythongh-119180: Make FORWARDREF format look at __annotations__ first (python#124479)
  pythonGH-58058: Add quick reference for `ArgumentParser` to argparse docs (pythongh-124227)
  pythongh-41431: Add `datetime.time.strptime()` and `datetime.date.strptime()` (python#120752)
  pythongh-102450: Add ISO-8601 alternative for midnight to `fromisoformat()` calls. (python#105856)
  pythongh-124370: Add "howto" for free-threaded Python (python#124371)
  pythongh-121277: Allow `.. versionadded:: next` in docs (pythonGH-121278)
  pythongh-119400:  make_ssl_certs: update reference test data automatically, pass in expiration dates as parameters python#119400  (pythonGH-119401)
  pythongh-119180: Avoid going through AST and eval() when possible in annotationlib (python#124337)
  pythongh-124448: Update Windows builds to use Tcl/Tk 8.6.15 (pythonGH-124449)
  pythongh-123884 Tee of tee was not producing n independent iterators (pythongh-124490)
  pythongh-124378: Update test_ttk for Tcl/Tk 8.6.15 (pythonGH-124542)
  pythongh-124513: Check args in framelocalsproxy_new() (python#124515)
  pythongh-101100: Add a table of class attributes to the "Custom classes" section of the data model docs (python#124480)
  Doc: Use ``major.minor`` for documentation distribution archive filenames (python#124489)
  ...
Yhg1s pushed a commit that referenced this pull request Sep 26, 2024
.. doctest::

>>> int.__subclasses__()
[<class 'bool'>, <enum 'IntEnum'>, <flag 'IntFlag'>, <class 're._constants._NamedIntConstant'>, <class 're._ZeroSentinel'>]
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This failed spuriously on https://github.com/python/cpython/actions/runs/11043320393/job/30677452220?pr=124569. I suspect it depends on whether GC has run and collected the MyIntEnum class. Example:

>>> print(int.__subclasses__())
[<class 'bool'>, <enum 'IntEnum'>, <flag 'IntFlag'>, <class 're._constants._NamedIntConstant'>, <class 're._ZeroSentinel'>]
>>> import enum
>>> def f():
...     class MyIntEnum(int, enum.Enum): pass
...     
>>> f()
>>> print(int.__subclasses__())
[<class 'bool'>, <enum 'IntEnum'>, <flag 'IntFlag'>, <class 're._constants._NamedIntConstant'>, <class 're._ZeroSentinel'>, <enum 'MyIntEnum'>]
>>> import gc
>>> gc.collect()
31
>>> print(int.__subclasses__())
[<class 'bool'>, <enum 'IntEnum'>, <flag 'IntFlag'>, <class 're._constants._NamedIntConstant'>, <class 're._ZeroSentinel'>]
>>> 

I'll send a PR to change this.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh, interesting! Thanks!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
docs Documentation in the Doc dir skip news
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants