Remove almost all unpaired backticks in docstrings (#119231)

As reported in #117847 and #115366, an unpaired backtick in a docstring
tends to confuse e.g. Sphinx running on subclasses of standard library
objects, and the typographic style of using a backtick as an opening
quote is no longer in favor. Convert almost all uses of the form

    The variable `foo' should do xyz

to

    The variable 'foo' should do xyz

and also fix up miscellaneous other unpaired backticks (extraneous /
missing characters).

No functional change is intended here other than in human-readable
docstrings.

Author: geofft

Diff for: Lib/_pyrepl/keymap.py

@@ -30,20 +30,20 @@
 pyrepl uses its own keyspec format that is meant to be a strict superset of
 readline's KEYSEQ format. This means that if a spec is found that readline
 accepts that this doesn't, it should be logged as a bug. Note that this means
-we're using the `\\C-o' style of readline's keyspec, not the `Control-o' sort.
+we're using the '\\C-o' style of readline's keyspec, not the 'Control-o' sort.
 
 The extension to readline is that the sequence \\<KEY> denotes the
 sequence of characters produced by hitting KEY.
 
 Examples:
-`a'      - what you get when you hit the `a' key
-`\\EOA'  - Escape - O - A (up, on my terminal)
-`\\<UP>' - the up arrow key
-`\\<up>' - ditto (keynames are case-insensitive)
-`\\C-o', `\\c-o'  - control-o
-`\\M-.'  - meta-period
-`\\E.'   - ditto (that's how meta works for pyrepl)
-`\\<tab>', `\\<TAB>', `\\t', `\\011', '\\x09', '\\X09', '\\C-i', '\\C-I'
+'a'      - what you get when you hit the 'a' key
+'\\EOA'  - Escape - O - A (up, on my terminal)
+'\\<UP>' - the up arrow key
+'\\<up>' - ditto (keynames are case-insensitive)
+'\\C-o', '\\c-o'  - control-o
+'\\M-.'  - meta-period
+'\\E.'   - ditto (that's how meta works for pyrepl)
+'\\<tab>', '\\<TAB>', '\\t', '\\011', '\\x09', '\\X09', '\\C-i', '\\C-I'
    - all of these are the tab character.
 """
 

Diff for: Lib/_pyrepl/reader.py

@@ -171,15 +171,15 @@ class Reader:
       * console:
         Hopefully encapsulates the OS dependent stuff.
       * pos:
-        A 0-based index into `buffer' for where the insertion point
+        A 0-based index into 'buffer' for where the insertion point
         is.
       * screeninfo:
         Ahem.  This list contains some info needed to move the
         insertion point around reasonably efficiently.
       * cxy, lxy:
         the position of the insertion point in screen ...
       * syntax_table:
-        Dictionary mapping characters to `syntax class'; read the
+        Dictionary mapping characters to 'syntax class'; read the
         emacs docs to see what this means :-)
       * commands:
         Dictionary mapping command names to command classes.
@@ -431,7 +431,7 @@ def max_row(self) -> int:
 
     def get_arg(self, default: int = 1) -> int:
         """Return any prefix argument that the user has supplied,
-        returning `default' if there is None.  Defaults to 1.
+        returning 'default' if there is None.  Defaults to 1.
         """
         if self.arg is None:
             return default
@@ -440,7 +440,7 @@ def get_arg(self, default: int = 1) -> int:
 
     def get_prompt(self, lineno: int, cursor_on_line: bool) -> str:
         """Return what should be in the left-hand margin for line
