Clean up comma usage in Doc/library/functions.rst #27083

Adminixtrator · 2021-07-10T03:51:57Z

"Readability counts."

Excerpt from The Zen of Python by Tim Peters

the-knights-who-say-ni · 2021-07-10T03:51:59Z

Hello, and thanks for your contribution!

I'm a bot set up to make sure that the project can legally accept this contribution by verifying everyone involved has signed the PSF contributor agreement (CLA).

Recognized GitHub username

We couldn't find a bugs.python.org (b.p.o) account corresponding to the following GitHub usernames:

@Adminixtrator

This might be simply due to a missing "GitHub Name" entry in one's b.p.o account settings. This is necessary for legal reasons before we can look at this contribution. Please follow the steps outlined in the CPython devguide to rectify this issue.

You can check yourself to see if the CLA has been received.

Thanks again for the contribution, we look forward to reviewing it!

ambv · 2021-07-13T13:16:24Z

Doc/library/functions.rst

@@ -4,8 +4,8 @@
 Built-in Functions
 ==================

-The Python interpreter has a number of functions and types built into it that
-are always available.  They are listed here in alphabetical order.
+The Python interpreter has several functions and types built into it that 


How is "several" more readable than "a number of"?

(also note trailing space)

ambv · 2021-07-13T13:16:49Z

Doc/library/functions.rst

@@ -4,8 +4,8 @@
 Built-in Functions
 ==================

-The Python interpreter has a number of functions and types built into it that
-are always available.  They are listed here in alphabetical order.


We generally use double spaces after periods between sentences.

That's from formatting, didn't notice.

ambv · 2021-07-13T13:21:24Z

Doc/library/functions.rst

@@ -96,7 +96,7 @@ are always available.  They are listed here in alphabetical order.
   This calls the :meth:`~object.__anext__` method of *async_iterator*,
   returning an :term:`awaitable`. Awaiting this returns the next value of the
   iterator. If *default* is given, it is returned if the iterator is exhausted,
-   otherwise :exc:`StopAsyncIteration` is raised.
+   otherwise, :exc:`StopAsyncIteration` is raised.


The usage before was correct. If you insist on using the comma when "otherwise" begins a sentence fragment, you need to change the preceding comma into a semicolon to emphasize the composition of the sentence (it looks too similar to enumeration otherwise). I would just leave those cases alone.

ambv · 2021-07-13T13:23:55Z

Doc/library/functions.rst

@@ -222,7 +222,7 @@ are always available.  They are listed here in alphabetical order.

   Return :const:`True` if the *object* argument appears callable,
   :const:`False` if not.  If this returns ``True``, it is still possible that a
-   call fails, but if it is ``False``, calling *object* will never succeed.
+   call fails, but if it is ``False``, the calling *object* will never succeed.


"calling" is a verb here, this is invalid.

ambv · 2021-07-13T13:24:46Z

Doc/library/functions.rst

@@ -479,7 +479,7 @@ are always available.  They are listed here in alphabetical order.
 .. function:: enumerate(iterable, start=0)

   Return an enumerate object. *iterable* must be a sequence, an
-   :term:`iterator`, or some other object which supports iteration.
+   :term:`iterator`, or some other object that supports iteration.


How is "that" better than "which"?

It's referring to a defining clause

"which" can also refer to defining clauses, see: https://dictionary.cambridge.org/grammar/british-grammar/relative-clauses-defining-and-non-defining

ambv · 2021-07-13T13:26:26Z

Doc/library/functions.rst

   iteration protocol (the :meth:`__iter__` method), or it must support the
   sequence protocol (the :meth:`__getitem__` method with integer arguments
   starting at ``0``).  If it does not support either of those protocols,
   :exc:`TypeError` is raised. If the second argument, *sentinel*, is given,
   then *object* must be a callable object.  The iterator created in this case
   will call *object* with no arguments for each call to its
   :meth:`~iterator.__next__` method; if the value returned is equal to
-   *sentinel*, :exc:`StopIteration` will be raised, otherwise the value will
+   *sentinel*, :exc:`StopIteration` will be raised, otherwise, the value will


ambv · 2021-07-13T13:26:33Z

