From 3dd3388229995e00cf0ba858700576a79de0d6ec Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Mon, 1 Jun 2009 17:35:27 +0000 Subject: Convert all "i" docs to new style optional args. --- Doc/library/imaplib.rst | 12 ++++++------ Doc/library/imghdr.rst | 3 +-- Doc/library/imp.rst | 1 - Doc/library/inspect.rst | 34 +++++++++++++++++----------------- Doc/library/internet.rst | 1 - Doc/library/intro.rst | 1 - Doc/library/io.rst | 39 ++++++++++++++++++++------------------- Doc/library/ipc.rst | 1 - Doc/library/itertools.rst | 13 ++++++------- 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*. -- cgit v0.12