-        `lineno'."""
+        'lineno'."""
         if self.arg is not None and cursor_on_line:
             prompt = "(arg: %s) " % self.arg
         elif self.paste_mode:

Diff for: Lib/cmd.py

@@ -5,16 +5,16 @@
 1. End of file on input is processed as the command 'EOF'.
 2. A command is parsed out of each line by collecting the prefix composed
    of characters in the identchars member.
-3. A command `foo' is dispatched to a method 'do_foo()'; the do_ method
+3. A command 'foo' is dispatched to a method 'do_foo()'; the do_ method
    is passed a single argument consisting of the remainder of the line.
 4. Typing an empty line repeats the last command.  (Actually, it calls the
-   method `emptyline', which may be overridden in a subclass.)
-5. There is a predefined `help' method.  Given an argument `topic', it
-   calls the command `help_topic'.  With no arguments, it lists all topics
+   method 'emptyline', which may be overridden in a subclass.)
+5. There is a predefined 'help' method.  Given an argument 'topic', it
+   calls the command 'help_topic'.  With no arguments, it lists all topics
    with defined help_ functions, broken into up to three topics; documented
    commands, miscellaneous help topics, and undocumented commands.
-6. The command '?' is a synonym for `help'.  The command '!' is a synonym
-   for `shell', if a do_shell method exists.
+6. The command '?' is a synonym for 'help'.  The command '!' is a synonym
+   for 'shell', if a do_shell method exists.
 7. If completion is enabled, completing commands will be done automatically,
    and completing of commands args is done by calling complete_foo() with
    arguments text, line, begidx, endidx.  text is string we are matching
@@ -23,21 +23,21 @@
    indexes of the text being matched, which could be used to provide
    different completion depending upon which position the argument is in.
 
-The `default' method may be overridden to intercept commands for which there
+The 'default' method may be overridden to intercept commands for which there
 is no do_ method.
 
-The `completedefault' method may be overridden to intercept completions for
+The 'completedefault' method may be overridden to intercept completions for
 commands that have no complete_ method.
 
-The data member `self.ruler' sets the character used to draw separator lines
+The data member 'self.ruler' sets the character used to draw separator lines
 in the help messages.  If empty, no ruler line is drawn.  It defaults to "=".
 
-If the value of `self.intro' is nonempty when the cmdloop method is called,
+If the value of 'self.intro' is nonempty when the cmdloop method is called,
 it is printed out on interpreter startup.  This value may be overridden
 via an optional argument to the cmdloop() method.
 
-The data members `self.doc_header', `self.misc_header', and
-`self.undoc_header' set the headers used for the help function's
+The data members 'self.doc_header', 'self.misc_header', and
+'self.undoc_header' set the headers used for the help function's
 listings of documented functions, miscellaneous topics, and undocumented
 functions respectively.
 """

Diff for: Lib/configparser.py

@@ -957,7 +957,7 @@ def write(self, fp, space_around_delimiters=True):
                                 self._sections[section].items(), d)
 
     def _write_section(self, fp, section_name, section_items, delimiter, unnamed=False):
-        """Write a single section to the specified `fp'."""
+        """Write a single section to the specified 'fp'."""
         if not unnamed:
             fp.write("[{}]\n".format(section_name))
         for key, value in section_items:

Diff for: Lib/doctest.py

@@ -1227,7 +1227,7 @@ class DocTestRunner:
     `OutputChecker` to the constructor.
 
     The test runner's display output can be controlled in two ways.
-    First, an output function (`out) can be passed to
+    First, an output function (`out`) can be passed to
     `TestRunner.run`; this function will be called with strings that
     should be displayed.  It defaults to `sys.stdout.write`.  If
     capturing the output is not sufficient, then the display output
@@ -2734,7 +2734,7 @@ def testsource(module, name):
     return testsrc
 
 def debug_src(src, pm=False, globs=None):
-    """Debug a single doctest docstring, in argument `src`'"""
+    """Debug a single doctest docstring, in argument `src`"""
     testsrc = script_from_examples(src)
     debug_script(testsrc, pm, globs)
 

Diff for: Lib/email/_parseaddr.py

@@ -224,7 +224,7 @@ class AddrlistClass:
     def __init__(self, field):
         """Initialize a new instance.
 
-        `field' is an unparsed address header field, containing
+        'field' is an unparsed address header field, containing
         one or more addresses.
         """
         self.specials = '()<>@,:;.\"[]'
@@ -233,7 +233,7 @@ def __init__(self, field):
         self.CR = '\r\n'
         self.FWS = self.LWS + self.CR
         self.atomends = self.specials + self.LWS + self.CR
-        # Note that RFC 2822 now specifies `.' as obs-phrase, meaning that it
+        # Note that RFC 2822 now specifies '.' as obs-phrase, meaning that it
         # is obsolete syntax.  RFC 2822 requires that we recognize obsolete
         # syntax, so allow dots in phrases.
         self.phraseends = self.atomends.replace('.', '')
@@ -423,14 +423,14 @@ def getdomain(self):
     def getdelimited(self, beginchar, endchars, allowcomments=True):
         """Parse a header fragment delimited by special characters.
 
-        `beginchar' is the start character for the fragment.
-        If self is not looking at an instance of `beginchar' then
+        'beginchar' is the start character for the fragment.
+        If self is not looking at an instance of 'beginchar' then
         getdelimited returns the empty string.
 
-        `endchars' is a sequence of allowable end-delimiting characters.
+        'endchars' is a sequence of allowable end-delimiting characters.
         Parsing stops when one of these is encountered.
 
-        If `allowcomments' is non-zero, embedded RFC 2822 comments are allowed
+        If 'allowcomments' is non-zero, embedded RFC 2822 comments are allowed
         within the parsed fragment.
         """
         if self.field[self.pos] != beginchar:
@@ -474,7 +474,7 @@ def getatom(self, atomends=None):
 
         Optional atomends specifies a different set of end token delimiters
         (the default is to use self.atomends).  This is used e.g. in
-        getphraselist() since phrase endings must not include the `.' (which
+        getphraselist() since phrase endings must not include the '.' (which
         is legal in phrases)."""
         atomlist = ['']
         if atomends is None:

Diff for: Lib/email/_policybase.py

@@ -150,7 +150,7 @@ class Policy(_PolicyBase, metaclass=abc.ABCMeta):
                            wrapping is done.  Default is 78.
 
     mangle_from_        -- a flag that, when True escapes From_ lines in the
-                           body of the message by putting a `>' in front of
+                           body of the message by putting a '>' in front of
                            them. This is used when the message is being
                            serialized by a generator. Default: False.
 

Diff for: Lib/email/base64mime.py

@@ -15,7 +15,7 @@
 with Base64 encoding.
 
 RFC 2045 defines a method for including character set information in an
-`encoded-word' in a header.  This method is commonly used for 8-bit real names
+'encoded-word' in a header.  This method is commonly used for 8-bit real names
 in To:, From:, Cc:, etc. fields, as well as Subject: lines.
 
 This module does not do the line wrapping or end-of-line character conversion

Diff for: Lib/email/charset.py

@@ -175,7 +175,7 @@ class Charset:
     module expose the following information about a character set:
 
     input_charset: The initial character set specified.  Common aliases
-                   are converted to their `official' email names (e.g. latin_1
+                   are converted to their 'official' email names (e.g. latin_1
                    is converted to iso-8859-1).  Defaults to 7-bit us-ascii.
 
     header_encoding: If the character set must be encoded before it can be
@@ -245,7 +245,7 @@ def __eq__(self, other):
     def get_body_encoding(self):
         """Return the content-transfer-encoding used for body encoding.
 
-        This is either the string `quoted-printable' or `base64' depending on
+        This is either the string 'quoted-printable' or 'base64' depending on
         the encoding used, or it is a function in which case you should call
         the function with a single argument, the Message object being
         encoded.  The function should then set the Content-Transfer-Encoding

Diff for: Lib/email/generator.py

@@ -41,7 +41,7 @@ def __init__(self, outfp, mangle_from_=None, maxheaderlen=None, *,
 
         Optional mangle_from_ is a flag that, when True (the default if policy
         is not set), escapes From_ lines in the body of the message by putting
-        a `>' in front of them.
+        a '>' in front of them.
 
         Optional maxheaderlen specifies the longest length for a non-continued
         header.  When a header line is longer (in characters, with tabs
@@ -74,7 +74,7 @@ def flatten(self, msg, unixfrom=False, linesep=None):
 
         unixfrom is a flag that forces the printing of a Unix From_ delimiter
         before the first object in the message tree.  If the original message
-        has no From_ delimiter, a `standard' one is crafted.  By default, this
+        has no From_ delimiter, a 'standard' one is crafted.  By default, this
         is False to inhibit the printing of any From_ delimiter.
 
         Note that for subobjects, no From_ line is printed.
@@ -456,7 +456,7 @@ def __init__(self, outfp, mangle_from_=None, maxheaderlen=None, fmt=None, *,
         argument is allowed.
 
         Walks through all subparts of a message.  If the subpart is of main
-        type `text', then it prints the decoded payload of the subpart.
+        type 'text', then it prints the decoded payload of the subpart.
 
         Otherwise, fmt is a format string that is used instead of the message
         payload.  fmt is expanded with the following keywords (in

Diff for: Lib/email/header.py

@@ -192,7 +192,7 @@ def __init__(self, s=None, charset=None,
 
         The maximum line length can be specified explicitly via maxlinelen. For
         splitting the first line to a shorter value (to account for the field
-        header which isn't included in s, e.g. `Subject') pass in the name of
+        header which isn't included in s, e.g. 'Subject') pass in the name of
         the field in header_name.  The default maxlinelen is 78 as recommended
         by RFC 2822.
 
@@ -276,7 +276,7 @@ def append(self, s, charset=None, errors='strict'):
         output codec of the charset.  If the string cannot be encoded to the
         output codec, a UnicodeError will be raised.
 
-        Optional `errors' is passed as the errors argument to the decode
+        Optional 'errors' is passed as the errors argument to the decode
         call if s is a byte string.
         """
         if charset is None:
@@ -326,7 +326,7 @@ def encode(self, splitchars=';, \t', maxlinelen=None, linesep='\n'):
 
         Optional splitchars is a string containing characters which should be
         given extra weight by the splitting algorithm during normal header
-        wrapping.  This is in very rough support of RFC 2822's `higher level
+        wrapping.  This is in very rough support of RFC 2822's 'higher level
         syntactic breaks':  split points preceded by a splitchar are preferred
         during line splitting, with the characters preferred in the order in
         which they appear in the string.  Space and tab may be included in the

Diff for: Lib/email/iterators.py

@@ -43,8 +43,8 @@ def body_line_iterator(msg, decode=False):
 def typed_subpart_iterator(msg, maintype='text', subtype=None):
     """Iterate over the subparts with a given MIME type.
 
-    Use `maintype' as the main MIME type to match against; this defaults to
-    "text".  Optional `subtype' is the MIME subtype to match against; if
+    Use 'maintype' as the main MIME type to match against; this defaults to
+    "text".  Optional 'subtype' is the MIME subtype to match against; if
     omitted, only the main type is matched.
     """
     for subpart in msg.walk():

Diff for: Lib/email/message.py

@@ -21,7 +21,7 @@
 
 SEMISPACE = '; '
 
-# Regular expression that matches `special' characters in parameters, the
+# Regular expression that matches 'special' characters in parameters, the
 # existence of which force quoting of the parameter value.
 tspecials = re.compile(r'[ \(\)<>@,;:\\"/\[\]\?=]')
 
@@ -141,7 +141,7 @@ class Message:
     multipart or a message/rfc822), then the payload is a list of Message
     objects, otherwise it is a string.
 
-    Message objects implement part of the `mapping' interface, which assumes
+    Message objects implement part of the 'mapping' interface, which assumes
     there is exactly one occurrence of the header per message.  Some headers
     do in fact appear multiple times (e.g. Received) and for those headers,
     you must use the explicit API to set or get all the headers.  Not all of
@@ -597,7 +597,7 @@ def get_content_type(self):
         """Return the message's content type.
 
         The returned string is coerced to lower case of the form
-        `maintype/subtype'.  If there was no Content-Type header in the
+        'maintype/subtype'.  If there was no Content-Type header in the
         message, the default type as given by get_default_type() will be
         returned.  Since according to RFC 2045, messages always have a default
         type this will always return a value.
@@ -620,7 +620,7 @@ def get_content_type(self):
     def get_content_maintype(self):
         """Return the message's main content type.
 
-        This is the `maintype' part of the string returned by
+        This is the 'maintype' part of the string returned by
         get_content_type().
         """
         ctype = self.get_content_type()
@@ -629,14 +629,14 @@ def get_content_maintype(self):
     def get_content_subtype(self):
         """Returns the message's sub-content type.
 
-        This is the `subtype' part of the string returned by
+        This is the 'subtype' part of the string returned by
         get_content_type().
         """
         ctype = self.get_content_type()
         return ctype.split('/')[1]
 
     def get_default_type(self):
-        """Return the `default' content type.
+        """Return the 'default' content type.
 
         Most messages have a default content type of text/plain, except for
         messages that are subparts of multipart/digest containers.  Such
@@ -645,7 +645,7 @@ def get_default_type(self):
         return self._default_type
 
     def set_default_type(self, ctype):
-        """Set the `default' content type.
+        """Set the 'default' content type.
 
         ctype should be either "text/plain" or "message/rfc822", although this
         is not enforced.  The default content type is not stored in the
@@ -678,8 +678,8 @@ def get_params(self, failobj=None, header='content-type', unquote=True):
         """Return the message's Content-Type parameters, as a list.
 
         The elements of the returned list are 2-tuples of key/value pairs, as
-        split on the `=' sign.  The left hand side of the `=' is the key,
-        while the right hand side is the value.  If there is no `=' sign in
+        split on the '=' sign.  The left hand side of the '=' is the key,
+        while the right hand side is the value.  If there is no '=' sign in
         the parameter the value is the empty string.  The value is as
         described in the get_param() method.
 
@@ -839,9 +839,9 @@ def get_filename(self, failobj=None):
         """Return the filename associated with the payload if present.
 
         The filename is extracted from the Content-Disposition header's
-        `filename' parameter, and it is unquoted.  If that header is missing
-        the `filename' parameter, this method falls back to looking for the
-        `name' parameter.
+        'filename' parameter, and it is unquoted.  If that header is missing
+        the 'filename' parameter, this method falls back to looking for the
+        'name' parameter.
         """
         missing = object()
         filename = self.get_param('filename', missing, 'content-disposition')
@@ -854,7 +854,7 @@ def get_filename(self, failobj=None):
     def get_boundary(self, failobj=None):
         """Return the boundary associated with the payload if present.
 
-        The boundary is extracted from the Content-Type header's `boundary'
+        The boundary is extracted from the Content-Type header's 'boundary'
         parameter, and it is unquoted.
         """
         missing = object()

Diff for: Lib/email/mime/multipart.py

@@ -21,7 +21,7 @@ def __init__(self, _subtype='mixed', boundary=None, _subparts=None,
         Content-Type and MIME-Version headers.
 
         _subtype is the subtype of the multipart content type, defaulting to
-        `mixed'.
+        'mixed'.
 
         boundary is the multipart boundary string.  By default it is
         calculated as needed.