Skip to content

typo in random.shuffle's docstring#2194

Closed
reynoldsnlp wants to merge 1 commit into
python:masterfrom
reynoldsnlp:patch-1
Closed

typo in random.shuffle's docstring#2194
reynoldsnlp wants to merge 1 commit into
python:masterfrom
reynoldsnlp:patch-1

Conversation

@reynoldsnlp

Copy link
Copy Markdown
Contributor

The brackets do not match: [0.0, 1.0)

I changed it to be square brackets on both sides: [0.0, 1.0]

The brackets do not match: [0.0, 1.0)

I changed it to be square brackets on both sides: [0.0, 1.0]
@the-knights-who-say-ni

Copy link
Copy Markdown

Hello, and thanks for your contribution!

I'm a bot set up to make sure that the project can legally accept your contribution by verifying you have signed the PSF contributor agreement (CLA).

Unfortunately we couldn't find an account corresponding to your GitHub username on bugs.python.org (b.p.o) to verify you have signed the CLA (this might be simply due to a missing "GitHub Name" entry in your b.p.o account settings). This is necessary for legal reasons before we can look at your contribution. Please follow the steps outlined in the CPython devguide to rectify this issue.

Thanks again to your contribution and we look forward to looking at it!

@mention-bot

Copy link
Copy Markdown

@reynoldsnlp, thanks for your PR! By analyzing the history of the files in this pull request, we identified @rhettinger, @tim-one and @tiran to be potential reviewers.

@jonathaneunice

Copy link
Copy Markdown
Contributor

That was not a typo.

The string "[0.0, 1.0)" is mathematical notation for the "half-open interval" 0.0 <= x < 1.0. It is correct as it stands, and consistent with other documentation in—and more to the point, the code of—the random module. To change it to the string "[0.0, 1.0]" would erroneously specify the "closed interval" 0.0 <= x <= 1.0, which is not how random works.

@reynoldsnlp

reynoldsnlp commented Jun 15, 2017

Copy link
Copy Markdown
Contributor Author

@jonathaneunice Ah, I didn't know about that notation. It seems to me that we shouldn't be using esoteric mathematical notation in documentation for a commonly used standard library. My guess is that the vast majority of python coders will not understand it. (That's how I comfort myself for not knowing it myself.) ;-)

Wouldn't your explanation above, "0.0 <= x < 1.0", be more enlightening?

@jonathaneunice

Copy link
Copy Markdown
Contributor

random is a mathematical / numerical module, so at least some use of mathematical notation is par for the course. While I'm not sure interval notation really qualifies as esoteric, I accept your point that comparative notation (e.g. 0.0 <= x < 1.0) might be more widely known.

If you feel strongly enough to make the case, suggest you search out other places the interval notation lives (e.g. in docs for random.random()) and propose updating those at the same time. (You should also sign the CLA and create a corresponding issue (at bugs.python.org). Absent those, it's hard to get traction on a PR.)

@reynoldsnlp

Copy link
Copy Markdown
Contributor Author

@jonathaneunice I think you're definitely right that any change would have to be consistent across the documentation. I don't have the time/energy to pursue that now, but I have put it in my "someday" to-do list. Thanks for directing me to interval notation, and for blocking a very flawed PR.

@reynoldsnlp reynoldsnlp deleted the patch-1 branch June 15, 2017 22:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants