Skip to content

Fix inspect.Parameter docstring on the kind attribute#143541

Merged
encukou merged 4 commits into
python:mainfrom
johnslavik:fix-inspect-parameter-docstring
Feb 24, 2026
Merged

Fix inspect.Parameter docstring on the kind attribute#143541
encukou merged 4 commits into
python:mainfrom
johnslavik:fix-inspect-parameter-docstring

Conversation

@johnslavik

@johnslavik johnslavik commented Jan 8, 2026

Copy link
Copy Markdown
Member

I've checked the docs and they're correct; only the docstring was wrong.
I think we can use this pseudocode type annotation here? Open for a better idea.

@johnslavik johnslavik changed the title Fix inspect parameter docstring Fix inspect.Parameter docstring on the kind attribute Jan 8, 2026
@johnslavik johnslavik requested a review from picnixz January 18, 2026 02:31
@picnixz

picnixz commented Jan 18, 2026

Copy link
Copy Markdown
Member

Is it just a C/C from the online docs?

@johnslavik

Copy link
Copy Markdown
Member Author

Is it just a C/C from the online docs?

No, not at all

@picnixz

picnixz commented Jan 18, 2026

Copy link
Copy Markdown
Member

Then I am a bit confused about the change. When I asked C/C from the online docs, I wanted to know whether the online docs indicated the description field and that 'kind' was an enumeration.

@johnslavik

johnslavik commented Jan 18, 2026

Copy link
Copy Markdown
Member Author

The online documentation does not specifiy whether kind is a string or int or enum, if that's what your asking (see https://docs.python.org/3/library/inspect.html#inspect.Parameter.kind). However, https://docs.python.org/3/library/inspect.html#inspect.Parameter.kind.description does imply that Parameter.kind is an enum.

Then I am a bit confused about the change.

What makes it confusing? What can I do?

@picnixz

picnixz commented Jan 18, 2026

Copy link
Copy Markdown
Member

I am confused by "the docstring was wrong". AFAICT, it is not wrong. If you indicate that kind is an enum in te docstring it should be reflected in the online docs as well.

Comment thread Lib/inspect.py Outdated
@johnslavik

johnslavik commented Jan 18, 2026

Copy link
Copy Markdown
Member Author

If you indicate that kind is an enum in te docstring it should be reflected in the online docs as well.

It is not explicitly reflected. Online docs don't annotate types as this docstring does.
From the .description online documentation I linked to, one can imply that inspect.Parameter.kind is an enum.

@johnslavik

johnslavik commented Jan 18, 2026

Copy link
Copy Markdown
Member Author

What can I do to address the concerns about the PR?

@picnixz picnixz left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Ok I actually missed the fact that it was documented as a string...

As a follow-up, I would suggest that:

  • You explicitly mention that it is an enumeration in the docs.
  • You explicitly say that it has a description property.

We could document the enumeration as well as a class right? (or is it an implementation detail?)

@encukou encukou merged commit 4c95ad8 into python:main Feb 24, 2026
45 checks passed
@miss-islington-app

Copy link
Copy Markdown

Thanks @johnslavik for the PR, and @encukou for merging it 🌮🎉.. I'm working now to backport this PR to: 3.13, 3.14.
🐍🍒⛏🤖 I'm not a witch! I'm not a witch!

miss-islington pushed a commit to miss-islington/cpython that referenced this pull request Feb 24, 2026
…43541)

(cherry picked from commit 4c95ad8)

Co-authored-by: Bartosz Sławecki <bartosz@ilikepython.com>
miss-islington pushed a commit to miss-islington/cpython that referenced this pull request Feb 24, 2026
…43541)

(cherry picked from commit 4c95ad8)

Co-authored-by: Bartosz Sławecki <bartosz@ilikepython.com>
@bedevere-app

bedevere-app Bot commented Feb 24, 2026

Copy link
Copy Markdown

GH-145174 is a backport of this pull request to the 3.14 branch.

@bedevere-app bedevere-app Bot removed the needs backport to 3.14 bugs and security fixes label Feb 24, 2026
@bedevere-app

bedevere-app Bot commented Feb 24, 2026

Copy link
Copy Markdown

GH-145175 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 Feb 24, 2026
@johnslavik johnslavik deleted the fix-inspect-parameter-docstring branch February 24, 2026 13:05
encukou pushed a commit that referenced this pull request Feb 24, 2026
…143541) (GH-145175)

(cherry picked from commit 4c95ad8)

Co-authored-by: Bartosz Sławecki <bartosz@ilikepython.com>
encukou pushed a commit that referenced this pull request Feb 24, 2026
…143541) (GH-145174)

(cherry picked from commit 4c95ad8)

Co-authored-by: Bartosz Sławecki <bartosz@ilikepython.com>
brijkapadia pushed a commit to brijkapadia/cpython that referenced this pull request Feb 28, 2026
ljfp pushed a commit to ljfp/cpython that referenced this pull request Apr 25, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants