Skip to content

Minor changes in Doc/faq/library. #15449

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.

Sign up for GitHub

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

Merged
matrixise merged 5 commits into from
Sep 9, 2019
Merged

Minor changes in Doc/faq/library. #15449

Changes from 1 commit
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
8438d52
Minor changes.
Aug 24, 2019
bd06e6b
Update Doc/faq/library.rst
awecx Aug 25, 2019
129f4e3
Apply suggestions from aeros167.
Aug 26, 2019
57d0ea3
Update Doc/faq/library.rst
awecx Aug 26, 2019
7533b0e
Apply suggestions from aeros167 + re-add a "a" that was accidentally …
Aug 26, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 8 additions & 8 deletions Doc/faq/library.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -125,7 +125,7 @@ argument list. It is called as ::

handler(signum, frame)

so it should be declared with two arguments::
so it should be declared with two parameters::
Copy link
Contributor

@aeros aeros Aug 24, 2019

Choose a reason for hiding this comment

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

Agreed, a function is called with arguments and declared with parameters.


def handler(signum, frame):
...
Expand Down Expand Up @@ -159,7 +159,7 @@ The "global main logic" of your program may be as simple as ::

at the bottom of the main module of your program.

Once your program is organized as a tractable collection of functions and class
Once your program is organized as a tractable collection of function and class
Copy link
Contributor

@aeros aeros Aug 24, 2019 •
edited
Loading

Choose a reason for hiding this comment

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

I think this section is okay as it is. I can see where you were going with this though, you might have assumed that the "and" was implying: "... collection of functions behaviors and class behaviors" (which would be grammatically incorrect). But, in this case the two are entirely separate. The "behaviors" part is only connected to "class". The two items are:

  1. Collection of functions
  2. Collection of class behaviors

Copy link
Contributor Author

@awecx awecx Aug 25, 2019

Choose a reason for hiding this comment

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

In that case, I don't understand why the doc states that "you should write test functions that exercise the behaviours". If "behaviours" only applies to "class" and not to "function", then the doc would say that functions not embedded into classes should not be tested. Am I missing something here ?

Copy link
Contributor

@aeros aeros Aug 25, 2019 •
edited
Loading

Choose a reason for hiding this comment

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

If "behaviours" only applies to "class" and not to "function", then the doc would say that functions not embedded into classes should not be tested.

Hmm, good point. I might've been looking at this correction too much in isolation without fully considering the surrounding context. While reading over that sentence a couple of times, I also realized it's missing a comma:

Once your program is organized as a tractable collection of function and class
behaviours, you should write test functions that exercise the behaviours.

