Convert all "i" docs to new style optional args.

9 files changed, 50 insertions, 55 deletions

diff --git a/Doc/library/imaplib.rst b/Doc/library/imaplib.rst
index 3cbb45c..b8ac03d 100644
--- a/Doc/library/imaplib.rst
+++ b/Doc/library/imaplib.rst
@@ -26,7 +26,7 @@ Three classes are provided by the :mod:`imaplib` module, :class:`IMAP4` is the
 base class:
 
 
-.. class:: IMAP4([host[, port]])
+.. class:: IMAP4(host='', port=IMAP4_PORT)
 
    This class implements the actual IMAP4 protocol.  The connection is created and
    protocol version (IMAP4 or IMAP4rev1) is determined when the instance is
@@ -59,7 +59,7 @@ Three exceptions are defined as attributes of the :class:`IMAP4` class:
 There's also a subclass for secure connections:
 
 
-.. class:: IMAP4_SSL([host[, port[, keyfile[, certfile]]]])
+.. class:: IMAP4_SSL(host='', port=IMAP4_SSL_PORT, keyfile=None, certfile=None)
 
    This is a subclass derived from :class:`IMAP4` that connects over an SSL
    encrypted socket (to use this class you need a socket module that was compiled
@@ -264,7 +264,7 @@ An :class:`IMAP4` instance has the following methods:
    Shutdown connection to server. Returns server ``BYE`` response.
 
 
-.. method:: IMAP4.lsub([directory[, pattern]])
+.. method:: IMAP4.lsub(directory='""', pattern='*')
 
    List subscribed mailbox names in directory matching pattern. *directory*
    defaults to the top level directory and *pattern* defaults to match any mailbox.
@@ -348,7 +348,7 @@ An :class:`IMAP4` instance has the following methods:
       typ, msgnums = M.search(None, '(FROM "LDJ")')
 
 
-.. method:: IMAP4.select([mailbox[, readonly]])
+.. method:: IMAP4.select(mailbox='INBOX', readonly=False)
 
    Select a mailbox. Returned data is the count of messages in *mailbox*
    (``EXISTS`` response).  The default *mailbox* is ``'INBOX'``.  If the *readonly*
@@ -464,12 +464,12 @@ An :class:`IMAP4` instance has the following methods:
    Unsubscribe from old mailbox.
 
 
-.. method:: IMAP4.xatom(name[, arg[, ...]])
+.. method:: IMAP4.xatom(name[, ...])
 
    Allow simple extension commands notified by server in ``CAPABILITY`` response.
 
-The following attributes are defined on instances of :class:`IMAP4`:
 
+The following attributes are defined on instances of :class:`IMAP4`:
 
 .. attribute:: IMAP4.PROTOCOL_VERSION
 
diff --git a/Doc/library/imghdr.rst b/Doc/library/imghdr.rst
index d533a3e..0c0722d 100644
--- a/Doc/library/imghdr.rst
+++ b/Doc/library/imghdr.rst
@@ -1,4 +1,3 @@
-
 :mod:`imghdr` --- Determine the type of an image
 ================================================
 
@@ -12,7 +11,7 @@ byte stream.
 The :mod:`imghdr` module defines the following function:
 
 
-.. function:: what(filename[, h])
+.. function:: what(filename, h=None)
 
    Tests the image data contained in the file named by *filename*, and returns a
    string describing the image type.  If optional *h* is provided, the *filename*
diff --git a/Doc/library/imp.rst b/Doc/library/imp.rst
index eacb4bb..06cfefc 100644
--- a/Doc/library/imp.rst
+++ b/Doc/library/imp.rst
@@ -1,4 +1,3 @@
-
 :mod:`imp` --- Access the :keyword:`import` internals
 =====================================================
 
diff --git a/Doc/library/inspect.rst b/Doc/library/inspect.rst
index f002994..03bdf3e 100644
--- a/Doc/library/inspect.rst
+++ b/Doc/library/inspect.rst
@@ -1,4 +1,3 @@
-
 :mod:`inspect` --- Inspect live objects
 =======================================
 
@@ -215,7 +214,8 @@ attributes:
 
 .. function:: isfunction(object)
 
-   Return true if the object is a Python function or unnamed (:term:`lambda`) function.
+   Return true if the object is a Python function or unnamed (:term:`lambda`)
+   function.
 
 
 .. function:: isgeneratorfunction(object)
@@ -370,8 +370,7 @@ Retrieving source code
 Classes and functions
 ---------------------
 
-
-.. function:: getclasstree(classes[, unique])
+.. function:: getclasstree(classes, unique=False)
 
    Arrange the given list of classes into a hierarchy of nested lists. Where a
    nested list appears, it contains classes derived from the class whose entry
@@ -399,10 +398,11 @@ Classes and functions
 
 .. function:: getfullargspec(func)
 
-   Get the names and default values of a function's arguments.  A :term:`named tuple`
-   is returned:
+   Get the names and default values of a function's arguments.  A :term:`named
+   tuple` is returned:
 
-   ``FullArgSpec(args, varargs, varkw, defaults, kwonlyargs, kwonlydefaults, annotations)``
+   ``FullArgSpec(args, varargs, varkw, defaults, kwonlyargs, kwonlydefaults,
+   annotations)``
 
    *args* is a list of the argument names.  *varargs* and *varkw* are the names
    of the ``*`` and ``**`` arguments or ``None``.  *defaults* is an n-tuple of
@@ -416,11 +416,11 @@ Classes and functions
 
 .. function:: getargvalues(frame)
 
-   Get information about arguments passed into a particular frame. A :term:`named tuple`
-   ``ArgInfo(args, varargs, keywords, locals)`` is returned. *args* is a list of the
-   argument names (it may contain nested lists). *varargs* and *varkw* are the
-   names of the ``*`` and ``**`` arguments or ``None``. *locals* is the locals
-   dictionary of the given frame.
+   Get information about arguments passed into a particular frame.  A
+   :term:`named tuple` ``ArgInfo(args, varargs, keywords, locals)`` is
+   returned. *args* is a list of the argument names (it may contain nested
+   lists). *varargs* and *varkw* are the names of the ``*`` and ``**`` arguments
+   or ``None``. *locals* is the locals dictionary of the given frame.
 
 
 .. function:: formatargspec(args[, varargs, varkw, defaults, formatarg, formatvarargs, formatvarkw, formatvalue, join])
@@ -482,13 +482,13 @@ the number of lines of context to return, which are centered around the current
 line.
 
 
-.. function:: getframeinfo(frame[, context])
+.. function:: getframeinfo(frame, context=1)
 
    Get information about a frame or traceback object.  A :term:`named tuple`
    ``Traceback(filename, lineno, function, code_context, index)`` is returned.
 
 
-.. function:: getouterframes(frame[, context])
+.. function:: getouterframes(frame, context=1)
 
    Get a list of frame records for a frame and all outer frames.  These frames
    represent the calls that lead to the creation of *frame*. The first entry in the
@@ -496,7 +496,7 @@ line.
    on *frame*'s stack.
 
 
-.. function:: getinnerframes(traceback[, context])
+.. function:: getinnerframes(traceback, context=1)
 
    Get a list of frame records for a traceback's frame and all inner frames.  These
    frames represent calls made as a consequence of *frame*.  The first entry in the
@@ -509,14 +509,14 @@ line.
    Return the frame object for the caller's stack frame.
 
 
-.. function:: stack([context])
+.. function:: stack(context=1)
 
    Return a list of frame records for the caller's stack.  The first entry in the
    returned list represents the caller; the last entry represents the outermost
    call on the stack.
 
 
-.. function:: trace([context])
+.. function:: trace(context=1)
 
    Return a list of frame records for the stack between the current frame and the
    frame in which an exception currently being handled was raised in.  The first
diff --git a/Doc/library/internet.rst b/Doc/library/internet.rst
index c5c02ac..288ea7b 100644
--- a/Doc/library/internet.rst
+++ b/Doc/library/internet.rst
@@ -1,4 +1,3 @@
-
 .. _internet:
 
 ******************************
diff --git a/Doc/library/intro.rst b/Doc/library/intro.rst
index 33bdefd..ce1691d 100644
--- a/Doc/library/intro.rst
+++ b/Doc/library/intro.rst
@@ -1,4 +1,3 @@
-
 .. _library-intro:
 
 ************
diff --git a/Doc/library/io.rst b/Doc/library/io.rst
index 2a3ee50..d8a498b 100644
--- a/Doc/library/io.rst
+++ b/Doc/library/io.rst
@@ -51,7 +51,7 @@ Module Interface
    classes.  :func:`open` uses the file's blksize (as obtained by
    :func:`os.stat`) if possible.
 
-.. function:: open(file[, mode[, buffering[, encoding[, errors[, newline[, closefd=True]]]]]])
+.. function:: open(file, mode='r', buffering=None, encoding=None, errors=None, newline=None, closefd=True)
 
    Open *file* and return a corresponding stream.  If the file cannot be opened,
    an :exc:`IOError` is raised.
@@ -250,7 +250,7 @@ I/O Base Classes
       Return ``True`` if the stream can be read from.  If False, :meth:`read`
       will raise :exc:`IOError`.
 
-   .. method:: readline([limit])
+   .. method:: readline(limit=-1)
 
       Read and return one line from the stream.  If *limit* is specified, at
       most *limit* bytes will be read.
@@ -259,13 +259,13 @@ I/O Base Classes
       the *newlines* argument to :func:`open` can be used to select the line
       terminator(s) recognized.
 
-   .. method:: readlines([hint])
+   .. method:: readlines(hint=-1)
 
       Read and return a list of lines from the stream.  *hint* can be specified
       to control the number of lines read: no more lines will be read if the
       total size (in bytes/characters) of all lines so far exceeds *hint*.
 
-   .. method:: seek(offset[, whence])
+   .. method:: seek(offset, whence=SEEK_SET)
 
       Change the stream position to the given byte *offset*.  *offset* is
       interpreted relative to the position indicated by *whence*.  Values for
@@ -292,7 +292,7 @@ I/O Base Classes
 
       Return the current stream position.
 
-   .. method:: truncate([size])
+   .. method:: truncate(size=None)
 
       Truncate the file to at most *size* bytes.  *size* defaults to the current
       file position, as returned by :meth:`tell`.
@@ -317,7 +317,7 @@ I/O Base Classes
    In addition to the attributes and methods from :class:`IOBase`,
    RawIOBase provides the following methods:
 
-   .. method:: read([n])
+   .. method:: read(n=-1)
 
       Read and return all the bytes from the stream until EOF, or if *n* is
       specified, up to *n* bytes.  Only one system call is ever made.  An empty
@@ -375,7 +375,7 @@ I/O Base Classes
 
       .. versionadded:: 3.1
 
-   .. method:: read([n])
+   .. method:: read(n=-1)
 
       Read and return up to *n* bytes.  If the argument is omitted, ``None``, or
       negative, data is read and returned until EOF is reached.  An empty bytes
@@ -390,7 +390,7 @@ I/O Base Classes
       A :exc:`BlockingIOError` is raised if the underlying raw stream has no
       data at the moment.
 
-   .. method:: read1([n])
+   .. method:: read1(n=-1)
 
       Read and return up to *n* bytes, with at most one call to the underlying
       raw stream's :meth:`~RawIOBase.read` method.
@@ -419,7 +419,7 @@ I/O Base Classes
 Raw File I/O
 ------------
 
-.. class:: FileIO(name[, mode])
+.. class:: FileIO(name, mode='r', closefd=True)
 
    :class:`FileIO` represents a file containing bytes data.  It implements
    the :class:`RawIOBase` interface (and therefore the :class:`IOBase`
@@ -443,7 +443,7 @@ Raw File I/O
       The file name.  This is the file descriptor of the file when no name is
       given in the constructor.
 
-   .. method:: read([n])
+   .. method:: read(n=-1)
 
       Read and return at most *n* bytes.  Only one system call is made, so it is
       possible that less data than was requested is returned.  Use :func:`len`
@@ -490,7 +490,7 @@ Buffered Streams
       current stream position, as returned by :meth:`tell`.
 
 
-.. class:: BufferedReader(raw[, buffer_size])
+.. class:: BufferedReader(raw, buffer_size=DEFAULT_BUFFER_SIZE)
 
    A buffer for a readable, sequential :class:`RawIOBase` object.  It inherits
    :class:`BufferedIOBase`.
@@ -522,7 +522,7 @@ Buffered Streams
       Otherwise, one raw stream read call is made.
 
 
-.. class:: BufferedWriter(raw[, buffer_size[, max_buffer_size]])
+.. class:: BufferedWriter(raw, buffer_size=DEFAULT_BUFFER_SIZE)
 
    A buffer for a writeable sequential RawIO object.  It inherits
    :class:`BufferedIOBase`.
@@ -531,7 +531,7 @@ Buffered Streams
    *raw* stream.  If the *buffer_size* is not given, it defaults to
    :data:`DEFAULT_BUFFER_SIZE`.
 
-   *max_buffer_size* is unused and deprecated.
+   A third argument, *max_buffer_size*, is supported, but unused and deprecated.
 
    :class:`BufferedWriter` provides or overrides these methods in addition to
    those from :class:`BufferedIOBase` and :class:`IOBase`:
@@ -548,7 +548,7 @@ Buffered Streams
       raw stream blocks.
 
 
-.. class:: BufferedRWPair(reader, writer[, buffer_size[, max_buffer_size]])
+.. class:: BufferedRWPair(reader, writer, buffer_size, max_buffer_size=DEFAULT_BUFFER_SIZE)
 
    A combined buffered writer and reader object for a raw stream that can be
    written to and read from.  It has and supports both :meth:`read`, :meth:`write`,
@@ -559,14 +559,15 @@ Buffered Streams
    writeable respectively.  If the *buffer_size* is omitted it defaults to
    :data:`DEFAULT_BUFFER_SIZE`.
 
-   *max_buffer_size* is unused and deprecated.
+   A fourth argument, *max_buffer_size*, is supported, but unused and
+   deprecated.
 
    :class:`BufferedRWPair` implements all of :class:`BufferedIOBase`\'s methods
    except for :meth:`~BufferedIOBase.detach`, which raises
    :exc:`UnsupportedOperation`.
 
 
-.. class:: BufferedRandom(raw[, buffer_size[, max_buffer_size]])
+.. class:: BufferedRandom(raw, buffer_size=DEFAULT_BUFFER_SIZE)
 
    A buffered interface to random access streams.  It inherits
    :class:`BufferedReader` and :class:`BufferedWriter`.
@@ -575,7 +576,7 @@ Buffered Streams
    in the first argument.  If the *buffer_size* is omitted it defaults to
    :data:`DEFAULT_BUFFER_SIZE`.
 
-   *max_buffer_size* is unused and deprecated.
+   A third argument, *max_buffer_size*, is supported, but unused and deprecated.
 
    :class:`BufferedRandom` is capable of anything :class:`BufferedReader` or
    :class:`BufferedWriter` can do.
@@ -633,7 +634,7 @@ Text I/O
       written.
 
 
-.. class:: TextIOWrapper(buffer[, encoding[, errors[, newline[, line_buffering]]]])
+.. class:: TextIOWrapper(buffer, encoding=None, errors=None, newline=None, line_buffering=False)
 
    A buffered text stream over a :class:`BufferedIOBase` raw stream, *buffer*.
    It inherits :class:`TextIOBase`.
@@ -676,7 +677,7 @@ Text I/O
       Whether line buffering is enabled.
 
 
-.. class:: StringIO([initial_value[, newline]])
+.. class:: StringIO(initial_value='', newline=None)
 
    An in-memory stream for text.  It inherits :class:`TextIOWrapper`.
 
diff --git a/Doc/library/ipc.rst b/Doc/library/ipc.rst
index 86a66f1..c873065 100644
--- a/Doc/library/ipc.rst
+++ b/Doc/library/ipc.rst
@@ -1,4 +1,3 @@
-
 .. _ipc:
 
 *****************************************
diff --git a/Doc/library/itertools.rst b/Doc/library/itertools.rst
index fa4484d..e6a9fe2 100644
--- a/Doc/library/itertools.rst
+++ b/Doc/library/itertools.rst
@@ -1,4 +1,3 @@
-
 :mod:`itertools` --- Functions creating iterators for efficient looping
 =======================================================================
 
@@ -291,7 +290,7 @@ loops that truncate the stream.
                   yield x
 
 
-.. function:: groupby(iterable[, key])
+.. function:: groupby(iterable, key=None)
 
    Make an iterator that returns consecutive keys and groups from the *iterable*.
    The *key* is a function computing a key value for each element.  If not
@@ -372,7 +371,7 @@ loops that truncate the stream.
    then the step defaults to one.
 
 
-.. function:: permutations(iterable[, r])
+.. function:: permutations(iterable, r=None)
 
    Return successive *r* length permutations of elements in the *iterable*.
 
@@ -430,7 +429,7 @@ loops that truncate the stream.
    The number of items returned is ``n! / (n-r)!`` when ``0 <= r <= n``
    or zero when ``r > n``.
 
-.. function:: product(*iterables[, repeat])
+.. function:: product(*iterables, repeat=1)
 
    Cartesian product of input iterables.
 
@@ -460,7 +459,7 @@ loops that truncate the stream.
                yield tuple(prod)
 
 
-.. function:: repeat(object[, times])
+.. function:: repeat(object, times=-1)
 
    Make an iterator that returns *object* over and over again. Runs indefinitely
    unless the *times* argument is specified. Used as argument to :func:`map` for
@@ -505,7 +504,7 @@ loops that truncate the stream.
                   break
 
 
-.. function:: tee(iterable[, n=2])
+.. function:: tee(iterable, n=2)
 
    Return *n* independent iterators from a single iterable.  Equivalent to::
 
@@ -531,7 +530,7 @@ loops that truncate the stream.
    :func:`list` instead of :func:`tee`.
 
 
-.. function:: zip_longest(*iterables[, fillvalue])
+.. function:: zip_longest(*iterables, fillvalue=None)
 
    Make an iterator that aggregates elements from each of the iterables. If the
    iterables are of uneven length, missing values are filled-in with *fillvalue*.