Mailman 3 May 2016 - docs

[issue27050] Demote run() below the high level APIs in subprocess docs
by Nick Coghlan May 18, 2016

May 18, 2016

Nick Coghlan added the comment: For reference, http://bugs.python.org/issue13237 covers the original change to emphasise the convenience functions over the full flexibility of Popen. The intent behind that reorganisation was to make it straightforward to get started with the module without needing to first learn what a pipe is (or much of anything about command invocation other than the value of breaking things up into lists to ensure correct quoting). The direct link to the Popen docs in the introductory text was intended to make it easy for advanced users to skip directly to the full Popen docs. In that context, the three convenience operations are "I don't really care if this works or not", "complain loudly if this doesn't work" and "capture the command output, while complaining loudly if it doesn't work". (Not coincidentally, these are roughly comparable to the operations supported by Perl's system() command and backtick expressions, only with exceptions taking the place of the "$?" magic variable) Once a user understands what a pipe is well enough to have an opinion on the usefulness of operations other than the 3 basic ones, then I agree run() makes for a nice improvement over using Popen objects directly (thank you Thomas!), but it's still lower level than the convenience APIs (since you need more prior knowledge in order to use it effectively). I do like David's suggestion of an introductory table providing quick links to the rest of the documentation. Something in the style of the itertools docs would likely be most suitable: https://docs.python.org/3/library/itertools.html Also +1 on thrashing out the details at the PyCon US sprints, although I'll aim to put an initial draft together before then (so Thomas has a chance to comment on it) ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue27050> _______________________________________

1 0

[issue27050] Demote run() below the high level APIs in subprocess docs
by R. David Murray May 18, 2016

May 18, 2016

R. David Murray added the comment: Just as a data point, I always found it confusing when viewing the subprocess docs that I had to page past the 'convenience functions' to get to what I consider to be the "real" docs, the docs for Popen. I rarely use the convenience functions; I find it harder to remember how they work than just using Popen, and in any case I usually end up writing an application-specific 'cmd' function that uses Popen. I haven't tried using run yet, so I don't really have an opinion on that. I suppose its like carrying a swiss army knife in your pocket rather than carrying a steak knife, a pair of scissors, and a screwdriver. If you were carrying a toolbox with *all* the tools, it might be different, but your choices are three tools or the swiss army knife, and to make matters worse those individual tools are really just the swiss army knife in disguise, but it looks different enough to be confusing. Maybe having table of links at the start of the doc would be the most helpful, regardless of how the docs are re-organized. ---------- nosy: +r.david.murray _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue27050> _______________________________________

1 0

[issue27036] Mark up of references in different form
by Serhiy Storchaka May 18, 2016

May 18, 2016

New submission from Serhiy Storchaka: When there is a reference from the term in different form (e.g. in plural), the modified part can be appended outside of the reference: ":term:`bytes-like object`\ s". But this looks not very nice in rendered document, since only a part of the word is undescored. Proposed patch expands similar references to full words: ":term:`bytes-like objects <bytes-like object>`". ---------- assignee: docs@python components: Documentation files: refs_forms.patch keywords: patch messages: 265686 nosy: docs@python, georg.brandl, serhiy.storchaka priority: normal severity: normal stage: patch review status: open title: Mark up of references in different form type: enhancement versions: Python 2.7, Python 3.5, Python 3.6 Added file: http://bugs.python.org/file42869/refs_forms.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue27036> _______________________________________

4 8

[issue27050] Demote run() below the high level APIs in subprocess docs
by Thomas Kluyver May 18, 2016

May 18, 2016

Thomas Kluyver added the comment: I'm obviously biased, but I find the 'high level convenience API' less convenient than the run() function: there are three different functions for the same basic operation, they're not clearly named (check_output is nothing to do with checking output), and there are things that should be simple but they can only do awkwardly (i.e. capturing both output and the exit code). Once I can depend on Python >= 3.5, I hope to never use call/check_call/check_output again. Using run() might make code slightly longer, but I think it also makes it clearer. I accept that the trio can probably never be removed, but this is why I demoted them a long way down the docs. Unfortunately I won't be at PyCon this year to discuss this. ---------- nosy: +takluyver _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue27050> _______________________________________