Doc/library/functions.rst

@@ -928,22 +928,22 @@ are always available.  They are listed here in alphabetical order.

   Return an :term:`iterator` object.  The first argument is interpreted very
   differently depending on the presence of the second argument. Without a
-   second argument, *object* must be a collection object which supports the
+   second argument, *object* must be a collection object that supports the


ambv · 2021-07-13T13:29:15Z

Doc/library/functions.rst

   be returned.

   See also :ref:`typeiter`.

   One useful application of the second form of :func:`iter` is to build a
   block-reader. For example, reading fixed-width blocks from a binary
-   database file until the end of file is reached::
+   database file until the end of the file is reached::


This makes it arguably less readable, "end of file" is an IT idiom.

ambv · 2021-07-13T13:29:27Z

Doc/library/functions.rst

@@ -1062,13 +1062,13 @@ are always available.  They are listed here in alphabetical order.

   Retrieve the next item from the *iterator* by calling its
   :meth:`~iterator.__next__` method.  If *default* is given, it is returned
-   if the iterator is exhausted, otherwise :exc:`StopIteration` is raised.
+   if the iterator is exhausted, otherwise, :exc:`StopIteration` is raised.


Doc/library/functions.rst

Adminixtrator

Hi @ambv
Once resolved, should I fix these and create a new PR or that will be done from your end?

ambv · 2021-07-16T13:20:31Z

Once resolved, should I fix these and create a new PR or that will be done from your end?

I'm not sure what you mean. You resolve issues by updating your PR. I'll merge it once it's in an acceptable state.

Adminixtrator

All done @ambv

Doc/library/functions.rst

bedevere-bot · 2021-07-19T16:02:26Z

@ambv: Please replace # with GH- in the commit message next time. Thanks!

ambv · 2021-07-19T16:02:29Z

Thanks! ✨ 🍰 ✨

