Signature documentation style update, modules J, K, L and M.

cd7f32b6 · Georg Brandl · cdf8b34b · cd7f32b6 · cd7f32b6 · cd7f32b6
Commit cd7f32b6 authored Jun 08, 2009 by Georg Brandl
20 changed files
--- a/Doc/library/json.rst
+++ b/Doc/library/json.rst
@@ -112,7 +112,7 @@ Using json.tool from the shell to validate and pretty-print::
 Basic Usage
 -----------

-.. function:: dump(obj, fp[, skipkeys[, ensure_ascii[, check_circular[, allow_nan[, cls[, indent[, separators[, default[, **kw]]]]]]]]]])
+.. function:: dump(obj, fp, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, cls=None, indent=None, separators=None, default=None, **kw)

   Serialize *obj* as a JSON formatted stream to *fp* (a ``.write()``-supporting
   file-like object).
@@ -126,7 +126,6 @@ Basic Usage
   :class:`bytes` objects. Therefore, ``fp.write()`` must support :class:`str`
   input.

-
   If *check_circular* is ``False`` (default: ``True``), then the circular
   reference check for container types will be skipped and a circular reference
   will result in an :exc:`OverflowError` (or worse).
@@ -153,13 +152,13 @@ Basic Usage
   *cls* kwarg.


-.. function:: dumps(obj[, skipkeys[, ensure_ascii[, check_circular[, allow_nan[, cls[, indent[, separators[, default[, **kw]]]]]]]]]])
+.. function:: dumps(obj, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, cls=None, indent=None, separators=None, default=None, **kw)

   Serialize *obj* to a JSON formatted :class:`str`.  The arguments have the
   same meaning as in :func:`dump`.


-.. function:: load(fp[, cls[, object_hook[, parse_float[, parse_int[, parse_constant[, object_pairs_hook[, **kw]]]]]]]])
+.. function:: load(fp, cls=None, object_hook=None, parse_float=None, parse_int=None, parse_constant=None, object_pairs_hook=None, **kw)

   Deserialize *fp* (a ``.read()``-supporting file-like object containing a JSON
   document) to a Python object.
@@ -200,7 +199,7 @@ Basic Usage
   class.


-.. function:: loads(s[, encoding[, cls[, object_hook[, parse_float[, parse_int[, parse_constant[, object_pairs_hook[, **kw]]]]]]]])
+.. function:: loads(s, encoding=None, cls=None, object_hook=None, parse_float=None, parse_int=None, parse_constant=None, object_pairs_hook=None, **kw)

   Deserialize *s* (a :class:`str` or :class:`unicode` instance containing a JSON
   document) to a Python object.
@@ -216,7 +215,7 @@ Basic Usage
 Encoders and decoders
 ---------------------

-.. class:: JSONDecoder([encoding[, object_hook[, parse_float[, parse_int[, parse_constant[, strict[, object_pairs_hook]]]]]]])
+.. class:: JSONDecoder(object_hook=None, parse_float=None, parse_int=None, parse_constant=None, strict=True, object_pairs_hook=None)

   Simple JSON decoder.

@@ -292,7 +291,7 @@ Encoders and decoders
      extraneous data at the end.


-.. class:: JSONEncoder([skipkeys[, ensure_ascii[, check_circular[, allow_nan[, sort_keys[, indent[, separators[, default]]]]]]]])
+.. class:: JSONEncoder(skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)

   Extensible JSON encoder for Python data structures.


--- a/Doc/library/keyword.rst
+++ b/Doc/library/keyword.rst
-
 :mod:`keyword` --- Testing for Python keywords
 ==============================================


--- a/Doc/library/language.rst
+++ b/Doc/library/language.rst
-
 .. _language:

 ************************

--- a/Doc/library/linecache.rst
+++ b/Doc/library/linecache.rst
-
 :mod:`linecache` --- Random access to text lines
 ================================================

@@ -15,7 +14,7 @@ to retrieve source lines for inclusion in  the formatted traceback.
 The :mod:`linecache` module defines the following functions:


