From 9fa61bb37d68225c827aa7809382ea701c264db5 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sun, 26 Jul 2009 14:19:57 +0000 Subject: #6577: fix (hopefully) all links to builtin instead of module/class-specific objects. --- Doc/library/2to3.rst | 5 +++-- Doc/library/aifc.rst | 4 ++-- Doc/library/anydbm.rst | 2 +- Doc/library/audioop.rst | 2 +- Doc/library/cd.rst | 6 +++--- Doc/library/cgi.rst | 8 ++++---- Doc/library/csv.rst | 2 +- Doc/library/curses.rst | 2 +- Doc/library/dbhash.rst | 4 ++-- Doc/library/decimal.rst | 4 ++-- Doc/library/dis.rst | 2 +- Doc/library/dl.rst | 6 +++--- Doc/library/exceptions.rst | 8 ++++---- Doc/library/fileinput.rst | 4 ++-- Doc/library/functions.rst | 10 +++++----- Doc/library/io.rst | 10 +++++----- Doc/library/locale.rst | 6 +++--- Doc/library/logging.rst | 2 +- Doc/library/mailbox.rst | 4 ++-- Doc/library/multifile.rst | 2 +- Doc/library/multiprocessing.rst | 4 ++-- Doc/library/optparse.rst | 38 +++++++++++++++++++------------------- Doc/library/os.rst | 16 ++++++++-------- Doc/library/ossaudiodev.rst | 2 +- Doc/library/posixfile.rst | 5 ++--- Doc/library/pyclbr.rst | 4 ++-- Doc/library/repr.rst | 12 ++++++------ Doc/library/shelve.rst | 8 ++++---- Doc/library/stdtypes.rst | 4 ++-- Doc/library/sunau.rst | 10 +++++----- Doc/library/sunaudio.rst | 2 +- Doc/library/tempfile.rst | 4 ++-- Doc/library/threading.rst | 12 +++++++----- Doc/library/tkinter.rst | 4 ++-- Doc/library/wave.rst | 6 +++--- Doc/library/webbrowser.rst | 2 +- 36 files changed, 114 insertions(+), 112 deletions(-) diff --git a/Doc/library/2to3.rst b/Doc/library/2to3.rst index 435aed1..a87a29c 100644 --- a/Doc/library/2to3.rst +++ b/Doc/library/2to3.rst @@ -239,8 +239,9 @@ and off individually. They are described here in more detail. .. 2to3fixer:: next - Converts the use of iterator's :meth:`next` methods to the :func:`next` - function. It also renames :meth:`next` methods to :meth:`~object.__next__`. + Converts the use of iterator's :meth:`~iterator.next` methods to the + :func:`next` function. It also renames :meth:`next` methods to + :meth:`~object.__next__`. .. 2to3fixer:: nonzero diff --git a/Doc/library/aifc.rst b/Doc/library/aifc.rst index 062f1f2..0bb1635 100644 --- a/Doc/library/aifc.rst +++ b/Doc/library/aifc.rst @@ -48,7 +48,7 @@ Module :mod:`aifc` defines the following function: time how many samples you are going to write in total and use :meth:`writeframesraw` and :meth:`setnframes`. -Objects returned by :func:`open` when a file is opened for reading have the +Objects returned by :func:`.open` when a file is opened for reading have the following methods: @@ -131,7 +131,7 @@ following methods: Close the AIFF file. After calling this method, the object can no longer be used. -Objects returned by :func:`open` when a file is opened for writing have all the +Objects returned by :func:`.open` when a file is opened for writing have all the above methods, except for :meth:`readframes` and :meth:`setpos`. In addition the following methods exist. The :meth:`get\*` methods can only be called after the corresponding :meth:`set\*` methods have been called. Before the first diff --git a/Doc/library/anydbm.rst b/Doc/library/anydbm.rst index aad1776..7c6f99f 100644 --- a/Doc/library/anydbm.rst +++ b/Doc/library/anydbm.rst @@ -62,7 +62,7 @@ these modules is installed, the slow-but-simple implementation in module modules, with a unique exception also named :exc:`anydbm.error` as the first item --- the latter is used when :exc:`anydbm.error` is raised. -The object returned by :func:`open` supports most of the same functionality as +The object returned by :func:`.open` supports most of the same functionality as dictionaries; keys and their corresponding values can be stored, retrieved, and deleted, and the :meth:`has_key` and :meth:`keys` methods are available. Keys and values must always be strings. diff --git a/Doc/library/audioop.rst b/Doc/library/audioop.rst index 8b7aa9e..b497e1f 100644 --- a/Doc/library/audioop.rst +++ b/Doc/library/audioop.rst @@ -228,7 +228,7 @@ The module defines the following variables and functions: u-LAW encoding always uses 8 bits samples, so *width* refers only to the sample width of the output fragment here. -Note that operations such as :func:`mul` or :func:`max` make no distinction +Note that operations such as :func:`.mul` or :func:`.max` make no distinction between mono and stereo fragments, i.e. all samples are treated equal. If this is a problem the stereo fragment should be split into two mono fragments first and recombined later. Here is an example of how to do that:: diff --git a/Doc/library/cd.rst b/Doc/library/cd.rst index 0043764..f1d9763 100644 --- a/Doc/library/cd.rst +++ b/Doc/library/cd.rst @@ -16,8 +16,8 @@ This module provides an interface to the Silicon Graphics CD library. It is available only on Silicon Graphics systems. The way the library works is as follows. A program opens the CD-ROM device with -:func:`open` and creates a parser to parse the data from the CD with -:func:`createparser`. The object returned by :func:`open` can be used to read +:func:`.open` and creates a parser to parse the data from the CD with +:func:`createparser`. The object returned by :func:`.open` can be used to read data from the CD, but also to get status information for the CD-ROM device, and to get information about the CD, such as the table of contents. Data from the CD is passed to the parser, which parses the frames, and calls any callback @@ -133,7 +133,7 @@ The following variables are states as returned by :func:`getstatus`: Player Objects -------------- -Player objects (returned by :func:`open`) have the following methods: +Player objects (returned by :func:`.open`) have the following methods: .. method:: CD player.allowremoval() diff --git a/Doc/library/cgi.rst b/Doc/library/cgi.rst index 58222ea..138f808 100644 --- a/Doc/library/cgi.rst +++ b/Doc/library/cgi.rst @@ -136,8 +136,8 @@ commas:: If a field represents an uploaded file, accessing the value via the :attr:`value` attribute or the :func:`getvalue` method reads the entire file in memory as a string. This may not be what you want. You can test for an uploaded -file by testing either the :attr:`filename` attribute or the :attr:`file` -attribute. You can then read the data at leisure from the :attr:`file` +file by testing either the :attr:`filename` attribute or the :attr:`!file` +attribute. You can then read the data at leisure from the :attr:`!file` attribute:: fileitem = form["userfile"] @@ -157,7 +157,7 @@ field will be set to the value -1. The file upload draft standard entertains the possibility of uploading multiple files from one field (using a recursive :mimetype:`multipart/\*` encoding). When this occurs, the item will be a dictionary-like :class:`FieldStorage` item. -This can be determined by testing its :attr:`type` attribute, which should be +This can be determined by testing its :attr:`!type` attribute, which should be :mimetype:`multipart/form-data` (or perhaps another MIME type matching :mimetype:`multipart/\*`). In this case, it can be iterated over recursively just like the top-level form object. @@ -165,7 +165,7 @@ just like the top-level form object. When a form is submitted in the "old" format (as the query string or as a single data part of type :mimetype:`application/x-www-form-urlencoded`), the items will actually be instances of the class :class:`MiniFieldStorage`. In this case, the -:attr:`list`, :attr:`file`, and :attr:`filename` attributes are always ``None``. +:attr:`!list`, :attr:`!file`, and :attr:`filename` attributes are always ``None``. A form submitted via POST that also has a query string will contain both :class:`FieldStorage` and :class:`MiniFieldStorage` items. diff --git a/Doc/library/csv.rst b/Doc/library/csv.rst index b5994c1..8949465 100644 --- a/Doc/library/csv.rst +++ b/Doc/library/csv.rst @@ -61,7 +61,7 @@ The :mod:`csv` module defines the following functions: Return a reader object which will iterate over lines in the given *csvfile*. *csvfile* can be any object which supports the :term:`iterator` protocol and returns a - string each time its :meth:`next` method is called --- file objects and list + string each time its :meth:`!next` method is called --- file objects and list objects are both suitable. If *csvfile* is a file object, it must be opened with the 'b' flag on platforms where that makes a difference. An optional *dialect* parameter can be given which is used to define a set of parameters diff --git a/Doc/library/curses.rst b/Doc/library/curses.rst index 01689a2..c53b105 100644 --- a/Doc/library/curses.rst +++ b/Doc/library/curses.rst @@ -186,7 +186,7 @@ The module :mod:`curses` defines the following functions: .. function:: filter() - The :func:`filter` routine, if used, must be called before :func:`initscr` is + The :func:`.filter` routine, if used, must be called before :func:`initscr` is called. The effect is that, during those calls, LINES is set to 1; the capabilities clear, cup, cud, cud1, cuu1, cuu, vpa are disabled; and the home string is set to the value of cr. The effect is that the cursor is confined to diff --git a/Doc/library/dbhash.rst b/Doc/library/dbhash.rst index 6f9a24f..0b440ab 100644 --- a/Doc/library/dbhash.rst +++ b/Doc/library/dbhash.rst @@ -72,7 +72,7 @@ This module provides an exception and a function: Database Objects ---------------- -The database objects returned by :func:`open` provide the methods common to all +The database objects returned by :func:`.open` provide the methods common to all the DBM-style databases and mapping objects. The following methods are available in addition to the standard methods. @@ -80,7 +80,7 @@ available in addition to the standard methods. .. method:: dbhash.first() It's possible to loop over every key/value pair in the database using this - method and the :meth:`next` method. The traversal is ordered by the databases + method and the :meth:`!next` method. The traversal is ordered by the databases internal hash values, and won't be sorted by the key values. This method returns the starting key. diff --git a/Doc/library/decimal.rst b/Doc/library/decimal.rst index 0b498a1..53caff8 100644 --- a/Doc/library/decimal.rst +++ b/Doc/library/decimal.rst @@ -656,7 +656,7 @@ Decimal objects .. method:: max_mag(other[, context]) - Similar to the :meth:`max` method, but the comparison is done using the + Similar to the :meth:`.max` method, but the comparison is done using the absolute values of the operands. .. versionadded:: 2.6 @@ -670,7 +670,7 @@ Decimal objects .. method:: min_mag(other[, context]) - Similar to the :meth:`min` method, but the comparison is done using the + Similar to the :meth:`.min` method, but the comparison is done using the absolute values of the operands. .. versionadded:: 2.6 diff --git a/Doc/library/dis.rst b/Doc/library/dis.rst index 9bd65dd..6871d7e 100644 --- a/Doc/library/dis.rst +++ b/Doc/library/dis.rst @@ -705,7 +705,7 @@ the more significant byte last. .. opcode:: FOR_ITER (delta) - ``TOS`` is an :term:`iterator`. Call its :meth:`next` method. If this + ``TOS`` is an :term:`iterator`. Call its :meth:`!next` method. If this yields a new value, push it on the stack (leaving the iterator below it). If the iterator indicates it is exhausted ``TOS`` is popped, and the bytecode counter is incremented by *delta*. diff --git a/Doc/library/dl.rst b/Doc/library/dl.rst index fdda2f9..a383729 100644 --- a/Doc/library/dl.rst +++ b/Doc/library/dl.rst @@ -44,12 +44,12 @@ The :mod:`dl` module defines the following constants: .. data:: RTLD_LAZY - Useful as an argument to :func:`open`. + Useful as an argument to :func:`.open`. .. data:: RTLD_NOW - Useful as an argument to :func:`open`. Note that on systems which do not + Useful as an argument to :func:`.open`. Note that on systems which do not support immediate binding, this constant will not appear in the module. For maximum portability, use :func:`hasattr` to determine if the system supports immediate binding. @@ -78,7 +78,7 @@ the fact that using this module is usually a bad alternative. Dl Objects ---------- -Dl objects, as returned by :func:`open` above, have the following methods: +Dl objects, as returned by :func:`.open` above, have the following methods: .. method:: dl.close() diff --git a/Doc/library/exceptions.rst b/Doc/library/exceptions.rst index 4679e70..2f07d29 100644 --- a/Doc/library/exceptions.rst +++ b/Doc/library/exceptions.rst @@ -281,10 +281,10 @@ The following exceptions are the exceptions that are actually raised. .. exception:: StopIteration - Raised by an :term:`iterator`\'s :meth:`next` method to signal that there are - no further values. This is derived from :exc:`Exception` rather than - :exc:`StandardError`, since this is not considered an error in its normal - application. + Raised by an :term:`iterator`\'s :meth:`~iterator.next` method to signal that + there are no further values. This is derived from :exc:`Exception` rather + than :exc:`StandardError`, since this is not considered an error in its + normal application. .. versionadded:: 2.2 diff --git a/Doc/library/fileinput.rst b/Doc/library/fileinput.rst index 3253a07..ffd109c 100644 --- a/Doc/library/fileinput.rst +++ b/Doc/library/fileinput.rst @@ -20,10 +20,10 @@ The typical use is:: This iterates over the lines of all files listed in ``sys.argv[1:]``, defaulting to ``sys.stdin`` if the list is empty. If a filename is ``'-'``, it is also replaced by ``sys.stdin``. To specify an alternative list of filenames, pass it -as the first argument to :func:`input`. A single file name is also allowed. +as the first argument to :func:`.input`. A single file name is also allowed. All files are opened in text mode by default, but you can override this by -specifying the *mode* parameter in the call to :func:`input` or +specifying the *mode* parameter in the call to :func:`.input` or :class:`FileInput()`. If an I/O error occurs during opening or reading a file, :exc:`IOError` is raised. diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index ade57a3..1ae00d5 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -291,7 +291,7 @@ available. They are listed here in alphabetical order. Return an enumerate object. *sequence* must be a sequence, an :term:`iterator`, or some other object which supports iteration. The - :meth:`next` method of the iterator returned by :func:`enumerate` returns a + :meth:`!next` method of the iterator returned by :func:`enumerate` returns a tuple containing a count (from *start* which defaults to 0) and the corresponding value obtained from iterating over *iterable*. :func:`enumerate` is useful for obtaining an indexed series: ``(0, seq[0])``, @@ -595,7 +595,7 @@ available. They are listed here in alphabetical order. does not support either of those protocols, :exc:`TypeError` is raised. If the second argument, *sentinel*, is given, then *o* must be a callable object. The iterator created in this case will call *o* with no arguments for each call to - its :meth:`next` method; if the value returned is equal to *sentinel*, + its :meth:`~iterator.next` method; if the value returned is equal to *sentinel*, :exc:`StopIteration` will be raised, otherwise the value will be returned. One useful application of the second form of :func:`iter` is to read lines of @@ -705,9 +705,9 @@ available. They are listed here in alphabetical order. .. function:: next(iterator[, default]) - Retrieve the next item from the *iterator* by calling its :meth:`next` - method. If *default* is given, it is returned if the iterator is exhausted, - otherwise :exc:`StopIteration` is raised. + Retrieve the next item from the *iterator* by calling its + :meth:`~iterator.next` method. If *default* is given, it is returned if the + iterator is exhausted, otherwise :exc:`StopIteration` is raised. .. versionadded:: 2.6 diff --git a/Doc/library/io.rst b/Doc/library/io.rst index 9e130bf..184e443 100644 --- a/Doc/library/io.rst +++ b/Doc/library/io.rst @@ -37,7 +37,7 @@ buffered text interface to a buffered raw stream stream for text. Argument names are not part of the specification, and only the arguments of -:func:`open` are intended to be used as keyword arguments. +:func:`.open` are intended to be used as keyword arguments. Module Interface @@ -46,7 +46,7 @@ Module Interface .. data:: DEFAULT_BUFFER_SIZE An int containing the default buffer size used by the module's buffered I/O - classes. :func:`open` uses the file's blksize (as obtained by + 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]]]]]]) @@ -138,8 +138,8 @@ Module Interface when the file is closed. If a filename is given *closefd* has no effect but must be ``True`` (the default). - The type of file object returned by the :func:`open` function depends - on the mode. When :func:`open` is used to open a file in a text mode + The type of file object returned by the :func:`.open` function depends + on the mode. When :func:`.open` is used to open a file in a text mode (``'w'``, ``'r'``, ``'wt'``, ``'rt'``, etc.), it returns a :class:`TextIOWrapper`. When used to open a file in a binary mode, the returned class varies: in read binary mode, it returns a @@ -250,7 +250,7 @@ I/O Base Classes most *limit* bytes will be read. The line terminator is always ``b'\n'`` for binary files; for text files, - the *newlines* argument to :func:`open` can be used to select the line + the *newlines* argument to :func:`.open` can be used to select the line terminator(s) recognized. .. method:: readlines([hint]) diff --git a/Doc/library/locale.rst b/Doc/library/locale.rst index af2fd4b..c8be7af 100644 --- a/Doc/library/locale.rst +++ b/Doc/library/locale.rst @@ -454,8 +454,8 @@ The :mod:`locale` module defines the following exception and functions: .. data:: LC_NUMERIC - Locale category for formatting numbers. The functions :func:`format`, - :func:`atoi`, :func:`atof` and :func:`str` of the :mod:`locale` module are + Locale category for formatting numbers. The functions :func:`.format`, + :func:`atoi`, :func:`atof` and :func:`.str` of the :mod:`locale` module are affected by that category. All other numeric formatting operations are not affected. @@ -523,7 +523,7 @@ e.g. ``from string import letters``, is not affected by subsequent The only way to perform numeric operations according to the locale is to use the special functions defined by this module: :func:`atof`, :func:`atoi`, -:func:`format`, :func:`str`. +:func:`.format`, :func:`.str`. .. _embedding-locale: diff --git a/Doc/library/logging.rst b/Doc/library/logging.rst index 4847c70..06f4ea9 100644 --- a/Doc/library/logging.rst +++ b/Doc/library/logging.rst @@ -1012,7 +1012,7 @@ instantiated directly, but always through the module-level function Handles a record by passing it to all handlers associated with this logger and its ancestors (until a false value of *propagate* is found). This method is used for unpickled records received from a socket, as well as those created locally. - Logger-level filtering is applied using :meth:`filter`. + Logger-level filtering is applied using :meth:`~Logger.filter`. .. method:: Logger.makeRecord(name, lvl, fn, lno, msg, args, exc_info [, func, extra]) diff --git a/Doc/library/mailbox.rst b/Doc/library/mailbox.rst index 01d3f4b..ca15475 100644 --- a/Doc/library/mailbox.rst +++ b/Doc/library/mailbox.rst @@ -1530,7 +1530,7 @@ Older mailbox objects support only iteration and provide a single public method: Most of the older mailbox classes have names that differ from the current mailbox class names, except for :class:`Maildir`. For this reason, the new -:class:`Maildir` class defines a :meth:`next` method and its constructor differs +:class:`Maildir` class defines a :meth:`!next` method and its constructor differs slightly from those of the other new mailbox classes. The older mailbox classes whose names are not the same as their newer @@ -1543,7 +1543,7 @@ counterparts are as follows: single file and separated by ``From`` (a.k.a. ``From_``) lines. The file object *fp* points to the mailbox file. The optional *factory* parameter is a callable that should create new message objects. *factory* is called with one argument, - *fp* by the :meth:`next` method of the mailbox object. The default is the + *fp* by the :meth:`!next` method of the mailbox object. The default is the :class:`rfc822.Message` class (see the :mod:`rfc822` module -- and the note below). diff --git a/Doc/library/multifile.rst b/Doc/library/multifile.rst index 0614b86..14b9d37 100644 --- a/Doc/library/multifile.rst +++ b/Doc/library/multifile.rst @@ -109,7 +109,7 @@ A :class:`MultiFile` instance has the following methods: an input line, it will be interpreted as a section-divider or end-marker (depending on the decoration, see :rfc:`2045`). All subsequent reads will return the empty string to indicate end-of-file, until a call to :meth:`pop` - removes the boundary a or :meth:`next` call reenables it. + removes the boundary a or :meth:`.next` call reenables it. It is possible to push more than one boundary. Encountering the most-recently-pushed boundary will return EOF; encountering any other diff --git a/Doc/library/multiprocessing.rst b/Doc/library/multiprocessing.rst index 39d0b45..9522865 100644 --- a/Doc/library/multiprocessing.rst +++ b/Doc/library/multiprocessing.rst @@ -1580,7 +1580,7 @@ with the :class:`Pool` class. .. method:: map_async(func, iterable[, chunksize[, callback]]) - A variant of the :meth:`map` method which returns a result object. + A variant of the :meth:`.map` method which returns a result object. If *callback* is specified then it should be a callable which accepts a single argument. When the result becomes ready *callback* is applied to @@ -1596,7 +1596,7 @@ with the :class:`Pool` class. make make the job complete **much** faster than using the default value of ``1``. - Also if *chunksize* is ``1`` then the :meth:`next` method of the iterator + Also if *chunksize* is ``1`` then the :meth:`!next` method of the iterator returned by the :meth:`imap` method has an optional *timeout* parameter: ``next(timeout)`` will raise :exc:`multiprocessing.TimeoutError` if the result cannot be returned within *timeout* seconds. diff --git a/Doc/library/optparse.rst b/Doc/library/optparse.rst index a1055d8..49371be 100644 --- a/Doc/library/optparse.rst +++ b/Doc/library/optparse.rst @@ -286,7 +286,7 @@ that's rarely necessary: by default it uses ``sys.argv[1:]``.) * ``args``, the list of positional arguments leftover after parsing options This tutorial section only covers the four most important option attributes: -:attr:`action`, :attr:`type`, :attr:`dest` (destination), and :attr:`help`. Of +:attr:`action`, :attr:`!type`, :attr:`dest` (destination), and :attr:`help`. Of these, :attr:`action` is the most fundamental. @@ -834,7 +834,7 @@ this option on the command-line. The standard option actions hard-coded into print a usage message including all options and the documentation for them (If you don't supply an action, the default is ``store``. For this action, you -may also supply :attr:`type` and :attr:`dest` option attributes; see below.) +may also supply :attr:`!type` and :attr:`dest` option attributes; see below.) As you can see, most actions involve storing or updating a value somewhere. :mod:`optparse` always creates a special object for this, conventionally called @@ -865,7 +865,7 @@ then :mod:`optparse`, on seeing this option, will do the equivalent of :: options.filename = "foo" -The :attr:`type` and :attr:`dest` option attributes are almost as important as +The :attr:`!type` and :attr:`dest` option attributes are almost as important as :attr:`action`, but :attr:`action` is the only one that makes sense for *all* options. @@ -880,18 +880,18 @@ Most actions have several relevant option attributes which you may specify to guide :mod:`optparse`'s behaviour; a few have required attributes, which you must specify for any option using that action. -* ``store`` [relevant: :attr:`type`, :attr:`dest`, ``nargs``, ``choices``] +* ``store`` [relevant: :attr:`!type`, :attr:`dest`, ``nargs``, ``choices``] The option must be followed by an argument, which is converted to a value - according to :attr:`type` and stored in :attr:`dest`. If ``nargs`` > 1, + according to :attr:`!type` and stored in :attr:`dest`. If ``nargs`` > 1, multiple arguments will be consumed from the command line; all will be converted - according to :attr:`type` and stored to :attr:`dest` as a tuple. See the + according to :attr:`!type` and stored to :attr:`dest` as a tuple. See the "Option types" section below. If ``choices`` is supplied (a list or tuple of strings), the type defaults to ``choice``. - If :attr:`type` is not supplied, it defaults to ``string``. + If :attr:`!type` is not supplied, it defaults to ``string``. If :attr:`dest` is not supplied, :mod:`optparse` derives a destination from the first long option string (e.g., ``"--foo-bar"`` implies ``foo_bar``). If there @@ -943,7 +943,7 @@ must specify for any option using that action. parser.add_option("--clobber", action="store_true", dest="clobber") parser.add_option("--no-clobber", action="store_false", dest="clobber") -* ``append`` [relevant: :attr:`type`, :attr:`dest`, ``nargs``, ``choices``] +* ``append`` [relevant: :attr:`!type`, :attr:`dest`, ``nargs``, ``choices``] The option must be followed by an argument, which is appended to the list in :attr:`dest`. If no default value for :attr:`dest` is supplied, an empty list @@ -951,7 +951,7 @@ must specify for any option using that action. the command-line. If ``nargs`` > 1, multiple arguments are consumed, and a tuple of length ``nargs`` is appended to :attr:`dest`. - The defaults for :attr:`type` and :attr:`dest` are the same as for the ``store`` + The defaults for :attr:`!type` and :attr:`dest` are the same as for the ``store`` action. Example:: @@ -993,7 +993,7 @@ must specify for any option using that action. options.verbosity += 1 -* ``callback`` [required: ``callback``; relevant: :attr:`type`, ``nargs``, +* ``callback`` [required: ``callback``; relevant: :attr:`!type`, ``nargs``, ``callback_args``, ``callback_kwargs``] Call the function specified by ``callback``, which is called as :: @@ -1066,7 +1066,7 @@ to a particular option, or fail to pass a required option attribute, Determines :mod:`optparse`'s behaviour when this option is seen on the command line; the available options are documented above. -* :attr:`type` (default: ``"string"``) +* :attr:`!type` (default: ``"string"``) The argument type expected by this option (e.g., ``"string"`` or ``"int"``); the available option types are documented below. @@ -1084,7 +1084,7 @@ to a particular option, or fail to pass a required option attribute, * ``nargs`` (default: 1) - How many arguments of type :attr:`type` should be consumed when this option is + How many arguments of type :attr:`!type` should be consumed when this option is seen. If > 1, :mod:`optparse` will store a tuple of values to :attr:`dest`. * ``const`` @@ -1415,15 +1415,15 @@ The four arguments to a callback are described below. There are several other option attributes that you can supply when you define a callback option: -:attr:`type` +:attr:`!type` has its usual meaning: as with the ``store`` or ``append`` actions, it instructs - :mod:`optparse` to consume one argument and convert it to :attr:`type`. Rather + :mod:`optparse` to consume one argument and convert it to :attr:`!type`. Rather than storing the converted value(s) anywhere, though, :mod:`optparse` passes it to your callback function. ``nargs`` also has its usual meaning: if it is supplied and > 1, :mod:`optparse` will - consume ``nargs`` arguments, each of which must be convertible to :attr:`type`. + consume ``nargs`` arguments, each of which must be convertible to :attr:`!type`. It then passes a tuple of converted values to your callback. ``callback_args`` @@ -1455,8 +1455,8 @@ where ``value`` is the argument to this option seen on the command-line. :mod:`optparse` will - only expect an argument if :attr:`type` is set; the type of ``value`` will be - the type implied by the option's type. If :attr:`type` for this option is + only expect an argument if :attr:`!type` is set; the type of ``value`` will be + the type implied by the option's type. If :attr:`!type` for this option is ``None`` (no argument expected), then ``value`` will be ``None``. If ``nargs`` > 1, ``value`` will be a tuple of values of the appropriate type. @@ -1583,7 +1583,7 @@ Callback example 5: fixed arguments Things get slightly more interesting when you define callback options that take a fixed number of arguments. Specifying that a callback option takes arguments is similar to defining a ``store`` or ``append`` option: if you define -:attr:`type`, then the option takes one argument that must be convertible to +:attr:`!type`, then the option takes one argument that must be convertible to that type; if you further define ``nargs``, then the option takes ``nargs`` arguments. @@ -1762,7 +1762,7 @@ Adding new actions is a bit trickier, because you have to understand that "typed" actions actions that take a value from the command line and expect it to be of a certain type; or rather, a string that can be converted to a certain type. These - options require a :attr:`type` attribute to the Option constructor. + options require a :attr:`!type` attribute to the Option constructor. These are overlapping sets: some default "store" actions are ``store``, ``store_const``, ``append``, and ``count``, while the default "typed" actions diff --git a/Doc/library/os.rst b/Doc/library/os.rst index b83e665..01118de 100644 --- a/Doc/library/os.rst +++ b/Doc/library/os.rst @@ -606,10 +606,10 @@ by file descriptors. .. note:: - This function is intended for low-level I/O. For normal usage, use the built-in - function :func:`open`, which returns a "file object" with :meth:`~file.read` and - :meth:`~file.write` methods (and many more). To wrap a file descriptor in a "file - object", use :func:`fdopen`. + This function is intended for low-level I/O. For normal usage, use the + built-in function :func:`open`, which returns a "file object" with + :meth:`~file.read` and :meth:`~file.write` methods (and many more). To + wrap a file descriptor in a "file object", use :func:`fdopen`. .. function:: openpty() @@ -754,10 +754,10 @@ Files and Directories .. note:: - Using :func:`access` to check if a user is authorized to e.g. open a file before - actually doing so using :func:`open` creates a security hole, because the user - might exploit the short time interval between checking and opening the file to - manipulate it. + Using :func:`access` to check if a user is authorized to e.g. open a file + before actually doing so using :func:`open` creates a security hole, + because the user might exploit the short time interval between checking + and opening the file to manipulate it. .. note:: diff --git a/Doc/library/ossaudiodev.rst b/Doc/library/ossaudiodev.rst index d8ff3f2..37ead5d 100644 --- a/Doc/library/ossaudiodev.rst +++ b/Doc/library/ossaudiodev.rst @@ -120,7 +120,7 @@ Alternately, you can use the :meth:`setparameters` method to set all three audio parameters at once. This is more convenient, but may not be as flexible in all cases. -The audio device objects returned by :func:`open` define the following methods +The audio device objects returned by :func:`.open` define the following methods and (read-only) attributes: diff --git a/Doc/library/posixfile.rst b/Doc/library/posixfile.rst index aaacc22..c27e412 100644 --- a/Doc/library/posixfile.rst +++ b/Doc/library/posixfile.rst @@ -24,9 +24,8 @@ new file object, the posixfile object. It has all the standard file object methods and adds the methods described below. This module only works for certain flavors of Unix, since it uses :func:`fcntl.fcntl` for file locking. -To instantiate a posixfile object, use the :func:`open` function in the -:mod:`posixfile` module. The resulting object looks and feels roughly the same -as a standard file object. +To instantiate a posixfile object, use the :func:`posixfile.open` function. The +resulting object looks and feels roughly the same as a standard file object. The :mod:`posixfile` module defines the following constants: diff --git a/Doc/library/pyclbr.rst b/Doc/library/pyclbr.rst index a5d8494..36b46f4 100644 --- a/Doc/library/pyclbr.rst +++ b/Doc/library/pyclbr.rst @@ -78,7 +78,7 @@ members: .. attribute:: Class.lineno The line number of the ``class`` statement within the file named by - :attr:`file`. + :attr:`~Class.file`. .. _pyclbr-function-objects: @@ -109,5 +109,5 @@ The :class:`Function` objects used as values in the dictionary returned by .. attribute:: Function.lineno The line number of the ``def`` statement within the file named by - :attr:`file`. + :attr:`~Function.file`. diff --git a/Doc/library/repr.rst b/Doc/library/repr.rst index 2b75257..78284f0 100644 --- a/Doc/library/repr.rst +++ b/Doc/library/repr.rst @@ -27,16 +27,16 @@ This module provides a class, an instance, and a function: .. data:: aRepr - This is an instance of :class:`Repr` which is used to provide the :func:`repr` + This is an instance of :class:`Repr` which is used to provide the :func:`.repr` function described below. Changing the attributes of this object will affect - the size limits used by :func:`repr` and the Python debugger. + the size limits used by :func:`.repr` and the Python debugger. .. function:: repr(obj) - This is the :meth:`repr` method of ``aRepr``. It returns a string similar to - that returned by the built-in function of the same name, but with limits on - most sizes. + This is the :meth:`~Repr.repr` method of ``aRepr``. It returns a string + similar to that returned by the built-in function of the same name, but with + limits on most sizes. .. _repr-objects: @@ -99,7 +99,7 @@ which format specific object types. .. method:: Repr.repr1(obj, level) - Recursive implementation used by :meth:`repr`. This uses the type of *obj* to + Recursive implementation used by :meth:`.repr`. This uses the type of *obj* to determine which formatting method to call, passing it *obj* and *level*. The type-specific methods should call :meth:`repr1` to perform recursive formatting, with ``level - 1`` for the value of *level* in the recursive call. diff --git a/Doc/library/shelve.rst b/Doc/library/shelve.rst index 4e18ab1..503db0f 100644 --- a/Doc/library/shelve.rst +++ b/Doc/library/shelve.rst @@ -108,7 +108,7 @@ Restrictions .. class:: BsdDbShelf(dict[, protocol=None[, writeback=False]]) - A subclass of :class:`Shelf` which exposes :meth:`first`, :meth:`next`, + A subclass of :class:`Shelf` which exposes :meth:`first`, :meth:`!next`, :meth:`previous`, :meth:`last` and :meth:`set_location` which are available in the :mod:`bsddb` module but not in other database modules. The *dict* object passed to the constructor must support those methods. This is generally @@ -122,7 +122,7 @@ Restrictions A subclass of :class:`Shelf` which accepts a *filename* instead of a dict-like object. The underlying file will be opened using :func:`anydbm.open`. By default, the file will be created and opened for both read and write. The - optional *flag* parameter has the same interpretation as for the :func:`open` + optional *flag* parameter has the same interpretation as for the :func:`.open` function. The optional *protocol* and *writeback* parameters have the same interpretation as for the :class:`Shelf` class. @@ -174,8 +174,8 @@ object):: BSD ``db`` database interface. Module :mod:`dbhash` - Thin layer around the :mod:`bsddb` which provides an :func:`open` function like - the other database modules. + Thin layer around the :mod:`bsddb` which provides an :func:`~dbhash.open` + function like the other database modules. Module :mod:`dbm` Standard Unix database interface. diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index 68dfea4..2e47c59 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -2179,12 +2179,12 @@ Files have the following methods: A file object is its own iterator, for example ``iter(f)`` returns *f* (unless *f* is closed). When a file is used as an iterator, typically in a :keyword:`for` loop (for example, ``for line in f: print line``), the - :meth:`next` method is called repeatedly. This method returns the next input + :meth:`.next` method is called repeatedly. This method returns the next input line, or raises :exc:`StopIteration` when EOF is hit when the file is open for reading (behavior is undefined when the file is open for writing). In order to make a :keyword:`for` loop the most efficient way of looping over the lines of a file (a very common operation), the :meth:`next` method uses a hidden read-ahead - buffer. As a consequence of using a read-ahead buffer, combining :meth:`next` + buffer. As a consequence of using a read-ahead buffer, combining :meth:`.next` with other file methods (like :meth:`readline`) does not work right. However, using :meth:`seek` to reposition the file to an absolute position will flush the read-ahead buffer. diff --git a/Doc/library/sunau.rst b/Doc/library/sunau.rst index 9930133..3f231b4 100644 --- a/Doc/library/sunau.rst +++ b/Doc/library/sunau.rst @@ -58,18 +58,18 @@ The :mod:`sunau` module defines the following functions: .. function:: openfp(file, mode) - A synonym for :func:`open`, maintained for backwards compatibility. + A synonym for :func:`.open`, maintained for backwards compatibility. -The :mod:`sunau` module defines the following exception: +The :mod:`sunau` module defines the following exception: .. exception:: Error An error raised when something is impossible because of Sun AU specs or implementation deficiency. -The :mod:`sunau` module defines the following data items: +The :mod:`sunau` module defines the following data items: .. data:: AUDIO_FILE_MAGIC @@ -104,7 +104,7 @@ The :mod:`sunau` module defines the following data items: AU_read Objects --------------- -AU_read objects, as returned by :func:`open` above, have the following methods: +AU_read objects, as returned by :func:`.open` above, have the following methods: .. method:: AU_read.close() @@ -197,7 +197,7 @@ and don't do anything interesting. AU_write Objects ---------------- -AU_write objects, as returned by :func:`open` above, have the following methods: +AU_write objects, as returned by :func:`.open` above, have the following methods: .. method:: AU_write.setnchannels(n) diff --git a/Doc/library/sunaudio.rst b/Doc/library/sunaudio.rst index 4d67b21..9637b09 100644 --- a/Doc/library/sunaudio.rst +++ b/Doc/library/sunaudio.rst @@ -54,7 +54,7 @@ This module defines the following variables and functions: Audio Device Objects -------------------- -The audio device objects are returned by :func:`open` define the following +The audio device objects are returned by :func:`.open` define the following methods (except ``control`` objects which only provide :meth:`getinfo`, :meth:`setinfo`, :meth:`fileno`, and :meth:`drain`): diff --git a/Doc/library/tempfile.rst b/Doc/library/tempfile.rst index e4838ef..c155d66 100644 --- a/Doc/library/tempfile.rst +++ b/Doc/library/tempfile.rst @@ -51,7 +51,7 @@ The module defines the following user-callable functions: The *dir*, *prefix* and *suffix* parameters are passed to :func:`mkstemp`. The returned object is a true file object on POSIX platforms. On other - platforms, it is a file-like object whose :attr:`file` attribute is the + platforms, it is a file-like object whose :attr:`!file` attribute is the underlying true file object. This file-like object can be used in a :keyword:`with` statement, just like a normal file. @@ -67,7 +67,7 @@ The module defines the following user-callable functions: on Windows NT or later). If *delete* is true (the default), the file is deleted as soon as it is closed. - The returned object is always a file-like object whose :attr:`file` + The returned object is always a file-like object whose :attr:`!file` attribute is the underlying true file object. This file-like object can be used in a :keyword:`with` statement, just like a normal file. diff --git a/Doc/library/threading.rst b/Doc/library/threading.rst index d8af157..53a72bd 100644 --- a/Doc/library/threading.rst +++ b/Doc/library/threading.rst @@ -65,8 +65,9 @@ This module defines the following functions and objects: :noindex: A factory function that returns a new event object. An event manages a flag - that can be set to true with the :meth:`set` method and reset to false with the - :meth:`clear` method. The :meth:`wait` method blocks until the flag is true. + that can be set to true with the :meth:`~Event.set` method and reset to false + with the :meth:`clear` method. The :meth:`wait` method blocks until the flag + is true. .. class:: local @@ -666,7 +667,7 @@ This is one of the simplest mechanisms for communication between threads: one thread signals an event and other threads wait for it. An event object manages an internal flag that can be set to true with the -:meth:`set` method and reset to false with the :meth:`clear` method. The +:meth:`~Event.set` method and reset to false with the :meth:`clear` method. The :meth:`wait` method blocks until the flag is true. @@ -691,13 +692,14 @@ An event object manages an internal flag that can be set to true with the .. method:: Event.clear() Reset the internal flag to false. Subsequently, threads calling :meth:`wait` - will block until :meth:`set` is called to set the internal flag to true again. + will block until :meth:`.set` is called to set the internal flag to true + again. .. method:: Event.wait([timeout]) Block until the internal flag is true. If the internal flag is true on entry, - return immediately. Otherwise, block until another thread calls :meth:`set` + return immediately. Otherwise, block until another thread calls :meth:`.set` to set the flag to true, or until the optional timeout occurs. When the timeout argument is present and not ``None``, it should be a floating diff --git a/Doc/library/tkinter.rst b/Doc/library/tkinter.rst index b1a1791..3431f86 100644 --- a/Doc/library/tkinter.rst +++ b/Doc/library/tkinter.rst @@ -524,7 +524,7 @@ defined in the :mod:`Tkinter` module. There are many useful subclasses of Variable already defined: :class:`StringVar`, :class:`IntVar`, :class:`DoubleVar`, and :class:`BooleanVar`. To read the current value of such a variable, call the -:meth:`get` method on it, and to change its value you call the :meth:`set` +:meth:`get` method on it, and to change its value you call the :meth:`!set` method. If you follow this protocol, the widget will always track the value of the variable, with no further intervention on your part. @@ -665,7 +665,7 @@ relief ``"raised"``, ``"sunken"``, ``"flat"``, ``"groove"``, and ``"ridge"``. scrollcommand - This is almost always the :meth:`set` method of some scrollbar widget, but can + This is almost always the :meth:`!set` method of some scrollbar widget, but can be any widget method that takes a single argument. Refer to the file :file:`Demo/tkinter/matt/canvas-with-scrollbars.py` in the Python source distribution for an example. diff --git a/Doc/library/wave.rst b/Doc/library/wave.rst index b931fed..3be0343 100644 --- a/Doc/library/wave.rst +++ b/Doc/library/wave.rst @@ -33,7 +33,7 @@ The :mod:`wave` module defines the following function and exception: .. function:: openfp(file, mode) - A synonym for :func:`open`, maintained for backwards compatibility. + A synonym for :func:`.open`, maintained for backwards compatibility. .. exception:: Error @@ -47,7 +47,7 @@ The :mod:`wave` module defines the following function and exception: Wave_read Objects ----------------- -Wave_read objects, as returned by :func:`open`, have the following methods: +Wave_read objects, as returned by :func:`.open`, have the following methods: .. method:: Wave_read.close() @@ -134,7 +134,7 @@ them, and is otherwise implementation dependent. Wave_write Objects ------------------ -Wave_write objects, as returned by :func:`open`, have the following methods: +Wave_write objects, as returned by :func:`.open`, have the following methods: .. method:: Wave_write.close() diff --git a/Doc/library/webbrowser.rst b/Doc/library/webbrowser.rst index 87b97b1..53829c4 100644 --- a/Doc/library/webbrowser.rst +++ b/Doc/library/webbrowser.rst @@ -10,7 +10,7 @@ The :mod:`webbrowser` module provides a high-level interface to allow displaying Web-based documents to users. Under most circumstances, simply calling the -:func:`open` function from this module will do the right thing. +:func:`.open` function from this module will do the right thing. Under Unix, graphical browsers are preferred under X11, but text-mode browsers will be used if graphical browsers are not available or an X11 display isn't -- cgit v0.12