1 0

[issue27050] Demote run() below the high level APIs in subprocess docs
by Gregory P. Smith May 18, 2016

May 18, 2016

Gregory P. Smith added the comment: FWIW i consider the whole subprocess module doc to be pretty unapproachable and in need of refactoring. Your suggestions sound like good ones. We should sit down and make it sane at pycon. ---------- nosy: +gregory.p.smith _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue27050> _______________________________________

1 0

[issue27050] Demote run() below the high level APIs in subprocess docs
by Nick Coghlan May 17, 2016

May 17, 2016

Nick Coghlan added the comment: Likely revised structure: * Move the high level convenience API back to the first section under a subheading like "Common operations" * Give the new run() function its own subheading like "Flexible command invocation" * Move the exception definitions to the Exceptions subheading * give the stream constants their own subheading after "Frequently Used Arguments" * consider whether or not the "Using the subprocess module" heading level is worthwhile, or whether it makes more sense to pull all its subheading up one level ---------- assignee: -> docs@python components: +Documentation nosy: +docs@python stage: -> needs patch type: -> enhancement versions: +Python 3.5, Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue27050> _______________________________________

1 0

[issue27045] Forward slashes in Windows paths
by Ed Doxtator May 17, 2016

May 17, 2016

New submission from Ed Doxtator: In the documentation for pyvenv (https://docs.python.org/dev/library/venv.html), there is a table that shows by platform the command required to activate a virtual environment by OS. For Windows, the values are: Platform Shell Command to activate virtual environment ------------------------------------------------------------------- Windows cmd.exe C:> <venv>/Scripts/activate.bat PowerShell PS C:> <venv>/Scripts/Activate.ps1 The commands are incorrect-- they contain forward slashes and should be back slashes. ---------- assignee: docs@python components: Documentation messages: 265744 nosy: doc, docs@python priority: normal severity: normal status: open title: Forward slashes in Windows paths type: enhancement versions: Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue27045> _______________________________________

9 8

[issue27049] Typo in "The Python Language Reference" 7.11 -- "individiual"
by RoadrunnerWMC May 17, 2016

May 17, 2016

New submission from RoadrunnerWMC: In the Python 3.3 documentation onward, in "The Python Language Reference" section 7.11 (https://docs.python.org/3/reference/simple_stmts.html#import), the following sentence appears: "When the statement contains multiple clauses (separated by commas) the two steps are carried out separately for each clause, just as though the clauses had been separated out into individiual import statements." The word "individual" is misspelled there as "individiual." ---------- assignee: docs@python components: Documentation messages: 265795 nosy: RoadrunnerWMC, docs@python priority: normal severity: normal status: open title: Typo in "The Python Language Reference" 7.11 -- "individiual" type: behavior versions: Python 3.3, Python 3.4, Python 3.5, Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue27049> _______________________________________

3 2

[issue27042] Incorrect grammar for function definitions
by Eric Wieser May 16, 2016

May 16, 2016

New submission from Eric Wieser: https://docs.python.org/3.2/reference/compound_stmts.html#function-definiti… and onwards say the following decorator ::= "@" dotted_name ["(" [parameter_list [","]] ")"] NEWLINE This is a regression from the 2.7 docs, which correctly said decorator ::= "@" dotted_name ["(" [argument_list [","]] ")"] NEWLINE The implication is that the following is supposedly valid in python 3: @deco(what : "is this" = "supposed to mean") def foo(annotations: "are only for here" = "right?"): pass The interpreter disagrees with the docs, and correctly rejects this syntax as garbage ---------- assignee: docs@python components: Documentation messages: 265735 nosy: Eric.Wieser, docs@python priority: normal severity: normal status: open title: Incorrect grammar for function definitions versions: Python 3.2, Python 3.3, Python 3.4, Python 3.5, Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue27042> _______________________________________

3 4

Re: [docs] Mark up of references in different form (issue 27036)
by storchaka＠gmail.com May 16, 2016

May 16, 2016

Reviewers: vadmium, http://bugs.python.org/review/27036/diff/17256/Doc/library/asyncore.rst File Doc/library/asyncore.rst (right): http://bugs.python.org/review/27036/diff/17256/Doc/library/asyncore.rst#new… Doc/library/asyncore.rst:104: :c:func:`polled <poll>` for read and write events. On 2016/05/16 11:38:10, vadmium wrote: > Would it hurt to just drop the markup? As far as I know it normally just changes > the font, and doesn’t make a link. Ah, I missed that this is just :c:func:. Maybe use references to corresponding functions in the select module? http://bugs.python.org/review/27036/diff/17256/Doc/library/email.headerregi… File Doc/library/email.headerregistry.rst (right): http://bugs.python.org/review/27036/diff/17256/Doc/library/email.headerregi… Doc/library/email.headerregistry.rst:214: ``decoded`` value is set by :attr:`joining <~str.join>` the :class:`str` value of On 2016/05/16 11:38:10, vadmium wrote: > I think you would have to drop the tilde (~) to get the link to work. There are > other changes that also have this problem. Good catch! > But I don’t like this version any better than the original. What about something > like: > > . . . is set to the concatenation of the :class:`str` value of each element > . . ., using :meth:`str.join` and a separator of ``', '``. I don't know. I left this for David. Maybe this sentence should be merged with the first sentence in this paragraph. http://bugs.python.org/review/27036/diff/17256/Doc/library/threading.rst File Doc/library/threading.rst (right): http://bugs.python.org/review/27036/diff/17256/Doc/library/threading.rst#ne… Doc/library/threading.rst:272: A thread can be :meth:`joined <~Thread.join>` many times. Since there are multiple references to Thread.join in surrounding paragraphs, I think it is better to remove this reference. http://bugs.python.org/review/27036/diff/17256/Doc/whatsnew/3.4.rst File Doc/whatsnew/3.4.rst (right): http://bugs.python.org/review/27036/diff/17256/Doc/whatsnew/3.4.rst#newcode… Doc/whatsnew/3.4.rst:1116: mmap objects can now be :mod:`weakrefed <weakref>`. (Contributed by Valerie Lambert in On 2016/05/16 11:38:10, vadmium wrote: > Should probably be spelt “weakreffed” (refed means re-fed as in fed again) > > Maybe “weakly referenced with :mod:`weakref` ”, or similar? What about "mmap objects are now :mod:`weakly referenceable <weakref>`"? Terms "weakly referenceable", "weak referenceable" and "weakly referenced" are already used in the documentation. See also yet one change in this file. Please review this at http://bugs.python.org/review/27036/ Affected files: Doc/library/array.rst Doc/library/asyncore.rst Doc/library/audioop.rst Doc/library/base64.rst Doc/library/binascii.rst Doc/library/doctest.rst Doc/library/email.headerregistry.rst Doc/library/email.rst Doc/library/hashlib.rst Doc/library/http.cookies.rst Doc/library/logging.config.rst Doc/library/logging.rst Doc/library/nntplib.rst Doc/library/threading.rst Doc/library/urllib.request.rst Doc/whatsnew/3.4.rst diff -r 3ceb54a49387 Doc/library/array.rst --- a/Doc/library/array.rst Sat May 07 10:49:58 2016 +0300 +++ b/Doc/library/array.rst Sat May 07 14:38:30 2016 +0300 @@ -91,7 +91,7 @@ Array objects support the ordinary seque concatenation, and multiplication. When using slice assignment, the assigned value must be an array object with the same type code; in all other cases, :exc:`TypeError` is raised. Array objects also implement the buffer interface, -and may be used wherever :term:`bytes-like object`\ s are supported. +and may be used wherever :term:`bytes-like objects <bytes-like object>` are supported. The following data items and methods are also supported: diff -r 3ceb54a49387 Doc/library/asyncore.rst --- a/Doc/library/asyncore.rst Sat May 07 10:49:58 2016 +0300 +++ b/Doc/library/asyncore.rst Sat May 07 14:38:30 2016 +0300 @@ -100,8 +100,8 @@ any that have been added to the map duri During asynchronous processing, each mapped channel's :meth:`readable` and :meth:`writable` methods are used to determine whether the channel's socket - should be added to the list of channels :c:func:`select`\ ed or - :c:func:`poll`\ ed for read and write events. + should be added to the list of channels :c:func:`selected <select>` or + :c:func:`polled <poll>` for read and write events. Thus, the set of channel events is larger than the basic socket events. The full set of methods that can be overridden in your subclass follows: diff -r 3ceb54a49387 Doc/library/audioop.rst --- a/Doc/library/audioop.rst Sat May 07 10:49:58 2016 +0300 +++ b/Doc/library/audioop.rst Sat May 07 14:38:30 2016 +0300 @@ -7,7 +7,7 @@ The :mod:`audioop` module contains some useful operations on sound fragments. It operates on sound fragments consisting of signed integer samples 8, 16, 24 -or 32 bits wide, stored in :term:`bytes-like object`\ s. All scalar items are +or 32 bits wide, stored in :term:`bytes-like objects <bytes-like object>`. All scalar items are integers, unless specified otherwise. .. versionchanged:: 3.4 diff -r 3ceb54a49387 Doc/library/base64.rst --- a/Doc/library/base64.rst Sat May 07 10:49:58 2016 +0300 +++ b/Doc/library/base64.rst Sat May 07 14:38:30 2016 +0300 @@ -40,7 +40,7 @@ package instead. the modern interface. .. versionchanged:: 3.4 - Any :term:`bytes-like object`\ s are now accepted by all + Any :term:`bytes-like objects <bytes-like object>` are now accepted by all encoding and decoding functions in this module. Ascii85/Base85 support added. The modern interface provides: diff -r 3ceb54a49387 Doc/library/binascii.rst --- a/Doc/library/binascii.rst Sat May 07 10:49:58 2016 +0300 +++ b/Doc/library/binascii.rst Sat May 07 14:38:30 2016 +0300 @@ -21,7 +21,7 @@ higher-level modules. .. note:: ``a2b_*`` functions accept Unicode strings containing only ASCII characters. - Other functions only accept :term:`bytes-like object`\ s (such as + Other functions only accept :term:`bytes-like objects <bytes-like object>` (such as :class:`bytes`, :class:`bytearray` and other objects that support the buffer protocol). diff -r 3ceb54a49387 Doc/library/doctest.rst --- a/Doc/library/doctest.rst Sat May 07 10:49:58 2016 +0300 +++ b/Doc/library/doctest.rst Sat May 07 14:38:30 2016 +0300 @@ -464,12 +464,12 @@ Some details you should read once, but w exception name is ignored. * The interactive shell omits the traceback header line for some - :exc:`SyntaxError`\ s. But doctest uses the traceback header line to + :exc:`SyntaxErrors <SyntaxError>`. But doctest uses the traceback header line to distinguish exceptions from non-exceptions. So in the rare case where you need to test a :exc:`SyntaxError` that omits the traceback header, you will need to manually add the traceback header line to your test example. -* For some :exc:`SyntaxError`\ s, Python displays the character position of the +* For some :exc:`SyntaxErrors <SyntaxError>`, Python displays the character position of the syntax error, using a ``^`` marker:: >>> 1 1 @@ -1119,7 +1119,7 @@ the interactive examples extracted from * :class:`Example`: A single Python :term:`statement`, paired with its expected output. -* :class:`DocTest`: A collection of :class:`Example`\ s, typically extracted +* :class:`DocTest`: A collection of :class:`Examples <Example>`, typically extracted from a single docstring or text file. Additional processing classes are defined to find, parse, and run, and check @@ -1277,9 +1277,9 @@ DocTestFinder objects .. class:: DocTestFinder(verbose=False, parser=DocTestParser(), recurse=True, exclude_empty=True) - A processing class used to extract the :class:`DocTest`\ s that are relevant to + A processing class used to extract the :class:`DocTests <DocTest>` that are relevant to a given object, from its docstring and the docstrings of its contained objects. - :class:`DocTest`\ s can be extracted from modules, classes, functions, + :class:`DocTests <DocTest>` can be extracted from modules, classes, functions, methods, staticmethods, classmethods, and properties. The optional argument *verbose* can be used to display the objects searched by @@ -1300,11 +1300,11 @@ DocTestFinder objects .. method:: find(obj[, name][, module][, globs][, extraglobs]) - Return a list of the :class:`DocTest`\ s that are defined by *obj*'s + Return a list of the :class:`DocTests <DocTest>` that are defined by *obj*'s docstring, or by any of its contained objects' docstrings. The optional argument *name* specifies the object's name; this name will be - used to construct names for the returned :class:`DocTest`\ s. If *name* is + used to construct names for the returned :class:`DocTests <DocTest>`. If *name* is not specified, then ``obj.__name__`` is used. The optional parameter *module* is the module that contains the given object. @@ -1370,8 +1370,8 @@ DocTestParser objects .. method:: parse(string, name='<string>') Divide the given string into examples and intervening text, and return them as - a list of alternating :class:`Example`\ s and strings. Line numbers for the - :class:`Example`\ s are 0-based. The optional argument *name* is a name + a list of alternating :class:`Examples <Example>` and strings. Line numbers for the + :class:`Examples <Example>` are 0-based. The optional argument *name* is a name identifying this string, and is only used for error messages. diff -r 3ceb54a49387 Doc/library/email.headerregistry.rst --- a/Doc/library/email.headerregistry.rst Sat May 07 10:49:58 2016 +0300 +++ b/Doc/library/email.headerregistry.rst Sat May 07 14:38:30 2016 +0300 @@ -211,7 +211,7 @@ headers. The ``decoded`` value of the header will have all encoded words decoded to unicode. :class:`~encodings.idna` encoded domain names are also decoded to unicode. The - ``decoded`` value is set by :attr:`~str.join`\ ing the :class:`str` value of + ``decoded`` value is set by :attr:`joining <~str.join>` the :class:`str` value of the elements of the ``groups`` attribute with ``', '``. A list of :class:`.Address` and :class:`.Group` objects in any combination diff -r 3ceb54a49387 Doc/library/email.rst --- a/Doc/library/email.rst Sat May 07 10:49:58 2016 +0300 +++ b/Doc/library/email.rst Sat May 07 14:38:30 2016 +0300 @@ -176,13 +176,13 @@ Here are the major differences between : Problems found while parsing messages are stored in the message's *defect* attribute. -* All aspects of the API which raised :exc:`DeprecationWarning`\ s in version 2 +* All aspects of the API which raised :exc:`DeprecationWarnings <DeprecationWarning>` in version 2 have been removed. These include the *_encoder* argument to the :class:`~email.mime.text.MIMEText` constructor, the :meth:`Message.add_payload` method, the :func:`Utils.dump_address_pair` function, and the functions :func:`Utils.decode` and :func:`Utils.encode`. -* New :exc:`DeprecationWarning`\ s have been added to: +* New :exc:`DeprecationWarnings <DeprecationWarning>` have been added to: :meth:`Generator.__call__`, :meth:`Message.get_type`, :meth:`Message.get_main_type`, :meth:`Message.get_subtype`, and the *strict* argument to the :class:`~email.parser.Parser` class. These are expected to diff -r 3ceb54a49387 Doc/library/hashlib.rst --- a/Doc/library/hashlib.rst Sat May 07 10:49:58 2016 +0300 +++ b/Doc/library/hashlib.rst Sat May 07 14:38:30 2016 +0300 @@ -41,7 +41,7 @@ Hash algorithms There is one constructor method named for each type of :dfn:`hash`. All return a hash object with the same simple interface. For example: use :func:`sha1` to create a SHA1 hash object. You can now feed this object with :term:`bytes-like -object`\ s (normally :class:`bytes`) using the :meth:`update` method. +objects <bytes-like object>` (normally :class:`bytes`) using the :meth:`update` method. At any point you can ask it for the :dfn:`digest` of the concatenation of the data fed to it so far using the :meth:`digest` or :meth:`hexdigest` methods. diff -r 3ceb54a49387 Doc/library/http.cookies.rst --- a/Doc/library/http.cookies.rst Sat May 07 10:49:58 2016 +0300 +++ b/Doc/library/http.cookies.rst Sat May 07 14:38:30 2016 +0300 @@ -109,7 +109,7 @@ Cookie Objects .. method:: BaseCookie.load(rawdata) If *rawdata* is a string, parse it as an ``HTTP_COOKIE`` and add the values - found there as :class:`Morsel`\ s. If it is a dictionary, it is equivalent to:: + found there as :class:`Morsels <Morsel>`. If it is a dictionary, it is equivalent to:: for k, v in rawdata.items(): cookie[k] = v diff -r 3ceb54a49387 Doc/library/logging.config.rst --- a/Doc/library/logging.config.rst Sat May 07 10:49:58 2016 +0300 +++ b/Doc/library/logging.config.rst Sat May 07 14:38:30 2016 +0300 @@ -647,7 +647,7 @@ root logger section is given below. :: The ``level`` entry can be one of ``DEBUG, INFO, WARNING, ERROR, CRITICAL`` or ``NOTSET``. For the root logger only, ``NOTSET`` means that all messages will be -logged. Level values are :func:`eval`\ uated in the context of the ``logging`` +logged. Level values are :func:`evaluated <eval>` in the context of the ``logging`` package's namespace. The ``handlers`` entry is a comma-separated list of handler names, which must @@ -691,7 +691,7 @@ handler. If blank, a default formatter ( If a name is specified, it must appear in the ``[formatters]`` section and have a corresponding section in the configuration file. -The ``args`` entry, when :func:`eval`\ uated in the context of the ``logging`` +The ``args`` entry, when :func:`evaluated <eval>` in the context of the ``logging`` package's namespace, is the list of arguments to the constructor for the handler class. Refer to the constructors for the relevant handlers, or to the examples below, to see how typical entries are constructed. :: diff -r 3ceb54a49387 Doc/library/logging.rst --- a/Doc/library/logging.rst Sat May 07 10:49:58 2016 +0300 +++ b/Doc/library/logging.rst Sat May 07 14:38:30 2016 +0300 @@ -217,7 +217,7 @@ is the module's name in the Python packa many contexts, and interesting conditions which arise are dependent on this context (such as remote client IP address and authenticated user name, in the above example). In such circumstances, it is likely that specialized - :class:`Formatter`\ s would be used with particular :class:`Handler`\ s. + :class:`Formatters <Formatter>` would be used with particular :class:`Handlers <Handler>`. .. versionadded:: 3.2 The *stack_info* parameter was added. @@ -972,7 +972,7 @@ functions. many contexts, and interesting conditions which arise are dependent on this context (such as remote client IP address and authenticated user name, in the above example). In such circumstances, it is likely that specialized - :class:`Formatter`\ s would be used with particular :class:`Handler`\ s. + :class:`Formatters <Formatter>` would be used with particular :class:`Handlers <Handler>`. .. versionadded:: 3.2 The *stack_info* parameter was added. diff -r 3ceb54a49387 Doc/library/nntplib.rst --- a/Doc/library/nntplib.rst Sat May 07 10:49:58 2016 +0300 +++ b/Doc/library/nntplib.rst Sat May 07 14:38:30 2016 +0300 @@ -68,7 +68,7 @@ The module itself defines the following authentication is performed. Reader mode is sometimes necessary if you are connecting to an NNTP server on the local machine and intend to call reader-specific commands, such as ``group``. If you get unexpected - :exc:`NNTPPermanentError`\ s, you might need to set *readermode*. + :exc:`NNTPPermanentErrors <NNTPPermanentError>`, you might need to set *readermode*. The :class:`NNTP` class supports the :keyword:`with` statement to unconditionally consume :exc:`OSError` exceptions and to close the NNTP connection when done, e.g.: diff -r 3ceb54a49387 Doc/library/threading.rst --- a/Doc/library/threading.rst Sat May 07 10:49:58 2016 +0300 +++ b/Doc/library/threading.rst Sat May 07 14:38:30 2016 +0300 @@ -197,7 +197,7 @@ There is the possibility that "dummy thr thread objects corresponding to "alien threads", which are threads of control started outside the threading module, such as directly from C code. Dummy thread objects have limited functionality; they are always considered alive and -daemonic, and cannot be :meth:`~Thread.join`\ ed. They are never deleted, +daemonic, and cannot be :meth:`joined <~Thread.join>`. They are never deleted, since it is impossible to detect the termination of alien threads. @@ -269,7 +269,7 @@ since it is impossible to detect the ter When the *timeout* argument is not present or ``None``, the operation will block until the thread terminates. - A thread can be :meth:`~Thread.join`\ ed many times. + A thread can be :meth:`joined <~Thread.join>` many times. :meth:`~Thread.join` raises a :exc:`RuntimeError` if an attempt is made to join the current thread as that would cause a deadlock. It is also diff -r 3ceb54a49387 Doc/library/urllib.request.rst --- a/Doc/library/urllib.request.rst Sat May 07 10:49:58 2016 +0300 +++ b/Doc/library/urllib.request.rst Sat May 07 14:38:30 2016 +0300 @@ -233,7 +233,7 @@ The following classes are provided: .. class:: OpenerDirector() - The :class:`OpenerDirector` class opens URLs via :class:`BaseHandler`\ s chained + The :class:`OpenerDirector` class opens URLs via :class:`BaseHandlers <BaseHandler>` chained together. It manages the chaining of handlers, and recovery from errors. diff -r 3ceb54a49387 Doc/whatsnew/3.4.rst --- a/Doc/whatsnew/3.4.rst Sat May 07 10:49:58 2016 +0300 +++ b/Doc/whatsnew/3.4.rst Sat May 07 14:38:30 2016 +0300 @@ -1113,7 +1113,7 @@ with additional speedups by Antoine Pitr mmap ---- -mmap objects can now be :mod:`weakref`\ ed. (Contributed by Valerie Lambert in +mmap objects can now be :mod:`weakrefed <weakref>`. (Contributed by Valerie Lambert in :issue:`4885`.) @@ -1136,7 +1136,7 @@ the start method. (Contributed by Richa determines how child processes are created. New function :func:`~multiprocessing.get_context` returns a context that uses a specified start method. It has the same API as the :mod:`multiprocessing` module itself, -so you can use it to create :class:`~multiprocessing.pool.Pool`\ s and other +so you can use it to create :class:`Pools <~multiprocessing.pool.Pool>` and other objects that will operate within that context. This allows a framework and an application or different parts of the same application to use multiprocessing without interfering with each other. (Contributed by Richard Oudkerk in @@ -1698,7 +1698,7 @@ will ensure that a given block of code e :mod:`logging` module. By default the message can come from any logger and have a priority of ``INFO`` or higher, but both the logger name and an alternative minimum logging level may be specified. The object returned by the -context manager can be queried for the :class:`~logging.LogRecord`\ s and/or +context manager can be queried for the :class:`LogRecords <~logging.LogRecord>` and/or formatted messages that were logged. (Contributed by Antoine Pitrou in :issue:`18937`.) @@ -2366,7 +2366,7 @@ Changes in the Python API * :func:`base64.b32decode` now raises a :exc:`binascii.Error` when the input string contains non-b32-alphabet characters, instead of a :exc:`TypeError`. This particular :exc:`TypeError` was missed when the other - :exc:`TypeError`\ s were converted. (Contributed by Serhiy Storchaka in + :exc:`TypeErrors <TypeError>` were converted. (Contributed by Serhiy Storchaka in :issue:`18011`.) Note: this change was also inadvertently applied in Python 3.3.3.

1 0