-.. function:: getline(filename, lineno[, module_globals])
+.. function:: getline(filename, lineno, module_globals=None)

   Get line *lineno* from file named *filename*. This function will never throw an
   exception --- it will return ``''`` on errors (the terminating newline character
@@ -35,12 +34,13 @@ The :mod:`linecache` module defines the following functions:
   previously read using :func:`getline`.


-.. function:: checkcache([filename])
+.. function:: checkcache(filename=None)

   Check the cache for validity.  Use this function if files in the cache  may have
   changed on disk, and you require the updated version.  If *filename* is omitted,
   it will check all the entries in the cache.

+
 Example::

   >>> import linecache

--- a/Doc/library/locale.rst
+++ b/Doc/library/locale.rst
-
 :mod:`locale` --- Internationalization services
 ===============================================

@@ -26,7 +25,7 @@ The :mod:`locale` module defines the following exception and functions:
   Exception raised when :func:`setlocale` fails.


-.. function:: setlocale(category[, locale])
+.. function:: setlocale(category, locale=None)

   If *locale* is specified, it may be a string, a tuple of the form ``(language
   code, encoding)``, or ``None``. If it is a tuple, it is converted to a string
@@ -151,7 +150,7 @@ The :mod:`locale` module defines the following exception and functions:
   constants are available in the locale module.


-.. function:: getdefaultlocale([envvars])
+.. function:: getdefaultlocale(envvars=('LC_ALL', 'LC_CTYPE', 'LANG', 'LANGUAGE'))

   Tries to determine the default locale settings and returns them as a tuple of
   the form ``(language code, encoding)``.
@@ -164,17 +163,17 @@ The :mod:`locale` module defines the following exception and functions:

   To maintain compatibility with other platforms, not only the :envvar:`LANG`
   variable is tested, but a list of variables given as envvars parameter.  The
-   first found to be defined will be used.  *envvars* defaults to the search path
-   used in GNU gettext; it must always contain the variable name ``LANG``.  The GNU
-   gettext search path contains ``'LANGUAGE'``, ``'LC_ALL'``, ``'LC_CTYPE'``, and
-   ``'LANG'``, in that order.
+   first found to be defined will be used.  *envvars* defaults to the search
+   path used in GNU gettext; it must always contain the variable name
+   ``'LANG'``.  The GNU gettext search path contains ``'LC_ALL'``,
+   ``'LC_CTYPE'``, ``'LANG'`` and ``'LANGUAGE'``, in that order.

   Except for the code ``'C'``, the language code corresponds to :rfc:`1766`.
   *language code* and *encoding* may be ``None`` if their values cannot be
   determined.


-.. function:: getlocale([category])
+.. function:: getlocale(category=LC_CTYPE)

   Returns the current setting for the given locale category as sequence containing
   *language code*, *encoding*. *category* may be one of the :const:`LC_\*` values
@@ -185,7 +184,7 @@ The :mod:`locale` module defines the following exception and functions:
   determined.


-.. function:: getpreferredencoding([do_setlocale])
+.. function:: getpreferredencoding(do_setlocale=True)

   Return the encoding used for text data, according to user preferences.  User
   preferences are expressed differently on different systems, and might not be
@@ -207,7 +206,7 @@ The :mod:`locale` module defines the following exception and functions:
   encoding for the locale code just like :func:`setlocale`.


-.. function:: resetlocale([category])
+.. function:: resetlocale(category=LC_ALL)

   Sets the locale for *category* to the default setting.

@@ -232,7 +231,7 @@ The :mod:`locale` module defines the following exception and functions:
   sequence of strings.


-.. function:: format(format, val[, grouping[, monetary]])
+.. function:: format(format, val, grouping=False, monetary=False)

   Formats a number *val* according to the current :const:`LC_NUMERIC` setting.
   The format follows the conventions of the ``%`` operator.  For floating point
@@ -246,13 +245,13 @@ The :mod:`locale` module defines the following exception and functions:
   For whole format strings, use :func:`format_string`.


-.. function:: format_string(format, val[, grouping])
+.. function:: format_string(format, val, grouping=False)

   Processes formatting specifiers as in ``format % val``, but takes the current
   locale settings into account.


-.. function:: currency(val[, symbol[, grouping[, international]]])
+.. function:: currency(val, symbol=True, grouping=False, international=False)

   Formats a number *val* according to the current :const:`LC_MONETARY` settings.


--- a/Doc/library/logging.rst
+++ b/Doc/library/logging.rst
--- a/Doc/library/macpath.rst
+++ b/Doc/library/macpath.rst
-
 :mod:`macpath` --- Mac OS 9 path manipulation functions
 =======================================================


--- a/Doc/library/mailbox.rst
+++ b/Doc/library/mailbox.rst
-
 :mod:`mailbox` --- Manipulate mailboxes in various formats
 ==========================================================

@@ -27,7 +26,6 @@ Maildir, mbox, MH, Babyl, and MMDF.
 :class:`Mailbox` objects
 ------------------------

-
 .. class:: Mailbox

   A mailbox, which may be inspected and modified.
@@ -154,7 +152,7 @@ Maildir, mbox, MH, Babyl, and MMDF.
      when the :class:`Mailbox` instance was initialized.


-   .. method:: get(key[, default=None])
+   .. method:: get(key, default=None)
               __getitem__(key)

      Return a representation of the message corresponding to *key*. If no such
@@ -209,11 +207,10 @@ Maildir, mbox, MH, Babyl, and MMDF.
      Delete all messages from the mailbox.


-   .. method:: pop(key[, default])
+   .. method:: pop(key, default=None)

      Return a representation of the message corresponding to *key* and delete
-      the message. If no such message exists, return *default* if it was
-      supplied or else raise a :exc:`KeyError` exception. The message is
+      the message. If no such message exists, return *default*. The message is
      represented as an instance of the appropriate format-specific
      :class:`Message` subclass unless a custom message factory was specified
      when the :class:`Mailbox` instance was initialized.
@@ -277,7 +274,7 @@ Maildir, mbox, MH, Babyl, and MMDF.
 ^^^^^^^^^^^^^^^^


-.. class:: Maildir(dirname[, factory=None[, create=True]])
+.. class:: Maildir(dirname, factory=None, create=True)

   A subclass of :class:`Mailbox` for mailboxes in Maildir format. Parameter
   *factory* is a callable object that accepts a file-like message representation
@@ -419,7 +416,7 @@ Maildir, mbox, MH, Babyl, and MMDF.
 ^^^^^^^^^^^^^


-.. class:: mbox(path[, factory=None[, create=True]])
+.. class:: mbox(path, factory=None, create=True)

   A subclass of :class:`Mailbox` for mailboxes in mbox format. Parameter *factory*
   is a callable object that accepts a file-like message representation (which
@@ -479,7 +476,7 @@ Maildir, mbox, MH, Babyl, and MMDF.
 ^^^^^^^^^^^


-.. class:: MH(path[, factory=None[, create=True]])
+.. class:: MH(path, factory=None, create=True)

   A subclass of :class:`Mailbox` for mailboxes in MH format. Parameter *factory*
   is a callable object that accepts a file-like message representation (which
@@ -609,7 +606,7 @@ Maildir, mbox, MH, Babyl, and MMDF.
 ^^^^^^^^^^^^^^


-.. class:: Babyl(path[, factory=None[, create=True]])
+.. class:: Babyl(path, factory=None, create=True)

   A subclass of :class:`Mailbox` for mailboxes in Babyl format. Parameter
   *factory* is a callable object that accepts a file-like message representation
@@ -685,7 +682,7 @@ Maildir, mbox, MH, Babyl, and MMDF.
 ^^^^^^^^^^^^^


-.. class:: MMDF(path[, factory=None[, create=True]])
+.. class:: MMDF(path, factory=None, create=True)

   A subclass of :class:`Mailbox` for mailboxes in MMDF format. Parameter *factory*
   is a callable object that accepts a file-like message representation (which
@@ -737,7 +734,7 @@ Maildir, mbox, MH, Babyl, and MMDF.
 ------------------------


-.. class:: Message([message])
+.. class:: Message(message=None)

   A subclass of the :mod:`email.Message` module's :class:`Message`. Subclasses of
   :class:`mailbox.Message` add mailbox-format-specific state and behavior.
@@ -772,7 +769,7 @@ Maildir, mbox, MH, Babyl, and MMDF.
 ^^^^^^^^^^^^^^^^^^^^^^^


-.. class:: MaildirMessage([message])
+.. class:: MaildirMessage(message=None)

   A message with Maildir-specific behaviors. Parameter *message* has the same
   meaning as with the :class:`Message` constructor.
@@ -940,7 +937,7 @@ When a :class:`MaildirMessage` instance is created based upon a
 ^^^^^^^^^^^^^^^^^^^^


-.. class:: mboxMessage([message])
+.. class:: mboxMessage(message=None)

   A message with mbox-specific behaviors. Parameter *message* has the same meaning
   as with the :class:`Message` constructor.
@@ -983,7 +980,7 @@ When a :class:`MaildirMessage` instance is created based upon a
      are excluded.


-   .. method:: set_from(from_[, time_=None])
+   .. method:: set_from(from_, time_=None)

      Set the "From " line to *from_*, which should be specified without a
      leading "From " or trailing newline. For convenience, *time_* may be
@@ -1094,7 +1091,7 @@ instance, the "From " line is copied and all flags directly correspond:
 ^^^^^^^^^^^^^^^^^^


-.. class:: MHMessage([message])
+.. class:: MHMessage(message=None)

   A message with MH-specific behaviors. Parameter *message* has the same meaning
   as with the :class:`Message` constructor.
@@ -1184,7 +1181,7 @@ When an :class:`MHMessage` instance is created based upon a
 ^^^^^^^^^^^^^^^^^^^^^


-.. class:: BabylMessage([message])
+.. class:: BabylMessage(message=None)

   A message with Babyl-specific behaviors. Parameter *message* has the same
   meaning as with the :class:`Message` constructor.
@@ -1312,7 +1309,7 @@ When a :class:`BabylMessage` instance is created based upon an
 ^^^^^^^^^^^^^^^^^^^^


-.. class:: MMDFMessage([message])
+.. class:: MMDFMessage(message=None)

   A message with MMDF-specific behaviors. Parameter *message* has the same meaning
   as with the :class:`Message` constructor.
@@ -1354,7 +1351,7 @@ When a :class:`BabylMessage` instance is created based upon an
      are excluded.


-   .. method:: set_from(from_[, time_=None])
+   .. method:: set_from(from_, time_=None)

      Set the "From " line to *from_*, which should be specified without a
      leading "From " or trailing newline. For convenience, *time_* may be

--- a/Doc/library/mailcap.rst
+++ b/Doc/library/mailcap.rst
@@ -5,7 +5,6 @@
   :synopsis: Mailcap file handling.


-
 Mailcap files are used to configure how MIME-aware applications such as mail
 readers and Web browsers react to files with different MIME types. (The name
 "mailcap" is derived from the phrase "mail capability".)  For example, a mailcap
@@ -20,7 +19,7 @@ Mechanism For Multimedia Mail Format Information," but is not an Internet
 standard.  However, mailcap files are supported on most Unix systems.


-.. function:: findmatch(caps, MIMEtype[, key[, filename[, plist]]])
+.. function:: findmatch(caps, MIMEtype, key='view', filename='/dev/null', plist=[])

   Return a 2-tuple; the first element is a string containing the command line to
   be executed (which can be passed to :func:`os.system`), and the second element

--- a/Doc/library/markup.rst
+++ b/Doc/library/markup.rst
-
 .. _markup:

 **********************************

--- a/Doc/library/marshal.rst
+++ b/Doc/library/marshal.rst
-
 :mod:`marshal` --- Internal Python object serialization
 =======================================================


--- a/Doc/library/math.rst
+++ b/Doc/library/math.rst
-
 :mod:`math` --- Mathematical functions
 ======================================


--- a/Doc/library/mimetypes.rst
+++ b/Doc/library/mimetypes.rst
-
 :mod:`mimetypes` --- Map filenames to MIME types
 ================================================

@@ -23,7 +22,7 @@ the module has not been initialized, they will call :func:`init` if they rely on
 the information :func:`init` sets up.


-.. function:: guess_type(filename[, strict])
+.. function:: guess_type(url, strict=True)

   .. index:: pair: MIME; headers

@@ -47,7 +46,7 @@ the information :func:`init` sets up.
   are also recognized.


-.. function:: guess_all_extensions(type[, strict])
+.. function:: guess_all_extensions(type, strict=True)

   Guess the extensions for a file based on its MIME type, given by *type*. The
   return value is a list of strings giving all possible filename extensions,
@@ -58,7 +57,7 @@ the information :func:`init` sets up.
   Optional *strict* has the same meaning as with the :func:`guess_type` function.


-.. function:: guess_extension(type[, strict])
+.. function:: guess_extension(type, strict=True)

   Guess the extension for a file based on its MIME type, given by *type*. The
   return value is a string giving a filename extension, including the leading dot
@@ -73,7 +72,7 @@ Some additional functions and data items are available for controlling the
 behavior of the module.


-.. function:: init([files])
+.. function:: init(files=None)

   Initialize the internal data structures.  If given, *files* must be a sequence
   of file names which should be used to augment the default type map.  If omitted,
@@ -90,7 +89,7 @@ behavior of the module.
   does not exist or cannot be read, ``None`` is returned.


-.. function:: add_type(type, ext[, strict])
+.. function:: add_type(type, ext, strict=True)

   Add a mapping from the mimetype *type* to the extension *ext*. When the
   extension is already known, the new type will replace the old one. When the type
@@ -142,7 +141,7 @@ The :class:`MimeTypes` class may be useful for applications which may want more
 than one MIME-type database:


-.. class:: MimeTypes([filenames])
+.. class:: MimeTypes(filenames=(), strict=True)

   This class represents a MIME-types database.  By default, it provides access to
   the same database as the rest of this module. The initial database is a copy of
@@ -206,13 +205,13 @@ MimeTypes Objects
   module.


-.. method:: MimeTypes.guess_extension(type[, strict])
+.. method:: MimeTypes.guess_extension(type, strict=True)

   Similar to the :func:`guess_extension` function, using the tables stored as part
   of the object.


-.. method:: MimeTypes.guess_type(url[, strict])
+.. method:: MimeTypes.guess_type(url, strict=True)

   Similar to the :func:`guess_type` function, using the tables stored as part of
   the object.

--- a/Doc/library/misc.rst
+++ b/Doc/library/misc.rst
-
 .. _misc:

 **********************

--- a/Doc/library/mm.rst
+++ b/Doc/library/mm.rst
-
 .. _mmedia:

 *******************

--- a/Doc/library/mmap.rst
+++ b/Doc/library/mmap.rst
-
 :mod:`mmap` --- Memory-mapped file support
 ==========================================

@@ -37,7 +36,7 @@ memory but does not update the underlying file.

 To map anonymous memory, -1 should be passed as the fileno along with the length.

-.. class:: mmap(fileno, length[, tagname[, access[, offset]]])
+.. class:: mmap(fileno, length, tagname=None, access=ACCESS_DEFAULT[, offset])

   **(Windows version)** Maps *length* bytes from the file specified by the
   file handle *fileno*, and creates a mmap object.  If *length* is larger
@@ -59,7 +58,7 @@ To map anonymous memory, -1 should be passed as the fileno along with the length
   defaults to 0.  *offset* must be a multiple of the ALLOCATIONGRANULARITY.


-.. class:: mmap(fileno, length[, flags[, prot[, access[, offset]]]])
+.. class:: mmap(fileno, length, flags=MAP_SHARED, prot=PROT_WRITE|PROT_READ, access=ACCESS_DEFAULT[, offset])
   :noindex:

   **(Unix version)** Maps *length* bytes from the file specified by the file
@@ -148,7 +147,7 @@ To map anonymous memory, -1 should be passed as the fileno along with the length
      Returns ``-1`` on failure.


-   .. method:: flush([offset, size])
+   .. method:: flush([offset[, size]])

      Flushes changes made to the in-memory copy of a file back to disk. Without
      use of this call there is no guarantee that changes are written back before

--- a/Doc/library/modulefinder.rst
+++ b/Doc/library/modulefinder.rst
-
 :mod:`modulefinder` --- Find modules used by a script
 =====================================================

@@ -27,7 +26,7 @@ report of the imported modules will be printed.
   package replaces the :mod:`xml` package.


-.. class:: ModuleFinder([path=None, debug=0, excludes=[], replace_paths=[]])
+.. class:: ModuleFinder(path=None, debug=0, excludes=[], replace_paths=[])

   This class provides :meth:`run_script` and :meth:`report` methods to determine
   the set of modules imported by a script. *path* can be a list of directories to

--- a/Doc/library/modules.rst
+++ b/Doc/library/modules.rst
-
 .. _modules:

 *****************

--- a/Doc/library/msilib.rst
+++ b/Doc/library/msilib.rst
@@ -363,7 +363,7 @@ Directory Objects
   the default flags that new components get.


-   .. method:: start_component([component[, feature[, flags[, keyfile[, uuid]]]]])
+   .. method:: start_component(component=None, feature=None, flags=None, keyfile=None, uuid=None)

      Add an entry to the Component table, and make this component the current
      component for this directory. If no component name is given, the directory
@@ -372,7 +372,7 @@ Directory Objects
      is given, the KeyPath is left null in the Component table.


-   .. method:: add_file(file[, src[, version[, language]]])
+   .. method:: add_file(file, src=None, version=None, language=None)

      Add a file to the current component of the directory, starting a new one
      if there is no current component. By default, the file name in the source
@@ -381,7 +381,7 @@ Directory Objects
      and a *language* can be specified for the entry in the File table.


-   .. method:: glob(pattern[, exclude])
+   .. method:: glob(pattern, exclude=None)

      Add a list of files to the current component as specified in the glob
      pattern.  Individual files can be excluded in the *exclude* list.
@@ -405,7 +405,7 @@ Features
 --------


-.. class:: Feature(database, id, title, desc, display[, level=1[, parent[, directory[,  attributes=0]]]])
+.. class:: Feature(db, id, title, desc, display, level=1, parent=None, directory=None,  attributes=0)

   Add a new record to the ``Feature`` table, using the values *id*, *parent.id*,
   *title*, *desc*, *display*, *level*, *directory*, and *attributes*. The
@@ -440,7 +440,7 @@ to create MSI files with a user-interface for installing Python packages.
   belongs to, and *name* is the control's name.


-   .. method:: event(event, argument[,  condition=1[, ordering]])
+   .. method:: event(event, argument, condition=1, ordering=None)

      Make an entry into the ``ControlEvent`` table for this control.

@@ -461,10 +461,10 @@ to create MSI files with a user-interface for installing Python packages.
   that gets set when a radio button is selected.


-   .. method:: add(name, x, y, width, height, text [, value])
+   .. method:: add(name, x, y, width, height, text, value=None)

      Add a radio button named *name* to the group, at the coordinates *x*, *y*,
-      *width*, *height*, and with the label *text*. If *value* is omitted, it
+      *width*, *height*, and with the label *text*. If *value* is ``None``, it
      defaults to *name*.



--- a/Doc/library/msvcrt.rst
+++ b/Doc/library/msvcrt.rst
-
 :mod:`msvcrt` -- Useful routines from the MS VC++ runtime
 =========================================================