The Wayback Machine - https://web.archive.org/web/20250525001013/https://github.com/python/cpython/pull/102554
Skip to content

gh-66646: Explain __base__ attribute in the docs #102554

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

Open
wants to merge 15 commits into
base: main
Choose a base branch
from

Conversation

furkanonder
Copy link
Contributor

@furkanonder furkanonder commented Mar 9, 2023

Co-authored by: Anupama Srinivas Murthy

@bedevere-bot bedevere-bot added docs Documentation in the Doc dir skip news labels Mar 9, 2023
@merwok
Copy link
Member

merwok commented Mar 9, 2023

I’m not sure that this implementation detail should be documented in three places.
One place with an index should be enough. Please also use the right markup to mark it as an impl. detail.

@furkanonder
Copy link
Contributor Author

@merwok Since class.__bases__ is defined in stdtypes.rst and datamodel.rst files, I wanted to define class.__base__ in these files.

@merwok
Copy link
Member

merwok commented Mar 13, 2023

I understand your reason, but still think one place would be better than 3. I would like to see other people’s opinion!

For the markup, I meant this: https://devguide.python.org/documentation/markup/#codecell33 🙂

@furkanonder
Copy link
Contributor Author

I understand your reason, but still think one place would be better than 3. I would like to see other people’s opinion!

CC: @hugovk @CAM-Gerlach

@hugovk
Copy link
Member

hugovk commented Jul 23, 2023

I don't have a strong opinion, but if it's an implementation detail, fewer places might be better. The search should help people find it when they're looking.

@furkanonder furkanonder changed the title GH-66646: Explain __base__ attribute in the docs gh-66646: Explain __base__ attribute in the docs Aug 6, 2023
@erlend-aasland
Copy link
Contributor

@furkanonder, can you please rework this PR to align with the comments Raymond, Guido, and Éric gave on the issue?

@erlend-aasland erlend-aasland added the pending The issue will be closed if no feedback is provided label Jan 17, 2024
@furkanonder
Copy link
Contributor Author

@erlend-aasland Based on Raymond, Guido, and Éric's feedback, I believe changes have been made. Could you please let me know if there is anything I missed?

@@ -307,7 +307,7 @@ Object Protocol
class, are considered classes. However, objects can override this by having
a :attr:`~class.__bases__` attribute (which must be a tuple of base classes).

Another function, :attr:`__base__` that is specific to Cpython and also
Another function, :attr:`__base__` that is specific to CPython and also
Copy link
Member

Choose a reason for hiding this comment

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

Should this say function?

@erlend-aasland
Copy link
Contributor

@erlend-aasland Based on Raymond, Guido, and Éric's feedback, I believe changes have been made. Could you please let me know if there is anything I missed?

Not at all. I will repeat their comments here:

Raymond said in #66646 (comment):

I think that base was intended to be a non-guaranteed implementation detail for new-style classes just like dictoffset and flags .

Guido followed up in #66646 (comment):

Raymond is correct. base is closely tied to the C implementation. I think it might be worth a mention, but with an explicit note that it is CPython-specific. It is sometimes useful, e.g. when wondering why a certain case of multiple inheritance is rejected.

So, we're talking about a non-guaranteed implementation detail. You've also been told multiple times that a single mention is sufficient, yet you do not follow up this; your PR still changes three doc files, including the reference. "Worth a mention" is far from your PR which adds 64 (!) lines.

I'm sorry, but I cannot see that you've taken any review or issue remarks into account.

@furkanonder
Copy link
Contributor Author

I understand your reason, but still think one place would be better than 3. I would like to see other people’s opinion!

I didn't think that the idea of repetition here was stated unequivocally, since he said I would like to see other people's views!.

So, we're talking about a non-guaranteed implementation detail.

This has already been stated in three parts.

In object.rst

In stdtypes.rst

In datamodel.rst

@furkanonder
Copy link
Contributor Author

furkanonder commented Jan 21, 2024

"Worth a mention" is far from your PR which adds 64 (!) lines.

I think it might be worth a mention, but with an explicit note that it is CPython-specific.

The statement does not include a line count for the section to be documented. Hence I did not consider the amount of lines for the section. The reason for the 64 lines of the section was to ensure a better understanding of the subject by supporting it with examples.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
awaiting review DO-NOT-MERGE docs Documentation in the Doc dir pending The issue will be closed if no feedback is provided skip news
Projects
Status: Todo
Development

Successfully merging this pull request may close these issues.

5 participants