.. 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
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:
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
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::
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"]
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.
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.
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 should be opened
with ``newline=''``. [#]_ An optional
*dialect* parameter can be given which is used to define a set of parameters
.. 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
modified by the prevailing umask).
-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 :keyword:`in` operator and the :meth:`keys` method are
available. Key and values are always stored as bytes. This means that when
.. 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.
.. method:: min(other[, context])
.. 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.
.. method:: next_minus([context])
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
.. 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='r', buffering=None, encoding=None, errors=None, newline=None, closefd=True)
closed. If a filename is given *closefd* has no effect and 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 (``'w'``,
+ 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 subclass of
:class:`TextIOBase` (specifically :class:`TextIOWrapper`). When used to open
a file in a binary mode with buffering, the returned class is a subclass of
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=-1)
.. 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.
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`.
There is no way to perform case conversions and character classifications
according to the locale. For (Unicode) text strings these are done according
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=None, extra=None)
.. 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
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.
* ``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.
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
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.
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
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
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::
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 ::
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.
* ``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``
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``
``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.
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.
"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
.. 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()
.. 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::
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:
.. attribute:: Class.lineno
The line number of the ``class`` statement within the file named by
- :attr:`file`.
+ :attr:`~Class.file`.
.. _pyclbr-function-objects:
.. attribute:: Function.lineno
The line number of the ``def`` statement within the file named by
- :attr:`file`.
+ :attr:`~Function.file`.
.. data:: aRepr
- 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.
+ 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.
.. 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:
.. 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.
.. 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 third-party :mod:`bsddb` module from `pybsddb
<http://www.jcea.es/programacion/pybsddb.htm>`_ but not in other database
A subclass of :class:`Shelf` which accepts a *filename* instead of a dict-like
object. The underlying file will be opened using :func:`dbm.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.
.. 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
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()
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)
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.
still open, varies across platforms (it can be so used on Unix; it cannot
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.
: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
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.
.. method:: clear()
Reset the internal flag to false. Subsequently, threads calling
- :meth:`wait` will block until :meth:`set` is called to set the internal
+ :meth:`wait` will block until :meth:`.set` is called to set the internal
flag to true again.
.. method:: wait([timeout])
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.
``"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.
.. function:: openfp(file, mode)
- A synonym for :func:`open`, maintained for backwards compatibility.
+ A synonym for :func:`.open`, maintained for backwards compatibility.
.. exception:: Error
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()
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()
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
projects / thirdparty / Python / cpython.git / commitdiff
