diff options
| author | DongHun Kwak <dh0128.kwak@samsung.com> | 2017-07-12 11:05:38 +0900 |
|---|---|---|
| committer | DongHun Kwak <dh0128.kwak@samsung.com> | 2017-07-12 11:05:46 +0900 |
| commit | 6cc694c4c77aac634cca05c9943b43f22bbe042a (patch) | |
| tree | 09b69821a34ec6804d3e0e912b24b9fe3e81c8aa /Doc/library | |
| parent | cd850db82fbac76771227dd7cf7e2d7b1f39ef96 (diff) | |
| download | python-6cc694c4c77aac634cca05c9943b43f22bbe042a.tar.gz python-6cc694c4c77aac634cca05c9943b43f22bbe042a.tar.bz2 python-6cc694c4c77aac634cca05c9943b43f22bbe042a.zip | |
Imported Upstream version 2.7.11upstream/2.7.11
Change-Id: I6fd1d4f1828aa56cf9e1ece97699852529157243
Signed-off-by: DongHun Kwak <dh0128.kwak@samsung.com>
Diffstat (limited to 'Doc/library')
56 files changed, 511 insertions, 233 deletions
diff --git a/Doc/library/2to3.rst b/Doc/library/2to3.rst index bfa7ea3..7ebc208 100644 --- a/Doc/library/2to3.rst +++ b/Doc/library/2to3.rst @@ -271,7 +271,7 @@ and off individually. They are described here in more detail. .. 2to3fixer:: input - Converts ``input(prompt)`` to ``eval(input(prompt))`` + Converts ``input(prompt)`` to ``eval(input(prompt))``. .. 2to3fixer:: intern diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index 9955646..181291f 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -1948,4 +1948,4 @@ A partial upgrade path from :mod:`optparse` to :mod:`argparse`: ``%(default)s`` and ``%(prog)s``. * Replace the OptionParser constructor ``version`` argument with a call to - ``parser.add_argument('--version', action='version', version='<the version>')`` + ``parser.add_argument('--version', action='version', version='<the version>')``. diff --git a/Doc/library/bdb.rst b/Doc/library/bdb.rst index 82ef37e..6980353 100644 --- a/Doc/library/bdb.rst +++ b/Doc/library/bdb.rst @@ -223,7 +223,7 @@ The :mod:`bdb` module also defines two classes: .. method:: set_until(frame) Stop when the line with the line no greater than the current one is - reached or when returning from current frame + reached or when returning from current frame. .. method:: set_trace([frame]) diff --git a/Doc/library/codecs.rst b/Doc/library/codecs.rst index feeb236..6f8b7af 100644 --- a/Doc/library/codecs.rst +++ b/Doc/library/codecs.rst @@ -392,8 +392,8 @@ interfaces of the stateless encoder and decoder: handling. The method may not store state in the :class:`Codec` instance. Use - :class:`StreamCodec` for codecs which have to keep state in order to make - encoding/decoding efficient. + :class:`StreamWriter` for codecs which have to keep state in order to make + encoding efficient. The encoder must be able to handle zero length input and return an empty object of the output object type in this situation. @@ -413,8 +413,8 @@ interfaces of the stateless encoder and decoder: handling. The method may not store state in the :class:`Codec` instance. Use - :class:`StreamCodec` for codecs which have to keep state in order to make - encoding/decoding efficient. + :class:`StreamReader` for codecs which have to keep state in order to make + decoding efficient. The decoder must be able to handle zero length input and return an empty object of the output object type in this situation. @@ -1067,6 +1067,8 @@ particular, the following variants typically exist: +-----------------+--------------------------------+--------------------------------+ | iso8859_10 | iso-8859-10, latin6, L6 | Nordic languages | +-----------------+--------------------------------+--------------------------------+ +| iso8859_11 | iso-8859-11, thai | Thai languages | ++-----------------+--------------------------------+--------------------------------+ | iso8859_13 | iso-8859-13, latin7, L7 | Baltic languages | +-----------------+--------------------------------+--------------------------------+ | iso8859_14 | iso-8859-14, latin8, L8 | Celtic languages | @@ -1193,21 +1195,22 @@ The following codecs provide str-to-str encoding and decoding +--------------------+---------------------------+---------------------------+------------------------------+ | Codec | Aliases | Purpose | Encoder/decoder | +====================+===========================+===========================+==============================+ -| base64_codec | base64, base-64 | Convert operand to MIME | :meth:`base64.b64encode`, | -| | | base64 (the result always | :meth:`base64.b64decode` | -| | | includes a trailing | | -| | | ``'\n'``) | | +| base64_codec | base64, base-64 | Convert operand to | :meth:`base64.encodestring`, | +| | | multiline MIME base64 (the| :meth:`base64.decodestring` | +| | | result always includes a | | +| | | trailing ``'\n'``) | | +--------------------+---------------------------+---------------------------+------------------------------+ | bz2_codec | bz2 | Compress the operand | :meth:`bz2.compress`, | | | | using bz2 | :meth:`bz2.decompress` | +--------------------+---------------------------+---------------------------+------------------------------+ -| hex_codec | hex | Convert operand to | :meth:`base64.b16encode`, | -| | | hexadecimal | :meth:`base64.b16decode` | +| hex_codec | hex | Convert operand to | :meth:`binascii.b2a_hex`, | +| | | hexadecimal | :meth:`binascii.a2b_hex` | | | | representation, with two | | | | | digits per byte | | +--------------------+---------------------------+---------------------------+------------------------------+ -| quopri_codec | quopri, quoted-printable, | Convert operand to MIME | :meth:`quopri.encodestring`, | -| | quotedprintable | quoted printable | :meth:`quopri.decodestring` | +| quopri_codec | quopri, quoted-printable, | Convert operand to MIME | :meth:`quopri.encode` with | +| | quotedprintable | quoted printable | ``quotetabs=True``, | +| | | | :meth:`quopri.decode` | +--------------------+---------------------------+---------------------------+------------------------------+ | string_escape | | Produce a string that is | | | | | suitable as string | | diff --git a/Doc/library/collections.rst b/Doc/library/collections.rst index b947e27..58278d1 100644 --- a/Doc/library/collections.rst +++ b/Doc/library/collections.rst @@ -104,9 +104,9 @@ For example:: .. method:: most_common([n]) Return a list of the *n* most common elements and their counts from the - most common to the least. If *n* is not specified, :func:`most_common` - returns *all* elements in the counter. Elements with equal counts are - ordered arbitrarily: + most common to the least. If *n* is omitted or ``None``, + :func:`most_common` returns *all* elements in the counter. + Elements with equal counts are ordered arbitrarily: >>> Counter('abracadabra').most_common(3) [('a', 5), ('r', 2), ('b', 2)] @@ -696,6 +696,7 @@ field names, the method and attribute names start with an underscore. Return a new :class:`OrderedDict` which maps field names to their corresponding values:: + >>> p = Point(x=11, y=22) >>> p._asdict() OrderedDict([('x', 11), ('y', 22)]) @@ -977,7 +978,7 @@ ABC Inherits from Abstract Methods Mixin KeysView ValuesView - ABCs for mapping, items, keys, and values :term:`views <view>`. + ABCs for mapping, items, keys, and values :term:`views <dictionary view>`. These ABCs allow us to ask classes or instances if they provide diff --git a/Doc/library/cookie.rst b/Doc/library/cookie.rst index 19786f7..8d64206 100644 --- a/Doc/library/cookie.rst +++ b/Doc/library/cookie.rst @@ -116,7 +116,7 @@ Cookie Objects Return an encoded value. *val* can be any type, but return value must be a string. This method does nothing in :class:`BaseCookie` --- it exists so it can - be overridden + be overridden. In general, it should be the case that :meth:`value_encode` and :meth:`value_decode` are inverses on the range of *value_decode*. diff --git a/Doc/library/cookielib.rst b/Doc/library/cookielib.rst index e559f82..7829f53 100644 --- a/Doc/library/cookielib.rst +++ b/Doc/library/cookielib.rst @@ -546,7 +546,7 @@ Netscape protocol strictness switches: .. attribute:: DefaultCookiePolicy.strict_ns_unverifiable - apply RFC 2965 rules on unverifiable transactions even to Netscape cookies + Apply RFC 2965 rules on unverifiable transactions even to Netscape cookies. .. attribute:: DefaultCookiePolicy.strict_ns_domain diff --git a/Doc/library/csv.rst b/Doc/library/csv.rst index 1f5ae65..d3d505e 100644 --- a/Doc/library/csv.rst +++ b/Doc/library/csv.rst @@ -338,7 +338,7 @@ Dialects support the following attributes: .. attribute:: Dialect.doublequote - Controls how instances of *quotechar* appearing inside a field should be + Controls how instances of *quotechar* appearing inside a field should themselves be quoted. When :const:`True`, the character is doubled. When :const:`False`, the *escapechar* is used as a prefix to the *quotechar*. It defaults to :const:`True`. diff --git a/Doc/library/decimal.rst b/Doc/library/decimal.rst index 564d10c..a203fbd 100644 --- a/Doc/library/decimal.rst +++ b/Doc/library/decimal.rst @@ -890,7 +890,7 @@ Decimal objects Engineering notation has an exponent which is a multiple of 3, so there are up to 3 digits left of the decimal place. For example, converts - ``Decimal('123E+1')`` to ``Decimal('1.23E+3')`` + ``Decimal('123E+1')`` to ``Decimal('1.23E+3')``. .. method:: to_integral([rounding[, context]]) diff --git a/Doc/library/difflib.rst b/Doc/library/difflib.rst index 89a457c..03e8cb8 100644 --- a/Doc/library/difflib.rst +++ b/Doc/library/difflib.rst @@ -94,9 +94,9 @@ diffs. For comparing directories and files, see also, the :mod:`filecmp` module. *wrapcolumn* is an optional keyword to specify column number where lines are broken and wrapped, defaults to ``None`` where lines are not wrapped. - *linejunk* and *charjunk* are optional keyword arguments passed into ``ndiff()`` + *linejunk* and *charjunk* are optional keyword arguments passed into :func:`ndiff` (used by :class:`HtmlDiff` to generate the side by side HTML differences). See - ``ndiff()`` documentation for argument default values and descriptions. + :func:`ndiff` documentation for argument default values and descriptions. The following methods are public: diff --git a/Doc/library/dis.rst b/Doc/library/dis.rst index 727af41..04b9b15 100644 --- a/Doc/library/dis.rst +++ b/Doc/library/dis.rst @@ -647,6 +647,13 @@ the more significant byte last. Works as ``BUILD_TUPLE``, but creates a list. +.. opcode:: BUILD_SET (count) + + Works as ``BUILD_TUPLE``, but creates a set. + + .. versionadded:: 2.7 + + .. opcode:: BUILD_MAP (count) Pushes a new dictionary object onto the stack. The dictionary is pre-sized diff --git a/Doc/library/doctest.rst b/Doc/library/doctest.rst index a1e270d..4558123 100644 --- a/Doc/library/doctest.rst +++ b/Doc/library/doctest.rst @@ -950,15 +950,11 @@ and :ref:`doctest-simple-testfile`. .. versionchanged:: 2.5 The optional argument *isprivate*, deprecated in 2.4, was removed. -There's also a function to run the doctests associated with a single object. -This function is provided for backward compatibility. There are no plans to -deprecate it, but it's rarely useful: - .. function:: run_docstring_examples(f, globs[, verbose][, name][, compileflags][, optionflags]) - Test examples associated with object *f*; for example, *f* may be a module, - function, or class object. + Test examples associated with object *f*; for example, *f* may be a string, + a module, a function, or a class object. A shallow copy of dictionary argument *globs* is used for the execution context. @@ -1899,6 +1895,27 @@ several options for organizing tests: * Define a ``__test__`` dictionary mapping from regression test topics to docstrings containing test cases. +When you have placed your tests in a module, the module can itself be the test +runner. When a test fails, you can arrange for your test runner to re-run only +the failing doctest while you debug the problem. Here is a minimal example of +such a test runner:: + + if __name__ == '__main__': + import doctest + flags = doctest.REPORT_NDIFF|doctest.REPORT_ONLY_FIRST_FAILURE + if len(sys.argv) > 1: + name = sys.argv[1] + if name in globals(): + obj = globals()[name] + else: + obj = __test__[name] + doctest.run_docstring_examples(obj, globals(), name=name, + optionflags=flags) + else: + fail, total = doctest.testmod(optionflags=flags) + print("{} failures out of {} tests".format(fail, total)) + + .. rubric:: Footnotes .. [#] Examples containing both expected output and an exception are not supported. diff --git a/Doc/library/email.parser.rst b/Doc/library/email.parser.rst index 0f99a2f..04e2334 100644 --- a/Doc/library/email.parser.rst +++ b/Doc/library/email.parser.rst @@ -133,7 +133,7 @@ class. methods on file-like objects. The text contained in *fp* must be formatted as a block of :rfc:`2822` - style headers and header continuation lines, optionally preceded by a + style headers and header continuation lines, optionally preceded by an envelope header. The header block is terminated either by the end of the data or by a blank line. Following the header block is the body of the message (which may contain MIME-encoded subparts). diff --git a/Doc/library/exceptions.rst b/Doc/library/exceptions.rst index 9291c18..fe14656 100644 --- a/Doc/library/exceptions.rst +++ b/Doc/library/exceptions.rst @@ -496,7 +496,7 @@ module for more information. .. exception:: SyntaxWarning - Base class for warnings about dubious syntax + Base class for warnings about dubious syntax. .. exception:: RuntimeWarning diff --git a/Doc/library/fcntl.rst b/Doc/library/fcntl.rst index 562e78f..478c450 100644 --- a/Doc/library/fcntl.rst +++ b/Doc/library/fcntl.rst @@ -82,6 +82,8 @@ The module defines the following functions: which is a change from versions 2.3 and 2.4. Supply the argument explicitly if version portability is a priority. + If the :c:func:`ioctl` fails, an :exc:`IOError` exception is raised. + An example:: >>> import array, fcntl, struct, termios, os @@ -103,6 +105,8 @@ The module defines the following functions: :manpage:`flock(2)` for details. (On some systems, this function is emulated using :c:func:`fcntl`.) + If the :c:func:`flock` fails, an :exc:`IOError` exception is raised. + .. function:: lockf(fd, operation, [length, [start, [whence]]]) diff --git a/Doc/library/fractions.rst b/Doc/library/fractions.rst index 81b419e..00a7672 100644 --- a/Doc/library/fractions.rst +++ b/Doc/library/fractions.rst @@ -89,7 +89,7 @@ another rational number, or from a string. This class method constructs a :class:`Fraction` representing the exact value of *flt*, which must be a :class:`float`. Beware that - ``Fraction.from_float(0.3)`` is not the same value as ``Fraction(3, 10)`` + ``Fraction.from_float(0.3)`` is not the same value as ``Fraction(3, 10)``. .. note:: From Python 2.7 onwards, you can also construct a :class:`Fraction` instance directly from a :class:`float`. diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index 8af9f58..8b677ed 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -261,7 +261,7 @@ section. .. class:: complex([real[, imag]]) - Return a complex number with the value *real* + *imag*\*j or convert a string or + Return a complex number with the value *real* + *imag*\*1j or convert a string or number to a complex number. If the first parameter is a string, it will be interpreted as a complex number and the function must be called without a second parameter. The second parameter can never be a string. Each argument may be any @@ -687,10 +687,10 @@ section. is a type object (new-style class) and *object* is an object of that type or of a (direct, indirect or :term:`virtual <abstract base class>`) subclass thereof. If *object* is not a class instance or - an object of the given type, the function always returns false. If *classinfo* - is neither a class object nor a type object, it may be a tuple of class or type - objects, or may recursively contain other such tuples (other sequence types are - not accepted). If *classinfo* is not a class, type, or tuple of classes, types, + an object of the given type, the function always returns false. + If *classinfo* is a tuple of class or type objects (or recursively, other + such tuples), return true if *object* is an instance of any of the classes + or types. If *classinfo* is not a class, type, or tuple of classes, types, and such tuples, a :exc:`TypeError` exception is raised. .. versionchanged:: 2.2 @@ -1191,10 +1191,11 @@ section. except NameError: cache = {} - It is legal though generally not very useful to reload built-in or dynamically - loaded modules, except for :mod:`sys`, :mod:`__main__` and :mod:`__builtin__`. - In many cases, however, extension modules are not designed to be initialized - more than once, and may fail in arbitrary ways when reloaded. + It is generally not very useful to reload built-in or dynamically loaded + modules. Reloading :mod:`sys`, :mod:`__main__`, :mod:`builtins` and other + key modules is not recommended. In many cases extension modules are not + designed to be initialized more than once, and may fail in arbitrary ways + when reloaded. If a module imports objects from another module using :keyword:`from` ... :keyword:`import` ..., calling :func:`reload` for the other module does not @@ -1761,4 +1762,3 @@ bypass these functions without concerns about missing something important. .. [#] In the current implementation, local variable bindings cannot normally be affected this way, but variables retrieved from other scopes (such as modules) can be. This may change. - diff --git a/Doc/library/glob.rst b/Doc/library/glob.rst index 75f67b9..75f0f8a 100644 --- a/Doc/library/glob.rst +++ b/Doc/library/glob.rst @@ -12,13 +12,13 @@ -------------- The :mod:`glob` module finds all the pathnames matching a specified pattern -according to the rules used by the Unix shell. No tilde expansion is done, but -``*``, ``?``, and character ranges expressed with ``[]`` will be correctly -matched. This is done by using the :func:`os.listdir` and -:func:`fnmatch.fnmatch` functions in concert, and not by actually invoking a -subshell. Note that unlike :func:`fnmatch.fnmatch`, :mod:`glob` treats -filenames beginning with a dot (``.``) as special cases. (For tilde and shell -variable expansion, use :func:`os.path.expanduser` and +according to the rules used by the Unix shell, although results are returned in +arbitrary order. No tilde expansion is done, but ``*``, ``?``, and character +ranges expressed with ``[]`` will be correctly matched. This is done by using +the :func:`os.listdir` and :func:`fnmatch.fnmatch` functions in concert, and +not by actually invoking a subshell. Note that unlike :func:`fnmatch.fnmatch`, +:mod:`glob` treats filenames beginning with a dot (``.``) as special cases. +(For tilde and shell variable expansion, use :func:`os.path.expanduser` and :func:`os.path.expandvars`.) For a literal match, wrap the meta-characters in brackets. diff --git a/Doc/library/gzip.rst b/Doc/library/gzip.rst index e26fe28..7c16d3a 100644 --- a/Doc/library/gzip.rst +++ b/Doc/library/gzip.rst @@ -96,26 +96,22 @@ Examples of usage Example of how to read a compressed file:: import gzip - f = gzip.open('file.txt.gz', 'rb') - file_content = f.read() - f.close() + with gzip.open('file.txt.gz', 'rb') as f: + file_content = f.read() Example of how to create a compressed GZIP file:: import gzip content = "Lots of content here" - f = gzip.open('file.txt.gz', 'wb') - f.write(content) - f.close() + with gzip.open('file.txt.gz', 'wb') as f: + f.write(content) Example of how to GZIP compress an existing file:: import gzip - f_in = open('file.txt', 'rb') - f_out = gzip.open('file.txt.gz', 'wb') - f_out.writelines(f_in) - f_out.close() - f_in.close() + import shutil + with open('file.txt', 'rb') as f_in, gzip.open('file.txt.gz', 'wb') as f_out: + shutil.copyfileobj(f_in, f_out) .. seealso:: diff --git a/Doc/library/hashlib.rst b/Doc/library/hashlib.rst index e33ef50..9bb3bb7 100644 --- a/Doc/library/hashlib.rst +++ b/Doc/library/hashlib.rst @@ -153,8 +153,8 @@ A hash object has the following methods: compute the digests of strings that share a common initial substring. -Key Derivation Function ------------------------ +Key derivation +-------------- Key derivation and key stretching algorithms are designed for secure password hashing. Naive algorithms such as ``sha1(password)`` are not resistant against @@ -204,7 +204,7 @@ include a `salt <https://en.wikipedia.org/wiki/Salt_%28cryptography%29>`_. http://csrc.nist.gov/publications/fips/fips180-2/fips180-2.pdf The FIPS 180-2 publication on Secure Hash Algorithms. - http://en.wikipedia.org/wiki/Cryptographic_hash_function#Cryptographic_hash_algorithms + https://en.wikipedia.org/wiki/Cryptographic_hash_function#Cryptographic_hash_algorithms Wikipedia article with information on which algorithms have known issues and what that means regarding their use. diff --git a/Doc/library/hmac.rst b/Doc/library/hmac.rst index 09e819a..eef8856 100644 --- a/Doc/library/hmac.rst +++ b/Doc/library/hmac.rst @@ -2,7 +2,7 @@ ======================================================== .. module:: hmac - :synopsis: Keyed-Hashing for Message Authentication (HMAC) implementation for Python. + :synopsis: Keyed-Hashing for Message Authentication (HMAC) implementation .. moduleauthor:: Gerhard Häring <ghaering@users.sourceforge.net> .. sectionauthor:: Gerhard Häring <ghaering@users.sourceforge.net> diff --git a/Doc/library/htmllib.rst b/Doc/library/htmllib.rst index d9d81df..e5045dd 100644 --- a/Doc/library/htmllib.rst +++ b/Doc/library/htmllib.rst @@ -7,6 +7,8 @@ .. deprecated:: 2.6 The :mod:`htmllib` module has been removed in Python 3. + Use :mod:`HTMLParser` instead in Python 2, and the equivalent, + :mod:`html.parser`, in Python 3. .. index:: diff --git a/Doc/library/htmlparser.rst b/Doc/library/htmlparser.rst index 3aba74e..81d5c53 100644 --- a/Doc/library/htmlparser.rst +++ b/Doc/library/htmlparser.rst @@ -201,7 +201,7 @@ implementations do nothing (except for :meth:`~HTMLParser.handle_startendtag`): The content of Internet Explorer conditional comments (condcoms) will also be sent to this method, so, for ``<!--[if IE 9]>IE9-specific content<![endif]-->``, - this method will receive ``'[if IE 9]>IE-specific content<![endif]'``. + this method will receive ``'[if IE 9]>IE9-specific content<![endif]'``. .. method:: HTMLParser.handle_decl(decl) diff --git a/Doc/library/idle.rst b/Doc/library/idle.rst index c842b26..4384d56 100644 --- a/Doc/library/idle.rst +++ b/Doc/library/idle.rst @@ -8,23 +8,29 @@ IDLE single: Python Editor single: Integrated Development Environment -.. moduleauthor:: Guido van Rossum <guido@Python.org> +.. moduleauthor:: Guido van Rossum <guido@python.org> -IDLE is the Python IDE built with the :mod:`tkinter` GUI toolkit. +IDLE is Python's Integrated Development and Learning Environment. IDLE has the following features: * coded in 100% pure Python, using the :mod:`tkinter` GUI toolkit -* cross-platform: works on Windows, Unix, and Mac OS X +* cross-platform: works mostly the same on Windows, Unix, and Mac OS X + +* Python shell window (interactive interpreter) with colorizing + of code input, output, and error messages * multi-window text editor with multiple undo, Python colorizing, - smart indent, call tips, and many other features + smart indent, call tips, auto completion, and other features -* Python shell window (a.k.a. interactive interpreter) +* search within any window, replace within editor windows, and search + through multiple files (grep) -* debugger (not complete, but you can set breakpoints, view and step) +* debugger with persistent breakpoints, stepping, and viewing + of global and local namespaces +* configuration, browsers, and other dialogs Menus ----- @@ -37,8 +43,6 @@ context menu. IDLE's menus dynamically change based on which window is currently selected. Each menu documented below indicates which window type it is associated with. -Click on the dotted line at the top of a menu to "tear it off": a separate -window containing the menu is created (for Unix and Windows only). File menu (Shell and Editor) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -202,7 +206,12 @@ Check Module Run Module Do Check Module (above). If no error, restart the shell to clean the - environment, then execute the module. + environment, then execute the module. Output is displayed in the Shell + window. Note that output requires use of ``print`` or ``write``. + When execution is complete, the Shell retains focus and displays a prompt. + At this point, one may interactively explore the result of execution. + This is similar to executing a file with ``python -i file`` at a command + line. Shell menu (Shell window only) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -243,16 +252,16 @@ Options menu (Shell and Editor) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Configure IDLE - Open a configuration dialog. Fonts, indentation, keybindings, and color - themes may be altered. Startup Preferences may be set, and additional - help sources can be specified. Non-default user setting are saved in a - .idlerc directory in the user's home directory. Problems caused by bad user - configuration files are solved by editing or deleting one or more of the - files in .idlerc. + Open a configuration dialog and change preferences for the following: + fonts, indentation, keybindings, text color themes, startup windows and + size, additional help sources, and extensions (see below). On OS X, + open the configuration dialog by selecting Preferences in the application + menu. To use a new built-in color theme (IDLE Dark) with older IDLEs, + save it as a new custom theme. -Configure Extensions - Open a configuration dialog for setting preferences for extensions - (discussed below). See note above about the location of user settings. + Non-default user settings are saved in a .idlerc directory in the user's + home directory. Problems caused by bad user configuration files are solved + by editing or deleting one or more of the files in .idlerc. Code Context (toggle)(Editor Window only) Open a pane at the top of the edit window which shows the block context @@ -331,8 +340,8 @@ Go to file/line Editing and navigation ---------------------- -In this section, 'C' refers to the Control key on Windows and Unix and -the Command key on Mac OSX. +In this section, 'C' refers to the :kbd:`Control` key on Windows and Unix and +the :kbd:`Command` key on Mac OSX. * :kbd:`Backspace` deletes to the left; :kbd:`Del` deletes to the right @@ -425,9 +434,35 @@ Note that IDLE itself places quite a few modules in sys.modules, so much can be found by default, e.g. the re module. If you don't like the ACW popping up unbidden, simply make the delay -longer or disable the extension. Or another option is the delay could -be set to zero. Another alternative to preventing ACW popups is to -disable the call tips extension. +longer or disable the extension. + +Calltips +^^^^^^^^ + +A calltip is shown when one types :kbd:`(` after the name of an *acccessible* +function. A name expression may include dots and subscripts. A calltip +remains until it is clicked, the cursor is moved out of the argument area, +or :kbd:`)` is typed. When the cursor is in the argument part of a definition, +the menu or shortcut display a calltip. + +A calltip consists of the function signature and the first line of the +docstring. For builtins without an accessible signature, the calltip +consists of all lines up the fifth line or the first blank line. These +details may change. + +The set of *accessible* functions depends on what modules have been imported +into the user process, including those imported by Idle itself, +and what definitions have been run, all since the last restart. + +For example, restart the Shell and enter ``itertools.count(``. A calltip +appears because Idle imports itertools into the user process for its own use. +(This could change.) Enter ``turtle.write(`` and nothing appears. Idle does +not import turtle. The menu or shortcut do nothing either. Enter +``import turtle`` and then ``turtle.write(`` will work. + +In an editor, import statements have no effect until one runs the file. One +might want to run a file after writing the import statements at the top, +or immediately run an existing file before editing. Python Shell window ^^^^^^^^^^^^^^^^^^^ @@ -448,42 +483,24 @@ Python Shell window * :kbd:`Return` while on any previous command retrieves that command -Syntax colors -------------- - -The coloring is applied in a background "thread," so you may occasionally see -uncolorized text. To change the color scheme, edit the ``[Colors]`` section in -:file:`config.txt`. - -Python syntax colors: - Keywords - orange - - Strings - green - - Comments - red - - Definitions - blue - -Shell colors: - Console output - brown - - stdout - blue +Text colors +^^^^^^^^^^^ - stderr - dark green +Idle defaults to black on white text, but colors text with special meanings. +For the shell, these are shell output, shell error, user output, and +user error. For Python code, at the shell prompt or in an editor, these are +keywords, builtin class and function names, names following ``class`` and +``def``, strings, and comments. For any text window, these are the cursor (when +present), found text (when possible), and selected text. - stdin - black +Text coloring is done in the background, so uncolorized text is occasionally +visible. To change the color scheme, use the Configure IDLE dialog +Highlighting tab. The marking of debugger breakpoint lines in the editor and +text in popups and dialogs is not user-configurable. -Startup -------- +Startup and code execution +-------------------------- Upon startup with the ``-s`` option, IDLE will execute the file referenced by the environment variables :envvar:`IDLESTARTUP` or :envvar:`PYTHONSTARTUP`. @@ -505,31 +522,60 @@ Command line usage :: - idle.py [-c command] [-d] [-e] [-s] [-t title] [arg] ... + idle.py [-c command] [-d] [-e] [-h] [-i] [-r file] [-s] [-t title] [-] [arg] ... - -c command run this command - -d enable debugger - -e edit mode; arguments are files to be edited - -s run $IDLESTARTUP or $PYTHONSTARTUP first + -c command run command in the shell window + -d enable debugger and open shell window + -e open editor window + -h print help message with legal combinatios and exit + -i open shell window + -r file run file in shell window + -s run $IDLESTARTUP or $PYTHONSTARTUP first, in shell window -t title set title of shell window + - run stdin in shell (- must be last option before args) If there are arguments: -#. If ``-e`` is used, arguments are files opened for editing and - ``sys.argv`` reflects the arguments passed to IDLE itself. +* If ``-``, ``-c``, or ``r`` is used, all arguments are placed in + ``sys.argv[1:...]`` and ``sys.argv[0]`` is set to ``''``, ``'-c'``, + or ``'-r'``. No editor window is opened, even if that is the default + set in the Options dialog. + +* Otherwise, arguments are files opened for editing and + ``sys.argv`` reflects the arguments passed to IDLE itself. -#. Otherwise, if ``-c`` is used, all arguments are placed in - ``sys.argv[1:...]``, with ``sys.argv[0]`` set to ``'-c'``. -#. Otherwise, if neither ``-e`` nor ``-c`` is used, the first - argument is a script which is executed with the remaining arguments in - ``sys.argv[1:...]`` and ``sys.argv[0]`` set to the script name. If the - script name is '-', no script is executed but an interactive Python session - is started; the arguments are still available in ``sys.argv``. +IDLE-console differences +^^^^^^^^^^^^^^^^^^^^^^^^ + +As much as possible, the result of executing Python code with IDLE is the +same as executing the same code in a console window. However, the different +interface and operation occasionally affects results. + +For instance, IDLE normally executes user code in a separate process from +the IDLE GUI itself. The IDLE versions of sys.stdin, .stdout, and .stderr in the +execution process get input from and send output to the GUI process, +which keeps control of the keyboard and screen. This is normally transparent, +but code that access these object will see different attribute values. +Also, functions that directly access the keyboard and screen will not work. + +With IDLE's Shell, one enters, edits, and recalls complete statements. +Some consoles only work with a single physical line at a time. Running without a subprocess ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +By default, IDLE executes user code in a separate subprocess via a socket, +which uses the internal loopback interface. This connection is not +externally visible and no data is sent to or received from the Internet. +If firewall software complains anyway, you can ignore it. + +If the attempt to make the socket connection fails, Idle will notify you. +Such failures are sometimes transient, but if persistent, the problem +may be either a firewall blocking the connecton or misconfiguration of +a particular system. Until the problem is fixed, one can run Idle with +the -n command line switch. + If IDLE is started with the -n command line switch it will run in a single process and will not create the subprocess which runs the RPC Python execution server. This can be useful if Python cannot create diff --git a/Doc/library/io.rst b/Doc/library/io.rst index ab5a043..6743b27 100644 --- a/Doc/library/io.rst +++ b/Doc/library/io.rst @@ -299,11 +299,11 @@ I/O Base Classes Note that it's already possible to iterate on file objects using ``for line in file: ...`` without calling ``file.readlines()``. - .. method:: seek(offset, whence=SEEK_SET) + .. method:: seek(offset[, whence]) Change the stream position to the given byte *offset*. *offset* is - interpreted relative to the position indicated by *whence*. Values for - *whence* are: + interpreted relative to the position indicated by *whence*. The default + value for *whence* is :data:`SEEK_SET`. Values for *whence* are: * :data:`SEEK_SET` or ``0`` -- start of the stream (the default); *offset* should be zero or positive @@ -716,10 +716,11 @@ Text I/O If *limit* is specified, at most *limit* characters will be read. - .. method:: seek(offset, whence=SEEK_SET) + .. method:: seek(offset[, whence]) - Change the stream position to the given *offset*. Behaviour depends - on the *whence* parameter: + Change the stream position to the given *offset*. Behaviour depends on + the *whence* parameter. The default value for *whence* is + :data:`SEEK_SET`. * :data:`SEEK_SET` or ``0``: seek from the start of the stream (the default); *offset* must either be a number returned by @@ -802,10 +803,16 @@ Text I/O An in-memory stream for unicode text. It inherits :class:`TextIOWrapper`. - The initial value of the buffer (an empty unicode string by default) can - be set by providing *initial_value*. The *newline* argument works like - that of :class:`TextIOWrapper`. The default is to consider only ``\n`` - characters as end of lines and to do no newline translation. + The initial value of the buffer can be set by providing *initial_value*. + If newline translation is enabled, newlines will be encoded as if by + :meth:`~TextIOBase.write`. The stream is positioned at the start of + the buffer. + + The *newline* argument works like that of :class:`TextIOWrapper`. + The default is to consider only ``\n`` characters as ends of lines and + to do no newline translation. If *newline* is set to ``None``, + newlines are written as ``\n`` on all platforms, but universal + newline decoding is still performed when reading. :class:`StringIO` provides this method in addition to those from :class:`TextIOWrapper` and its parents: @@ -814,7 +821,8 @@ Text I/O Return a ``unicode`` containing the entire contents of the buffer at any time before the :class:`StringIO` object's :meth:`close` method is - called. + called. Newlines are decoded as if by :meth:`~TextIOBase.read`, + although the stream position is not changed. Example usage:: diff --git a/Doc/library/json.rst b/Doc/library/json.rst index 6db8f97..b501d65 100644 --- a/Doc/library/json.rst +++ b/Doc/library/json.rst @@ -356,7 +356,7 @@ Encoders and Decoders .. method:: decode(s) Return the Python representation of *s* (a :class:`str` or - :class:`unicode` instance containing a JSON document) + :class:`unicode` instance containing a JSON document). .. method:: raw_decode(s) diff --git a/Doc/library/locale.rst b/Doc/library/locale.rst index 5590514..8fa1a1b 100644 --- a/Doc/library/locale.rst +++ b/Doc/library/locale.rst @@ -208,7 +208,7 @@ The :mod:`locale` module defines the following exception and functions: .. data:: RADIXCHAR - Get the radix character (decimal dot, decimal comma, etc.) + Get the radix character (decimal dot, decimal comma, etc.). .. data:: THOUSEP diff --git a/Doc/library/math.rst b/Doc/library/math.rst index 562388e..22d2316 100644 --- a/Doc/library/math.rst +++ b/Doc/library/math.rst @@ -280,12 +280,12 @@ Angular conversion .. function:: degrees(x) - Converts angle *x* from radians to degrees. + Convert angle *x* from radians to degrees. .. function:: radians(x) - Converts angle *x* from degrees to radians. + Convert angle *x* from degrees to radians. Hyperbolic functions diff --git a/Doc/library/modulefinder.rst b/Doc/library/modulefinder.rst index 40bf60f..4acddd2 100644 --- a/Doc/library/modulefinder.rst +++ b/Doc/library/modulefinder.rst @@ -55,7 +55,7 @@ report of the imported modules will be printed. .. attribute:: modules A dictionary mapping module names to modules. See - :ref:`modulefinder-example` + :ref:`modulefinder-example`. .. _modulefinder-example: diff --git a/Doc/library/msvcrt.rst b/Doc/library/msvcrt.rst index d7fd3fb..87b8166 100644 --- a/Doc/library/msvcrt.rst +++ b/Doc/library/msvcrt.rst @@ -19,7 +19,7 @@ documentation. The module implements both the normal and wide char variants of the console I/O api. The normal API deals only with ASCII characters and is of limited use for internationalized applications. The wide char API should be used where -ever possible +ever possible. .. _msvcrt-files: diff --git a/Doc/library/multiprocessing.rst b/Doc/library/multiprocessing.rst index 021e3c8..2c765f5 100644 --- a/Doc/library/multiprocessing.rst +++ b/Doc/library/multiprocessing.rst @@ -908,10 +908,16 @@ object -- see :ref:`multiprocessing-managers`. .. class:: BoundedSemaphore([value]) - A bounded semaphore object: a clone of :class:`threading.BoundedSemaphore`. + A bounded semaphore object: a close analog of + :class:`threading.BoundedSemaphore`. - (On Mac OS X, this is indistinguishable from :class:`Semaphore` because - ``sem_getvalue()`` is not implemented on that platform). + A solitary difference from its close analog exists: its ``acquire`` method's + first argument is named *block* and it supports an optional second argument + *timeout*, as is consistent with :meth:`Lock.acquire`. + + .. note:: + On Mac OS X, this is indistinguishable from :class:`Semaphore` because + ``sem_getvalue()`` is not implemented on that platform. .. class:: Condition([lock]) @@ -930,17 +936,124 @@ object -- see :ref:`multiprocessing-managers`. .. versionchanged:: 2.7 Previously, the method always returned ``None``. + .. class:: Lock() - A non-recursive lock object: a clone of :class:`threading.Lock`. + A non-recursive lock object: a close analog of :class:`threading.Lock`. + Once a process or thread has acquired a lock, subsequent attempts to + acquire it from any process or thread will block until it is released; + any process or thread may release it. The concepts and behaviors of + :class:`threading.Lock` as it applies to threads are replicated here in + :class:`multiprocessing.Lock` as it applies to either processes or threads, + except as noted. + + Note that :class:`Lock` is actually a factory function which returns an + instance of ``multiprocessing.synchronize.Lock`` initialized with a + default context. + + :class:`Lock` supports the :term:`context manager` protocol and thus may be + used in :keyword:`with` statements. + + .. method:: acquire(block=True, timeout=None) + + Acquire a lock, blocking or non-blocking. + + With the *block* argument set to ``True`` (the default), the method call + will block until the lock is in an unlocked state, then set it to locked + and return ``True``. Note that the name of this first argument differs + from that in :meth:`threading.Lock.acquire`. + + With the *block* argument set to ``False``, the method call does not + block. If the lock is currently in a locked state, return ``False``; + otherwise set the lock to a locked state and return ``True``. + + When invoked with a positive, floating-point value for *timeout*, block + for at most the number of seconds specified by *timeout* as long as + the lock can not be acquired. Invocations with a negative value for + *timeout* are equivalent to a *timeout* of zero. Invocations with a + *timeout* value of ``None`` (the default) set the timeout period to + infinite. The *timeout* argument has no practical implications if the + *block* argument is set to ``False`` and is thus ignored. Returns + ``True`` if the lock has been acquired or ``False`` if the timeout period + has elapsed. Note that the *timeout* argument does not exist in this + method's analog, :meth:`threading.Lock.acquire`. + + .. method:: release() + + Release a lock. This can be called from any process or thread, not only + the process or thread which originally acquired the lock. + + Behavior is the same as in :meth:`threading.Lock.release` except that + when invoked on an unlocked lock, a :exc:`ValueError` is raised. + .. class:: RLock() - A recursive lock object: a clone of :class:`threading.RLock`. + A recursive lock object: a close analog of :class:`threading.RLock`. A + recursive lock must be released by the process or thread that acquired it. + Once a process or thread has acquired a recursive lock, the same process + or thread may acquire it again without blocking; that process or thread + must release it once for each time it has been acquired. + + Note that :class:`RLock` is actually a factory function which returns an + instance of ``multiprocessing.synchronize.RLock`` initialized with a + default context. + + :class:`RLock` supports the :term:`context manager` protocol and thus may be + used in :keyword:`with` statements. + + + .. method:: acquire(block=True, timeout=None) + + Acquire a lock, blocking or non-blocking. + + When invoked with the *block* argument set to ``True``, block until the + lock is in an unlocked state (not owned by any process or thread) unless + the lock is already owned by the current process or thread. The current + process or thread then takes ownership of the lock (if it does not + already have ownership) and the recursion level inside the lock increments + by one, resulting in a return value of ``True``. Note that there are + several differences in this first argument's behavior compared to the + implementation of :meth:`threading.RLock.acquire`, starting with the name + of the argument itself. + + When invoked with the *block* argument set to ``False``, do not block. + If the lock has already been acquired (and thus is owned) by another + process or thread, the current process or thread does not take ownership + and the recursion level within the lock is not changed, resulting in + a return value of ``False``. If the lock is in an unlocked state, the + current process or thread takes ownership and the recursion level is + incremented, resulting in a return value of ``True``. + + Use and behaviors of the *timeout* argument are the same as in + :meth:`Lock.acquire`. Note that the *timeout* argument does + not exist in this method's analog, :meth:`threading.RLock.acquire`. + + + .. method:: release() + + Release a lock, decrementing the recursion level. If after the + decrement the recursion level is zero, reset the lock to unlocked (not + owned by any process or thread) and if any other processes or threads + are blocked waiting for the lock to become unlocked, allow exactly one + of them to proceed. If after the decrement the recursion level is still + nonzero, the lock remains locked and owned by the calling process or + thread. + + Only call this method when the calling process or thread owns the lock. + An :exc:`AssertionError` is raised if this method is called by a process + or thread other than the owner or if the lock is in an unlocked (unowned) + state. Note that the type of exception raised in this situation + differs from the implemented behavior in :meth:`threading.RLock.release`. + .. class:: Semaphore([value]) - A semaphore object: a clone of :class:`threading.Semaphore`. + A semaphore object: a close analog of :class:`threading.Semaphore`. + + A solitary difference from its close analog exists: its ``acquire`` method's + first argument is named *block* and it supports an optional second argument + *timeout*, as is consistent with :meth:`Lock.acquire`. .. note:: @@ -957,7 +1070,7 @@ object -- see :ref:`multiprocessing-managers`. .. note:: - If the SIGINT signal generated by Ctrl-C arrives while the main thread is + If the SIGINT signal generated by :kbd:`Ctrl-C` arrives while the main thread is blocked by a call to :meth:`BoundedSemaphore.acquire`, :meth:`Lock.acquire`, :meth:`RLock.acquire`, :meth:`Semaphore.acquire`, :meth:`Condition.acquire` or :meth:`Condition.wait` then the call will be immediately interrupted and @@ -1592,7 +1705,7 @@ itself. This means, for example, that one shared object can contain a second: raised by :meth:`_callmethod`. Note in particular that an exception will be raised if *methodname* has - not been *exposed* + not been *exposed*. An example of the usage of :meth:`_callmethod`: diff --git a/Doc/library/os.rst b/Doc/library/os.rst index 1ab039a..77f02ab 100644 --- a/Doc/library/os.rst +++ b/Doc/library/os.rst @@ -1608,9 +1608,9 @@ Files and Directories recurse into the subdirectories whose names remain in *dirnames*; this can be used to prune the search, impose a specific order of visiting, or even to inform :func:`walk` about directories the caller creates or renames before it resumes - :func:`walk` again. Modifying *dirnames* when *topdown* is ``False`` is - ineffective, because in bottom-up mode the directories in *dirnames* are - generated before *dirpath* itself is generated. + :func:`walk` again. Modifying *dirnames* when *topdown* is ``False`` has + no effect on the behavior of the walk, because in bottom-up mode the directories + in *dirnames* are generated before *dirpath* itself is generated. By default, errors from the :func:`listdir` call are ignored. If optional argument *onerror* is specified, it should be a function; it will be called with diff --git a/Doc/library/pickle.rst b/Doc/library/pickle.rst index a42eabc..41be2c4 100644 --- a/Doc/library/pickle.rst +++ b/Doc/library/pickle.rst @@ -27,9 +27,9 @@ This documentation describes both the :mod:`pickle` module and the .. warning:: - The :mod:`pickle` module is not intended to be secure against erroneous or - maliciously constructed data. Never unpickle data received from an untrusted - or unauthenticated source. + The :mod:`pickle` module is not secure against erroneous or maliciously + constructed data. Never unpickle data received from an untrusted or + unauthenticated source. Relationship to other Python modules diff --git a/Doc/library/platform.rst b/Doc/library/platform.rst index cb7144a..28b6f08 100644 --- a/Doc/library/platform.rst +++ b/Doc/library/platform.rst @@ -126,7 +126,7 @@ Cross Platform .. function:: python_version() - Returns the Python version as string ``'major.minor.patchlevel'`` + Returns the Python version as string ``'major.minor.patchlevel'``. Note that unlike the Python ``sys.version``, the returned value will always include the patchlevel (it defaults to 0). diff --git a/Doc/library/profile.rst b/Doc/library/profile.rst index c7007a6..210e99c 100644 --- a/Doc/library/profile.rst +++ b/Doc/library/profile.rst @@ -35,7 +35,7 @@ profiling interface: 2. :mod:`profile`, a pure Python module whose interface is imitated by :mod:`cProfile`, but which adds significant overhead to profiled programs. If you're trying to extend the profiler in some way, the task might be easier - with this module. + with this module. Originally designed and written by Jim Roskind. .. versionchanged:: 2.4 Now also reports the time spent in calls to built-in functions diff --git a/Doc/library/re.rst b/Doc/library/re.rst index b353c4c..c4029c5 100644 --- a/Doc/library/re.rst +++ b/Doc/library/re.rst @@ -514,13 +514,15 @@ form. .. data:: X VERBOSE - This flag allows you to write regular expressions that look nicer. Whitespace - within the pattern is ignored, except when in a character class or preceded by - an unescaped backslash, and, when a line contains a ``'#'`` neither in a - character class or preceded by an unescaped backslash, all characters from the - leftmost such ``'#'`` through the end of the line are ignored. - - That means that the two following regular expression objects that match a + This flag allows you to write regular expressions that look nicer and are + more readable by allowing you to visually separate logical sections of the + pattern and add comments. Whitespace within the pattern is ignored, except + when in a character class or when preceded by an unescaped backslash. + When a line contains a ``#`` that is not in a character class and is not + preceded by an unescaped backslash, all characters from the leftmost such + ``#`` through the end of the line are ignored. + + This means that the two following regular expression objects that match a decimal number are functionally equal:: a = re.compile(r"""\d + # the integral part diff --git a/Doc/library/resource.rst b/Doc/library/resource.rst index 7ca4534..f6d6058 100644 --- a/Doc/library/resource.rst +++ b/Doc/library/resource.rst @@ -223,10 +223,7 @@ These functions are used to retrieve resource usage information: .. function:: getpagesize() Returns the number of bytes in a system page. (This need not be the same as the - hardware page size.) This function is useful for determining the number of bytes - of memory a process is using. The third element of the tuple returned by - :func:`getrusage` describes memory usage in pages; multiplying by page size - produces number of bytes. + hardware page size.) The following :const:`RUSAGE_\*` symbols are passed to the :func:`getrusage` function to specify which processes information should be provided for. diff --git a/Doc/library/shutil.rst b/Doc/library/shutil.rst index f350f5e..2bf9680 100644 --- a/Doc/library/shutil.rst +++ b/Doc/library/shutil.rst @@ -291,7 +291,7 @@ provided. They rely on the :mod:`zipfile` and :mod:`tarfile` modules. .. function:: get_archive_formats() Return a list of supported formats for archiving. - Each element of the returned sequence is a tuple ``(name, description)`` + Each element of the returned sequence is a tuple ``(name, description)``. By default :mod:`shutil` provides these formats: diff --git a/Doc/library/signal.rst b/Doc/library/signal.rst index 29d56fc..fe7983b 100644 --- a/Doc/library/signal.rst +++ b/Doc/library/signal.rst @@ -77,7 +77,7 @@ The variables defined in the :mod:`signal` module are: .. data:: CTRL_C_EVENT - The signal corresponding to the CTRL+C keystroke event. This signal can + The signal corresponding to the :kbd:`Ctrl+C` keystroke event. This signal can only be used with :func:`os.kill`. Availability: Windows. @@ -87,7 +87,7 @@ The variables defined in the :mod:`signal` module are: .. data:: CTRL_BREAK_EVENT - The signal corresponding to the CTRL+BREAK keystroke event. This signal can + The signal corresponding to the :kbd:`Ctrl+Break` keystroke event. This signal can only be used with :func:`os.kill`. Availability: Windows. diff --git a/Doc/library/socket.rst b/Doc/library/socket.rst index 4aafe38..d80ad57 100644 --- a/Doc/library/socket.rst +++ b/Doc/library/socket.rst @@ -262,12 +262,12 @@ The module :mod:`socket` exports the following constants and functions: method. The following example fetches address information for a hypothetical TCP - connection to ``www.python.org`` on port 80 (results may differ on your + connection to ``example.org`` on port 80 (results may differ on your system if IPv6 isn't enabled):: - >>> socket.getaddrinfo("www.python.org", 80, 0, 0, socket.IPPROTO_TCP) - [(2, 1, 6, '', ('82.94.164.162', 80)), - (10, 1, 6, '', ('2001:888:2000:d::a2', 80, 0, 0))] + >>> socket.getaddrinfo("example.org", 80, 0, 0, socket.IPPROTO_TCP) + [(10, 1, 6, '', ('2606:2800:220:1:248:1893:25c8:1946', 80, 0, 0)), + (2, 1, 6, '', ('93.184.216.34', 80))] .. versionadded:: 2.2 diff --git a/Doc/library/socketserver.rst b/Doc/library/socketserver.rst index a9053d1..bb933a6 100644 --- a/Doc/library/socketserver.rst +++ b/Doc/library/socketserver.rst @@ -39,9 +39,10 @@ Creating a server requires several steps. First, you must create a request handler class by subclassing the :class:`BaseRequestHandler` class and overriding its :meth:`handle` method; this method will process incoming requests. Second, you must instantiate one of the server classes, passing it -the server's address and the request handler class. Finally, call the +the server's address and the request handler class. Then call the :meth:`handle_request` or :meth:`serve_forever` method of the server object to -process one or many requests. +process one or many requests. Finally, call :meth:`~BaseServer.server_close` +to close the socket. When inheriting from :class:`ThreadingMixIn` for threaded connection behavior, you should explicitly declare how you want your threads to behave on an abrupt @@ -170,6 +171,13 @@ Server Objects .. versionadded:: 2.6 +.. method:: BaseServer.server_close() + + Clean up the server. May be overridden. + + .. versionadded:: 2.6 + + .. attribute:: BaseServer.address_family The family of protocols to which the server's socket belongs. @@ -540,6 +548,7 @@ An example for the :class:`ThreadingMixIn` class:: client(ip, port, "Hello World 3") server.shutdown() + server.server_close() The output of the example should look something like this:: diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index bc437a4..94bfac1 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -736,8 +736,8 @@ In the table, *s* and *t* are sequences of the same type; *n*, *i* and *j* are i | ``s + t`` | the concatenation of *s* and | \(6) | | | *t* | | +------------------+--------------------------------+----------+ -| ``s * n, n * s`` | *n* shallow copies of *s* | \(2) | -| | concatenated | | +| ``s * n, n * s`` | equivalent to adding *s* to | \(2) | +| | itself *n* times | | +------------------+--------------------------------+----------+ | ``s[i]`` | *i*\ th item of *s*, origin 0 | \(3) | +------------------+--------------------------------+----------+ @@ -789,9 +789,9 @@ Notes: (2) Values of *n* less than ``0`` are treated as ``0`` (which yields an empty - sequence of the same type as *s*). Note also that the copies are shallow; - nested structures are not copied. This often haunts new Python programmers; - consider: + sequence of the same type as *s*). Note that items in the sequence *s* + are not copied; they are referenced multiple times. This often haunts + new Python programmers; consider: >>> lists = [[]] * 3 >>> lists @@ -801,7 +801,7 @@ Notes: [[3], [3], [3]] What has happened is that ``[[]]`` is a one-element list containing an empty - list, so all three elements of ``[[]] * 3`` are (pointers to) this single empty + list, so all three elements of ``[[]] * 3`` are references to this single empty list. Modifying any of the elements of ``lists`` modifies this single list. You can create a list of different lists this way: @@ -812,6 +812,9 @@ Notes: >>> lists [[3], [5], [7]] + Further explanation is available in the FAQ entry + :ref:`faq-multidimensional-list`. + (3) If *i* or *j* is negative, the index is relative to the end of the string: ``len(s) + i`` or ``len(s) + j`` is substituted. But note that ``-0`` is still @@ -1610,8 +1613,11 @@ an arbitrary object): | ``s.append(x)`` | same as ``s[len(s):len(s)] = | \(2) | | | [x]`` | | +------------------------------+--------------------------------+---------------------+ -| ``s.extend(x)`` | same as ``s[len(s):len(s)] = | \(3) | -| | x`` | | +| ``s.extend(x)`` or | for the most part the same as | \(3) | +| ``s += t`` | ``s[len(s):len(s)] = x`` | | ++------------------------------+--------------------------------+---------------------+ +| ``s *= n`` | updates *s* with its contents | \(11) | +| | repeated *n* times | | +------------------------------+--------------------------------+---------------------+ | ``s.count(x)`` | return number of *i*'s for | | | | which ``s[i] == x`` | | @@ -1717,6 +1723,12 @@ Notes: :exc:`ValueError` if it can detect that the list has been mutated during a sort. +(11) + The value *n* is an integer, or an object implementing + :meth:`~object.__index__`. Zero and negative values of *n* clear + the sequence. Items in the sequence are not copied; they are referenced + multiple times, as explained for ``s * n`` under :ref:`typesseq`. + .. _types-set: @@ -2230,6 +2242,9 @@ pairs within braces, for example: ``{'jack': 4098, 'sjoerd': 4127}`` or ``{4098: .. versionadded:: 2.7 + Dictionaries compare equal if and only if they have the same ``(key, + value)`` pairs. + .. _dict-views: diff --git a/Doc/library/subprocess.rst b/Doc/library/subprocess.rst index 114907f..01a791c 100644 --- a/Doc/library/subprocess.rst +++ b/Doc/library/subprocess.rst @@ -852,7 +852,7 @@ Return code handling translates as follows:: if rc is not None and rc >> 8: print "There were some errors" ==> - process = Popen("cmd", 'w', shell=True, stdin=PIPE) + process = Popen("cmd", shell=True, stdin=PIPE) ... process.stdin.close() if process.wait() != 0: diff --git a/Doc/library/thread.rst b/Doc/library/thread.rst index 8a625f8..f1cee24 100644 --- a/Doc/library/thread.rst +++ b/Doc/library/thread.rst @@ -98,7 +98,8 @@ It defines the following constant and functions: Return the thread stack size used when creating new threads. The optional *size* argument specifies the stack size to be used for subsequently created threads, and must be 0 (use platform or configured default) or a positive - integer value of at least 32,768 (32kB). If changing the thread stack size is + integer value of at least 32,768 (32kB). If *size* is not specified, + 0 is used. If changing the thread stack size is unsupported, the :exc:`error` exception is raised. If the specified stack size is invalid, a :exc:`ValueError` is raised and the stack size is unmodified. 32kB is currently the minimum supported stack size value to guarantee sufficient diff --git a/Doc/library/threading.rst b/Doc/library/threading.rst index a24c385..ccb922b 100644 --- a/Doc/library/threading.rst +++ b/Doc/library/threading.rst @@ -194,7 +194,8 @@ This module defines the following functions and objects: Return the thread stack size used when creating new threads. The optional *size* argument specifies the stack size to be used for subsequently created threads, and must be 0 (use platform or configured default) or a positive - integer value of at least 32,768 (32kB). If changing the thread stack size is + integer value of at least 32,768 (32 KiB). If *size* is not specified, + 0 is used. If changing the thread stack size is unsupported, a :exc:`ThreadError` is raised. If the specified stack size is invalid, a :exc:`ValueError` is raised and the stack size is unmodified. 32kB is currently the minimum supported stack size value to guarantee sufficient @@ -710,8 +711,8 @@ 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:`~Event.set` method and reset to false with the :meth:`clear` method. The -:meth:`wait` method blocks until the flag is true. +:meth:`~Event.set` method and reset to false with the :meth:`~Event.clear` +method. The :meth:`~Event.wait` method blocks until the flag is true. .. class:: Event() diff --git a/Doc/library/time.rst b/Doc/library/time.rst index be2dd15..c2ea834 100644 --- a/Doc/library/time.rst +++ b/Doc/library/time.rst @@ -47,8 +47,6 @@ An explanation of some terminology and conventions is in order. years for all year input. When 2-digit years are accepted, they are converted according to the POSIX or X/Open standard: values 69-99 are mapped to 1969-1999, and values 0--68 are mapped to 2000--2068. Values 100--1899 are always illegal. - Note that this is new as of Python 1.5.2(a2); earlier versions, up to Python - 1.5.1 and 1.5.2a1, would add 1900 to year values below 1900. .. index:: single: UTC diff --git a/Doc/library/tkinter.rst b/Doc/library/tkinter.rst index 846f96e..fa60c15 100644 --- a/Doc/library/tkinter.rst +++ b/Doc/library/tkinter.rst @@ -817,3 +817,53 @@ reference to the image. When the last Python reference to the image object is deleted, the image data is deleted as well, and Tk will display an empty box wherever the image was used. + +.. _tkinter-file-handlers: + +File Handlers +------------- + +Tk allows you to register and unregister a callback function which will be +called from the Tk mainloop when I/O is possible on a file descriptor. +Only one handler may be registered per file descriptor. Example code:: + + import Tkinter + widget = Tkinter.Tk() + mask = Tkinter.READABLE | Tkinter.WRITABLE + widget.tk.createfilehandler(file, mask, callback) + ... + widget.tk.deletefilehandler(file) + +This feature is not available on Windows. + +Since you don't know how many bytes are available for reading, you may not +want to use the :class:`~io.BufferedIOBase` or :class:`~io.TextIOBase` +:meth:`~io.BufferedIOBase.read` or :meth:`~io.IOBase.readline` methods, +since these will insist on reading a predefined number of bytes. +For sockets, the :meth:`~socket.socket.recv` or +:meth:`~socket.socket.recvfrom` methods will work fine; for other files, +use raw reads or ``os.read(file.fileno(), maxbytecount)``. + + +.. method:: Widget.tk.createfilehandler(file, mask, func) + + Registers the file handler callback function *func*. The *file* argument + may either be an object with a :meth:`~io.IOBase.fileno` method (such as + a file or socket object), or an integer file descriptor. The *mask* + argument is an ORed combination of any of the three constants below. + The callback is called as follows:: + + callback(file, mask) + + +.. method:: Widget.tk.deletefilehandler(file) + + Unregisters a file handler. + + +.. data:: READABLE + WRITABLE + EXCEPTION + + Constants used in the *mask* arguments. + diff --git a/Doc/library/ttk.rst b/Doc/library/ttk.rst index 6cab3e0..ad4aa92 100644 --- a/Doc/library/ttk.rst +++ b/Doc/library/ttk.rst @@ -544,9 +544,9 @@ ttk.Notebook This will extend the bindings for the toplevel window containing the notebook as follows: - * Control-Tab: selects the tab following the currently selected one. - * Shift-Control-Tab: selects the tab preceding the currently selected one. - * Alt-K: where K is the mnemonic (underlined) character of any tab, will + * :kbd:`Control-Tab`: selects the tab following the currently selected one. + * :kbd:`Shift-Control-Tab`: selects the tab preceding the currently selected one. + * :kbd:`Alt-K`: where *K* is the mnemonic (underlined) character of any tab, will select that tab. Multiple notebooks in a single toplevel may be enabled for traversal, diff --git a/Doc/library/unittest.rst b/Doc/library/unittest.rst index bc3046a..ca91cd7 100644 --- a/Doc/library/unittest.rst +++ b/Doc/library/unittest.rst @@ -83,7 +83,7 @@ need to derive from a specific class. discovery. unittest2 allows you to use these features with earlier versions of Python. - `Simple Smalltalk Testing: With Patterns <http://www.XProgramming.com/testfram.htm>`_ + `Simple Smalltalk Testing: With Patterns <https://web.archive.org/web/20150315073817/http://www.xprogramming.com/testfram.htm>`_ Kent Beck's original paper on testing frameworks using the pattern shared by :mod:`unittest`. @@ -226,8 +226,8 @@ Command-line options .. cmdoption:: -c, --catch - Control-C during the test run waits for the current test to end and then - reports all the results so far. A second control-C raises the normal + :kbd:`Control-C` during the test run waits for the current test to end and then + reports all the results so far. A second :kbd:`Control-C` raises the normal :exc:`KeyboardInterrupt` exception. See `Signal Handling`_ for the functions that provide this functionality. @@ -286,8 +286,8 @@ The :option:`-s`, :option:`-p`, and :option:`-t` options can be passed in as positional arguments in that order. The following two command lines are equivalent:: - python -m unittest discover -s project_directory -p '*_test.py' - python -m unittest discover project_directory '*_test.py' + python -m unittest discover -s project_directory -p "*_test.py" + python -m unittest discover project_directory "*_test.py" As well as being a path it is possible to pass a package name, for example ``myproject.subpackage.test``, as the start directory. The package name you @@ -568,7 +568,7 @@ Skipping tests and expected failures .. versionadded:: 2.7 Unittest supports skipping individual test methods and even whole classes of -tests. In addition, it supports marking a test as a "expected failure," a test +tests. In addition, it supports marking a test as an "expected failure," a test that is broken and will fail, but shouldn't be counted as a failure on a :class:`TestResult`. diff --git a/Doc/library/urllib.rst b/Doc/library/urllib.rst index d0cc548..927696a 100644 --- a/Doc/library/urllib.rst +++ b/Doc/library/urllib.rst @@ -296,7 +296,7 @@ Utility functions .. note:: urllib also exposes certain utility functions like splittype, splithost and others parsing url into various components. But it is recommended to use - :mod:`urlparse` for parsing urls than using these functions directly. + :mod:`urlparse` for parsing urls rather than using these functions directly. Python 3 does not expose these helper functions from :mod:`urllib.parse` module. diff --git a/Doc/library/urlparse.rst b/Doc/library/urlparse.rst index 87e08dd..c119190 100644 --- a/Doc/library/urlparse.rst +++ b/Doc/library/urlparse.rst @@ -93,7 +93,7 @@ The :mod:`urlparse` module defines the following functions: +------------------+-------+--------------------------+----------------------+ | Attribute | Index | Value | Value if not present | +==================+=======+==========================+======================+ - | :attr:`scheme` | 0 | URL scheme specifier | empty string | + | :attr:`scheme` | 0 | URL scheme specifier | *scheme* parameter | +------------------+-------+--------------------------+----------------------+ | :attr:`netloc` | 1 | Network location part | empty string | +------------------+-------+--------------------------+----------------------+ @@ -197,7 +197,7 @@ The :mod:`urlparse` module defines the following functions: +------------------+-------+-------------------------+----------------------+ | Attribute | Index | Value | Value if not present | +==================+=======+=========================+======================+ - | :attr:`scheme` | 0 | URL scheme specifier | empty string | + | :attr:`scheme` | 0 | URL scheme specifier | *scheme* parameter | +------------------+-------+-------------------------+----------------------+ | :attr:`netloc` | 1 | Network location part | empty string | +------------------+-------+-------------------------+----------------------+ diff --git a/Doc/library/wsgiref.rst b/Doc/library/wsgiref.rst index 0b0c7c2..98989c3 100644 --- a/Doc/library/wsgiref.rst +++ b/Doc/library/wsgiref.rst @@ -479,7 +479,7 @@ input, output, and error streams. Similar to :class:`BaseCGIHandler`, but designed for use with HTTP origin servers. If you are writing an HTTP server implementation, you will probably - want to subclass this instead of :class:`BaseCGIHandler` + want to subclass this instead of :class:`BaseCGIHandler`. This class is a subclass of :class:`BaseHandler`. It overrides the :meth:`__init__`, :meth:`get_stdin`, :meth:`get_stderr`, :meth:`add_cgi_vars`, diff --git a/Doc/library/xml.dom.minidom.rst b/Doc/library/xml.dom.minidom.rst index 5cde5e2..4e7cd5a 100644 --- a/Doc/library/xml.dom.minidom.rst +++ b/Doc/library/xml.dom.minidom.rst @@ -18,7 +18,7 @@ Model interface, with an API similar to that in other languages. It is intended to be simpler than the full DOM and also significantly smaller. Users who are not already proficient with the DOM should consider using the -:mod:`xml.etree.ElementTree` module for their XML processing instead +:mod:`xml.etree.ElementTree` module for their XML processing instead. .. warning:: diff --git a/Doc/library/xml.dom.rst b/Doc/library/xml.dom.rst index b496aa1..6dba900 100644 --- a/Doc/library/xml.dom.rst +++ b/Doc/library/xml.dom.rst @@ -321,7 +321,7 @@ All of the components of an XML document are subclasses of :class:`Node`. .. attribute:: Node.prefix The part of the :attr:`tagName` preceding the colon if there is one, else the - empty string. The value is a string, or ``None`` + empty string. The value is a string, or ``None``. .. attribute:: Node.namespaceURI diff --git a/Doc/library/xml.etree.elementtree.rst b/Doc/library/xml.etree.elementtree.rst index 46396dd..212a9e1 100644 --- a/Doc/library/xml.etree.elementtree.rst +++ b/Doc/library/xml.etree.elementtree.rst @@ -600,21 +600,29 @@ Element Objects .. attribute:: text + tail - The *text* attribute can be used to hold additional data associated with - the element. As the name implies this attribute is usually a string but - may be any application-specific object. If the element is created from - an XML file the attribute will contain any text found between the element - tags. + These attributes can be used to hold additional data associated with + the element. Their values are usually strings but may be any + application-specific object. If the element is created from + an XML file, the *text* attribute holds either the text between + the element's start tag and its first child or end tag, or ``None``, and + the *tail* attribute holds either the text between the element's + end tag and the next tag, or ``None``. For the XML data + .. code-block:: xml - .. attribute:: tail + <a><b>1<c>2<d/>3</c></b>4</a> - The *tail* attribute can be used to hold additional data associated with - the element. This attribute is usually a string but may be any - application-specific object. If the element is created from an XML file - the attribute will contain any text found after the element's end tag and - before the next tag. + the *a* element has ``None`` for both *text* and *tail* attributes, + the *b* element has *text* ``"1"`` and *tail* ``"4"``, + the *c* element has *text* ``"2"`` and *tail* ``None``, + and the *d* element has *text* ``None`` and *tail* ``"3"``. + + To collect the inner text of an element, see :meth:`itertext`, for + example ``"".join(element.itertext())``. + + Applications may store arbitrary objects in these attributes. .. attribute:: attrib @@ -821,7 +829,7 @@ ElementTree Objects Creates and returns a tree iterator for the root element. The iterator loops over all elements in this tree, in section order. *tag* is the tag - to look for (default is to return all elements) + to look for (default is to return all elements). .. method:: iterfind(match) diff --git a/Doc/library/zlib.rst b/Doc/library/zlib.rst index 192bd4d..96e723b 100644 --- a/Doc/library/zlib.rst +++ b/Doc/library/zlib.rst @@ -31,7 +31,7 @@ The available exception and functions in this module are: .. function:: adler32(data[, value]) - Computes a Adler-32 checksum of *data*. (An Adler-32 checksum is almost as + Computes an Adler-32 checksum of *data*. (An Adler-32 checksum is almost as reliable as a CRC32 but can be computed much more quickly.) If *value* is present, it is used as the starting value of the checksum; otherwise, a fixed default value is used. This allows computing a running checksum over the @@ -221,7 +221,7 @@ Decompression objects support the following methods, and two attributes: :meth:`decompress` method. Some of the input data may be preserved in internal buffers for later processing. - If the optional parameter *max_length* is supplied then the return value will be + If the optional parameter *max_length* is non-zero then the return value will be no longer than *max_length*. This may mean that not all of the compressed input can be processed; and unconsumed data will be stored in the attribute :attr:`unconsumed_tail`. This string must be passed to a subsequent call to |