Clean up comma usage in Doc/library/functions.rst (python#27083)

miss-islington · 2021-07-19T16:08:31Z

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

(cherry picked from commit 1e651c6) Co-authored-by: α∂мιηιχтяαтσя <sadiqherritage@gmail.com>

bedevere-bot · 2021-07-19T16:08:38Z

GH-27243 is a backport of this pull request to the 3.10 branch.

(cherry picked from commit 1e651c6) Co-authored-by: α∂мιηιχтяαтσя <sadiqherritage@gmail.com>

* origin/main: (1146 commits) bpo-42064: Finalise establishing sqlite3 global state (pythonGH-27155) bpo-44678: Separate error message for discontinuous padding in binascii.a2b_base64 strict mode (pythonGH-27249) correct spelling (pythonGH-27076) bpo-44524: Add missed __name__ and __qualname__ to typing module objects (python#27237) bpo-27513: email.utils.getaddresses() now handles Header objects (python#13797) Clean up comma usage in Doc/library/functions.rst (python#27083) bpo-42238: Fix small rst issue in NEWS.d/. (python#27238) bpo-41972: Tweak fastsearch.h string search algorithms (pythonGH-27091) bpo-44340: Add support for building with clang full/thin lto (pythonGH-27231) bpo-44661: Update property_descr_set to use vectorcall if possible. (pythonGH-27206) bpo-44645: Check for interrupts on any potentially backwards edge (pythonGH-27216) bpo-41546: make pprint (like print) not write to stdout when it is None (pythonGH-26810) bpo-44554: refactor pdb targets (and internal tweaks) (pythonGH-26992) bpo-43086: Add handling for out-of-spec data in a2b_base64 (pythonGH-24402) bpo-44561: Update hyperlinks in Doc/distributing/index.rst (python#27032) bpo-42355: symtable.get_namespace() now checks whether there are multiple or any namespaces found (pythonGH-23278) bpo-44654: Do not export the union type related symbols (pythonGH-27223) bpo-44633: Fix parameter substitution of the union type with wrong types. (pythonGH-27218) bpo-44654: Refactor and clean up the union type implementation (pythonGH-27196) bpo-20291: Fix MSVC warnings in getargs.c (pythonGH-27211) ...

Update functions.rst

a1eb540

the-knights-who-say-ni added the CLA not signed label Jul 10, 2021

bedevere-bot added awaiting review docs Documentation in the Doc dir labels Jul 10, 2021

Merge branch 'python:main' into main

faff1df

ambv reviewed Jul 13, 2021

View reviewed changes

Adminixtrator commented Jul 16, 2021

View reviewed changes

Adminixtrator added 8 commits July 18, 2021 00:54

Update functions.rst

8d4dd94

Update functions.rst

98c4ce0

Update functions.rst

361fdae

Update functions.rst

8fd9f04

Update functions.rst

9cc2cd6

Update functions.rst

9cc0f43

Update functions.rst

3aa17f2

Update functions.rst

f98497c

Adminixtrator commented Jul 18, 2021

View reviewed changes

ambv reviewed Jul 19, 2021

View reviewed changes

ambv added 5 commits July 19, 2021 17:10

revert comma move

19d062a

s/,/;/

0441c2a

s/,/;/

e20614d

revert that/which change

f2b54db

revert that/which change

0c2f755

ambv added skip issue skip news labels Jul 19, 2021

ambv changed the title ~~--improved readability~~ Clean up comma usage Jul 19, 2021

ambv changed the title ~~Clean up comma usage~~ Clean up comma usage in Doc/library/functions.rst Jul 19, 2021

ambv merged commit 1e651c6 into python:main Jul 19, 2021

bedevere-bot removed the awaiting review label Jul 19, 2021

sthagen added a commit to sthagen/python-cpython that referenced this pull request Jul 19, 2021

Merge pull request #541 from python/main

f209a64

Clean up comma usage in Doc/library/functions.rst (python#27083)

ambv added the needs backport to 3.10 only security fixes label Jul 19, 2021

miss-islington pushed a commit to miss-islington/cpython that referenced this pull request Jul 19, 2021

Clean up comma usage in Doc/library/functions.rst (pythonGH-27083)

68dec1c

(cherry picked from commit 1e651c6) Co-authored-by: α∂мιηιχтяαтσя <sadiqherritage@gmail.com>

bedevere-bot removed the needs backport to 3.10 only security fixes label Jul 19, 2021

ambv pushed a commit that referenced this pull request Jul 19, 2021

Clean up comma usage in Doc/library/functions.rst (GH-27083) (#27243)

2d04920

(cherry picked from commit 1e651c6) Co-authored-by: α∂мιηιχтяαтσя <sadiqherritage@gmail.com>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Clean up comma usage in Doc/library/functions.rst #27083

Clean up comma usage in Doc/library/functions.rst #27083

Adminixtrator commented Jul 10, 2021 •

edited

Loading

the-knights-who-say-ni commented Jul 10, 2021

ambv Jul 13, 2021

ambv Jul 13, 2021

ambv Jul 13, 2021

Adminixtrator Jul 16, 2021

ambv Jul 13, 2021

ambv Jul 13, 2021

ambv Jul 13, 2021

Adminixtrator Jul 16, 2021

ambv Jul 16, 2021

ambv Jul 13, 2021

ambv Jul 13, 2021

ambv Jul 13, 2021

ambv Jul 13, 2021

Adminixtrator left a comment

ambv commented Jul 16, 2021

Adminixtrator left a comment

bedevere-bot commented Jul 19, 2021

ambv commented Jul 19, 2021

miss-islington commented Jul 19, 2021

bedevere-bot commented Jul 19, 2021

Clean up comma usage in Doc/library/functions.rst #27083

Clean up comma usage in Doc/library/functions.rst #27083

Conversation

Adminixtrator commented Jul 10, 2021 • edited Loading

the-knights-who-say-ni commented Jul 10, 2021

Recognized GitHub username

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Adminixtrator left a comment

Choose a reason for hiding this comment

ambv commented Jul 16, 2021

Adminixtrator left a comment

Choose a reason for hiding this comment

bedevere-bot commented Jul 19, 2021

ambv commented Jul 19, 2021

miss-islington commented Jul 19, 2021

bedevere-bot commented Jul 19, 2021

Adminixtrator commented Jul 10, 2021 •

edited

Loading