GV

GeezerVison

The World Wide Web, restored to 800 pixels of glory.

Home|About|Gaming cabinet|Archives|How it works|Starter sites

On this site

  • Sign in
  • ActionsCI/CD and automation
  • CodespacesCloud development environments
  • All Features
  • Documentation
  • Training
  • Certifications
  • Build with Copilot
  • Customize Copilot
  • Integrations
  • Trending repos
  • GitHub Sponsors
  • Developer articles
  • Enterprises

This view

  • Original page
  • New address

GeezerVison is showing github.com — gh-101118: correct function signatures in the math module docs by skirpichev · Pull Request #101120 · python/cpython

Conversation

@skirpichev

@skirpichev skirpichev commented Jan 18, 2023 •
edited by bedevere-bot
Loading

Uh oh!

There was an error while loading. Please reload this page.

Copy link
Copy Markdown
Member
  • Issue: Missing "/" in function signatures of the rst docs of stdlib (e.g. the math module) #101118

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions
@skirpichev
gh-101118: correct function signatures in the math module docs
fcea431
@bedevere-bot bedevere-bot added the awaiting review label Jan 18, 2023
@bedevere-bot bedevere-bot mentioned this pull request Jan 18, 2023
Missing "/" in function signatures of the rst docs of stdlib (e.g. the math module) #101118
Closed
@bedevere-bot bedevere-bot added docs Documentation in the Doc dir skip news labels Jan 18, 2023
sobolevn
sobolevn reviewed Jan 18, 2023
View reviewed changes

@sobolevn sobolevn left a comment

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

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

Right now we haven't decided yet what to do with positional only args in the docs.

Some maintainers add them, some later remove them, some prefer not to touch it.

This is just for the context for this change :)

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions
@rhettinger

rhettinger commented Jan 18, 2023

Copy link
Copy Markdown
Contributor

There was a decision not to add these to the docs because lay readers mostly find them confusing, because it makes the docs harder to read, and there are no known usability issues with the docs as they are now. So exceptions have been made for functions likes sorted() that have a complex signature that users need to know about. In the case of the math module, we don't get users writing sin(x=pi/4) so these edits are just gratuitous.

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@rhettinger rhettinger closed this Jan 18, 2023
@skirpichev

skirpichev commented Jan 18, 2023 •
edited
Loading

Uh oh!

There was an error while loading. Please reload this page.

Copy link
Copy Markdown
Member Author

Well, the inspect module does very clear distinction:

>>> def foo(x): pass  # like e.g. math.ceil shown in docs
... 
>>> def bar(x, /): pass
... 
>>> inspect.signature(foo)
<Signature (x)>
>>> inspect.signature(bar)
<Signature (x, /)>
>>> foo(x=1)
>>> bar(x=1)  # that's how math,ceil behave in the reality
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: bar() got some positional-only arguments passed as keyword arguments: 'x'

So exceptions have been made for functions likes sorted() that have a complex signature

The os module seems to be one using "/". I doubt that the os.setegid has a complex signature.

Sorry for the nitpick, anyway.

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@skirpichev
skirpichev deleted the fix-101118 branch January 18, 2023 09:02
@skirpichev skirpichev mentioned this pull request Feb 18, 2025
gh-125957: sync argument naming in sphinx docs of the cmath and help() #125958
Merged
@skirpichev skirpichev mentioned this pull request Mar 30, 2025
gh-131885: simplify function signatures in the cmath module #131886
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@sobolevn sobolevn sobolevn left review comments

Uh oh!

There was an error while loading. Please reload this page.

Assignees

No one assigned

Labels

awaiting review docs Documentation in the Doc dir skip news

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Uh oh!

There was an error while loading. Please reload this page.

4 participants

@skirpichev @rhettinger @sobolevn @bedevere-bot
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
You are visitor 01402503 — GeezerVison does not store the pages you look up.
Best viewed with Netscape Navigator 4.7 or Internet Explorer 6 at 800×600. No cookies required.