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#newc... 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.headerregis... File Doc/library/email.headerregistry.rst (right): http://bugs.python.org/review/27036/diff/17256/Doc/library/email.headerregis... 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#new... 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#newcode1... 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.