Also an interesting tidbit (this is definitely subjective though, so I wouldn't suggest changing it for this PR), but we actually alternate between the American English and British English versions of "behaviors/behaviours" within the documentation:

$ git grep -E "behaviors" -- "*.rst" | wc -l
26
$ git grep -E "behaviours" -- "*.rst" | wc -l
8

Copy link
Contributor Author

@awecx awecx Aug 26, 2019

Choose a reason for hiding this comment

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

Ah nice catch (never occured to me there were two versions of this word). I've added the comma.

behaviours you should write test functions that exercise the behaviours. A test
suite that automates a sequence of tests can be associated with each module.
This sounds like a lot of work, but since Python is so terse and flexible it's
Expand Down Expand Up @@ -295,7 +295,7 @@ queue as there are threads.
How do I parcel out work among a bunch of worker threads?
---------------------------------------------------------

The easiest way is to use the new :mod:`concurrent.futures` module,
The easiest way is to use the :mod:`concurrent.futures` module,
Copy link
Contributor

@aeros aeros Aug 24, 2019

Choose a reason for hiding this comment

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

Agreed, concurrent.futures is no longer new.

especially the :mod:`~concurrent.futures.ThreadPoolExecutor` class.

Or, if you want fine control over the dispatching algorithm, you can write
Expand Down Expand Up @@ -679,7 +679,7 @@ How can I mimic CGI form submission (METHOD=POST)?
I would like to retrieve web pages that are the result of POSTing a form. Is
there existing code that would let me do this easily?

Yes. Here's a simple example that uses urllib.request::
Yes. Here's a simple example that uses :mod:`urllib.request`::

#!/usr/local/bin/python

Expand Down Expand Up @@ -774,10 +774,10 @@ have to check what's returned on your system.
You can use the ``connect_ex()`` method to avoid creating an exception. It will
just return the errno value. To poll, you can call ``connect_ex()`` again later
-- ``0`` or ``errno.EISCONN`` indicate that you're connected -- or you can pass this
socket to select to check if it's writable.
socket to ``select()`` to check if it's writable.
Copy link
Contributor

@aeros aeros Aug 24, 2019

Choose a reason for hiding this comment

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

If we're going to reference the method itself, a link should be provided to the corresponding documentation with Sphinx roles:

Suggested change
socket to ``select()`` to check if it's writable.
socket to :meth:`select.select` to check if it's writable.

Copy link
Contributor Author

@awecx awecx Aug 25, 2019

Choose a reason for hiding this comment

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

Of course, but since "connect_ex()" and "errno.EISCONN" were only highlighted in the previous sentence, I felt I would do the same for "select()". But I agree maybe we should provide a link to those as well.

Copy link
Contributor

@aeros aeros Aug 25, 2019 •
edited
Loading

Choose a reason for hiding this comment

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

Of course, but since "connect_ex()" and "errno.EISCONN" were only highlighted in the previous sentence, I felt I would do the same for "select()".

There's quite a lot of the existing documentation which simply hasn't been updated to use the Sphinx roles, since they're a fairly new addition in comparison. Generally speaking, they are only intentionally not used when the link wouldn't provide readers any additional information, such as when an object is being referred to within it's own definition.

Copy link
Contributor Author

@awecx awecx Aug 26, 2019

Choose a reason for hiding this comment

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

I see. I have made a new commit where "connect" and "connect_ex" have the link, but not "errno.EISCONN", nor "EISINPROGRESS" as their meaning is already detailed in this doc.

Copy link
Contributor

@aeros aeros Aug 27, 2019

Choose a reason for hiding this comment

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

I see. I have made a new commit where "connect" and "connect_ex" have the link, but not "errno.EISCONN", nor "EISINPROGRESS" as their meaning is already detailed in this doc.

Just for clarification: Terms on the same doc page can be linked to if they're not defined in the same section (or in a very nearby paragraph), but that's fine.


.. note::
The :mod:`asyncore` module presents a framework-like approach to the problem
The :mod:`asyncio` module presents a framework-like approach to the problem
Copy link
Contributor

@aeros aeros Aug 24, 2019

Choose a reason for hiding this comment

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

Asyncore is a separate module from asyncio, see https://docs.python.org/3.5/library/asyncore.html

Copy link
Contributor Author

@awecx awecx Aug 25, 2019

Choose a reason for hiding this comment

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

Of course but it is now deprecated and all all its functionnality has been moved to asyncio, hence the proposed update.

Copy link
Contributor

@aeros aeros Aug 25, 2019 •
edited
Loading

Choose a reason for hiding this comment

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

Of course but it is now deprecated and all all its functionnality has been moved to asyncio, hence the proposed update.

My point was that the two are not exactly one-to-one.

I agree that this section should be updated to recommend asyncio, but the surrounding text should be adjusted a bit as well. Their purposes are similar, but the existing text is more aimed at asyncore. Asyncio is a general purpose concurrency library, whereas asyncore was more of a framework for a specific purpose.

The :mod:`asyncio` module provides a general purpose single-threaded and
concurrent asynchronous library, which can be used for writing non-blocking
network code.

Edit: Slightly improved section update suggestion.

Copy link
Contributor Author

@awecx awecx Aug 26, 2019

Choose a reason for hiding this comment

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

OK great, I've committed your proposal.

of writing non-blocking networking code.
The third-party `Twisted <https://twistedmatrix.com/trac/>`_ library is
a popular and feature-rich alternative.
Expand Down Expand Up @@ -832,8 +832,8 @@ There are also many other specialized generators in this module, such as:

Some higher-level functions operate on sequences directly, such as:

* ``choice(S)`` chooses random element from a given sequence
* ``shuffle(L)`` shuffles a list in-place, i.e. permutes it randomly
* ``choice(S)`` chooses random element from a given sequence.
* ``shuffle(L)`` shuffles a list in-place, i.e. permutes it randomly.

There's also a ``Random`` class you can instantiate to create independent
multiple random number generators.