diff -r afe119a3619f Doc/about.rst --- a/Doc/about.rst +++ b/Doc/about.rst @@ -38,4 +38,4 @@ source distribution for a partial list of contributors. It is only with the input and contributions of the Python community -that Python has such wonderful documentation -- Thank You! +that Python has such wonderful documentation---Thank You! diff -r afe119a3619f Doc/c-api/arg.rst --- a/Doc/c-api/arg.rst +++ b/Doc/c-api/arg.rst @@ -332,10 +332,10 @@ *items*. Format units for sequences may be nested. It is possible to pass "long" integers (integers whose value exceeds the -platform's :const:`LONG_MAX`) however no proper range checking is done --- the +platform's :const:`LONG_MAX`) however no proper range checking is done---the most significant bits are silently truncated when the receiving field is too small to receive the value (actually, the semantics are inherited from downcasts -in C --- your mileage may vary). +in C---your mileage may vary). A few other characters have a meaning in a format string. These may not occur inside nested parentheses. They are: @@ -343,7 +343,7 @@ ``|`` Indicates that the remaining arguments in the Python argument list are optional. The C variables corresponding to optional arguments should be initialized to - their default value --- when an optional argument is not specified, + their default value---when an optional argument is not specified, :c:func:`PyArg_ParseTuple` does not touch the contents of the corresponding C variable(s). diff -r afe119a3619f Doc/c-api/bytes.rst --- a/Doc/c-api/bytes.rst +++ b/Doc/c-api/bytes.rst @@ -59,7 +59,7 @@ .. % XXX: This should be exactly the same as the table in PyErr_Format. .. % One should just refer to the other. .. % XXX: The descriptions for %zd and %zu are wrong, but the truth is complicated - .. % because not all compilers support the %z width modifier -- we fake it + .. % because not all compilers support the %z width modifier---we fake it .. % when necessary via interpolating PY_FORMAT_SIZE_T. .. tabularcolumns:: |l|l|L| diff -r afe119a3619f Doc/c-api/exceptions.rst --- a/Doc/c-api/exceptions.rst +++ b/Doc/c-api/exceptions.rst @@ -398,7 +398,7 @@ single: SIGINT single: KeyboardInterrupt (built-in exception) - This function simulates the effect of a :const:`SIGINT` signal arriving --- the + This function simulates the effect of a :const:`SIGINT` signal arriving---the next time :c:func:`PyErr_CheckSignals` is called, :exc:`KeyboardInterrupt` will be raised. It may be called without holding the interpreter lock. diff -r afe119a3619f Doc/c-api/import.rst --- a/Doc/c-api/import.rst +++ b/Doc/c-api/import.rst @@ -240,7 +240,7 @@ Load a frozen module named *name*. Return ``1`` for success, ``0`` if the module is not found, and ``-1`` with an exception set if the initialization failed. To access the imported module on a successful load, use - :c:func:`PyImport_ImportModule`. (Note the misnomer --- this function would + :c:func:`PyImport_ImportModule`. (Note the misnomer---this function would reload the module if it was already imported.) .. versionadded:: 3.3 diff -r afe119a3619f Doc/c-api/init.rst --- a/Doc/c-api/init.rst +++ b/Doc/c-api/init.rst @@ -627,7 +627,7 @@ The return value is an opaque "handle" to the thread state when :c:func:`PyGILState_Ensure` was called, and must be passed to :c:func:`PyGILState_Release` to ensure Python is left in the same state. Even - though recursive calls are allowed, these handles *cannot* be shared - each + though recursive calls are allowed, these handles *cannot* be shared---each unique call to :c:func:`PyGILState_Ensure` must save the handle for its call to :c:func:`PyGILState_Release`. @@ -786,7 +786,7 @@ Reset the current thread state to *NULL* and release the global interpreter lock. The lock must have been created earlier and must be held by the current thread. The *tstate* argument, which must not be *NULL*, is only used to check - that it represents the current thread state --- if it isn't, a fatal error is + that it represents the current thread state---if it isn't, a fatal error is reported. :c:func:`PyEval_SaveThread` is a higher-level function which is always @@ -891,7 +891,7 @@ ---------------- Because sub-interpreters (and the main interpreter) are part of the same -process, the insulation between them isn't perfect --- for example, using +process, the insulation between them isn't perfect---for example, using low-level file operations like :func:`os.close` they can (accidentally or maliciously) affect each other's open files. Because of the way extensions are shared between (sub-)interpreters, some extensions may not diff -r afe119a3619f Doc/c-api/intro.rst --- a/Doc/c-api/intro.rst +++ b/Doc/c-api/intro.rst @@ -276,10 +276,10 @@ always return a new reference (the caller becomes the owner of the reference). It is important to realize that whether you own a reference returned by a -function depends on which function you call only --- *the plumage* (the type of +function depends on which function you call only---\ *the plumage* (the type of the object passed as an argument to the function) *doesn't enter into it!* Thus, if you extract an item from a list using :c:func:`PyList_GetItem`, you -don't own the reference --- but if you obtain the same item from the same list +don't own the reference---but if you obtain the same item from the same list using :c:func:`PySequence_GetItem` (which happens to take exactly the same arguments), you do own a reference to the returned object. @@ -427,7 +427,7 @@ task should check whether the called function raised an exception, and if so, pass the exception state on to its caller. It should discard any object references that it owns, and return an error indicator, but it should *not* set -another exception --- that would overwrite the exception that was just raised, +another exception---that would overwrite the exception that was just raised, and lose important information about the exact cause of the error. .. index:: single: sum_sequence() diff -r afe119a3619f Doc/c-api/object.rst --- a/Doc/c-api/object.rst +++ b/Doc/c-api/object.rst @@ -189,7 +189,7 @@ be done against every entry in *cls*. The result will be ``1`` when at least one of the checks returns ``1``, otherwise it will be ``0``. If *inst* is not a class instance and *cls* is neither a type object, nor a class object, nor a - tuple, *inst* must have a :attr:`__class__` attribute --- the class relationship + tuple, *inst* must have a :attr:`__class__` attribute---the class relationship of the value of that attribute with *cls* will be used to determine the result of this function. @@ -202,7 +202,7 @@ class relationship of the two objects. When testing if *B* is a subclass of *A*, if *A* is *B*, :c:func:`PyObject_IsSubclass` returns true. If *A* and *B* are different objects, *B*'s :attr:`__bases__` attribute is searched in a -depth-first fashion for *A* --- the presence of the :attr:`__bases__` attribute +depth-first fashion for *A*\ ---the presence of the :attr:`__bases__` attribute is considered sufficient for this determination. diff -r afe119a3619f Doc/c-api/sys.rst --- a/Doc/c-api/sys.rst +++ b/Doc/c-api/sys.rst @@ -91,7 +91,7 @@ exceptions are raised, even if truncation occurs (see below). *format* should limit the total size of the formatted output string to - 1000 bytes or less -- after 1000 bytes, the output string is truncated. + 1000 bytes or less---after 1000 bytes, the output string is truncated. In particular, this means that no unrestricted "%s" formats should occur; these should be limited using "%.s" where is a decimal number calculated so that plus the maximum size of other formatted text does not diff -r afe119a3619f Doc/c-api/typeobj.rst --- a/Doc/c-api/typeobj.rst +++ b/Doc/c-api/typeobj.rst @@ -315,7 +315,7 @@ block inheritance of the hash method from a parent type. This is interpreted as the equivalent of ``__hash__ = None`` at the Python level, causing ``isinstance(o, collections.Hashable)`` to correctly return ``False``. Note - that the converse is also true - setting ``__hash__ = None`` on a class at + that the converse is also true---setting ``__hash__ = None`` on a class at the Python level will result in the ``tp_hash`` slot being set to :c:func:`PyObject_HashNotImplemented`. diff -r afe119a3619f Doc/c-api/unicode.rst --- a/Doc/c-api/unicode.rst +++ b/Doc/c-api/unicode.rst @@ -231,10 +231,10 @@ a Unicode object (not checked). .. versionchanged:: 3.3 - This macro is now inefficient -- because in many cases the - :c:type:`Py_UNICODE` representation does not exist and needs to be created - -- and can fail (return *NULL* with an exception set). Try to port the - code to use the new :c:func:`PyUnicode_nBYTE_DATA` macros or use + This macro is now inefficient---because in many cases the + :c:type:`Py_UNICODE` representation does not exist and needs to be + created---and can fail (return *NULL* with an exception set). Try to port + the code to use the new :c:func:`PyUnicode_nBYTE_DATA` macros or use :c:func:`PyUnicode_WRITE` or :c:func:`PyUnicode_READ`. .. deprecated-removed:: 3.3 4.0 @@ -434,7 +434,7 @@ .. % This should be exactly the same as the table in PyErr_Format. .. % The descriptions for %zd and %zu are wrong, but the truth is complicated - .. % because not all compilers support the %z width modifier -- we fake it + .. % because not all compilers support the %z width modifier---we fake it .. % when necessary via interpolating PY_FORMAT_SIZE_T. .. % Similar comments apply to the %ll width modifier and .. % PY_FORMAT_LONG_LONG. diff -r afe119a3619f Doc/c-api/veryhigh.rst --- a/Doc/c-api/veryhigh.rst +++ b/Doc/c-api/veryhigh.rst @@ -304,7 +304,7 @@ This is the main, unvarnished function of Python interpretation. It is literally 2000 lines long. The code object associated with the execution frame *f* is executed, interpreting bytecode and executing calls as needed. - The additional *throwflag* parameter can mostly be ignored - if true, then + The additional *throwflag* parameter can mostly be ignored---if true, then it causes an exception to immediately be thrown; this is used for the :meth:`throw` methods of generator objects. diff -r afe119a3619f Doc/distutils/apiref.rst --- a/Doc/distutils/apiref.rst +++ b/Doc/distutils/apiref.rst @@ -5,7 +5,7 @@ ************* -:mod:`distutils.core` --- Core Distutils functionality +:mod:`distutils.core`\ ---Core Distutils functionality ====================================================== .. module:: distutils.core @@ -84,7 +84,7 @@ | | class to use | :class:`distutils.core.Distribution` | +--------------------+--------------------------------+-------------------------------------------------------------+ | *script_name* | The name of the setup.py | a string | - | | script - defaults to | | + | | script---defaults to | | | | ``sys.argv[0]`` | | +--------------------+--------------------------------+-------------------------------------------------------------+ | *script_args* | Arguments to supply to the | a list of strings | @@ -176,7 +176,7 @@ +========================+================================+===========================+ | *name* | the full name of the | a string | | | extension, including any | | - | | packages --- ie. *not* a | | + | | packages---ie. *not* a | | | | filename or pathname, but | | | | Python dotted name | | +------------------------+--------------------------------+---------------------------+ @@ -292,7 +292,7 @@ implement a single distutils command. -:mod:`distutils.ccompiler` --- CCompiler base class +:mod:`distutils.ccompiler`\ ---CCompiler base class =================================================== .. module:: distutils.ccompiler @@ -302,7 +302,7 @@ This module provides the abstract base class for the :class:`CCompiler` classes. A :class:`CCompiler` instance can be used for all the compile and link steps needed to build a single project. Methods are provided to set -options for the compiler --- macro definitions, include directories, link path, +options for the compiler---macro definitions, include directories, link path, libraries and the like. This module provides the following functions. @@ -371,8 +371,8 @@ The basic idea behind a compiler abstraction class is that each instance can be used for all the compile/link steps in building a single project. Thus, - attributes common to all of those compile and link steps --- include - directories, macros to define, libraries to link against, etc. --- are + attributes common to all of those compile and link steps---include + directories, macros to define, libraries to link against, etc.---are attributes of the compiler instance. To allow for variability in how individual files are treated, most of those attributes may be varied on a per-compilation or per-link basis. @@ -381,7 +381,7 @@ Flags are *verbose* (show verbose output), *dry_run* (don't actually execute the steps) and *force* (rebuild everything, regardless of dependencies). All of these flags default to ``0`` (off). Note that you probably don't want to - instantiate :class:`CCompiler` or one of its subclasses directly - use the + instantiate :class:`CCompiler` or one of its subclasses directly---use the :func:`distutils.CCompiler.new_compiler` factory function instead. The following methods allow you to manually alter compiler options for the @@ -779,7 +779,7 @@ .. % function. -:mod:`distutils.unixccompiler` --- Unix C Compiler +:mod:`distutils.unixccompiler`\ ---Unix C Compiler ================================================== .. module:: distutils.unixccompiler @@ -808,7 +808,7 @@ * link shared library handled by :program:`cc` :option:`-shared` -:mod:`distutils.msvccompiler` --- Microsoft Compiler +:mod:`distutils.msvccompiler`\ ---Microsoft Compiler ==================================================== .. module:: distutils.msvccompiler @@ -831,7 +831,7 @@ selection by :class:`MSVCCompiler`. -:mod:`distutils.bcppcompiler` --- Borland Compiler +:mod:`distutils.bcppcompiler`\ ---Borland Compiler ================================================== .. module:: distutils.bcppcompiler @@ -841,7 +841,7 @@ :class:`CCompiler` class for the Borland C++ compiler. -:mod:`distutils.cygwincompiler` --- Cygwin Compiler +:mod:`distutils.cygwincompiler`\ ---Cygwin Compiler =================================================== .. module:: distutils.cygwinccompiler @@ -853,7 +853,7 @@ port of GCC (same as cygwin in no-cygwin mode). -:mod:`distutils.emxccompiler` --- OS/2 EMX Compiler +:mod:`distutils.emxccompiler`\ ---OS/2 EMX Compiler =================================================== .. module:: distutils.emxccompiler @@ -864,7 +864,7 @@ :class:`UnixCCompiler` that handles the EMX port of the GNU C compiler to OS/2. -:mod:`distutils.archive_util` --- Archiving utilities +:mod:`distutils.archive_util`\ ---Archiving utilities ====================================================== .. module:: distutils.archive_util @@ -907,7 +907,7 @@ :exc:`DistutilsExecError`. Returns the name of the output zip file. -:mod:`distutils.dep_util` --- Dependency checking +:mod:`distutils.dep_util`\ ---Dependency checking ================================================= .. module:: distutils.dep_util @@ -950,7 +950,7 @@ the commands). -:mod:`distutils.dir_util` --- Directory tree operations +:mod:`distutils.dir_util`\ ---Directory tree operations ======================================================= .. module:: distutils.dir_util @@ -1015,7 +1015,7 @@ true). -:mod:`distutils.file_util` --- Single file operations +:mod:`distutils.file_util`\ ---Single file operations ===================================================== .. module:: distutils.file_util @@ -1073,7 +1073,7 @@ without line terminators) to it. -:mod:`distutils.util` --- Miscellaneous other utility functions +:mod:`distutils.util`\ ---Miscellaneous other utility functions =============================================================== .. module:: distutils.util @@ -1151,8 +1151,8 @@ users can use in config files, command-line options, etc. Currently this includes: - * :envvar:`HOME` - user's home directory (Unix only) - * :envvar:`PLAT` - description of the current platform, including hardware and + * :envvar:`HOME`\ ---user's home directory (Unix only) + * :envvar:`PLAT`\ ---description of the current platform, including hardware and OS (see :func:`get_platform`) @@ -1217,9 +1217,9 @@ *py_files* is a list of files to compile; any files that don't end in :file:`.py` are silently skipped. *optimize* must be one of the following: - * ``0`` - don't optimize (generate :file:`.pyc`) - * ``1`` - normal optimization (like ``python -O``) - * ``2`` - extra optimization (like ``python -OO``) + * ``0``\ ---don't optimize (generate :file:`.pyc`) + * ``1``\ ---normal optimization (like ``python -O``) + * ``2``\ ---extra optimization (like ``python -OO``) If *force* is true, all files are recompiled regardless of timestamps. @@ -1257,7 +1257,7 @@ .. % \subsection{Distutils objects} -:mod:`distutils.dist` --- The Distribution class +:mod:`distutils.dist`\ ---The Distribution class ================================================ .. module:: distutils.dist @@ -1269,7 +1269,7 @@ module distribution being built/installed/distributed. -:mod:`distutils.extension` --- The Extension class +:mod:`distutils.extension`\ ---The Extension class ================================================== .. module:: distutils.extension @@ -1284,7 +1284,7 @@ .. % The following haven't been moved into a more appropriate section yet. -:mod:`distutils.debug` --- Distutils debug mode +:mod:`distutils.debug`\ ---Distutils debug mode =============================================== .. module:: distutils.debug @@ -1294,7 +1294,7 @@ This module provides the DEBUG flag. -:mod:`distutils.errors` --- Distutils exceptions +:mod:`distutils.errors`\ ---Distutils exceptions ================================================ .. module:: distutils.errors @@ -1309,7 +1309,7 @@ symbols whose names start with ``Distutils`` and end with ``Error``. -:mod:`distutils.fancy_getopt` --- Wrapper around the standard getopt module +:mod:`distutils.fancy_getopt`\ ---Wrapper around the standard getopt module =========================================================================== .. module:: distutils.fancy_getopt @@ -1326,7 +1326,7 @@ * options set attributes of a passed-in object -* boolean options can have "negative aliases" --- eg. if :option:`--quiet` is +* boolean options can have "negative aliases"\ ---eg. if :option:`--quiet` is the "negative alias" of :option:`--verbose`, then :option:`--quiet` on the command line sets *verbose* to false. @@ -1388,7 +1388,7 @@ If supplied, prints the supplied *header* at the top of the help. -:mod:`distutils.filelist` --- The FileList class +:mod:`distutils.filelist`\ ---The FileList class ================================================ .. module:: distutils.filelist @@ -1400,14 +1400,14 @@ filesystem and building lists of files. -:mod:`distutils.log` --- Simple PEP 282-style logging +:mod:`distutils.log`\ ---Simple PEP 282-style logging ===================================================== .. module:: distutils.log :synopsis: A simple logging mechanism, 282-style -:mod:`distutils.spawn` --- Spawn a sub-process +:mod:`distutils.spawn`\ ---Spawn a sub-process ============================================== .. module:: distutils.spawn @@ -1420,7 +1420,7 @@ name. -:mod:`distutils.sysconfig` --- System configuration information +:mod:`distutils.sysconfig`\ ---System configuration information =============================================================== .. module:: distutils.sysconfig @@ -1532,7 +1532,7 @@ Python. -:mod:`distutils.text_file` --- The TextFile class +:mod:`distutils.text_file`\ ---The TextFile class ================================================= .. module:: distutils.text_file @@ -1671,7 +1671,7 @@ to :meth:`readline`, the lines will be returned most in most recent first order. -:mod:`distutils.version` --- Version number classes +:mod:`distutils.version`\ ---Version number classes =================================================== .. module:: distutils.version @@ -1686,7 +1686,7 @@ .. % separate module, with the command name as the name of the module. -:mod:`distutils.cmd` --- Abstract base class for Distutils commands +:mod:`distutils.cmd`\ ---Abstract base class for Distutils commands =================================================================== .. module:: distutils.cmd @@ -1707,7 +1707,7 @@ class. The distinction between the two is necessary because option values might come from the outside world (command line, config file, ...), and any options dependent on other options must be computed after these outside - influences have been processed --- hence :meth:`finalize_options`. The body + influences have been processed---hence :meth:`finalize_options`. The body of the subroutine, where it does all its work based on the values of its options, is the :meth:`run` method, which must also be implemented by every command class. @@ -1779,7 +1779,7 @@ defined. The canonical example is the :command:`install` command. -:mod:`distutils.command` --- Individual Distutils commands +:mod:`distutils.command`\ ---Individual Distutils commands ========================================================== .. module:: distutils.command @@ -1790,7 +1790,7 @@ .. % todo -:mod:`distutils.command.bdist` --- Build a binary installer +:mod:`distutils.command.bdist`\ ---Build a binary installer =========================================================== .. module:: distutils.command.bdist @@ -1800,7 +1800,7 @@ .. % todo -:mod:`distutils.command.bdist_packager` --- Abstract base class for packagers +:mod:`distutils.command.bdist_packager`\ ---Abstract base class for packagers ============================================================================= .. module:: distutils.command.bdist_packager @@ -1810,17 +1810,17 @@ .. % todo -:mod:`distutils.command.bdist_dumb` --- Build a "dumb" installer +:mod:`distutils.command.bdist_dumb`\ ---Build a "dumb" installer ================================================================ .. module:: distutils.command.bdist_dumb - :synopsis: Build a "dumb" installer - a simple archive of files + :synopsis: Build a "dumb" installer---a simple archive of files .. % todo -:mod:`distutils.command.bdist_msi` --- Build a Microsoft Installer binary package +:mod:`distutils.command.bdist_msi`\ ---Build a Microsoft Installer binary package ================================================================================= .. module:: distutils.command.bdist_msi @@ -1838,7 +1838,7 @@ installations, and allows installation through group policies. -:mod:`distutils.command.bdist_rpm` --- Build a binary distribution as a Redhat RPM and SRPM +:mod:`distutils.command.bdist_rpm`\ ---Build a binary distribution as a Redhat RPM and SRPM =========================================================================================== .. module:: distutils.command.bdist_rpm @@ -1848,7 +1848,7 @@ .. % todo -:mod:`distutils.command.bdist_wininst` --- Build a Windows installer +:mod:`distutils.command.bdist_wininst`\ ---Build a Windows installer ==================================================================== .. module:: distutils.command.bdist_wininst @@ -1858,7 +1858,7 @@ .. % todo -:mod:`distutils.command.sdist` --- Build a source distribution +:mod:`distutils.command.sdist`\ ---Build a source distribution ============================================================== .. module:: distutils.command.sdist @@ -1868,7 +1868,7 @@ .. % todo -:mod:`distutils.command.build` --- Build all files of a package +:mod:`distutils.command.build`\ ---Build all files of a package =============================================================== .. module:: distutils.command.build @@ -1878,7 +1878,7 @@ .. % todo -:mod:`distutils.command.build_clib` --- Build any C libraries in a package +:mod:`distutils.command.build_clib`\ ---Build any C libraries in a package ========================================================================== .. module:: distutils.command.build_clib @@ -1888,7 +1888,7 @@ .. % todo -:mod:`distutils.command.build_ext` --- Build any extensions in a package +:mod:`distutils.command.build_ext`\ ---Build any extensions in a package ======================================================================== .. module:: distutils.command.build_ext @@ -1898,7 +1898,7 @@ .. % todo -:mod:`distutils.command.build_py` --- Build the .py/.pyc files of a package +:mod:`distutils.command.build_py`\ ---Build the .py/.pyc files of a package =========================================================================== .. module:: distutils.command.build_py @@ -1926,7 +1926,7 @@ to the invocation of setup(). -:mod:`distutils.command.build_scripts` --- Build the scripts of a package +:mod:`distutils.command.build_scripts`\ ---Build the scripts of a package ========================================================================= .. module:: distutils.command.build_scripts @@ -1936,7 +1936,7 @@ .. % todo -:mod:`distutils.command.clean` --- Clean a package build area +:mod:`distutils.command.clean`\ ---Clean a package build area ============================================================= .. module:: distutils.command.clean @@ -1946,7 +1946,7 @@ .. % todo -:mod:`distutils.command.config` --- Perform package configuration +:mod:`distutils.command.config`\ ---Perform package configuration ================================================================= .. module:: distutils.command.config @@ -1956,7 +1956,7 @@ .. % todo -:mod:`distutils.command.install` --- Install a package +:mod:`distutils.command.install`\ ---Install a package ====================================================== .. module:: distutils.command.install @@ -1966,7 +1966,7 @@ .. % todo -:mod:`distutils.command.install_data` --- Install data files from a package +:mod:`distutils.command.install_data`\ ---Install data files from a package =========================================================================== .. module:: distutils.command.install_data @@ -1976,7 +1976,7 @@ .. % todo -:mod:`distutils.command.install_headers` --- Install C/C++ header files from a package +:mod:`distutils.command.install_headers`\ ---Install C/C++ header files from a package ====================================================================================== .. module:: distutils.command.install_headers @@ -1986,7 +1986,7 @@ .. % todo -:mod:`distutils.command.install_lib` --- Install library files from a package +:mod:`distutils.command.install_lib`\ ---Install library files from a package ============================================================================= .. module:: distutils.command.install_lib @@ -1996,7 +1996,7 @@ .. % todo -:mod:`distutils.command.install_scripts` --- Install script files from a package +:mod:`distutils.command.install_scripts`\ ---Install script files from a package ================================================================================ .. module:: distutils.command.install_scripts @@ -2006,7 +2006,7 @@ .. % todo -:mod:`distutils.command.register` --- Register a module with the Python Package Index +:mod:`distutils.command.register`\ ---Register a module with the Python Package Index ===================================================================================== .. module:: distutils.command.register @@ -2019,7 +2019,7 @@ .. % todo -:mod:`distutils.command.check` --- Check the meta-data of a package +:mod:`distutils.command.check`\ ---Check the meta-data of a package =================================================================== .. module:: distutils.command.check diff -r afe119a3619f Doc/distutils/builtdist.rst --- a/Doc/distutils/builtdist.rst +++ b/Doc/distutils/builtdist.rst @@ -327,7 +327,7 @@ version number. This can be changed to another text by using the :option:`--title` option. -The installer file will be written to the "distribution directory" --- normally +The installer file will be written to the "distribution directory"\ ---normally :file:`dist/`, but customizable with the :option:`--dist-dir` option. .. _cross-compile-windows: @@ -354,7 +354,7 @@ would create a 64bit installation executable on your 32bit version of Windows. To cross-compile, you must download the Python source code and cross-compile -Python itself for the platform you are targetting - it is not possible from a +Python itself for the platform you are targetting---it is not possible from a binary installation of Python (as the .lib etc file for other platforms are not included.) In practice, this means the user of a 32 bit operating system will need to use Visual Studio 2008 to open the diff -r afe119a3619f Doc/distutils/commandref.rst --- a/Doc/distutils/commandref.rst +++ b/Doc/distutils/commandref.rst @@ -73,10 +73,10 @@ | ...` | the listed patterns | +-------------------------------------------+-----------------------------------------------+ | :command:`global-include pat1 pat2 ...` | include all files anywhere in the source tree | -| | matching --- & any of the listed patterns | +| | matching---& any of the listed patterns | +-------------------------------------------+-----------------------------------------------+ | :command:`global-exclude pat1 pat2 ...` | exclude all files anywhere in the source tree | -| | matching --- & any of the listed patterns | +| | matching---& any of the listed patterns | +-------------------------------------------+-----------------------------------------------+ | :command:`prune dir` | exclude all files under *dir* | +-------------------------------------------+-----------------------------------------------+ diff -r afe119a3619f Doc/extending/embedding.rst --- a/Doc/extending/embedding.rst +++ b/Doc/extending/embedding.rst @@ -20,7 +20,7 @@ Embedding Python is similar to extending it, but not quite. The difference is that when you extend Python, the main program of the application is still the Python interpreter, while if you embed Python, the main program may have nothing -to do with Python --- instead, some parts of the application occasionally call +to do with Python---instead, some parts of the application occasionally call the Python interpreter to run some Python code. So if you are embedding Python, you are providing your own main program. One of diff -r afe119a3619f Doc/extending/extending.rst --- a/Doc/extending/extending.rst +++ b/Doc/extending/extending.rst @@ -94,7 +94,7 @@ The *args* argument will be a pointer to a Python tuple object containing the arguments. Each item of the tuple corresponds to an argument in the call's -argument list. The arguments are Python objects --- in order to do anything +argument list. The arguments are Python objects---in order to do anything with them in our C function we have to convert them to C values. The function :c:func:`PyArg_ParseTuple` in the Python API checks the argument types and converts them to C values. It uses a template string to determine the required @@ -147,10 +147,10 @@ When a function *f* that calls another function *g* detects that the latter fails, *f* should itself return an error value (usually *NULL* or ``-1``). It -should *not* call one of the :c:func:`PyErr_\*` functions --- one has already +should *not* call one of the :c:func:`PyErr_\*` functions---one has already been called by *g*. *f*'s caller is then supposed to also return an error -indication to *its* caller, again *without* calling :c:func:`PyErr_\*`, and so on ---- the most detailed cause of the error was already reported by the function +indication to *its* caller, again *without* calling :c:func:`PyErr_\*`, and so +on---the most detailed cause of the error was already reported by the function that first detected it. Once the error reaches the Python interpreter's main loop, this aborts the currently executing Python code and tries to find an exception handler specified by the Python programmer. @@ -167,7 +167,7 @@ error on to the interpreter but wants to handle it completely by itself (possibly by trying something else, or pretending nothing went wrong). -Every failing :c:func:`malloc` call must be turned into an exception --- the +Every failing :c:func:`malloc` call must be turned into an exception---the direct caller of :c:func:`malloc` (or :c:func:`realloc`) must call :c:func:`PyErr_NoMemory` and return a failure indicator itself. All the object-creating functions (for example, :c:func:`PyLong_FromLong`) already do @@ -184,7 +184,7 @@ The choice of which exception to raise is entirely yours. There are predeclared C objects corresponding to all built-in Python exceptions, such as :c:data:`PyExc_ZeroDivisionError`, which you can use directly. Of course, you -should choose exceptions wisely --- don't use :c:data:`PyExc_TypeError` to mean +should choose exceptions wisely---don't use :c:data:`PyExc_TypeError` to mean that a file couldn't be opened (that should probably be :c:data:`PyExc_IOError`). If something's wrong with the argument list, the :c:func:`PyArg_ParseTuple` function usually raises :c:data:`PyExc_TypeError`. If you have an argument whose @@ -445,7 +445,7 @@ Fortunately, the Python interpreter is easily called recursively, and there is a standard interface to call a Python function. (I won't dwell on how to call the -Python parser with a particular string as input --- if you're interested, have a +Python parser with a particular string as input---if you're interested, have a look at the implementation of the :option:`-c` command line option in :file:`Modules/main.c` from the Python source code.) @@ -453,7 +453,7 @@ you the Python function object. You should provide a function (or some other interface) to do this. When this function is called, save a pointer to the Python function object (be careful to :c:func:`Py_INCREF` it!) in a global -variable --- or wherever you see fit. For example, the following function might +variable---or wherever you see fit. For example, the following function might be part of a module definition:: static PyObject *my_callback = NULL; @@ -810,7 +810,7 @@ leak`. On the other hand, if a program calls :c:func:`free` for a block and then continues to use the block, it creates a conflict with re-use of the block through another :c:func:`malloc` call. This is called :dfn:`using freed memory`. -It has the same bad consequences as referencing uninitialized data --- core +It has the same bad consequences as referencing uninitialized data---core dumps, wrong results, mysterious crashes. Common causes of memory leaks are unusual paths through the code. For instance, @@ -839,10 +839,10 @@ strategy, hence my use of "automatic" to distinguish the two.) The big advantage of automatic garbage collection is that the user doesn't need to call :c:func:`free` explicitly. (Another claimed advantage is an improvement in speed -or memory usage --- this is no hard fact however.) The disadvantage is that for +or memory usage---this is no hard fact however.) The disadvantage is that for C, there is no truly portable automatic garbage collector, while reference counting can be implemented portably (as long as the functions :c:func:`malloc` -and :c:func:`free` are available --- which the C Standard guarantees). Maybe some +and :c:func:`free` are available---which the C Standard guarantees). Maybe some day a sufficiently portable automatic garbage collector will be available for C. Until then, we'll have to live with reference counts. @@ -879,7 +879,7 @@ There are two macros, ``Py_INCREF(x)`` and ``Py_DECREF(x)``, which handle the incrementing and decrementing of the reference count. :c:func:`Py_DECREF` also frees the object when the count reaches zero. For flexibility, it doesn't call -:c:func:`free` directly --- rather, it makes a call through a function pointer in +:c:func:`free` directly---rather, it makes a call through a function pointer in the object's :dfn:`type object`. For this purpose (and others), every object also contains a pointer to its type object. @@ -899,8 +899,8 @@ memory and should be avoided completely. [#]_ The advantage of borrowing over owning a reference is that you don't need to -take care of disposing of the reference on all possible paths through the code ---- in other words, with a borrowed reference you don't run the risk of leaking +take care of disposing of the reference on all possible paths through the +code---in other words, with a borrowed reference you don't run the risk of leaking when a premature exit is taken. The disadvantage of borrowing over owning is that there are some subtle situations where in seemingly correct code a borrowed reference can be used after the owner from which it was borrowed has in fact @@ -908,7 +908,7 @@ A borrowed reference can be changed into an owned reference by calling :c:func:`Py_INCREF`. This does not affect the status of the owner from which the -reference was borrowed --- it creates a new owned reference, and gives full +reference was borrowed---it creates a new owned reference, and gives full owner responsibilities (the new owner must dispose of the reference properly, as well as the previous owner). @@ -942,12 +942,12 @@ owned reference to the object is stored in ``sys.modules``. When you pass an object reference into another function, in general, the -function borrows the reference from you --- if it needs to store it, it will use +function borrows the reference from you---if it needs to store it, it will use :c:func:`Py_INCREF` to become an independent owner. There are exactly two important exceptions to this rule: :c:func:`PyTuple_SetItem` and :c:func:`PyList_SetItem`. These functions take over ownership of the item passed -to them --- even if they fail! (Note that :c:func:`PyDict_SetItem` and friends -don't take over ownership --- they are "normal.") +to them---even if they fail! (Note that :c:func:`PyDict_SetItem` and friends +don't take over ownership---they are "normal.") When a C function is called from Python, it borrows references to its arguments from the caller. The caller owns a reference to the object, so the borrowed @@ -956,7 +956,7 @@ reference by calling :c:func:`Py_INCREF`. The object reference returned from a C function that is called from Python must -be an owned reference --- ownership is transferred from the function to its +be an owned reference---ownership is transferred from the function to its caller. @@ -1048,7 +1048,7 @@ you do so. Functions that return object references generally return *NULL* only to indicate that an exception occurred. The reason for not testing for *NULL* arguments is that functions often pass the objects they receive on to other -function --- if each function were to test for *NULL*, there would be a lot of +function---if each function were to test for *NULL*, there would be a lot of redundant tests and the code would run more slowly. It is better to test for *NULL* only at the "source:" when a pointer that may be @@ -1056,24 +1056,24 @@ may raise an exception. The macros :c:func:`Py_INCREF` and :c:func:`Py_DECREF` do not check for *NULL* -pointers --- however, their variants :c:func:`Py_XINCREF` and :c:func:`Py_XDECREF` +pointers---however, their variants :c:func:`Py_XINCREF` and :c:func:`Py_XDECREF` do. The macros for checking for a particular object type (``Pytype_Check()``) don't -check for *NULL* pointers --- again, there is much code that calls several of +check for *NULL* pointers---again, there is much code that calls several of these in a row to test an object against various different expected types, and this would generate redundant tests. There are no variants with *NULL* checking. The C function calling mechanism guarantees that the argument list passed to C -functions (``args`` in the examples) is never *NULL* --- in fact it guarantees +functions (``args`` in the examples) is never *NULL*\ ---in fact it guarantees that it is always a tuple. [#]_ It is a severe error to ever let a *NULL* pointer "escape" to the Python user. .. Frank Stajano: A pedagogically buggy example, along the lines of the previous listing, would - be helpful here -- showing in more concrete terms what sort of actions could + be helpful here---showing in more concrete terms what sort of actions could cause the problem. I can't very well imagine it from the description. @@ -1088,7 +1088,7 @@ not a problem if the main program is linked by the C++ compiler. Functions that will be called by the Python interpreter (in particular, module initialization functions) have to be declared using ``extern "C"``. It is unnecessary to -enclose the Python header files in ``extern "C" {...}`` --- they use this form +enclose the Python header files in ``extern "C" {...}``\ ---they use this form already if the symbol ``__cplusplus`` is defined (all recent C++ compilers define this symbol). @@ -1317,13 +1317,13 @@ .. rubric:: Footnotes -.. [#] An interface for this function already exists in the standard module :mod:`os` - --- it was chosen as a simple and straightforward example. +.. [#] An interface for this function already exists in the standard module + :mod:`os`\ ---it was chosen as a simple and straightforward example. .. [#] The metaphor of "borrowing" a reference is not completely correct: the owner still has a copy of the reference. -.. [#] Checking that the reference count is at least 1 **does not work** --- the +.. [#] Checking that the reference count is at least 1 **does not work**\ ---the reference count itself could be in freed memory and may thus be reused for another object! diff -r afe119a3619f Doc/extending/newtypes.rst --- a/Doc/extending/newtypes.rst +++ b/Doc/extending/newtypes.rst @@ -69,7 +69,7 @@ double ob_fval; } PyFloatObject; -Moving on, we come to the crunch --- the type object. :: +Moving on, we come to the crunch---the type object. :: static PyTypeObject noddy_NoddyType = { PyVarObject_HEAD_INIT(NULL, 0) @@ -181,7 +181,7 @@ if (PyType_Ready(&noddy_NoddyType) < 0) return; -All the other type methods are *NULL*, so we'll go over them later --- that's +All the other type methods are *NULL*, so we'll go over them later---that's for a later section! Everything else in the file should be familiar, except for some code in @@ -213,7 +213,7 @@ $ python setup.py build at a shell should produce a file :file:`noddy.so` in a subdirectory; move to -that directory and fire up Python --- you should be able to ``import noddy`` and +that directory and fire up Python---you should be able to ``import noddy`` and play around with Noddy objects. That wasn't so hard, was it? @@ -858,8 +858,9 @@ Before calling :c:func:`PyType_Ready`, the type structure must have the :attr:`tp_base` slot filled in. When we are deriving a new type, it is not -necessary to fill out the :attr:`tp_alloc` slot with :c:func:`PyType_GenericNew` --- the allocate function from the base type will be inherited. +necessary to fill out the :attr:`tp_alloc` slot with +:c:func:`PyType_GenericNew`\ ---the allocate function from the base type will +be inherited. After that, calling :c:func:`PyType_Ready` and adding the type object to the module is the same as with the basic :class:`Noddy` examples. @@ -879,7 +880,7 @@ .. literalinclude:: ../includes/typestruct.h -Now that's a *lot* of methods. Don't worry too much though - if you have a type +Now that's a *lot* of methods. Don't worry too much though---if you have a type you want to define, the chances are very good that you will only implement a handful of these. @@ -893,7 +894,7 @@ char *tp_name; /* For printing */ -The name of the type - as mentioned in the last section, this will appear in +The name of the type---as mentioned in the last section, this will appear in various places, almost entirely for diagnostic purposes. Try to choose something that will be helpful in such a situation! :: diff -r afe119a3619f Doc/extending/windows.rst --- a/Doc/extending/windows.rst +++ b/Doc/extending/windows.rst @@ -48,7 +48,7 @@ described here are distributed with the Python sources in the :file:`PC\\example_nt\\` directory. -#. **Copy the example files** --- The :file:`example_nt` directory is a +#. **Copy the example files**\ ---The :file:`example_nt` directory is a subdirectory of the :file:`PC` directory, in order to keep all the PC-specific files under the same directory in the source distribution. However, the :file:`example_nt` directory can't actually be used from this location. You @@ -56,12 +56,12 @@ sibling of the :file:`PC` and :file:`Include` directories. Do all your work from within this new location. -#. **Open the project** --- From VC++, use the :menuselection:`File --> Open +#. **Open the project**\ ---From VC++, use the :menuselection:`File --> Open Solution` dialog (not :menuselection:`File --> Open`!). Navigate to and select the file :file:`example.sln`, in the *copy* of the :file:`example_nt` directory you made above. Click Open. -#. **Build the example DLL** --- In order to check that everything is set up +#. **Build the example DLL**\ ---In order to check that everything is set up right, try building: #. Select a configuration. This step is optional. Choose @@ -74,7 +74,7 @@ :file:`Debug` or :file:`Release`, depending on which configuration you selected in the preceding step. -#. **Testing the debug-mode DLL** --- Once the Debug build has succeeded, bring +#. **Testing the debug-mode DLL**\ ---Once the Debug build has succeeded, bring up a DOS box, and change to the :file:`example_nt\\Debug` directory. You should now be able to repeat the following session (``C>`` is the DOS prompt, ``>>>`` is the Python prompt; note that build information and various debug output from @@ -94,10 +94,10 @@ Congratulations! You've successfully built your first Python extension module. -#. **Creating your own project** --- Choose a name and create a directory for +#. **Creating your own project**\ ---Choose a name and create a directory for it. Copy your C sources into it. Note that the module source file name does not necessarily have to match the module name, but the name of the - initialization function should match the module name --- you can only import a + initialization function should match the module name---you can only import a module :mod:`spam` if its initialization function is called :c:func:`initspam`, and it should call :c:func:`Py_InitModule` with the string ``"spam"`` as its first argument (use the minimal :file:`example.c` in this directory as a guide). @@ -122,7 +122,7 @@ and add the option :option:`/export:initspam` somewhere to the Link settings, by manually editing the setting in Project Properties dialog). -#. **Creating a brand new project** --- Use the :menuselection:`File --> New +#. **Creating a brand new project**\ ---Use the :menuselection:`File --> New --> Project` dialog to create a new Project Workspace. Select :guilabel:`Visual C++ Projects/Win32/ Win32 Project`, enter the name (``spam``), and make sure the Location is set to parent of the :file:`spam` directory you have created (which diff -r afe119a3619f Doc/faq/design.rst --- a/Doc/faq/design.rst +++ b/Doc/faq/design.rst @@ -32,8 +32,8 @@ programs considerably longer and wastes valuable screen space, making it harder to get a good overview of a program. Ideally, a function should fit on one screen (say, 20-30 lines). 20 lines of Python can do a lot more work than 20 -lines of C. This is not solely due to the lack of begin/end brackets -- the -lack of declarations and the high-level data types are also responsible -- but +lines of C. This is not solely due to the lack of begin/end brackets---the +lack of declarations and the high-level data types are also responsible---but the indentation-based syntax certainly helps. @@ -111,16 +111,16 @@ instead of a local variable. Reading ``self.x`` or ``self.meth()`` makes it absolutely clear that an instance variable or method is used even if you don't know the class definition by heart. In C++, you can sort of tell by the lack of -a local variable declaration (assuming globals are rare or easily recognizable) --- but in Python, there are no local variable declarations, so you'd have to -look up the class definition to be sure. Some C++ and Java coding standards -call for instance attributes to have an ``m_`` prefix, so this explicitness is -still useful in those languages, too. +a local variable declaration (assuming globals are rare or easily +recognizable)\ ---but in Python, there are no local variable declarations, so +you'd have to look up the class definition to be sure. Some C++ and Java coding +standards call for instance attributes to have an ``m_`` prefix, so this +explicitness is still useful in those languages, too. Second, it means that no special syntax is necessary if you want to explicitly reference or call the method from a particular class. In C++, if you want to use a method from a base class which is overridden in a derived class, you have -to use the ``::`` operator -- in Python you can write +to use the ``::`` operator---in Python you can write ``baseclass.methodname(self, )``. This is particularly useful for :meth:`__init__` methods, and in general in cases where a derived class method wants to extend the base class method of the same name and thus has to @@ -195,7 +195,7 @@ The problem with this is that if you change your mind about exactly how you get the next line (e.g. you want to change it into ``sys.stdin.readline()``) you -have to remember to change two places in your program -- the second occurrence +have to remember to change two places in your program---the second occurrence is hidden at the bottom of the loop. The best approach is to use iterators, making it possible to loop through @@ -359,7 +359,7 @@ Functions are already first class objects in Python, and can be declared in a local scope. Therefore the only advantage of using a lambda form instead of a locally-defined function is that you don't need to invent a name for the -function -- but that's just a local variable to which the function object (which +function---but that's just a local variable to which the function object (which is exactly the same type of object that a lambda form yields) is assigned! @@ -517,7 +517,7 @@ to 1142331976. The hash code is then used to calculate a location in an internal array where the value will be stored. Assuming that you're storing keys that all have different hash values, this means that dictionaries take -constant time -- O(1), in computer science notation -- to retrieve a key. It +constant time---O(1), in computer science notation---to retrieve a key. It also means that no sorted order of the keys is maintained, and traversing the array as the ``.keys()`` and ``.items()`` do will output the dictionary's content in some arbitrary jumbled order that can change with every invocation of @@ -565,7 +565,7 @@ is that it's not just the top-level object that could change its value; you could use a tuple containing a list as a key. Entering anything as a key into a dictionary would require marking all objects reachable from there as - read-only -- and again, self-referential objects could cause an infinite loop. + read-only---and again, self-referential objects could cause an infinite loop. There is a trick to get around this if you need to, but use it at your own risk: You can wrap a mutable structure inside a class instance which has both a @@ -782,7 +782,7 @@ Other languages, such as Object Pascal, Delphi, and C++, use static types, so it's possible to know, in an unambiguous way, what member is being assigned -to. This is the main point of static typing -- the compiler *always* knows the +to. This is the main point of static typing---the compiler *always* knows the scope of every variable at compile time. Python uses dynamic types. It is impossible to know in advance which attribute diff -r afe119a3619f Doc/faq/extending.rst --- a/Doc/faq/extending.rst +++ b/Doc/faq/extending.rst @@ -93,7 +93,7 @@ :c:func:`PyBytes_Check`, :c:func:`PyTuple_Check`, :c:func:`PyList_Check`, etc. There is also a high-level API to Python objects which is provided by the -so-called 'abstract' interface -- read ``Include/abstract.h`` for further +so-called 'abstract' interface---read ``Include/abstract.h`` for further details. It allows interfacing with any kind of Python sequence using calls like :c:func:`PySequence_Length`, :c:func:`PySequence_GetItem`, etc.) as well as many other useful protocols such as numbers (:c:func:`PyNumber_Index` et. @@ -118,7 +118,7 @@ PyObject_CallMethod(PyObject *object, char *method_name, char *arg_format, ...); -This works for any object that has methods -- whether built-in or user-defined. +This works for any object that has methods---whether built-in or user-defined. You are responsible for eventually :c:func:`Py_DECREF`\ 'ing the return value. To call, e.g., a file object's "seek" method with arguments 10, 0 (assuming the @@ -184,7 +184,7 @@ If the module hasn't been imported yet (i.e. it is not yet present in :data:`sys.modules`), this initializes the module; otherwise it simply returns the value of ``sys.modules[""]``. Note that it doesn't enter the -module into any namespace -- it only ensures it has been initialized and is +module into any namespace---it only ensures it has been initialized and is stored in :data:`sys.modules`. You can then access the module's attributes (i.e. any name defined in the @@ -202,7 +202,7 @@ Depending on your requirements, there are many approaches. To do this manually, begin by reading :ref:`the "Extending and Embedding" document `. Realize that for the Python run-time system, there isn't a -whole lot of difference between C and C++ -- so the strategy of building a new +whole lot of difference between C and C++\ ---so the strategy of building a new Python type around a C structure (pointer) type will also work for C++ objects. For C++ libraries, see :ref:`c-wrapper-software`. @@ -316,7 +316,7 @@ :c:func:`Py_CompileString`. If it compiles without errors, try to execute the returned code object by calling :c:func:`PyEval_EvalCode`. Otherwise save the input for later. If the compilation fails, find out if it's an error or just -more input is required - by extracting the message string from the exception +more input is required---by extracting the message string from the exception tuple and comparing it to the string "unexpected EOF while parsing". Here is a complete example using the GNU readline library (you may want to ignore **SIGINT** while calling readline()):: diff -r afe119a3619f Doc/faq/general.rst --- a/Doc/faq/general.rst +++ b/Doc/faq/general.rst @@ -76,7 +76,7 @@ I had a number of gripes about the ABC language, but also liked many of its features. It was impossible to extend the ABC language (or its - implementation) to remedy my complaints -- in fact its lack of extensibility + implementation) to remedy my complaints---in fact its lack of extensibility was one of its biggest problems. I had some experience with using Modula-2+ and talked with the designers of Modula-3 and read the Modula-3 report. Modula-3 is the origin of the syntax and semantics used for exceptions, and @@ -124,10 +124,10 @@ How does the Python version numbering scheme work? -------------------------------------------------- -Python versions are numbered A.B.C or A.B. A is the major version number -- it +Python versions are numbered A.B.C or A.B. A is the major version number---it is only incremented for really major changes in the language. B is the minor version number, incremented for less earth-shattering changes. C is the -micro-level -- it is incremented for each bugfix release. See :pep:`6` for more +micro-level---it is incremented for each bugfix release. See :pep:`6` for more information about bugfix releases. Not all releases are bugfix releases. In the run-up to a new major release, a @@ -200,7 +200,7 @@ There is a newsgroup, :newsgroup:`comp.lang.python`, and a mailing list, `python-list `_. The -newsgroup and mailing list are gatewayed into each other -- if you can read news +newsgroup and mailing list are gatewayed into each other---if you can read news it's unnecessary to subscribe to the mailing list. :newsgroup:`comp.lang.python` is high-traffic, receiving hundreds of postings every day, and Usenet readers are often more able to cope with this volume. diff -r afe119a3619f Doc/faq/library.rst --- a/Doc/faq/library.rst +++ b/Doc/faq/library.rst @@ -95,7 +95,7 @@ For Unix variants: The standard Python source distribution comes with a curses module in the :source:`Modules` subdirectory, though it's not compiled by default. -(Note that this is not available in the Windows distribution -- there is no +(Note that this is not available in the Windows distribution---there is no curses module for Windows.) The :mod:`curses` module supports basic curses features as well as many additional @@ -144,7 +144,7 @@ To make testing easier, you should use good modular design in your program. Your program should have almost all functionality -encapsulated in either functions or class methods -- and this sometimes has the +encapsulated in either functions or class methods---and this sometimes has the surprising and delightful effect of making the program run faster (because local variable accesses are faster than global accesses). Furthermore the program should avoid depending on mutating global variables, since this makes testing @@ -765,9 +765,9 @@ have to check what's returned on your system. You can use the ``connect_ex()`` method to avoid creating an exception. It will -just return the errno value. To poll, you can call ``connect_ex()`` again later --- ``0`` or ``errno.EISCONN`` indicate that you're connected -- or you can pass this -socket to select to check if it's writable. +just return the errno value. To poll, you can call ``connect_ex()`` again +later---\ ``0`` or ``errno.EISCONN`` indicate that you're connected---or you +can pass this socket to select to check if it's writable. .. note:: The :mod:`asyncore` module presents a framework-like approach to the problem diff -r afe119a3619f Doc/faq/programming.rst --- a/Doc/faq/programming.rst +++ b/Doc/faq/programming.rst @@ -229,7 +229,7 @@ 16 This happens because ``x`` is not local to the lambdas, but is defined in -the outer scope, and it is accessed when the lambda is called --- not when it +the outer scope, and it is accessed when the lambda is called---not when it is defined. At the end of the loop, the value of ``x`` is ``4``, so all the functions now return ``4**2``, i.e. ``16``. You can also verify this by changing the value of ``x`` and see how the results of the lambdas change:: @@ -303,9 +303,9 @@ It's good practice if you import modules in the following order: -1. standard library modules -- e.g. ``sys``, ``os``, ``getopt``, ``re`` +1. standard library modules---e.g. ``sys``, ``os``, ``getopt``, ``re`` 2. third-party library modules (anything installed in Python's site-packages - directory) -- e.g. mx.DateTime, ZODB, PIL.Image, etc. + directory)\ ---e.g. mx.DateTime, ZODB, PIL.Image, etc. 3. locally-developed modules Never use relative package imports. If you're writing code that's in the @@ -573,7 +573,7 @@ this question: The same way as you get the name of that cat you found on your porch: the cat - (object) itself cannot tell you its name, and it doesn't really care -- so + (object) itself cannot tell you its name, and it doesn't really care---so the only way to find out what it's called is to ask all your neighbours (namespaces) if it's their cat (object)... @@ -1552,7 +1552,7 @@ There are several possible reasons for this. -The del statement does not necessarily call :meth:`__del__` -- it simply +The del statement does not necessarily call :meth:`__del__`\ ---it simply decrements the object's reference count, and if this reaches zero :meth:`__del__` is called. @@ -1570,7 +1570,7 @@ Despite the cycle collector, it's still a good idea to define an explicit ``close()`` method on objects to be called whenever you're done with them. The ``close()`` method can then remove attributes that refer to subobjecs. Don't -call :meth:`__del__` directly -- :meth:`__del__` should call ``close()`` and +call :meth:`__del__` directly---\ :meth:`__del__` should call ``close()`` and ``close()`` should make sure that it can be called more than once for the same object. @@ -1622,8 +1622,8 @@ ``xyz.pyc`` will be created since ``xyz`` is imported, but no ``foo.pyc`` file will be created since ``foo.py`` isn't being imported. -If you need to create ``foo.pyc`` -- that is, to create a ``.pyc`` file for a module -that is not imported -- you can, using the :mod:`py_compile` and +If you need to create ``foo.pyc``\ ---that is, to create a ``.pyc`` file for a module +that is not imported---you can, using the :mod:`py_compile` and :mod:`compileall` modules. The :mod:`py_compile` module can manually compile any module. One way is to use diff -r afe119a3619f Doc/glossary.rst --- a/Doc/glossary.rst +++ b/Doc/glossary.rst @@ -670,7 +670,7 @@ changes to such packages are not expected, as long as they are marked provisional, backwards incompatible changes (up to and including removal of the package) may occur if deemed necessary by core developers. Such - changes will not be made gratuitously -- they will occur only if serious + changes will not be made gratuitously---they will occur only if serious flaws are uncovered that were missed prior to the inclusion of the package. diff -r afe119a3619f Doc/howto/cporting.rst --- a/Doc/howto/cporting.rst +++ b/Doc/howto/cporting.rst @@ -96,7 +96,7 @@ -------------------- Python 3 has only one integer type, :func:`int`. But it actually -corresponds to Python 2's :func:`long` type--the :func:`int` type +corresponds to Python 2's :func:`long` type---the :func:`int` type used in Python 2 was removed. In the C-API, ``PyInt_*`` functions are replaced by their ``PyLong_*`` equivalents. diff -r afe119a3619f Doc/howto/functional.rst --- a/Doc/howto/functional.rst +++ b/Doc/howto/functional.rst @@ -1244,7 +1244,7 @@ .. comment - Handy little function for printing part of an iterator -- used + Handy little function for printing part of an iterator---used while writing this document. import itertools diff -r afe119a3619f Doc/howto/logging-cookbook.rst --- a/Doc/howto/logging-cookbook.rst +++ b/Doc/howto/logging-cookbook.rst @@ -602,8 +602,8 @@ For example in a web application, the request being processed (or at least, the interesting parts of it) can be stored in a threadlocal (:class:`threading.local`) variable, and then accessed from a ``Filter`` to -add, say, information from the request - say, the remote IP address and remote -user's username - to the ``LogRecord``, using the attribute names 'ip' and +add, say, information from the request---say, the remote IP address and remote +user's username---to the ``LogRecord``, using the attribute names 'ip' and 'user' as in the ``LoggerAdapter`` example above. In that case, the same format string can be used to get similar output to that shown above. Here's an example script:: @@ -696,7 +696,7 @@ a separate listener process listens for events sent by other processes and logs them according to its own logging configuration. Although the example only demonstrates one way of doing it (for example, you may want to use a listener -thread rather than a separate listener process -- the implementation would be +thread rather than a separate listener process---the implementation would be analogous) it does allow for completely different logging configurations for the listener and the other processes in your application, and can be used as the basis for code meeting your own specific requirements:: @@ -1211,7 +1211,7 @@ .. _zeromq-handlers: -Subclassing QueueHandler - a ZeroMQ example +Subclassing QueueHandler---a ZeroMQ example ------------------------------------------- You can use a :class:`QueueHandler` subclass to send messages to other kinds @@ -1251,7 +1251,7 @@ self.queue.close() -Subclassing QueueListener - a ZeroMQ example +Subclassing QueueListener---a ZeroMQ example -------------------------------------------- You can also subclass :class:`QueueListener` to get messages from other kinds @@ -1288,7 +1288,7 @@ An example dictionary-based configuration ----------------------------------------- -Below is an example of a logging configuration dictionary - it's taken from +Below is an example of a logging configuration dictionary---it's taken from the `documentation on the Django project `_. This dictionary is passed to :func:`~logging.config.dictConfig` to put the configuration into effect:: @@ -1393,7 +1393,7 @@ purely illustrative, but you should be able to adapt this example to your own scenario. -Here's the script - the docstrings and the comments hopefully explain how it +Here's the script---the docstrings and the comments hopefully explain how it works:: import logging @@ -1632,7 +1632,7 @@ 'ASCII section\ufeffUnicode section' The Unicode code point U+FEFF, when encoded using UTF-8, will be - encoded as a UTF-8 BOM -- the byte-string ``b'\xef\xbb\xbf'``. + encoded as a UTF-8 BOM---the byte-string ``b'\xef\xbb\xbf'``. #. Replace the ASCII section with whatever placeholders you like, but make sure that the data that appears in there after substitution is always ASCII (that @@ -1640,7 +1640,7 @@ #. Replace the Unicode section with whatever placeholders you like; if the data which appears there after substitution contains characters outside the ASCII - range, that's fine -- it will be encoded using UTF-8. + range, that's fine---it will be encoded using UTF-8. The formatted message *will* be encoded using UTF-8 encoding by ``SysLogHandler``. If you follow the above rules, you should be able to produce diff -r afe119a3619f Doc/howto/logging.rst --- a/Doc/howto/logging.rst +++ b/Doc/howto/logging.rst @@ -216,7 +216,7 @@ usage pattern, you won't know, by looking in the log file, *where* in your application your messages came from, apart from looking at the event description. If you want to track the location of your messages, you'll need -to refer to the documentation beyond the tutorial level -- see +to refer to the documentation beyond the tutorial level---see :ref:`logging-advanced-tutorial`. @@ -448,7 +448,7 @@ Loggers have a concept of *effective level*. If a level is not explicitly set on a logger, the level of its parent is used instead as its effective level. -If the parent has no explicit level set, *its* parent is examined, and so on - +If the parent has no explicit level set, *its* parent is examined, and so on --- all ancestors are searched until an explicitly set level is found. The root logger always has an explicit level set (``WARNING`` by default). When deciding whether to process an event, the effective level of the logger is used to @@ -509,7 +509,7 @@ message. Unlike the base :class:`logging.Handler` class, application code may instantiate formatter classes, although you could likely subclass the formatter if your application needs special behavior. The constructor takes three -optional arguments -- a message format string, a date format string and a style +optional arguments---a message format string, a date format string and a style indicator. .. method:: logging.Formatter.__init__(fmt=None, datefmt=None, style='%') @@ -675,7 +675,7 @@ value with key ``disable_existing_loggers``, which if not specified explicitly in the dictionary also defaults to being interpreted as ``True``. This leads to the logger-disabling behaviour described above, - which may not be what you want - in which case, provide the key + which may not be what you want---in which case, provide the key explicitly with a value of ``False``. @@ -749,7 +749,7 @@ logger, and acts like a :class:`~logging.StreamHandler` which writes the event description message to the current value of ``sys.stderr`` (therefore respecting any redirections which may be in effect). No formatting is - done on the message - just the bare event description message is printed. + done on the message---just the bare event description message is printed. The handler's level is set to ``WARNING``, so all events at this and greater severities will be output. @@ -761,7 +761,7 @@ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ When developing a library which uses logging, you should take care to -document how the library uses logging - for example, the names of loggers +document how the library uses logging---for example, the names of loggers used. Some consideration also needs to be given to its logging configuration. If the using application does not use logging, and library code makes logging calls, then (as described in the previous section) events of severity @@ -971,7 +971,7 @@ The logging package is designed to swallow exceptions which occur while logging in production. This is so that errors which occur while handling logging events -- such as logging misconfiguration, network or other similar errors - do not +- such as logging misconfiguration, network or other similar errors---do not cause the application using logging to terminate prematurely. :class:`SystemExit` and :class:`KeyboardInterrupt` exceptions are never @@ -999,7 +999,7 @@ possibility. You can pass an arbitrary object as a message, and its :meth:`__str__` method will be called when the logging system needs to convert it to a string representation. In fact, if you want to, you can avoid -computing a string representation altogether - for example, the +computing a string representation altogether---for example, the :class:`SocketHandler` emits an event by pickling it and sending it over the wire. diff -r afe119a3619f Doc/howto/regex.rst --- a/Doc/howto/regex.rst +++ b/Doc/howto/regex.rst @@ -232,7 +232,7 @@ You can omit either *m* or *n*; in that case, a reasonable value is assumed for the missing value. Omitting *m* is interpreted as a lower limit of 0, while -omitting *n* results in an upper bound of infinity --- actually, the upper bound +omitting *n* results in an upper bound of infinity---actually, the upper bound is the 2-billion limit mentioned earlier, but that might as well be infinity. Readers of a reductionist bent may notice that the three other qualifiers can @@ -837,9 +837,9 @@ >>> p.search('Paris in the the spring').group() 'the the' -Backreferences like this aren't often useful for just searching through a string ---- there are few text formats which repeat data in this way --- but you'll soon -find out that they're *very* useful when performing string substitutions. +Backreferences like this aren't often useful for just searching through a +string---there are few text formats which repeat data in this way---but you'll +soon find out that they're *very* useful when performing string substitutions. Non-capturing and Named Groups diff -r afe119a3619f Doc/howto/sockets.rst --- a/Doc/howto/sockets.rst +++ b/Doc/howto/sockets.rst @@ -11,7 +11,7 @@ Sockets are used nearly everywhere, but are one of the most severely misunderstood technologies around. This is a 10,000 foot overview of sockets. - It's not really a tutorial - you'll still have work to do in getting things + It's not really a tutorial---you'll still have work to do in getting things operational. It doesn't cover the fine points (and there are a lot of them), but I hope it will give you enough background to begin using them decently. @@ -21,12 +21,12 @@ Sockets are used nearly everywhere, but are one of the most severely misunderstood technologies around. This is a 10,000 foot overview of sockets. -It's not really a tutorial - you'll still have work to do in getting things +It's not really a tutorial---you'll still have work to do in getting things working. It doesn't cover the fine points (and there are a lot of them), but I hope it will give you enough background to begin using them decently. I'm only going to talk about INET (i.e. IPv4) sockets, but they account for at least 99% of -the sockets in use. And I'll only talk about STREAM (i.e. TCP) sockets - unless you really +the sockets in use. And I'll only talk about STREAM (i.e. TCP) sockets---unless you really know what you're doing (in which case this HOWTO isn't for you!), you'll get better behavior and performance from a STREAM socket than anything else. I will try to clear up the mystery of what a socket is, as well as some hints on how to @@ -36,7 +36,7 @@ Part of the trouble with understanding these things is that "socket" can mean a number of subtly different things, depending on context. So first, let's make a -distinction between a "client" socket - an endpoint of a conversation, and a +distinction between a "client" socket---an endpoint of a conversation, and a "server" socket, which is more like a switchboard operator. The client application (your browser, for example) uses "client" sockets exclusively; the web server it's talking to uses both "server" sockets and "client" sockets. @@ -51,7 +51,7 @@ cross-platform communication, sockets are about the only game in town. They were invented in Berkeley as part of the BSD flavor of Unix. They spread -like wildfire with the Internet. With good reason --- the combination of sockets +like wildfire with the Internet. With good reason---the combination of sockets with INET makes talking to arbitrary machines around the world unbelievably easy (at least compared to other schemes). @@ -109,7 +109,7 @@ ct = client_thread(clientsocket) ct.run() -There's actually 3 general ways in which this loop could work - dispatching a +There's actually 3 general ways in which this loop could work---dispatching a thread to handle ``clientsocket``, create a new process to handle ``clientsocket``, or restructure this app to use non-blocking sockets, and mulitplex between our "server" socket and any active ``clientsocket``\ s using @@ -119,7 +119,7 @@ created in response to some *other* "client" socket doing a ``connect()`` to the host and port we're bound to. As soon as we've created that ``clientsocket``, we go back to listening for more connections. The two "clients" are free to chat it -up - they are using some dynamically allocated port which will be recycled when +up---they are using some dynamically allocated port which will be recycled when the conversation ends. @@ -144,7 +144,7 @@ conversation. Or to put it another way, *as the designer, you will have to decide what the rules of etiquette are for a conversation*. Normally, the ``connect``\ ing socket starts the conversation, by sending in a request, or -perhaps a signon. But that's a design decision - it's not a rule of sockets. +perhaps a signon. But that's a design decision---it's not a rule of sockets. Now there are two sets of verbs to use for communication. You can use ``send`` and ``recv``, or you can transform your client socket into a file-like beast and @@ -155,7 +155,7 @@ there, you may wait forever for the reply, because the request may still be in your output buffer. -Now we come to the major stumbling block of sockets - ``send`` and ``recv`` operate +Now we come to the major stumbling block of sockets---\ ``send`` and ``recv`` operate on the network buffers. They do not necessarily handle all the bytes you hand them (or expect from them), because their major focus is handling the network buffers. In general, they return when the associated network buffers have been @@ -218,7 +218,7 @@ msg = msg + chunk return msg -The sending code here is usable for almost any messaging scheme - in Python you +The sending code here is usable for almost any messaging scheme---in Python you send strings, and you can use ``len()`` to determine its length (even if it has embedded ``\0`` characters). It's mostly the receiving code that gets more complex. (And in C, it's not much worse, except you can't use ``strlen`` if the @@ -226,7 +226,7 @@ The easiest enhancement is to make the first character of the message an indicator of message type, and have the type determine the length. Now you have -two ``recv``\ s - the first to get (at least) that first character so you can +two ``recv``\ s---the first to get (at least) that first character so you can look up the length, and the second in a loop to get the rest. If you decide to go the delimited route, you'll be receiving in some arbitrary chunk size, (4096 or 8192 is frequently a good match for network buffer sizes), and scanning what @@ -241,7 +241,7 @@ Prefixing the message with it's length (say, as 5 numeric characters) gets more complex, because (believe it or not), you may not get all 5 characters in one ``recv``. In playing around, you'll get away with it; but in high network loads, -your code will very quickly break unless you use two ``recv`` loops - the first +your code will very quickly break unless you use two ``recv`` loops---the first to determine the length, the second to get the data part of the message. Nasty. This is also when you'll discover that ``send`` does not always manage to get rid of everything in one pass. And despite having read this, you will eventually @@ -258,8 +258,8 @@ It is perfectly possible to send binary data over a socket. The major problem is that not all machines use the same formats for binary data. For example, a Motorola chip will represent a 16 bit integer with the value 1 as the two hex -bytes 00 01. Intel and DEC, however, are byte-reversed - that same 1 is 01 00. -Socket libraries have calls for converting 16 and 32 bit integers - ``ntohl, +bytes 00 01. Intel and DEC, however, are byte-reversed---that same 1 is 01 00. +Socket libraries have calls for converting 16 and 32 bit integers---\ ``ntohl, htonl, ntohs, htons`` where "n" means *network* and "h" means *host*, "s" means *short* and "l" means *long*. Where network order is host order, these do nothing, but where the machine is byte-reversed, these swap the bytes around @@ -307,7 +307,7 @@ essentially dead. There's not much you can do about it. As long as you aren't doing something dumb, like holding a lock while doing a blocking read, the thread isn't really consuming much in the way of resources. Do *not* try to kill -the thread - part of the reason that threads are more efficient than processes +the thread---part of the reason that threads are more efficient than processes is that they avoid the overhead associated with the automatic recycling of resources. In other words, if you do manage to kill the thread, your whole process is likely to be screwed up. @@ -353,7 +353,7 @@ to, and the last (normally left empty) those that you want to check for errors. You should note that a socket can go into more than one list. The ``select`` call is blocking, but you can give it a timeout. This is generally a sensible -thing to do - give it a nice long timeout (say a minute) unless you have good +thing to do---give it a nice long timeout (say a minute) unless you have good reason to do otherwise. In return, you will get three lists. They contain the sockets that are actually @@ -364,7 +364,7 @@ as-close-to-certain-as-we-ever-get-in-this-business that a ``recv`` on that socket will return *something*. Same idea for the writable list. You'll be able to send *something*. Maybe not all you want to, but *something* is better than -nothing. (Actually, any reasonably healthy socket will return as writable - it +nothing. (Actually, any reasonably healthy socket will return as writable---it just means outbound network buffer space is available.) If you have a "server" socket, put it in the potential_readers list. If it comes @@ -374,7 +374,7 @@ chance that it has connected. Actually, ``select`` can be handy even with blocking sockets. It's one way of -determining whether you will block - the socket returns as readable when there's +determining whether you will block---the socket returns as readable when there's something in the buffers. However, this still doesn't help with the problem of determining whether the other end is done, or just busy with something else. diff -r afe119a3619f Doc/howto/sorting.rst --- a/Doc/howto/sorting.rst +++ b/Doc/howto/sorting.rst @@ -25,7 +25,7 @@ You can also use the :meth:`list.sort` method. It modifies the list in-place (and returns *None* to avoid confusion). Usually it's less convenient -than :func:`sorted` - but if you don't need the original list, it's slightly +than :func:`sorted`\ ---but if you don't need the original list, it's slightly more efficient. >>> a = [5, 2, 3, 1, 4] @@ -175,7 +175,7 @@ It is not strictly necessary in all cases to include the index *i* in the decorated list, but including it gives two benefits: -* The sort is stable -- if two items have the same key, their order will be +* The sort is stable---if two items have the same key, their order will be preserved in the sorted list. * The original items do not have to be comparable because the ordering of the diff -r afe119a3619f Doc/howto/urllib2.rst --- a/Doc/howto/urllib2.rst +++ b/Doc/howto/urllib2.rst @@ -9,7 +9,7 @@ .. note:: There is a French translation of an earlier revision of this - HOWTO, available at `urllib2 - Le Manuel manquant + HOWTO, available at `urllib2---Le Manuel manquant `_. @@ -30,11 +30,11 @@ (Uniform Resource Locators). It offers a very simple interface, in the form of the *urlopen* function. This is capable of fetching URLs using a variety of different protocols. It also offers a slightly more complex interface for -handling common situations - like basic authentication, cookies, proxies and so +handling common situations---like basic authentication, cookies, proxies and so on. These are provided by objects called handlers and openers. urllib.request supports fetching URLs for many "URL schemes" (identified by the string -before the ":" in URL - for example "ftp" is the URL scheme of +before the ":" in URL---for example "ftp" is the URL scheme of "ftp://python.org/") using their associated network protocols (e.g. FTP, HTTP). This tutorial focuses on the most common case, HTTP. @@ -68,7 +68,7 @@ purpose of this tutorial to explain the more complicated cases, concentrating on HTTP. -HTTP is based on requests and responses - the client makes requests and servers +HTTP is based on requests and responses---the client makes requests and servers send responses. urllib.request mirrors this with a ``Request`` object which represents the HTTP request you are making. In its simplest form you create a Request object that specifies the URL you want to fetch. Calling ``urlopen`` with this @@ -90,7 +90,7 @@ In the case of HTTP, there are two extra things that Request objects allow you to do: First, you can pass data to be sent to the server. Second, you can pass extra information ("metadata") *about* the data or the about request itself, to -the server - this information is sent as HTTP "headers". Let's look at each of +the server---this information is sent as HTTP "headers". Let's look at each of these in turn. Data @@ -121,7 +121,7 @@ the_page = response.read() Note that other encodings are sometimes required (e.g. for file upload from HTML -forms - see `HTML Specification, Form Submission +forms---see `HTML Specification, Form Submission `_ for more details). @@ -394,11 +394,11 @@ useful methods :meth:`info` and :meth:`geturl` and is defined in the module :mod:`urllib.response`.. -**geturl** - this returns the real URL of the page fetched. This is useful +**geturl**\ ---this returns the real URL of the page fetched. This is useful because ``urlopen`` (or the opener object used) may have followed a redirect. The URL of the page fetched may not be the same as the URL requested. -**info** - this returns a dictionary-like object that describes the page +**info**\ ---this returns a dictionary-like object that describes the page fetched, particularly the headers sent by the server. It is currently an :class:`http.client.HTTPMessage` instance. @@ -413,7 +413,7 @@ When you fetch a URL you use an opener (an instance of the perhaps confusingly-named :class:`urllib.request.OpenerDirector`). Normally we have been using -the default opener - via ``urlopen`` - but you can create custom +the default opener---via ``urlopen``\ ---but you can create custom openers. Openers use handlers. All the "heavy lifting" is done by the handlers. Each handler knows how to open URLs for a particular URL scheme (http, ftp, etc.), or how to handle an aspect of URL opening, for example HTTP @@ -447,8 +447,8 @@ ==================== To illustrate creating and installing a handler we will use the -``HTTPBasicAuthHandler``. For a more detailed discussion of this subject -- -including an explanation of how Basic Authentication works - see the `Basic +``HTTPBasicAuthHandler``. For a more detailed discussion of this subject --- +including an explanation of how Basic Authentication works---see the `Basic Authentication Tutorial `_. @@ -503,18 +503,18 @@ .. note:: In the above example we only supplied our ``HTTPBasicAuthHandler`` to - ``build_opener``. By default openers have the handlers for normal situations - -- ``ProxyHandler`` (if a proxy setting such as an :envvar:`http_proxy` - environment variable is set), ``UnknownHandler``, ``HTTPHandler``, - ``HTTPDefaultErrorHandler``, ``HTTPRedirectHandler``, ``FTPHandler``, - ``FileHandler``, ``DataHandler``, ``HTTPErrorProcessor``. + ``build_opener``. By default openers have the handlers for normal + situations---\ ``ProxyHandler`` (if a proxy setting such as an + :envvar:`http_proxy` environment variable is set), ``UnknownHandler``, + ``HTTPHandler``, ``HTTPDefaultErrorHandler``, ``HTTPRedirectHandler``, + ``FTPHandler``, ``FileHandler``, ``DataHandler``, ``HTTPErrorProcessor``. ``top_level_url`` is in fact *either* a full URL (including the 'http:' scheme component and the hostname and optionally the port number) e.g. "http://example.com/" *or* an "authority" (i.e. the hostname, optionally including the port number) e.g. "example.com" or "example.com:8080" (the latter example includes a port number). The authority, if present, must -NOT contain the "userinfo" component - for example "joe@password:example.com" is +NOT contain the "userinfo" component---for example "joe@password:example.com" is not correct. @@ -578,7 +578,7 @@ is to use `PyGoogle `_ of course. See `Voidspace Google `_ for some examples of using the Google API. -.. [#] Browser sniffing is a very bad practise for website design - building +.. [#] Browser sniffing is a very bad practise for website design---building sites using web standards is much more sensible. Unfortunately a lot of sites still send different versions to different browsers. .. [#] The user agent for MSIE 6 is diff -r afe119a3619f Doc/howto/webservers.rst --- a/Doc/howto/webservers.rst +++ b/Doc/howto/webservers.rst @@ -47,7 +47,7 @@ support Python, it is easy to use Python to create dynamic web sites. Most HTTP servers are written in C or C++, so they cannot execute Python code -directly -- a bridge is needed between the server and the program. These +directly---a bridge is needed between the server and the program. These bridges, or rather interfaces, define how programs interact with the server. There have been numerous attempts to create the best possible interface, but there are only a few worth mentioning. @@ -63,11 +63,11 @@ This interface, most commonly referred to as "CGI", is the oldest, and is supported by nearly every web server out of the box. Programs using CGI to communicate with their web server need to be started by the server for every -request. So, every request starts a new Python interpreter -- which takes some -time to start up -- thus making the whole interface only usable for low load +request. So, every request starts a new Python interpreter---which takes some +time to start up---thus making the whole interface only usable for low load situations. -The upside of CGI is that it is simple -- writing a Python program which uses +The upside of CGI is that it is simple---writing a Python program which uses CGI is a matter of about three lines of code. This simplicity comes at a price: it does very few things to help the developer. @@ -81,8 +81,8 @@ The Python standard library includes some modules that are helpful for creating plain CGI programs: - * :mod:`cgi` -- Handling of user input in CGI scripts - * :mod:`cgitb` -- Displays nice tracebacks when errors happen in CGI + * :mod:`cgi`\ ---Handling of user input in CGI scripts + * :mod:`cgitb`\ ---Displays nice tracebacks when errors happen in CGI applications, instead of presenting a "500 Internal Server Error" message The Python wiki features a page on `CGI scripts @@ -117,7 +117,7 @@ Server Error" in the user's browser. This is useful for debugging, but it might risk exposing some confidential data to the user. You should not use ``cgitb`` in production code for this reason. You should *always* catch exceptions, and -display proper error pages -- end-users don't like to see nondescript "Internal +display proper error pages---end-users don't like to see nondescript "Internal Server Errors" in their browsers. @@ -224,15 +224,15 @@ ``mod_python`` does have some problems. Unlike the PHP interpreter, the Python interpreter uses caching when executing files, so changes to a file will -require the web server to be restarted. Another problem is the basic concept --- Apache starts child processes to handle the requests, and unfortunately -every child process needs to load the whole Python interpreter even if it does -not use it. This makes the whole web server slower. Another problem is that, -because ``mod_python`` is linked against a specific version of ``libpython``, -it is not possible to switch from an older version to a newer (e.g. 2.4 to 2.5) -without recompiling ``mod_python``. ``mod_python`` is also bound to the Apache -web server, so programs written for ``mod_python`` cannot easily run on other -web servers. +require the web server to be restarted. Another problem is the basic +concept---Apache starts child processes to handle the requests, and +unfortunately every child process needs to load the whole Python interpreter +even if it does not use it. This makes the whole web server slower. Another +problem is that, because ``mod_python`` is linked against a specific version of +``libpython``, it is not possible to switch from an older version to a newer +(e.g. 2.4 to 2.5) without recompiling ``mod_python``. ``mod_python`` is also +bound to the Apache web server, so programs written for ``mod_python`` cannot +easily run on other web servers. These are the reasons why ``mod_python`` should be avoided when writing new programs. In some circumstances it still might be a good idea to use @@ -354,11 +354,11 @@ development it is a good idea to choose one which supports WSGI. The big benefit of WSGI is the unification of the application programming -interface. When your program is compatible with WSGI -- which at the outer -level means that the framework you are using has support for WSGI -- your +interface. When your program is compatible with WSGI---which at the outer +level means that the framework you are using has support for WSGI---your program can be deployed via any web server interface for which there are WSGI wrappers. You do not need to care about whether the application user uses -mod_python or FastCGI or mod_wsgi -- with WSGI your application will work on +mod_python or FastCGI or mod_wsgi---with WSGI your application will work on any gateway interface. The Python standard library contains its own WSGI server, :mod:`wsgiref`, which is a small web server that can be used for testing. @@ -370,7 +370,7 @@ is a stateless protocol, so to associate multiple HTTP requests with a single user your application must create and manage such state via a session), you can just download middleware which does that, plug it in, and get on with coding -the unique parts of your application. The same thing with compression -- there +the unique parts of your application. The same thing with compression---there is existing middleware which handles compressing your HTML using gzip to save on your server's bandwidth. Authentication is another a problem easily solved using existing middleware. @@ -404,7 +404,7 @@ You might be interested in some WSGI-supporting modules already contained in the standard library, namely: - * :mod:`wsgiref` -- some tiny utilities and servers for WSGI + * :mod:`wsgiref`\ ---some tiny utilities and servers for WSGI Case study: MoinMoin @@ -461,7 +461,7 @@ to create a web site which uses the MVC pattern by separating the data logic (the model) from the user interaction logic (the controller) and the templates (the view). That's why it is important not to write unnecessary - Python code in the templates -- it works against the MVC model and creates + Python code in the templates---it works against the MVC model and creates chaos in the code base, making it harder to understand and modify. .. seealso:: diff -r afe119a3619f Doc/install/index.rst --- a/Doc/install/index.rst +++ b/Doc/install/index.rst @@ -563,7 +563,7 @@ python setup.py install --install-scripts=/usr/local/bin (This performs an installation using the "prefix scheme," where the prefix is -whatever your Python interpreter was installed with--- :file:`/usr/local/python` +whatever your Python interpreter was installed with---\ :file:`/usr/local/python` in this case.) If you maintain Python on Windows, you might want third-party modules to live in diff -r afe119a3619f Doc/library/2to3.rst --- a/Doc/library/2to3.rst +++ b/Doc/library/2to3.rst @@ -1,7 +1,7 @@ .. _2to3-reference: -2to3 - Automated Python 2 to 3 code translation -=============================================== +2to3---Automated Python 2 to 3 code translation +================================================= .. sectionauthor:: Benjamin Peterson @@ -411,8 +411,8 @@ ``from future_builtins import zip`` appears. -:mod:`lib2to3` - 2to3's library -------------------------------- +:mod:`lib2to3`\ ---2to3's library +--------------------------------- .. module:: lib2to3 :synopsis: the 2to3 library diff -r afe119a3619f Doc/library/__future__.rst --- a/Doc/library/__future__.rst +++ b/Doc/library/__future__.rst @@ -1,4 +1,4 @@ -:mod:`__future__` --- Future statement definitions +:mod:`__future__`\ ---Future statement definitions ================================================== .. module:: __future__ @@ -17,10 +17,10 @@ 2.1 at least yield runtime exceptions (the import of :mod:`__future__` will fail, because there was no module of that name prior to 2.1). -* To document when incompatible changes were introduced, and when they will be - --- or were --- made mandatory. This is a form of executable documentation, and - can be inspected programmatically via importing :mod:`__future__` and examining - its contents. +* To document when incompatible changes were introduced, and when they will + be---or were---made mandatory. This is a form of executable documentation, + and can be inspected programmatically via importing :mod:`__future__` and + examining its contents. Each statement in :file:`__future__.py` is of the form:: diff -r afe119a3619f Doc/library/__main__.rst --- a/Doc/library/__main__.rst +++ b/Doc/library/__main__.rst @@ -1,5 +1,5 @@ -:mod:`__main__` --- Top-level script environment +:mod:`__main__`\ ---Top-level script environment ================================================ .. module:: __main__ @@ -7,7 +7,7 @@ This module represents the (otherwise anonymous) scope in which the -interpreter's main program executes --- commands read either from standard +interpreter's main program executes---commands read either from standard input, from a script file, or from an interactive prompt. It is this environment in which the idiomatic "conditional script" stanza causes a script to run:: diff -r afe119a3619f Doc/library/_dummy_thread.rst --- a/Doc/library/_dummy_thread.rst +++ b/Doc/library/_dummy_thread.rst @@ -1,4 +1,4 @@ -:mod:`_dummy_thread` --- Drop-in replacement for the :mod:`_thread` module +:mod:`_dummy_thread`\ ---Drop-in replacement for the :mod:`_thread` module ========================================================================== .. module:: _dummy_thread diff -r afe119a3619f Doc/library/_thread.rst --- a/Doc/library/_thread.rst +++ b/Doc/library/_thread.rst @@ -1,4 +1,4 @@ -:mod:`_thread` --- Low-level threading API +:mod:`_thread`\ ---Low-level threading API ========================================== .. module:: _thread @@ -12,7 +12,7 @@ single: semaphores, binary This module provides low-level primitives for working with multiple threads -(also called :dfn:`light-weight processes` or :dfn:`tasks`) --- multiple threads of +(also called :dfn:`light-weight processes` or :dfn:`tasks`)\ ---multiple threads of control sharing their global data space. For synchronization, simple locks (also called :dfn:`mutexes` or :dfn:`binary semaphores`) are provided. The :mod:`threading` module provides an easier to use and higher-level @@ -100,7 +100,7 @@ stack space for the interpreter itself. Note that some platforms may have particular restrictions on values for the stack size, such as requiring a minimum stack size > 32 KiB or requiring allocation in multiples of the system - memory page size - platform documentation should be referred to for more + memory page size---platform documentation should be referred to for more information (4 KiB pages are common; using multiples of 4096 for the stack size is the suggested approach in the absence of more specific information). Availability: Windows, systems with POSIX threads. @@ -122,7 +122,7 @@ Without any optional argument, this method acquires the lock unconditionally, if necessary waiting until it is released by another thread (only one thread at a - time can acquire a lock --- that's their reason for existence). + time can acquire a lock---that's their reason for existence). If the integer *waitflag* argument is present, the action depends on its value: if it is zero, the lock is only acquired if it can be acquired @@ -180,7 +180,7 @@ to run. (The most popular ones (:func:`time.sleep`, :meth:`file.read`, :func:`select.select`) work as expected.) -* It is not possible to interrupt the :meth:`acquire` method on a lock --- the +* It is not possible to interrupt the :meth:`acquire` method on a lock---the :exc:`KeyboardInterrupt` exception will happen after the lock has been acquired. * When the main thread exits, it is system defined whether the other threads diff -r afe119a3619f Doc/library/abc.rst --- a/Doc/library/abc.rst +++ b/Doc/library/abc.rst @@ -1,4 +1,4 @@ -:mod:`abc` --- Abstract Base Classes +:mod:`abc`\ ---Abstract Base Classes ==================================== .. module:: abc @@ -31,7 +31,7 @@ Use this metaclass to create an ABC. An ABC can be subclassed directly, and then acts as a mix-in class. You can also register unrelated concrete - classes (even built-in classes) and unrelated ABCs as "virtual subclasses" -- + classes (even built-in classes) and unrelated ABCs as "virtual subclasses" --- these and their descendants will be considered subclasses of the registering ABC by the built-in :func:`issubclass` function, but the registering ABC won't show up in their MRO (Method Resolution Order) nor will method diff -r afe119a3619f Doc/library/aifc.rst --- a/Doc/library/aifc.rst +++ b/Doc/library/aifc.rst @@ -1,4 +1,4 @@ -:mod:`aifc` --- Read and write AIFF and AIFC files +:mod:`aifc`\ ---Read and write AIFF and AIFC files ================================================== .. module:: aifc diff -r afe119a3619f Doc/library/argparse.rst --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -1,4 +1,4 @@ -:mod:`argparse` --- Parser for command-line options, arguments and sub-commands +:mod:`argparse`\ ---Parser for command-line options, arguments and sub-commands =============================================================================== .. module:: argparse @@ -141,33 +141,33 @@ as keyword arguments. Each parameter has its own more detailed description below, but in short they are: - * prog_ - The name of the program (default: ``sys.argv[0]``) + * prog_---The name of the program (default: ``sys.argv[0]``) - * usage_ - The string describing the program usage (default: generated from + * usage_---The string describing the program usage (default: generated from arguments added to parser) - * description_ - Text to display before the argument help (default: none) + * description_---Text to display before the argument help (default: none) - * epilog_ - Text to display after the argument help (default: none) + * epilog_---Text to display after the argument help (default: none) - * parents_ - A list of :class:`ArgumentParser` objects whose arguments should + * parents_---A list of :class:`ArgumentParser` objects whose arguments should also be included - * formatter_class_ - A class for customizing the help output + * formatter_class_---A class for customizing the help output - * prefix_chars_ - The set of characters that prefix optional arguments + * prefix_chars_---The set of characters that prefix optional arguments (default: '-') - * fromfile_prefix_chars_ - The set of characters that prefix files from + * fromfile_prefix_chars_---The set of characters that prefix files from which additional arguments should be read (default: ``None``) - * argument_default_ - The global default value for arguments + * argument_default_---The global default value for arguments (default: ``None``) - * conflict_handler_ - The strategy for resolving conflicting optionals + * conflict_handler_---The strategy for resolving conflicting optionals (usually unnecessary) - * add_help_ - Add a -h/--help option to the parser (default: ``True``) + * add_help_---Add a -h/--help option to the parser (default: ``True``) The following sections describe how each of these are used. @@ -614,31 +614,31 @@ Define how a single command-line argument should be parsed. Each parameter has its own more detailed description below, but in short they are: - * `name or flags`_ - Either a name or a list of option strings, e.g. ``foo`` + * `name or flags`_---Either a name or a list of option strings, e.g. ``foo`` or ``-f, --foo``. - * action_ - The basic type of action to be taken when this argument is + * action_---The basic type of action to be taken when this argument is encountered at the command line. - * nargs_ - The number of command-line arguments that should be consumed. + * nargs_---The number of command-line arguments that should be consumed. - * const_ - A constant value required by some action_ and nargs_ selections. + * const_---A constant value required by some action_ and nargs_ selections. - * default_ - The value produced if the argument is absent from the + * default_---The value produced if the argument is absent from the command line. - * type_ - The type to which the command-line argument should be converted. + * type_---The type to which the command-line argument should be converted. - * choices_ - A container of the allowable values for the argument. + * choices_---A container of the allowable values for the argument. - * required_ - Whether or not the command-line option may be omitted + * required_---Whether or not the command-line option may be omitted (optionals only). - * help_ - A brief description of what the argument does. + * help_---A brief description of what the argument does. - * metavar_ - A name for the argument in usage messages. + * metavar_---A name for the argument in usage messages. - * dest_ - The name of the attribute to be added to the object returned by + * dest_---The name of the attribute to be added to the object returned by :meth:`parse_args`. The following sections describe how each of these are used. @@ -685,7 +685,7 @@ :meth:`~ArgumentParser.parse_args`. The ``action`` keyword argument specifies how the command-line arguments should be handled. The supported actions are: -* ``'store'`` - This just stores the argument's value. This is the default +* ``'store'``\ ---This just stores the argument's value. This is the default action. For example:: >>> parser = argparse.ArgumentParser() @@ -693,7 +693,7 @@ >>> parser.parse_args('--foo 1'.split()) Namespace(foo='1') -* ``'store_const'`` - This stores the value specified by the const_ keyword +* ``'store_const'``\ ---This stores the value specified by the const_ keyword argument. (Note that the const_ keyword argument defaults to the rather unhelpful ``None``.) The ``'store_const'`` action is most commonly used with optional arguments that specify some sort of flag. For example:: @@ -703,7 +703,7 @@ >>> parser.parse_args('--foo'.split()) Namespace(foo=42) -* ``'store_true'`` and ``'store_false'`` - These store the values ``True`` and +* ``'store_true'`` and ``'store_false'``\ ---These store the values ``True`` and ``False`` respectively. These are special cases of ``'store_const'``. For example:: @@ -713,7 +713,7 @@ >>> parser.parse_args('--foo --bar'.split()) Namespace(bar=False, foo=True) -* ``'append'`` - This stores a list, and appends each argument value to the +* ``'append'``\ ---This stores a list, and appends each argument value to the list. This is useful to allow an option to be specified multiple times. Example usage:: @@ -722,7 +722,7 @@ >>> parser.parse_args('--foo 1 --foo 2'.split()) Namespace(foo=['1', '2']) -* ``'append_const'`` - This stores a list, and appends the value specified by +* ``'append_const'``\ ---This stores a list, and appends the value specified by the const_ keyword argument to the list. (Note that the const_ keyword argument defaults to ``None``.) The ``'append_const'`` action is typically useful when multiple arguments need to store constants to the same list. For @@ -734,7 +734,7 @@ >>> parser.parse_args('--str --int'.split()) Namespace(types=[, ]) -* ``'count'`` - This counts the number of times a keyword argument occurs. For +* ``'count'``\ ---This counts the number of times a keyword argument occurs. For example, this is useful for increasing verbosity levels:: >>> parser = argparse.ArgumentParser() @@ -742,12 +742,12 @@ >>> parser.parse_args('-vvv'.split()) Namespace(verbose=3) -* ``'help'`` - This prints a complete help message for all the options in the +* ``'help'``\ ---This prints a complete help message for all the options in the current parser and then exits. By default a help action is automatically added to the parser. See :class:`ArgumentParser` for details of how the output is created. -* ``'version'`` - This expects a ``version=`` keyword argument in the +* ``'version'``\ ---This expects a ``version=`` keyword argument in the :meth:`~ArgumentParser.add_argument` call, and prints version information and exits when invoked:: @@ -762,17 +762,17 @@ :class:`argparse.Action`, supplying an appropriate ``__call__`` method. The ``__call__`` method should accept four parameters: -* ``parser`` - The ArgumentParser object which contains this action. +* ``parser``\ ---The ArgumentParser object which contains this action. -* ``namespace`` - The :class:`Namespace` object that will be returned by +* ``namespace``\ ---The :class:`Namespace` object that will be returned by :meth:`~ArgumentParser.parse_args`. Most actions add an attribute to this object. -* ``values`` - The associated command-line arguments, with any type conversions +* ``values``\ ---The associated command-line arguments, with any type conversions applied. (Type conversions are specified with the type_ keyword argument to :meth:`~ArgumentParser.add_argument`.) -* ``option_string`` - The option string that was used to invoke this action. +* ``option_string``\ ---The option string that was used to invoke this action. The ``option_string`` argument is optional, and will be absent if the action is associated with a positional argument. @@ -816,7 +816,7 @@ * ``'?'``. One argument will be consumed from the command line if possible, and produced as a single item. If no command-line argument is present, the value from default_ will be produced. Note that for optional arguments, there is an - additional case - the option string is present but not followed by a + additional case---the option string is present but not followed by a command-line argument. In this case the value from const_ will be produced. Some examples to illustrate this:: @@ -1179,7 +1179,7 @@ -h, --help show this help message and exit --foo YYY -Note that ``metavar`` only changes the *displayed* name - the name of the +Note that ``metavar`` only changes the *displayed* name---the name of the attribute on the :meth:`~ArgumentParser.parse_args` object is still determined by the dest_ value. diff -r afe119a3619f Doc/library/array.rst --- a/Doc/library/array.rst +++ b/Doc/library/array.rst @@ -1,4 +1,4 @@ -:mod:`array` --- Efficient arrays of numeric values +:mod:`array`\ ---Efficient arrays of numeric values =================================================== .. module:: array diff -r afe119a3619f Doc/library/ast.rst --- a/Doc/library/ast.rst +++ b/Doc/library/ast.rst @@ -1,4 +1,4 @@ -:mod:`ast` --- Abstract Syntax Trees +:mod:`ast`\ ---Abstract Syntax Trees ==================================== .. module:: ast diff -r afe119a3619f Doc/library/asynchat.rst --- a/Doc/library/asynchat.rst +++ b/Doc/library/asynchat.rst @@ -1,4 +1,4 @@ -:mod:`asynchat` --- Asynchronous socket command/response handler +:mod:`asynchat`\ ---Asynchronous socket command/response handler ================================================================ .. module:: asynchat @@ -142,7 +142,7 @@ by the channel after :meth:`found_terminator` is called. -asynchat - Auxiliary Classes +asynchat---Auxiliary Classes ------------------------------------------ .. class:: fifo(list=None) diff -r afe119a3619f Doc/library/asyncore.rst --- a/Doc/library/asyncore.rst +++ b/Doc/library/asyncore.rst @@ -1,4 +1,4 @@ -:mod:`asyncore` --- Asynchronous socket handler +:mod:`asyncore`\ ---Asynchronous socket handler =============================================== .. module:: asyncore @@ -221,7 +221,7 @@ .. method:: bind(address) Bind the socket to *address*. The socket must not already be bound. (The - format of *address* depends on the address family --- refer to the + format of *address* depends on the address family---refer to the :mod:`socket` documentation for more information.) To mark the socket as re-usable (setting the :const:`SO_REUSEADDR` option), call the :class:`dispatcher` object's :meth:`set_reuse_addr` method. diff -r afe119a3619f Doc/library/atexit.rst --- a/Doc/library/atexit.rst +++ b/Doc/library/atexit.rst @@ -1,4 +1,4 @@ -:mod:`atexit` --- Exit handlers +:mod:`atexit`\ ---Exit handlers =============================== .. module:: atexit diff -r afe119a3619f Doc/library/audioop.rst --- a/Doc/library/audioop.rst +++ b/Doc/library/audioop.rst @@ -1,4 +1,4 @@ -:mod:`audioop` --- Manipulate raw audio data +:mod:`audioop`\ ---Manipulate raw audio data ============================================ .. module:: audioop diff -r afe119a3619f Doc/library/base64.rst --- a/Doc/library/base64.rst +++ b/Doc/library/base64.rst @@ -1,4 +1,4 @@ -:mod:`base64` --- RFC 3548: Base16, Base32, Base64 Data Encodings +:mod:`base64`\ ---RFC 3548: Base16, Base32, Base64 Data Encodings ================================================================= .. module:: base64 @@ -183,7 +183,7 @@ Module :mod:`binascii` Support module containing ASCII-to-binary and binary-to-ASCII conversions. - :rfc:`1521` - MIME (Multipurpose Internet Mail Extensions) Part One: Mechanisms for Specifying and Describing the Format of Internet Message Bodies + :rfc:`1521`\ ---MIME (Multipurpose Internet Mail Extensions) Part One: Mechanisms for Specifying and Describing the Format of Internet Message Bodies Section 5.2, "Base64 Content-Transfer-Encoding," provides the definition of the base64 encoding. diff -r afe119a3619f Doc/library/bdb.rst --- a/Doc/library/bdb.rst +++ b/Doc/library/bdb.rst @@ -1,4 +1,4 @@ -:mod:`bdb` --- Debugger framework +:mod:`bdb`\ ---Debugger framework ================================= .. module:: bdb diff -r afe119a3619f Doc/library/binascii.rst --- a/Doc/library/binascii.rst +++ b/Doc/library/binascii.rst @@ -1,4 +1,4 @@ -:mod:`binascii` --- Convert between binary and ASCII +:mod:`binascii`\ ---Convert between binary and ASCII ==================================================== .. module:: binascii diff -r afe119a3619f Doc/library/binhex.rst --- a/Doc/library/binhex.rst +++ b/Doc/library/binhex.rst @@ -1,4 +1,4 @@ -:mod:`binhex` --- Encode and decode binhex4 files +:mod:`binhex`\ ---Encode and decode binhex4 files ================================================= .. module:: binhex diff -r afe119a3619f Doc/library/bisect.rst --- a/Doc/library/bisect.rst +++ b/Doc/library/bisect.rst @@ -1,4 +1,4 @@ -:mod:`bisect` --- Array bisection algorithm +:mod:`bisect`\ ---Array bisection algorithm =========================================== .. module:: bisect diff -r afe119a3619f Doc/library/builtins.rst --- a/Doc/library/builtins.rst +++ b/Doc/library/builtins.rst @@ -1,4 +1,4 @@ -:mod:`builtins` --- Built-in objects +:mod:`builtins`\ ---Built-in objects ==================================== .. module:: builtins diff -r afe119a3619f Doc/library/bz2.rst --- a/Doc/library/bz2.rst +++ b/Doc/library/bz2.rst @@ -1,4 +1,4 @@ -:mod:`bz2` --- Support for :program:`bzip2` compression +:mod:`bz2`\ ---Support for :program:`bzip2` compression ======================================================= .. module:: bz2 diff -r afe119a3619f Doc/library/calendar.rst --- a/Doc/library/calendar.rst +++ b/Doc/library/calendar.rst @@ -1,4 +1,4 @@ -:mod:`calendar` --- General calendar-related functions +:mod:`calendar`\ ---General calendar-related functions ====================================================== .. module:: calendar diff -r afe119a3619f Doc/library/cgi.rst --- a/Doc/library/cgi.rst +++ b/Doc/library/cgi.rst @@ -1,4 +1,4 @@ -:mod:`cgi` --- Common Gateway Interface support +:mod:`cgi`\ ---Common Gateway Interface support =============================================== .. module:: cgi @@ -181,7 +181,7 @@ :class:`FieldStorage` class. This section describes a higher level interface which was added to this class to allow one to do it in a more readable and intuitive way. The interface doesn't make the techniques described in previous -sections obsolete --- they are still useful to process file uploads efficiently, +sections obsolete---they are still useful to process file uploads efficiently, for example. .. XXX: Is this true ? @@ -287,10 +287,10 @@ Returns a dictionary just like :func:`urllib.parse.parse_qs` keys are the field names, each value is a list of values for that field. This is easy to use but not much good - if you are expecting megabytes to be uploaded --- in that case, use the + if you are expecting megabytes to be uploaded---in that case, use the :class:`FieldStorage` class instead which is much more flexible. - Note that this does not parse nested multipart parts --- use + Note that this does not parse nested multipart parts---use :class:`FieldStorage` for that. @@ -377,7 +377,7 @@ Make sure the Python interpreter exists and is executable by "others". Make sure that any files your script needs to read or write are readable or -writable, respectively, by "others" --- their mode should be ``0o644`` for +writable, respectively, by "others"\ ---their mode should be ``0o644`` for readable and ``0o666`` for writable. This is because, for security reasons, the HTTP server executes your script as user "nobody", without any special privileges. It can only read (write, execute) files that everybody can read @@ -420,7 +420,7 @@ .. index:: pair: CGI; debugging -First of all, check for trivial installation errors --- reading the section +First of all, check for trivial installation errors---reading the section above on installing your CGI script carefully can save you a lot of time. If you wonder whether you have understood the installation procedure correctly, try installing a copy of this module file (:file:`cgi.py`) as a CGI script. When @@ -431,7 +431,7 @@ http://yourhostname/cgi-bin/cgi.py?name=Joe+Blow&addr=At+Home -If this gives an error of type 404, the server cannot find the script -- perhaps +If this gives an error of type 404, the server cannot find the script---perhaps you need to install it in a different directory. If it gives another error, there's an installation problem that you should fix before trying to go any further. If you get a nicely formatted listing of the environment and form @@ -502,7 +502,7 @@ cgitb.enable()`` to the top of the script. * When invoking external programs, make sure they can be found. Usually, this - means using absolute path names --- :envvar:`PATH` is usually not set to a very + means using absolute path names---\ :envvar:`PATH` is usually not set to a very useful value in a CGI script. * When reading or writing external files, make sure they can be read or written diff -r afe119a3619f Doc/library/cgitb.rst --- a/Doc/library/cgitb.rst +++ b/Doc/library/cgitb.rst @@ -1,4 +1,4 @@ -:mod:`cgitb` --- Traceback manager for CGI scripts +:mod:`cgitb`\ ---Traceback manager for CGI scripts ================================================== .. module:: cgitb diff -r afe119a3619f Doc/library/chunk.rst --- a/Doc/library/chunk.rst +++ b/Doc/library/chunk.rst @@ -1,4 +1,4 @@ -:mod:`chunk` --- Read IFF chunked data +:mod:`chunk`\ ---Read IFF chunked data ====================================== .. module:: chunk diff -r afe119a3619f Doc/library/cmath.rst --- a/Doc/library/cmath.rst +++ b/Doc/library/cmath.rst @@ -1,4 +1,4 @@ -:mod:`cmath` --- Mathematical functions for complex numbers +:mod:`cmath`\ ---Mathematical functions for complex numbers =========================================================== .. module:: cmath diff -r afe119a3619f Doc/library/cmd.rst --- a/Doc/library/cmd.rst +++ b/Doc/library/cmd.rst @@ -1,4 +1,4 @@ -:mod:`cmd` --- Support for line-oriented command interpreters +:mod:`cmd`\ ---Support for line-oriented command interpreters ============================================================= .. module:: cmd diff -r afe119a3619f Doc/library/code.rst --- a/Doc/library/code.rst +++ b/Doc/library/code.rst @@ -1,4 +1,4 @@ -:mod:`code` --- Interpreter base classes +:mod:`code`\ ---Interpreter base classes ======================================== .. module:: code @@ -136,7 +136,7 @@ specify the banner to print before the first interaction; by default it prints a banner similar to the one printed by the standard Python interpreter, followed by the class name of the console object in parentheses (so as not to confuse - this with the real interpreter -- since it's so close!). + this with the real interpreter---since it's so close!). .. method:: InteractiveConsole.push(line) diff -r afe119a3619f Doc/library/codecs.rst --- a/Doc/library/codecs.rst +++ b/Doc/library/codecs.rst @@ -1,4 +1,4 @@ -:mod:`codecs` --- Codec registry and base classes +:mod:`codecs`\ ---Codec registry and base classes ================================================= .. module:: codecs @@ -394,7 +394,7 @@ character set encoding to a string object. *input* must be a bytes object or one which provides the read-only character - buffer interface -- for example, buffer objects and memory mapped files. + buffer interface---for example, buffer objects and memory mapped files. *errors* defines the error handling to apply. It defaults to ``'strict'`` handling. @@ -756,7 +756,7 @@ StreamRecoder Objects ^^^^^^^^^^^^^^^^^^^^^ -The :class:`StreamRecoder` provide a frontend - backend view of encoding data +The :class:`StreamRecoder` provide a frontend---backend view of encoding data which is sometimes useful when dealing with different encoding environments. The design is such that one can use the factory functions returned by the @@ -1255,7 +1255,7 @@ bytes-to-bytes and str-to-str codecs. -:mod:`encodings.idna` --- Internationalized Domain Names in Applications +:mod:`encodings.idna`\ ---Internationalized Domain Names in Applications ------------------------------------------------------------------------ .. module:: encodings.idna @@ -1320,7 +1320,7 @@ Convert a label to Unicode, as specified in :rfc:`3490`. -:mod:`encodings.mbcs` --- Windows ANSI codepage +:mod:`encodings.mbcs`\ ---Windows ANSI codepage ----------------------------------------------- .. module:: encodings.mbcs @@ -1338,7 +1338,7 @@ to encode, and ``'ignore'`` to decode. -:mod:`encodings.utf_8_sig` --- UTF-8 codec with BOM signature +:mod:`encodings.utf_8_sig`\ ---UTF-8 codec with BOM signature ------------------------------------------------------------- .. module:: encodings.utf_8_sig diff -r afe119a3619f Doc/library/codeop.rst --- a/Doc/library/codeop.rst +++ b/Doc/library/codeop.rst @@ -1,4 +1,4 @@ -:mod:`codeop` --- Compile Python code +:mod:`codeop`\ ---Compile Python code ===================================== .. module:: codeop diff -r afe119a3619f Doc/library/collections.abc.rst --- a/Doc/library/collections.abc.rst +++ b/Doc/library/collections.abc.rst @@ -1,4 +1,4 @@ -:mod:`collections.abc` --- Abstract Base Classes for Containers +:mod:`collections.abc`\ ---Abstract Base Classes for Containers =============================================================== .. module:: collections.abc diff -r afe119a3619f Doc/library/collections.rst --- a/Doc/library/collections.rst +++ b/Doc/library/collections.rst @@ -1,4 +1,4 @@ -:mod:`collections` --- Container datatypes +:mod:`collections`\ ---Container datatypes ========================================== .. module:: collections diff -r afe119a3619f Doc/library/colorsys.rst --- a/Doc/library/colorsys.rst +++ b/Doc/library/colorsys.rst @@ -1,4 +1,4 @@ -:mod:`colorsys` --- Conversions between color systems +:mod:`colorsys`\ ---Conversions between color systems ===================================================== .. module:: colorsys diff -r afe119a3619f Doc/library/compileall.rst --- a/Doc/library/compileall.rst +++ b/Doc/library/compileall.rst @@ -1,4 +1,4 @@ -:mod:`compileall` --- Byte-compile Python libraries +:mod:`compileall`\ ---Byte-compile Python libraries =================================================== .. module:: compileall diff -r afe119a3619f Doc/library/concurrent.futures.rst --- a/Doc/library/concurrent.futures.rst +++ b/Doc/library/concurrent.futures.rst @@ -1,4 +1,4 @@ -:mod:`concurrent.futures` --- Launching parallel tasks +:mod:`concurrent.futures`\ ---Launching parallel tasks ====================================================== .. module:: concurrent.futures @@ -379,7 +379,7 @@ .. seealso:: - :pep:`3148` -- futures - execute computations asynchronously + :pep:`3148`\ ---futures---execute computations asynchronously The proposal which described this feature for inclusion in the Python standard library. diff -r afe119a3619f Doc/library/concurrent.rst --- a/Doc/library/concurrent.rst +++ b/Doc/library/concurrent.rst @@ -3,4 +3,4 @@ Currently, there is only one module in this package: -* :mod:`concurrent.futures` -- Launching parallel tasks +* :mod:`concurrent.futures`\ ---Launching parallel tasks diff -r afe119a3619f Doc/library/configparser.rst --- a/Doc/library/configparser.rst +++ b/Doc/library/configparser.rst @@ -1,4 +1,4 @@ -:mod:`configparser` --- Configuration file parser +:mod:`configparser`\ ---Configuration file parser ================================================= .. module:: configparser @@ -397,7 +397,7 @@ * ``parser.popitem()`` never returns it. -* ``parser.get(section, option, **kwargs)`` - the second argument is **not** +* ``parser.get(section, option, **kwargs)``\ ---the second argument is **not** a fallback value. Note however that the section-level ``get()`` methods are compatible both with the mapping protocol and the classic configparser API. diff -r afe119a3619f Doc/library/contextlib.rst --- a/Doc/library/contextlib.rst +++ b/Doc/library/contextlib.rst @@ -1,4 +1,4 @@ -:mod:`contextlib` --- Utilities for :keyword:`with`\ -statement contexts +:mod:`contextlib`\ ---Utilities for :keyword:`with`\ -statement contexts ======================================================================== .. module:: contextlib @@ -218,7 +218,7 @@ Since registered callbacks are invoked in the reverse order of registration, this ends up behaving as if multiple nested :keyword:`with` statements had been used with the registered set of callbacks. This even - extends to exception handling - if an inner callback suppresses or replaces + extends to exception handling---if an inner callback suppresses or replaces an exception, then outer callbacks will be passed arguments based on that updated state. @@ -270,7 +270,7 @@ .. method:: pop_all() Transfers the callback stack to a fresh :class:`ExitStack` instance - and returns it. No callbacks are invoked by this operation - instead, + and returns it. No callbacks are invoked by this operation---instead, they will now be invoked when the new stack is closed (either explicitly or implicitly at the end of a :keyword:`with` statement). @@ -536,7 +536,7 @@ .. seealso:: - :pep:`0343` - The "with" statement + :pep:`0343`\ ---The "with" statement The specification, background, and examples for the Python :keyword:`with` statement. diff -r afe119a3619f Doc/library/copy.rst --- a/Doc/library/copy.rst +++ b/Doc/library/copy.rst @@ -1,4 +1,4 @@ -:mod:`copy` --- Shallow and deep copy operations +:mod:`copy`\ ---Shallow and deep copy operations ================================================ .. module:: copy diff -r afe119a3619f Doc/library/copyreg.rst --- a/Doc/library/copyreg.rst +++ b/Doc/library/copyreg.rst @@ -1,4 +1,4 @@ -:mod:`copyreg` --- Register :mod:`pickle` support functions +:mod:`copyreg`\ ---Register :mod:`pickle` support functions =========================================================== .. module:: copyreg diff -r afe119a3619f Doc/library/crypt.rst --- a/Doc/library/crypt.rst +++ b/Doc/library/crypt.rst @@ -1,4 +1,4 @@ -:mod:`crypt` --- Function to check Unix passwords +:mod:`crypt`\ ---Function to check Unix passwords ================================================= .. module:: crypt diff -r afe119a3619f Doc/library/csv.rst --- a/Doc/library/csv.rst +++ b/Doc/library/csv.rst @@ -1,4 +1,4 @@ -:mod:`csv` --- CSV File Reading and Writing +:mod:`csv`\ ---CSV File Reading and Writing =========================================== .. module:: csv @@ -34,7 +34,7 @@ .. seealso:: - :pep:`305` - CSV File API + :pep:`305`\ ---CSV File API The Python Enhancement Proposal which proposed this addition to Python. @@ -53,7 +53,7 @@ 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 --- :term:`file objects + string each time its :meth:`!__next__` method is called---\ :term:`file objects ` and list objects are both suitable. If *csvfile* is a file object, it should be opened with ``newline=''``. [1]_ An optional *dialect* parameter can be given which is used to define a set of parameters @@ -471,7 +471,7 @@ with open('passwd', newline='') as f: reader = csv.reader(f, 'unixpwd') -A slightly more advanced use of the reader --- catching and reporting errors:: +A slightly more advanced use of the reader---catching and reporting errors:: import csv, sys filename = 'some.csv' diff -r afe119a3619f Doc/library/ctypes.rst --- a/Doc/library/ctypes.rst +++ b/Doc/library/ctypes.rst @@ -1,4 +1,4 @@ -:mod:`ctypes` --- A foreign function library for Python +:mod:`ctypes`\ ---A foreign function library for Python ======================================================= .. module:: ctypes @@ -2393,6 +2393,6 @@ Arrays and pointers ^^^^^^^^^^^^^^^^^^^ -Not yet written - please see the sections :ref:`ctypes-pointers` and section +Not yet written---please see the sections :ref:`ctypes-pointers` and section :ref:`ctypes-arrays` in the tutorial. diff -r afe119a3619f Doc/library/curses.ascii.rst --- a/Doc/library/curses.ascii.rst +++ b/Doc/library/curses.ascii.rst @@ -1,4 +1,4 @@ -:mod:`curses.ascii` --- Utilities for ASCII characters +:mod:`curses.ascii`\ ---Utilities for ASCII characters ====================================================== .. module:: curses.ascii diff -r afe119a3619f Doc/library/curses.panel.rst --- a/Doc/library/curses.panel.rst +++ b/Doc/library/curses.panel.rst @@ -1,4 +1,4 @@ -:mod:`curses.panel` --- A panel stack extension for curses +:mod:`curses.panel`\ ---A panel stack extension for curses ========================================================== .. module:: curses.panel diff -r afe119a3619f Doc/library/curses.rst --- a/Doc/library/curses.rst +++ b/Doc/library/curses.rst @@ -1,4 +1,4 @@ -:mod:`curses` --- Terminal handling for character-cell displays +:mod:`curses`\ ---Terminal handling for character-cell displays =============================================================== .. module:: curses @@ -1628,7 +1628,7 @@ +-------------------+----------------------------+ -:mod:`curses.textpad` --- Text input widget for curses programs +:mod:`curses.textpad`\ ---Text input widget for curses programs =============================================================== .. module:: curses.textpad diff -r afe119a3619f Doc/library/datetime.rst --- a/Doc/library/datetime.rst +++ b/Doc/library/datetime.rst @@ -1,4 +1,4 @@ -:mod:`datetime` --- Basic date and time types +:mod:`datetime`\ ---Basic date and time types ============================================= .. module:: datetime diff -r afe119a3619f Doc/library/dbm.rst --- a/Doc/library/dbm.rst +++ b/Doc/library/dbm.rst @@ -1,4 +1,4 @@ -:mod:`dbm` --- Interfaces to Unix "databases" +:mod:`dbm`\ ---Interfaces to Unix "databases" ============================================= .. module:: dbm @@ -15,13 +15,13 @@ A tuple containing the exceptions that can be raised by each of the supported modules, with a unique exception also named :exc:`dbm.error` as the first - item --- the latter is used when :exc:`dbm.error` is raised. + item---the latter is used when :exc:`dbm.error` is raised. .. function:: whichdb(filename) This function attempts to guess which of the several simple database modules - available --- :mod:`dbm.gnu`, :mod:`dbm.ndbm` or :mod:`dbm.dumb` --- should + available---\ :mod:`dbm.gnu`, :mod:`dbm.ndbm` or :mod:`dbm.dumb`\ ---should be used to open a given file. Returns one of the following values: ``None`` if the file can't be opened @@ -111,7 +111,7 @@ The individual submodules are described in the following sections. -:mod:`dbm.gnu` --- GNU's reinterpretation of dbm +:mod:`dbm.gnu`\ ---GNU's reinterpretation of dbm ------------------------------------------------ .. module:: dbm.gnu @@ -217,7 +217,7 @@ unwritten data to be written to the disk. -:mod:`dbm.ndbm` --- Interface based on ndbm +:mod:`dbm.ndbm`\ ---Interface based on ndbm ------------------------------------------- .. module:: dbm.ndbm @@ -274,7 +274,7 @@ -:mod:`dbm.dumb` --- Portable DBM implementation +:mod:`dbm.dumb`\ ---Portable DBM implementation ----------------------------------------------- .. module:: dbm.dumb diff -r afe119a3619f Doc/library/decimal.rst --- a/Doc/library/decimal.rst +++ b/Doc/library/decimal.rst @@ -1,4 +1,4 @@ -:mod:`decimal` --- Decimal fixed point and floating point arithmetic +:mod:`decimal`\ ---Decimal fixed point and floating point arithmetic ==================================================================== .. module:: decimal @@ -26,9 +26,9 @@ :class:`float` datatype: * Decimal "is based on a floating-point model which was designed with people - in mind, and necessarily has a paramount guiding principle -- computers must + in mind, and necessarily has a paramount guiding principle---computers must provide an arithmetic that works in the same way as the arithmetic that - people learn at school." -- excerpt from the decimal arithmetic specification. + people learn at school."\ ---excerpt from the decimal arithmetic specification. * Decimal numbers can be represented exactly. In contrast, numbers like :const:`1.1` and :const:`2.2` do not have exact representations in binary @@ -70,7 +70,7 @@ * The decimal module was designed to support "without prejudice, both exact unrounded decimal arithmetic (sometimes called fixed-point arithmetic) - and rounded floating-point arithmetic." -- excerpt from the decimal + and rounded floating-point arithmetic."\ ---excerpt from the decimal arithmetic specification. The module design is centered around three concepts: the decimal number, the @@ -1710,7 +1710,7 @@ ``0/0`` returns :const:`NaN` which means "not a number". This variety of :const:`NaN` is quiet and, once created, will flow through other computations always resulting in another :const:`NaN`. This behavior can be useful for a -series of computations that occasionally have missing inputs --- it allows the +series of computations that occasionally have missing inputs---it allows the calculation to proceed while flagging specific results as invalid. A variant is :const:`sNaN` which signals rather than remaining quiet after every diff -r afe119a3619f Doc/library/difflib.rst --- a/Doc/library/difflib.rst +++ b/Doc/library/difflib.rst @@ -1,4 +1,4 @@ -:mod:`difflib` --- Helpers for computing deltas +:mod:`difflib`\ ---Helpers for computing deltas =============================================== .. module:: difflib @@ -214,10 +214,10 @@ *linejunk*: A function that accepts a single string argument, and returns true if the string is junk, or false if not. The default is ``None``. There is also a module-level function :func:`IS_LINE_JUNK`, which filters out lines - without visible characters, except for at most one pound character (``'#'``) - -- however the underlying :class:`SequenceMatcher` class does a dynamic - analysis of which lines are so frequent as to constitute noise, and this - usually works better than using this function. + without visible characters, except for at most one pound character + (``'#'``)\ ---however the underlying :class:`SequenceMatcher` class does a + dynamic analysis of which lines are so frequent as to constitute noise, and + this usually works better than using this function. *charjunk*: A function that accepts a character (a string of length 1), and returns if the character is junk, or false if not. The default is module-level diff -r afe119a3619f Doc/library/dis.rst --- a/Doc/library/dis.rst +++ b/Doc/library/dis.rst @@ -1,4 +1,4 @@ -:mod:`dis` --- Disassembler for Python bytecode +:mod:`dis`\ ---Disassembler for Python bytecode =============================================== .. module:: dis diff -r afe119a3619f Doc/library/distutils.rst --- a/Doc/library/distutils.rst +++ b/Doc/library/distutils.rst @@ -1,4 +1,4 @@ -:mod:`distutils` --- Building and installing Python modules +:mod:`distutils`\ ---Building and installing Python modules =========================================================== .. module:: distutils diff -r afe119a3619f Doc/library/doctest.rst --- a/Doc/library/doctest.rst +++ b/Doc/library/doctest.rst @@ -1,6 +1,6 @@ :keepdoctest: -:mod:`doctest` --- Test interactive Python examples +:mod:`doctest`\ ---Test interactive Python examples =================================================== .. module:: doctest diff -r afe119a3619f Doc/library/dummy_threading.rst --- a/Doc/library/dummy_threading.rst +++ b/Doc/library/dummy_threading.rst @@ -1,4 +1,4 @@ -:mod:`dummy_threading` --- Drop-in replacement for the :mod:`threading` module +:mod:`dummy_threading`\ ---Drop-in replacement for the :mod:`threading` module ============================================================================== .. module:: dummy_threading diff -r afe119a3619f Doc/library/email.errors.rst --- a/Doc/library/email.errors.rst +++ b/Doc/library/email.errors.rst @@ -67,44 +67,44 @@ All defect classes are subclassed from :class:`email.errors.MessageDefect`, but this class is *not* an exception! -* :class:`NoBoundaryInMultipartDefect` -- A message claimed to be a multipart, +* :class:`NoBoundaryInMultipartDefect`\ ---A message claimed to be a multipart, but had no :mimetype:`boundary` parameter. -* :class:`StartBoundaryNotFoundDefect` -- The start boundary claimed in the +* :class:`StartBoundaryNotFoundDefect`\ ---The start boundary claimed in the :mailheader:`Content-Type` header was never found. -* :class:`CloseBoundaryNotFoundDefect` -- A start boundary was found, but +* :class:`CloseBoundaryNotFoundDefect`\ ---A start boundary was found, but no corresponding close boundary was ever found. .. versionadded:: 3.3 -* :class:`FirstHeaderLineIsContinuationDefect` -- The message had a continuation +* :class:`FirstHeaderLineIsContinuationDefect`\ ---The message had a continuation line as its first header line. -* :class:`MisplacedEnvelopeHeaderDefect` - A "Unix From" header was found in the +* :class:`MisplacedEnvelopeHeaderDefect`\ ---A "Unix From" header was found in the middle of a header block. -* :class:`MissingHeaderBodySeparatorDefect` - A line was found while parsing +* :class:`MissingHeaderBodySeparatorDefect`\ ---A line was found while parsing headers that had no leading white space but contained no ':'. Parsing continues assuming that the line represents the first line of the body. .. versionadded:: 3.3 -* :class:`MalformedHeaderDefect` -- A header was found that was missing a colon, +* :class:`MalformedHeaderDefect`\ ---A header was found that was missing a colon, or was otherwise malformed. .. deprecated:: 3.3 This defect has not been used for several Python versions. -* :class:`MultipartInvariantViolationDefect` -- A message claimed to be a +* :class:`MultipartInvariantViolationDefect`\ ---A message claimed to be a :mimetype:`multipart`, but no subparts were found. Note that when a message has this defect, its :meth:`is_multipart` method may return false even though its content type claims to be :mimetype:`multipart`. -* :class:`InvalidBase64PaddingDefect` -- When decoding a block of base64 +* :class:`InvalidBase64PaddingDefect`\ ---When decoding a block of base64 enocded bytes, the padding was not correct. Enough padding is added to perform the decode, but the resulting decoded bytes may be invalid. -* :class:`InvalidBase64CharactersDefect` -- When decoding a block of base64 +* :class:`InvalidBase64CharactersDefect`\ ---When decoding a block of base64 enocded bytes, characters outside the base64 alphebet were encountered. The characters are ignored, but the resulting decoded bytes may be invalid. diff -r afe119a3619f Doc/library/email.generator.rst --- a/Doc/library/email.generator.rst +++ b/Doc/library/email.generator.rst @@ -208,17 +208,17 @@ string that is used instead of the message payload. *fmt* is expanded with the following keywords, ``%(keyword)s`` format: - * ``type`` -- Full MIME type of the non-\ :mimetype:`text` part + * ``type``\ ---Full MIME type of the non-\ :mimetype:`text` part - * ``maintype`` -- Main MIME type of the non-\ :mimetype:`text` part + * ``maintype``\ ---Main MIME type of the non-\ :mimetype:`text` part - * ``subtype`` -- Sub-MIME type of the non-\ :mimetype:`text` part + * ``subtype``\ ---Sub-MIME type of the non-\ :mimetype:`text` part - * ``filename`` -- Filename of the non-\ :mimetype:`text` part + * ``filename``\ ---Filename of the non-\ :mimetype:`text` part - * ``description`` -- Description associated with the non-\ :mimetype:`text` part + * ``description``\ ---Description associated with the non-\ :mimetype:`text` part - * ``encoding`` -- Content transfer encoding of the non-\ :mimetype:`text` part + * ``encoding``\ ---Content transfer encoding of the non-\ :mimetype:`text` part The default value for *fmt* is ``None``, meaning :: diff -r afe119a3619f Doc/library/email.rst --- a/Doc/library/email.rst +++ b/Doc/library/email.rst @@ -1,4 +1,4 @@ -:mod:`email` --- An email and MIME handling package +:mod:`email`\ ---An email and MIME handling package =================================================== .. module:: email diff -r afe119a3619f Doc/library/email.util.rst --- a/Doc/library/email.util.rst +++ b/Doc/library/email.util.rst @@ -23,8 +23,8 @@ .. function:: parseaddr(address) - Parse address -- which should be the value of some address-containing field such - as :mailheader:`To` or :mailheader:`Cc` -- into its constituent *realname* and + Parse address---which should be the value of some address-containing field such + as :mailheader:`To` or :mailheader:`Cc`\ ---into its constituent *realname* and *email address* parts. Returns a tuple of that information, unless the parse fails, in which case a 2-tuple of ``('', '')`` is returned. diff -r afe119a3619f Doc/library/enum.rst --- a/Doc/library/enum.rst +++ b/Doc/library/enum.rst @@ -1,4 +1,4 @@ -:mod:`enum` --- Support for enumerations +:mod:`enum`\ ---Support for enumerations ======================================== .. module:: enum diff -r afe119a3619f Doc/library/errno.rst --- a/Doc/library/errno.rst +++ b/Doc/library/errno.rst @@ -1,4 +1,4 @@ -:mod:`errno` --- Standard errno system symbols +:mod:`errno`\ ---Standard errno system symbols ============================================== .. module:: errno diff -r afe119a3619f Doc/library/exceptions.rst --- a/Doc/library/exceptions.rst +++ b/Doc/library/exceptions.rst @@ -553,7 +553,7 @@ .. exception:: PermissionError Raised when trying to run an operation without the adequate access - rights - for example filesystem permissions. + rights---for example filesystem permissions. Corresponds to :c:data:`errno` ``EACCES`` and ``EPERM``. .. exception:: ProcessLookupError @@ -572,7 +572,7 @@ .. seealso:: - :pep:`3151` - Reworking the OS and IO exception hierarchy + :pep:`3151`\ ---Reworking the OS and IO exception hierarchy Warnings diff -r afe119a3619f Doc/library/faulthandler.rst --- a/Doc/library/faulthandler.rst +++ b/Doc/library/faulthandler.rst @@ -1,4 +1,4 @@ -:mod:`faulthandler` --- Dump the Python traceback +:mod:`faulthandler`\ ---Dump the Python traceback ================================================= .. module:: faulthandler diff -r afe119a3619f Doc/library/fcntl.rst --- a/Doc/library/fcntl.rst +++ b/Doc/library/fcntl.rst @@ -1,4 +1,4 @@ -:mod:`fcntl` --- The :func:`fcntl` and :func:`ioctl` system calls +:mod:`fcntl`\ ---The :func:`fcntl` and :func:`ioctl` system calls ================================================================= .. module:: fcntl @@ -65,7 +65,7 @@ the *mutate_flag* parameter. If it is false, the buffer's mutability is ignored and behaviour is as for a - read-only buffer, except that the 1024 byte limit mentioned above is avoided -- + read-only buffer, except that the 1024 byte limit mentioned above is avoided --- so long as the buffer you pass is as least as long as what the operating system wants to put there, things should work. @@ -105,9 +105,9 @@ the file descriptor of the file to lock or unlock, and *operation* is one of the following values: - * :const:`LOCK_UN` -- unlock - * :const:`LOCK_SH` -- acquire a shared lock - * :const:`LOCK_EX` -- acquire an exclusive lock + * :const:`LOCK_UN`\ ---unlock + * :const:`LOCK_SH`\ ---acquire a shared lock + * :const:`LOCK_EX`\ ---acquire an exclusive lock When *operation* is :const:`LOCK_SH` or :const:`LOCK_EX`, it can also be bitwise ORed with :const:`LOCK_NB` to avoid blocking on lock acquisition. @@ -122,9 +122,9 @@ lock starts, relative to *whence*, and *whence* is as with :func:`fileobj.seek`, specifically: - * :const:`0` -- relative to the start of the file (:const:`SEEK_SET`) - * :const:`1` -- relative to the current buffer position (:const:`SEEK_CUR`) - * :const:`2` -- relative to the end of the file (:const:`SEEK_END`) + * :const:`0`\ ---relative to the start of the file (:const:`SEEK_SET`) + * :const:`1`\ ---relative to the current buffer position (:const:`SEEK_CUR`) + * :const:`2`\ ---relative to the end of the file (:const:`SEEK_END`) The default for *start* is 0, which means to start at the beginning of the file. The default for *length* is 0 which means to lock to the end of the file. The @@ -142,7 +142,7 @@ Note that in the first example the return value variable *rv* will hold an integer value; in the second example it will hold a string value. The structure -lay-out for the *lockdata* variable is system dependent --- therefore using the +lay-out for the *lockdata* variable is system dependent---therefore using the :func:`flock` call may be better. diff -r afe119a3619f Doc/library/filecmp.rst --- a/Doc/library/filecmp.rst +++ b/Doc/library/filecmp.rst @@ -1,4 +1,4 @@ -:mod:`filecmp` --- File and Directory Comparisons +:mod:`filecmp`\ ---File and Directory Comparisons ================================================= .. module:: filecmp diff -r afe119a3619f Doc/library/fileinput.rst --- a/Doc/library/fileinput.rst +++ b/Doc/library/fileinput.rst @@ -1,4 +1,4 @@ -:mod:`fileinput` --- Iterate over lines from multiple input streams +:mod:`fileinput`\ ---Iterate over lines from multiple input streams =================================================================== .. module:: fileinput diff -r afe119a3619f Doc/library/fnmatch.rst --- a/Doc/library/fnmatch.rst +++ b/Doc/library/fnmatch.rst @@ -1,4 +1,4 @@ -:mod:`fnmatch` --- Unix filename pattern matching +:mod:`fnmatch`\ ---Unix filename pattern matching ================================================= .. module:: fnmatch diff -r afe119a3619f Doc/library/formatter.rst --- a/Doc/library/formatter.rst +++ b/Doc/library/formatter.rst @@ -1,4 +1,4 @@ -:mod:`formatter` --- Generic output formatting +:mod:`formatter`\ ---Generic output formatting ============================================== .. module:: formatter diff -r afe119a3619f Doc/library/fpectl.rst --- a/Doc/library/fpectl.rst +++ b/Doc/library/fpectl.rst @@ -1,4 +1,4 @@ -:mod:`fpectl` --- Floating point exception control +:mod:`fpectl`\ ---Floating point exception control ================================================== .. module:: fpectl diff -r afe119a3619f Doc/library/fractions.rst --- a/Doc/library/fractions.rst +++ b/Doc/library/fractions.rst @@ -1,4 +1,4 @@ -:mod:`fractions` --- Rational numbers +:mod:`fractions`\ ---Rational numbers ===================================== .. module:: fractions diff -r afe119a3619f Doc/library/ftplib.rst --- a/Doc/library/ftplib.rst +++ b/Doc/library/ftplib.rst @@ -1,4 +1,4 @@ -:mod:`ftplib` --- FTP protocol client +:mod:`ftplib`\ ---FTP protocol client ===================================== .. module:: ftplib @@ -80,7 +80,7 @@ Connect as usual to port 21 implicitly securing the FTP control connection before authenticating. Securing the data connection requires the user to explicitly ask for it by calling the :meth:`prot_p` method. - *keyfile* and *certfile* are optional -- they can contain a PEM formatted + *keyfile* and *certfile* are optional---they can contain a PEM formatted private key and certificate chain file name for the SSL connection. *context* parameter is a :class:`ssl.SSLContext` object which allows bundling SSL configuration options, certificates and private keys into a diff -r afe119a3619f Doc/library/functions.rst --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -131,7 +131,7 @@ Return a new "bytes" object, which is an immutable sequence of integers in the range ``0 <= x < 256``. :class:`bytes` is an immutable version of - :class:`bytearray` -- it has the same non-mutating methods and the same + :class:`bytearray`\ ---it has the same non-mutating methods and the same indexing and slicing behavior. Accordingly, constructor arguments are interpreted as for :func:`bytearray`. @@ -175,7 +175,7 @@ @classmethod def f(cls, arg1, arg2, ...): ... - The ``@classmethod`` form is a function :term:`decorator` -- see the description + The ``@classmethod`` form is a function :term:`decorator`\ ---see the description of function definitions in :ref:`function` for details. It can be called either on the class (such as ``C.f()``) or on an instance (such @@ -214,7 +214,7 @@ *flags* argument is given and *dont_inherit* is not (or is zero) then the future statements specified by the *flags* argument are used in addition to those that would be used anyway. If *dont_inherit* is a non-zero integer then - the *flags* argument is it -- the future statements in effect around the call + the *flags* argument is it---the future statements in effect around the call to compile are ignored. Future statements are specified by bits which can be bitwise ORed together to @@ -1260,7 +1260,7 @@ @staticmethod def f(arg1, arg2, ...): ... - The ``@staticmethod`` form is a function :term:`decorator` -- see the + The ``@staticmethod`` form is a function :term:`decorator`\ ---see the description of function definitions in :ref:`function` for details. It can be called either on the class (such as ``C.f()``) or on an instance (such diff -r afe119a3619f Doc/library/functools.rst --- a/Doc/library/functools.rst +++ b/Doc/library/functools.rst @@ -1,4 +1,4 @@ -:mod:`functools` --- Higher-order functions and operations on callable objects +:mod:`functools`\ ---Higher-order functions and operations on callable objects ============================================================================== .. module:: functools diff -r afe119a3619f Doc/library/gc.rst --- a/Doc/library/gc.rst +++ b/Doc/library/gc.rst @@ -1,4 +1,4 @@ -:mod:`gc` --- Garbage Collector interface +:mod:`gc`\ ---Garbage Collector interface ========================================= .. module:: gc diff -r afe119a3619f Doc/library/getopt.rst --- a/Doc/library/getopt.rst +++ b/Doc/library/getopt.rst @@ -1,4 +1,4 @@ -:mod:`getopt` --- C-style parser for command line options +:mod:`getopt`\ ---C-style parser for command line options ========================================================= .. module:: getopt diff -r afe119a3619f Doc/library/getpass.rst --- a/Doc/library/getpass.rst +++ b/Doc/library/getpass.rst @@ -1,4 +1,4 @@ -:mod:`getpass` --- Portable password input +:mod:`getpass`\ ---Portable password input ========================================== .. module:: getpass diff -r afe119a3619f Doc/library/gettext.rst --- a/Doc/library/gettext.rst +++ b/Doc/library/gettext.rst @@ -1,4 +1,4 @@ -:mod:`gettext` --- Multilingual internationalization services +:mod:`gettext`\ ---Multilingual internationalization services ============================================================= .. module:: gettext @@ -440,7 +440,7 @@ In order to prepare your code for I18N, you need to look at all the strings in your files. Any string that needs to be translated should be marked by wrapping -it in ``_('...')`` --- that is, a call to the function :func:`_`. For example:: +it in ``_('...')``\ ---that is, a call to the function :func:`_`. For example:: filename = 'mylog.txt' message = _('writing a log message') diff -r afe119a3619f Doc/library/glob.rst --- a/Doc/library/glob.rst +++ b/Doc/library/glob.rst @@ -1,4 +1,4 @@ -:mod:`glob` --- Unix style pathname pattern expansion +:mod:`glob`\ ---Unix style pathname pattern expansion ===================================================== .. module:: glob diff -r afe119a3619f Doc/library/grp.rst --- a/Doc/library/grp.rst +++ b/Doc/library/grp.rst @@ -1,4 +1,4 @@ -:mod:`grp` --- The group database +:mod:`grp`\ ---The group database ================================= .. module:: grp diff -r afe119a3619f Doc/library/gzip.rst --- a/Doc/library/gzip.rst +++ b/Doc/library/gzip.rst @@ -1,4 +1,4 @@ -:mod:`gzip` --- Support for :program:`gzip` files +:mod:`gzip`\ ---Support for :program:`gzip` files ================================================= .. module:: gzip diff -r afe119a3619f Doc/library/hashlib.rst --- a/Doc/library/hashlib.rst +++ b/Doc/library/hashlib.rst @@ -1,4 +1,4 @@ -:mod:`hashlib` --- Secure hashes and message digests +:mod:`hashlib`\ ---Secure hashes and message digests ==================================================== .. module:: hashlib diff -r afe119a3619f Doc/library/heapq.rst --- a/Doc/library/heapq.rst +++ b/Doc/library/heapq.rst @@ -1,4 +1,4 @@ -:mod:`heapq` --- Heap queue algorithm +:mod:`heapq`\ ---Heap queue algorithm ===================================== .. module:: heapq diff -r afe119a3619f Doc/library/hmac.rst --- a/Doc/library/hmac.rst +++ b/Doc/library/hmac.rst @@ -1,4 +1,4 @@ -:mod:`hmac` --- Keyed-Hashing for Message Authentication +:mod:`hmac`\ ---Keyed-Hashing for Message Authentication ======================================================== .. module:: hmac diff -r afe119a3619f Doc/library/html.entities.rst --- a/Doc/library/html.entities.rst +++ b/Doc/library/html.entities.rst @@ -1,4 +1,4 @@ -:mod:`html.entities` --- Definitions of HTML general entities +:mod:`html.entities`\ ---Definitions of HTML general entities ============================================================= .. module:: html.entities diff -r afe119a3619f Doc/library/html.parser.rst --- a/Doc/library/html.parser.rst +++ b/Doc/library/html.parser.rst @@ -1,4 +1,4 @@ -:mod:`html.parser` --- Simple HTML and XHTML parser +:mod:`html.parser`\ ---Simple HTML and XHTML parser =================================================== .. module:: html.parser diff -r afe119a3619f Doc/library/html.rst --- a/Doc/library/html.rst +++ b/Doc/library/html.rst @@ -1,4 +1,4 @@ -:mod:`html` --- HyperText Markup Language support +:mod:`html`\ ---HyperText Markup Language support ================================================= .. module:: html @@ -24,5 +24,5 @@ Submodules in the ``html`` package are: -* :mod:`html.parser` -- HTML/XHTML parser with lenient parsing mode -* :mod:`html.entities` -- HTML entity definitions +* :mod:`html.parser`\ ---HTML/XHTML parser with lenient parsing mode +* :mod:`html.entities`\ ---HTML entity definitions diff -r afe119a3619f Doc/library/http.client.rst --- a/Doc/library/http.client.rst +++ b/Doc/library/http.client.rst @@ -1,4 +1,4 @@ -:mod:`http.client` --- HTTP protocol client +:mod:`http.client`\ ---HTTP protocol client =========================================== .. module:: http.client @@ -16,7 +16,7 @@ -------------- This module defines classes which implement the client side of the HTTP and -HTTPS protocols. It is normally not used directly --- the module +HTTPS protocols. It is normally not used directly---the module :mod:`urllib.request` uses it to handle URLs that use HTTP and HTTPS. .. note:: diff -r afe119a3619f Doc/library/http.cookiejar.rst --- a/Doc/library/http.cookiejar.rst +++ b/Doc/library/http.cookiejar.rst @@ -1,4 +1,4 @@ -:mod:`http.cookiejar` --- Cookie handling for HTTP clients +:mod:`http.cookiejar`\ ---Cookie handling for HTTP clients ========================================================== .. module:: http.cookiejar @@ -11,9 +11,9 @@ -------------- The :mod:`http.cookiejar` module defines classes for automatic handling of HTTP -cookies. It is useful for accessing web sites that require small pieces of data --- :dfn:`cookies` -- to be set on the client machine by an HTTP response from a -web server, and then returned to the server in later HTTP requests. +cookies. It is useful for accessing web sites that require small pieces of +data---\ :dfn:`cookies`\ ---to be set on the client machine by an HTTP response +from a web server, and then returned to the server in later HTTP requests. Both the regular Netscape cookie protocol and the protocol defined by :rfc:`2965` are handled. RFC 2965 handling is switched off by default. @@ -121,17 +121,17 @@ the major browsers (and :mod:`http.cookiejar`) only bears a passing resemblance to the one sketched out in ``cookie_spec.html``. - :rfc:`2109` - HTTP State Management Mechanism + :rfc:`2109`\ ---HTTP State Management Mechanism Obsoleted by RFC 2965. Uses :mailheader:`Set-Cookie` with version=1. - :rfc:`2965` - HTTP State Management Mechanism + :rfc:`2965`\ ---HTTP State Management Mechanism The Netscape protocol with the bugs fixed. Uses :mailheader:`Set-Cookie2` in place of :mailheader:`Set-Cookie`. Not widely used. http://kristol.org/cookie/errata.html Unfinished errata to RFC 2965. - :rfc:`2964` - Use of HTTP State Management + :rfc:`2964`\ ---Use of HTTP State Management .. _cookie-jar-objects: diff -r afe119a3619f Doc/library/http.cookies.rst --- a/Doc/library/http.cookies.rst +++ b/Doc/library/http.cookies.rst @@ -1,4 +1,4 @@ -:mod:`http.cookies` --- HTTP state management +:mod:`http.cookies`\ ---HTTP state management ============================================= .. module:: http.cookies @@ -63,7 +63,7 @@ HTTP cookie handling for web *clients*. The :mod:`http.cookiejar` and :mod:`http.cookies` modules do not depend on each other. - :rfc:`2109` - HTTP State Management Mechanism + :rfc:`2109`\ ---HTTP State Management Mechanism This is the state management specification implemented by this module. @@ -76,14 +76,14 @@ .. method:: BaseCookie.value_decode(val) Return a decoded value from a string representation. Return value can be any - type. This method does nothing in :class:`BaseCookie` --- it exists so it can be + type. This method does nothing in :class:`BaseCookie`\ ---it exists so it can be overridden. .. method:: BaseCookie.value_encode(val) 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 + string. This method does nothing in :class:`BaseCookie`\ ---it exists so it can be overridden In general, it should be the case that :meth:`value_encode` and @@ -125,7 +125,7 @@ Abstract a key/value pair, which has some :rfc:`2109` attributes. - Morsels are dictionary-like objects, whose set of keys is constant --- the valid + Morsels are dictionary-like objects, whose set of keys is constant---the valid :rfc:`2109` attributes, which are * ``expires`` @@ -151,7 +151,7 @@ .. attribute:: Morsel.coded_value - The encoded value of the cookie --- this is what should be sent. + The encoded value of the cookie---this is what should be sent. .. attribute:: Morsel.key diff -r afe119a3619f Doc/library/http.rst --- a/Doc/library/http.rst +++ b/Doc/library/http.rst @@ -1,4 +1,4 @@ -:mod:`http` --- HTTP modules +:mod:`http`\ ---HTTP modules ============================ ``http`` is a package that collects several modules for working with the diff -r afe119a3619f Doc/library/http.server.rst --- a/Doc/library/http.server.rst +++ b/Doc/library/http.server.rst @@ -1,4 +1,4 @@ -:mod:`http.server` --- HTTP servers +:mod:`http.server`\ ---HTTP servers =================================== .. module:: http.server diff -r afe119a3619f Doc/library/imaplib.rst --- a/Doc/library/imaplib.rst +++ b/Doc/library/imaplib.rst @@ -1,4 +1,4 @@ -:mod:`imaplib` --- IMAP4 protocol client +:mod:`imaplib`\ ---IMAP4 protocol client ======================================== .. module:: imaplib @@ -70,7 +70,7 @@ encrypted socket (to use this class you need a socket module that was compiled with SSL support). If *host* is not specified, ``''`` (the local host) is used. If *port* is omitted, the standard IMAP4-over-SSL port (993) is used. *keyfile* - and *certfile* are also optional - they can contain a PEM formatted private key + and *certfile* are also optional---they can contain a PEM formatted private key and certificate chain file for the SSL connection. *ssl_context* parameter is a :class:`ssl.SSLContext` object which allows bundling SSL configuration options, certificates and private keys into a single (potentially long-lived) @@ -176,9 +176,9 @@ .. method:: IMAP4.authenticate(mechanism, authobject) - Authenticate command --- requires response processing. + Authenticate command---requires response processing. - *mechanism* specifies which authentication mechanism is to be used - it should + *mechanism* specifies which authentication mechanism is to be used---it should appear in the instance variable ``capabilities`` in the form ``AUTH=mechanism``. *authobject* must be a callable object:: diff -r afe119a3619f Doc/library/imghdr.rst --- a/Doc/library/imghdr.rst +++ b/Doc/library/imghdr.rst @@ -1,4 +1,4 @@ -:mod:`imghdr` --- Determine the type of an image +:mod:`imghdr`\ ---Determine the type of an image ================================================ .. module:: imghdr diff -r afe119a3619f Doc/library/imp.rst --- a/Doc/library/imp.rst +++ b/Doc/library/imp.rst @@ -1,4 +1,4 @@ -:mod:`imp` --- Access the :ref:`import ` internals +:mod:`imp`\ ---Access the :ref:`import ` internals ================================================================ .. deprecated:: 3.4 @@ -156,7 +156,7 @@ definitions, so this is generally not a problem. If the new version of a module does not define a name that was defined by the old version, the old definition remains. This feature can be used to the module's advantage if it maintains a - global table or cache of objects --- with a :keyword:`try` statement it can test + global table or cache of objects---with a :keyword:`try` statement it can test for the table's presence and skip its initialization if desired:: try: @@ -171,12 +171,12 @@ If a module imports objects from another module using :keyword:`from` ... :keyword:`import` ..., calling :func:`reload` for the other module does not - redefine the objects imported from it --- one way around this is to re-execute + redefine the objects imported from it---one way around this is to re-execute the :keyword:`from` statement, another is to use :keyword:`import` and qualified names (*module*.*name*) instead. If a module instantiates instances of a class, reloading the module that defines - the class does not affect the method definitions of the instances --- they + the class does not affect the method definitions of the instances---they continue to use the old class definition. The same is true for derived classes. .. deprecated:: 3.4 diff -r afe119a3619f Doc/library/importlib.rst --- a/Doc/library/importlib.rst +++ b/Doc/library/importlib.rst @@ -1,5 +1,5 @@ -:mod:`importlib` -- An implementation of :keyword:`import` -========================================================== +:mod:`importlib`\ ---An implementation of :keyword:`import` +=========================================================== .. module:: importlib :synopsis: An implementation of the import machinery. @@ -154,7 +154,7 @@ definitions, so this is generally not a problem. If the new version of a module does not define a name that was defined by the old version, the old definition remains. This feature can be used to the module's advantage if it - maintains a global table or cache of objects --- with a :keyword:`try` + maintains a global table or cache of objects---with a :keyword:`try` statement it can test for the table's presence and skip its initialization if desired:: @@ -171,7 +171,7 @@ If a module imports objects from another module using :keyword:`from` ... :keyword:`import` ..., calling :func:`reload` for the other module does not - redefine the objects imported from it --- one way around this is to + redefine the objects imported from it---one way around this is to re-execute the :keyword:`from` statement, another is to use :keyword:`import` and qualified names (*module.name*) instead. @@ -183,8 +183,8 @@ .. versionadded:: 3.4 -:mod:`importlib.abc` -- Abstract base classes related to import ---------------------------------------------------------------- +:mod:`importlib.abc`\ ---Abstract base classes related to import +---------------------------------------------------------------- .. module:: importlib.abc :synopsis: Abstract base classes related to import @@ -607,8 +607,8 @@ .. versionadded:: 3.4 -:mod:`importlib.machinery` -- Importers and path hooks ------------------------------------------------------- +:mod:`importlib.machinery`\ ---Importers and path hooks +------------------------------------------------------- .. module:: importlib.machinery :synopsis: Importers and path hooks @@ -871,8 +871,8 @@ Returns ``None`` as extension modules do not have source code. -:mod:`importlib.util` -- Utility code for importers ---------------------------------------------------- +:mod:`importlib.util`\ ---Utility code for importers +---------------------------------------------------- .. module:: importlib.util :synopsis: Utility code for importers diff -r afe119a3619f Doc/library/inspect.rst --- a/Doc/library/inspect.rst +++ b/Doc/library/inspect.rst @@ -1,4 +1,4 @@ -:mod:`inspect` --- Inspect live objects +:mod:`inspect`\ ---Inspect live objects ======================================= .. module:: inspect @@ -204,7 +204,7 @@ Otherwise, ``None`` is returned. Note that this function *only* returns a meaningful name for actual - Python modules - paths that potentially refer to Python packages will + Python modules---paths that potentially refer to Python packages will still return ``None``. .. versionchanged:: 3.3 @@ -287,7 +287,7 @@ Methods implemented via descriptors that also pass one of the other tests return false from the :func:`ismethoddescriptor` test, simply because the - other tests promise more -- you can, e.g., count on having the + other tests promise more---you can, e.g., count on having the :attr:`__func__` attribute (etc) when an object passes :func:`ismethod`. @@ -651,7 +651,7 @@ .. seealso:: - :pep:`362` - Function Signature Object. + :pep:`362`\ ---Function Signature Object. The detailed specification, implementation details and examples. diff -r afe119a3619f Doc/library/intro.rst --- a/Doc/library/intro.rst +++ b/Doc/library/intro.rst @@ -12,7 +12,7 @@ does not fully define the semantics. (On the other hand, the language core does define syntactic properties like the spelling and priorities of operators.) -The library also contains built-in functions and exceptions --- objects that can +The library also contains built-in functions and exceptions---objects that can be used by all Python code without the need of an :keyword:`import` statement. Some of these are defined by the core language, but many are not essential for the core semantics and are only described here. @@ -38,7 +38,7 @@ This means that if you start reading this manual from the start, and skip to the next chapter when you get bored, you will get a reasonable overview of the available modules and application areas that are supported by the Python -library. Of course, you don't *have* to read it like a novel --- you can also +library. Of course, you don't *have* to read it like a novel---you can also browse the table of contents (in front of the manual), or look for a specific function, module or term in the index (in the back). And finally, if you enjoy learning about random subjects, you choose a random page number (see module diff -r afe119a3619f Doc/library/io.rst --- a/Doc/library/io.rst +++ b/Doc/library/io.rst @@ -1,4 +1,4 @@ -:mod:`io` --- Core tools for working with streams +:mod:`io`\ ---Core tools for working with streams ================================================= .. module:: io @@ -307,11 +307,11 @@ interpreted relative to the position indicated by *whence*. Values for *whence* are: - * :data:`SEEK_SET` or ``0`` -- start of the stream (the default); + * :data:`SEEK_SET` or ``0``\ ---start of the stream (the default); *offset* should be zero or positive - * :data:`SEEK_CUR` or ``1`` -- current stream position; *offset* may + * :data:`SEEK_CUR` or ``1``\ ---current stream position; *offset* may be negative - * :data:`SEEK_END` or ``2`` -- end of the stream; *offset* is usually + * :data:`SEEK_END` or ``2``\ ---end of the stream; *offset* is usually negative Return the new absolute position. @@ -669,7 +669,7 @@ .. class:: BufferedRWPair(reader, writer, buffer_size=DEFAULT_BUFFER_SIZE) A buffered I/O object combining two unidirectional :class:`RawIOBase` - objects -- one readable, the other writeable -- into a single bidirectional + objects---one readable, the other writeable---into a single bidirectional endpoint. It inherits :class:`BufferedIOBase`. *reader* and *writer* are :class:`RawIOBase` objects that are readable and diff -r afe119a3619f Doc/library/ipaddress.rst --- a/Doc/library/ipaddress.rst +++ b/Doc/library/ipaddress.rst @@ -1,4 +1,4 @@ -:mod:`ipaddress` --- IPv4/IPv6 manipulation library +:mod:`ipaddress`\ ---IPv4/IPv6 manipulation library =================================================== .. module:: ipaddress @@ -25,7 +25,7 @@ subnet, checking whether or not a string represents a valid IP address or network definition, and so on. -This is the full module API reference - for an overview and introduction, +This is the full module API reference---for an overview and introduction, see :ref:`ipaddress-howto`. .. versionadded:: 3.3 @@ -149,7 +149,7 @@ .. attribute:: packed - The binary representation of this address - a :class:`bytes` object of + The binary representation of this address---a :class:`bytes` object of the appropriate length (most significant octet first). This is 4 bytes for IPv4 and 16 bytes for IPv6. diff -r afe119a3619f Doc/library/itertools.rst --- a/Doc/library/itertools.rst +++ b/Doc/library/itertools.rst @@ -1,4 +1,4 @@ -:mod:`itertools` --- Functions creating iterators for efficient looping +:mod:`itertools`\ ---Functions creating iterators for efficient looping ======================================================================= .. module:: itertools diff -r afe119a3619f Doc/library/json.rst --- a/Doc/library/json.rst +++ b/Doc/library/json.rst @@ -1,4 +1,4 @@ -:mod:`json` --- JSON encoder and decoder +:mod:`json`\ ---JSON encoder and decoder ======================================== .. module:: json diff -r afe119a3619f Doc/library/keyword.rst --- a/Doc/library/keyword.rst +++ b/Doc/library/keyword.rst @@ -1,4 +1,4 @@ -:mod:`keyword` --- Testing for Python keywords +:mod:`keyword`\ ---Testing for Python keywords ============================================== .. module:: keyword diff -r afe119a3619f Doc/library/linecache.rst --- a/Doc/library/linecache.rst +++ b/Doc/library/linecache.rst @@ -1,4 +1,4 @@ -:mod:`linecache` --- Random access to text lines +:mod:`linecache`\ ---Random access to text lines ================================================ .. module:: linecache @@ -20,7 +20,7 @@ .. function:: getline(filename, lineno, module_globals=None) Get line *lineno* from file named *filename*. This function will never raise an - exception --- it will return ``''`` on errors (the terminating newline character + exception---it will return ``''`` on errors (the terminating newline character will be included for lines that are found). .. index:: triple: module; search; path diff -r afe119a3619f Doc/library/locale.rst --- a/Doc/library/locale.rst +++ b/Doc/library/locale.rst @@ -1,4 +1,4 @@ -:mod:`locale` --- Internationalization services +:mod:`locale`\ ---Internationalization services =============================================== .. module:: locale diff -r afe119a3619f Doc/library/logging.config.rst --- a/Doc/library/logging.config.rst +++ b/Doc/library/logging.config.rst @@ -1,4 +1,4 @@ -:mod:`logging.config` --- Logging configuration +:mod:`logging.config`\ ---Logging configuration =============================================== .. module:: logging.config @@ -25,7 +25,7 @@ ^^^^^^^^^^^^^^^^^^^^^^^ The following functions configure the logging module. They are located in the -:mod:`logging.config` module. Their use is optional --- you can configure the +:mod:`logging.config` module. Their use is optional---you can configure the logging module using these functions or by making calls to the main API (defined in :mod:`logging` itself) and defining handlers which are declared either in :mod:`logging` or :mod:`logging.handlers`. @@ -131,7 +131,7 @@ processed. This could be done by encrypting and/or signing what is sent across the socket, such that the ``verify`` callable can perform signature verification and/or decryption. The ``verify`` callable is called - with a single argument - the bytes received across the socket - and should + with a single argument---the bytes received across the socket---and should return the bytes to be processed, or None to indicate that the bytes should be discarded. The returned bytes could be the same as the passed in bytes (e.g. when only verification is done), or they could be completely different @@ -189,7 +189,7 @@ The dictionary passed to :func:`dictConfig` must contain the following keys: -* *version* - to be set to an integer value representing the schema +* *version*\ ---to be set to an integer value representing the schema version. The only valid value at present is 1, but having this key allows the schema to evolve while still preserving backwards compatibility. @@ -201,7 +201,7 @@ :ref:`logging-config-dict-userdef` below is used to create an instance; otherwise, the context is used to determine what to instantiate. -* *formatters* - the corresponding value will be a dict in which each +* *formatters*\ ---the corresponding value will be a dict in which each key is a formatter id and each value is a dict describing how to configure the corresponding Formatter instance. @@ -209,7 +209,7 @@ (with defaults of ``None``) and these are used to construct a :class:`logging.Formatter` instance. -* *filters* - the corresponding value will be a dict in which each key +* *filters*\ ---the corresponding value will be a dict in which each key is a filter id and each value is a dict describing how to configure the corresponding Filter instance. @@ -217,7 +217,7 @@ empty string) and this is used to construct a :class:`logging.Filter` instance. -* *handlers* - the corresponding value will be a dict in which each +* *handlers*\ ---the corresponding value will be a dict in which each key is a handler id and each value is a dict describing how to configure the corresponding Handler instance. @@ -257,7 +257,7 @@ :class:`logging.handlers.RotatingFileHandler` with the keyword arguments ``filename='logconfig.log', maxBytes=1024, backupCount=3``. -* *loggers* - the corresponding value will be a dict in which each key +* *loggers*\ ---the corresponding value will be a dict in which each key is a logger name and each value is a dict describing how to configure the corresponding Logger instance. @@ -276,11 +276,11 @@ The specified loggers will be configured according to the level, propagation, filters and handlers specified. -* *root* - this will be the configuration for the root logger. +* *root*\ ---this will be the configuration for the root logger. Processing of the configuration will be as for any logger, except that the ``propagate`` setting will not be applicable. -* *incremental* - whether the configuration is to be interpreted as +* *incremental*\ ---whether the configuration is to be interpreted as incremental to the existing configuration. This value defaults to ``False``, which means that the specified configuration replaces the existing configuration with the same semantics as used by the @@ -289,7 +289,7 @@ If the specified value is ``True``, the configuration is processed as described in the section on :ref:`logging-config-dict-incremental`. -* *disable_existing_loggers* - whether any existing loggers are to be +* *disable_existing_loggers*\ ---whether any existing loggers are to be disabled. This setting mirrors the parameter of the same name in :func:`fileConfig`. If absent, this parameter defaults to ``True``. This value is ignored if *incremental* is ``True``. @@ -330,8 +330,8 @@ Object connections """""""""""""""""" -The schema describes a set of logging objects - loggers, -handlers, formatters, filters - which are connected to each other in +The schema describes a set of logging objects---loggers, +handlers, formatters, filters---which are connected to each other in an object graph. Thus, the schema needs to represent connections between the objects. For example, say that, once configured, a particular logger has attached to it a particular handler. For the @@ -397,7 +397,7 @@ instantiated, but when a user-defined object is to be instantiated, the system will not know how to do this. In order to provide complete flexibility for user-defined object instantiation, the user needs -to provide a 'factory' - a callable which is called with a +to provide a 'factory'\ ---a callable which is called with a configuration dictionary and which returns the instantiated object. This is signalled by an absolute import path to the factory being made available under the special key ``'()'``. Here's a concrete @@ -450,7 +450,7 @@ and this contains the special key ``'()'``, which means that user-defined instantiation is wanted. In this case, the specified factory callable will be used. If it is an actual callable it will be -used directly - otherwise, if you specify a string (as in the example) +used directly---otherwise, if you specify a string (as in the example) the actual callable will be located using normal import mechanisms. The callable will be called with the **remaining** items in the configuration sub-dictionary as keyword arguments. In the above diff -r afe119a3619f Doc/library/logging.handlers.rst --- a/Doc/library/logging.handlers.rst +++ b/Doc/library/logging.handlers.rst @@ -1,4 +1,4 @@ -:mod:`logging.handlers` --- Logging handlers +:mod:`logging.handlers`\ ---Logging handlers ============================================ .. module:: logging.handlers @@ -143,8 +143,8 @@ new stream. This handler is not appropriate for use under Windows, because under Windows -open log files cannot be moved or renamed - logging opens the files with -exclusive locks - and so there is no need for such a handler. Furthermore, +open log files cannot be moved or renamed---logging opens the files with +exclusive locks---and so there is no need for such a handler. Furthermore, *ST_INO* is not supported under Windows; :func:`stat` always returns zero for this value. @@ -232,7 +232,7 @@ .. versionadded:: 3.3 -The reason the attributes exist is to save you having to subclass - you can use +The reason the attributes exist is to save you having to subclass---you can use the same callables for instances of :class:`RotatingFileHandler` and :class:`TimedRotatingFileHandler`. If either the namer or rotator callable raises an exception, this will be handled in the same way as any other @@ -506,7 +506,7 @@ Note that if your server is not listening on UDP port 514, :class:`SysLogHandler` may appear not to work. In that case, check what - address you should be using for a domain socket - it's system dependent. + address you should be using for a domain socket---it's system dependent. For example, on Linux it's usually '/dev/log' but on OS/X it's '/var/run/syslog'. You'll need to check your platform and use the appropriate address (you may need to do this check at runtime if your @@ -530,7 +530,7 @@ .. versionchanged:: 3.2.1 (See: :issue:`12168`.) In earlier versions, the message sent to the syslog daemons was always terminated with a NUL byte, because early - versions of these daemons expected a NUL terminated message - even + versions of these daemons expected a NUL terminated message---even though it's not in the relevant specification (RF 5424). More recent versions of these daemons don't expect the NUL byte but strip it off if it's there, and even more recent daemons (which adhere more closely @@ -555,7 +555,7 @@ .. method:: encodePriority(facility, priority) Encodes the facility and priority into an integer. You can pass in strings - or integers - if strings are passed, internal mapping dictionaries are + or integers---if strings are passed, internal mapping dictionaries are used to convert them to integers. The symbolic ``LOG_`` values are defined in :class:`SysLogHandler` and @@ -655,8 +655,8 @@ used to define the application name as it appears in the event log. An appropriate registry entry is created using this name. The *dllname* should give the fully qualified pathname of a .dll or .exe which contains message - definitions to hold in the log (if not specified, ``'win32service.pyd'`` is used - - this is installed with the Win32 extensions and contains some basic + definitions to hold in the log (if not specified, ``'win32service.pyd'`` is + used---this is installed with the Win32 extensions and contains some basic placeholder message definitions. Note that use of these placeholders will make your event logs big, as the entire message source is held in the log. If you want slimmer logs, you have to pass in the name of your own .dll or .exe which @@ -669,7 +669,7 @@ At this point, you can remove the application name from the registry as a source of event log entries. However, if you do this, you will not be able - to see the events as you intended in the Event Log Viewer - it needs to be + to see the events as you intended in the Event Log Viewer---it needs to be able to access the registry to get the .dll name. The current version does not do this. diff -r afe119a3619f Doc/library/logging.rst --- a/Doc/library/logging.rst +++ b/Doc/library/logging.rst @@ -1,4 +1,4 @@ -:mod:`logging` --- Logging facility for Python +:mod:`logging`\ ---Logging facility for Python ============================================== .. module:: logging @@ -73,7 +73,7 @@ If this evaluates to true, events logged to this logger will be passed to the handlers of higher level (ancestor) loggers, in addition to any handlers attached to this logger. Messages are passed directly to the ancestor - loggers' handlers - neither the level nor filters of the ancestor loggers in + loggers' handlers---neither the level nor filters of the ancestor loggers in question are considered. If this evaluates to false, logging messages are not passed to the handlers @@ -83,7 +83,7 @@ .. note:: If you attach a handler to a logger *and* one or more of its ancestors, it may emit the same record multiple times. In general, you - should not need to attach a handler to more than one logger - if you just + should not need to attach a handler to more than one logger---if you just attach it to the appropriate logger which is highest in the logger hierarchy, then it will see all events logged by all descendant loggers, provided that their propagate setting is left set to ``True``. A common @@ -224,7 +224,7 @@ .. note:: There is an obsolete method ``warn`` which is functionally identical to ``warning``. As ``warn`` is deprecated, please do not use - it - use ``warning`` instead. + it---use ``warning`` instead. .. method:: Logger.error(msg, *args, **kwargs) @@ -306,7 +306,7 @@ looking for handlers in this logger and its parents in the logger hierarchy. Returns True if a handler was found, else False. The method stops searching up the hierarchy whenever a logger with the 'propagate' attribute set to - False is found - that will be the last logger which is checked for the + False is found---that will be the last logger which is checked for the existence of handlers. .. versionadded:: 3.2 @@ -408,7 +408,7 @@ This method should be called from handlers when an exception is encountered during an :meth:`emit` call. If the module-level attribute ``raiseExceptions`` is ``False``, exceptions get silently ignored. This is - what is mostly wanted for a logging system - most users will not care about + what is mostly wanted for a logging system---most users will not care about errors in the logging system, they are more interested in application errors. You could, however, replace this with a custom handler if you wish. The specified record is the one which was being processed when the exception @@ -418,7 +418,7 @@ .. method:: Handler.format(record) - Do formatting for a record - if a formatter is set, use it. Otherwise, use the + Do formatting for a record---if a formatter is set, use it. Otherwise, use the default formatter for the module. @@ -444,7 +444,7 @@ supplied, the default value of ``'%(message)s'`` is used. A Formatter can be initialized with a format string which makes use of knowledge -of the :class:`LogRecord` attributes - such as the default value mentioned above +of the :class:`LogRecord` attributes---such as the default value mentioned above making use of the fact that the user's message and arguments are pre-formatted into a :class:`LogRecord`'s *message* attribute. This format string contains standard Python %-style mapping keys. See section :ref:`old-string-formatting` @@ -939,7 +939,7 @@ .. note:: There is an obsolete function ``warn`` which is functionally identical to ``warning``. As ``warn`` is deprecated, please do not use - it - use ``warning`` instead. + it---use ``warning`` instead. .. function:: error(msg, *args, **kwargs) @@ -1066,8 +1066,8 @@ +--------------+---------------------------------------------+ | ``stream`` | Use the specified stream to initialize the | | | StreamHandler. Note that this argument is | - | | incompatible with 'filename' - if both are | - | | present, a ``ValueError`` is raised. | + | | incompatible with 'filename'\ ---if both | + | | are present, a ``ValueError`` is raised. | +--------------+---------------------------------------------+ | ``handlers`` | If specified, this should be an iterable of | | | already created handlers to add to the root | @@ -1075,7 +1075,7 @@ | | have a formatter set will be assigned the | | | default formatter created in this function. | | | Note that this argument is incompatible | - | | with 'filename' or 'stream' - if both are | + | | with 'filename' or 'stream'\ ---if both are | | | present, a ``ValueError`` is raised. | +--------------+---------------------------------------------+ @@ -1178,7 +1178,7 @@ Module :mod:`logging.handlers` Useful handlers included with the logging module. - :pep:`282` - A Logging System + :pep:`282`\ ---A Logging System The proposal which described this feature for inclusion in the Python standard library. diff -r afe119a3619f Doc/library/lzma.rst --- a/Doc/library/lzma.rst +++ b/Doc/library/lzma.rst @@ -1,4 +1,4 @@ -:mod:`lzma` --- Compression using the LZMA algorithm +:mod:`lzma`\ ---Compression using the LZMA algorithm ==================================================== .. module:: lzma @@ -116,7 +116,7 @@ This is the default format. * :const:`FORMAT_ALONE`: The legacy ``.lzma`` container format. - This format is more limited than ``.xz`` -- it does not support integrity + This format is more limited than ``.xz``\ ---it does not support integrity checks or multiple filters. * :const:`FORMAT_RAW`: A raw data stream, not using any container format. @@ -311,7 +311,7 @@ * ``mode``: :const:`MODE_FAST` or :const:`MODE_NORMAL`. * ``nice_len``: What should be considered a "nice length" for a match. This should be 273 or less. - * ``mf``: What match finder to use -- :const:`MF_HC3`, :const:`MF_HC4`, + * ``mf``: What match finder to use---\ :const:`MF_HC3`, :const:`MF_HC4`, :const:`MF_BT2`, :const:`MF_BT3`, or :const:`MF_BT4`. * ``depth``: Maximum search depth used by match finder. 0 (default) means to select automatically based on other filter options. diff -r afe119a3619f Doc/library/macpath.rst --- a/Doc/library/macpath.rst +++ b/Doc/library/macpath.rst @@ -1,4 +1,4 @@ -:mod:`macpath` --- Mac OS 9 path manipulation functions +:mod:`macpath`\ ---Mac OS 9 path manipulation functions ======================================================= .. module:: macpath diff -r afe119a3619f Doc/library/mailbox.rst --- a/Doc/library/mailbox.rst +++ b/Doc/library/mailbox.rst @@ -1,4 +1,4 @@ -:mod:`mailbox` --- Manipulate mailboxes in various formats +:mod:`mailbox`\ ---Manipulate mailboxes in various formats ========================================================== .. module:: mailbox @@ -613,7 +613,7 @@ .. seealso:: - `nmh - Message Handling System `_ + `nmh---Message Handling System `_ Home page of :program:`nmh`, an updated version of the original :program:`mh`. `MH & nmh: Email for Users & Programmers `_ diff -r afe119a3619f Doc/library/mailcap.rst --- a/Doc/library/mailcap.rst +++ b/Doc/library/mailcap.rst @@ -1,4 +1,4 @@ -:mod:`mailcap` --- Mailcap file handling +:mod:`mailcap`\ ---Mailcap file handling ======================================== .. module:: mailcap diff -r afe119a3619f Doc/library/marshal.rst --- a/Doc/library/marshal.rst +++ b/Doc/library/marshal.rst @@ -1,4 +1,4 @@ -:mod:`marshal` --- Internal Python object serialization +:mod:`marshal`\ ---Internal Python object serialization ======================================================= .. module:: marshal @@ -24,7 +24,7 @@ writing the "pseudo-compiled" code for Python modules of :file:`.pyc` files. Therefore, the Python maintainers reserve the right to modify the marshal format in backward incompatible ways should the need arise. If you're serializing and -de-serializing Python objects, use the :mod:`pickle` module instead -- the +de-serializing Python objects, use the :mod:`pickle` module instead---the performance is comparable, version independence is guaranteed, and pickle supports a substantially wider range of objects than marshal. @@ -60,7 +60,7 @@ or ``'w+b'``). If the value has (or contains an object that has) an unsupported type, a - :exc:`ValueError` exception is raised --- but garbage data will also be written + :exc:`ValueError` exception is raised---but garbage data will also be written to the file. The object will not be properly read back by :func:`load`. The *version* argument indicates the data format that ``dump`` should use diff -r afe119a3619f Doc/library/math.rst --- a/Doc/library/math.rst +++ b/Doc/library/math.rst @@ -1,4 +1,4 @@ -:mod:`math` --- Mathematical functions +:mod:`math`\ ---Mathematical functions ====================================== .. module:: math diff -r afe119a3619f Doc/library/mimetypes.rst --- a/Doc/library/mimetypes.rst +++ b/Doc/library/mimetypes.rst @@ -1,4 +1,4 @@ -:mod:`mimetypes` --- Map filenames to MIME types +:mod:`mimetypes`\ ---Map filenames to MIME types ================================================ .. module:: mimetypes diff -r afe119a3619f Doc/library/mmap.rst --- a/Doc/library/mmap.rst +++ b/Doc/library/mmap.rst @@ -1,4 +1,4 @@ -:mod:`mmap` --- Memory-mapped file support +:mod:`mmap`\ ---Memory-mapped file support ========================================== .. module:: mmap diff -r afe119a3619f Doc/library/modulefinder.rst --- a/Doc/library/modulefinder.rst +++ b/Doc/library/modulefinder.rst @@ -1,4 +1,4 @@ -:mod:`modulefinder` --- Find modules used by a script +:mod:`modulefinder`\ ---Find modules used by a script ===================================================== .. sectionauthor:: A.M. Kuchling diff -r afe119a3619f Doc/library/msilib.rst --- a/Doc/library/msilib.rst +++ b/Doc/library/msilib.rst @@ -1,4 +1,4 @@ -:mod:`msilib` --- Read and write Microsoft Installer files +:mod:`msilib`\ ---Read and write Microsoft Installer files ========================================================== .. module:: msilib diff -r afe119a3619f Doc/library/msvcrt.rst --- a/Doc/library/msvcrt.rst +++ b/Doc/library/msvcrt.rst @@ -1,5 +1,5 @@ -:mod:`msvcrt` -- Useful routines from the MS VC++ runtime -========================================================= +:mod:`msvcrt`\ ---Useful routines from the MS VC++ runtime +========================================================== .. module:: msvcrt :platform: Windows diff -r afe119a3619f Doc/library/multiprocessing.rst --- a/Doc/library/multiprocessing.rst +++ b/Doc/library/multiprocessing.rst @@ -1,4 +1,4 @@ -:mod:`multiprocessing` --- Process-based parallelism +:mod:`multiprocessing`\ ---Process-based parallelism ==================================================== .. module:: multiprocessing @@ -434,7 +434,7 @@ on Windows :c:func:`TerminateProcess` is used. Note that exit handlers and finally clauses, etc., will not be executed. - Note that descendant processes of the process will *not* be terminated -- + Note that descendant processes of the process will *not* be terminated --- they will simply become orphaned. .. warning:: @@ -508,7 +508,7 @@ semaphore used to count the number of unfinished tasks may eventually overflow, raising an exception. -Note that one can also create a shared queue by using a manager object -- see +Note that one can also create a shared queue by using a manager object---see :ref:`multiprocessing-managers`. .. note:: @@ -523,7 +523,7 @@ When an object is put on a queue, the object is pickled and a background thread later flushes the pickled data to an underlying pipe. This has some consequences which are a little surprising, - but should not cause any practical difficulties -- if they really + but should not cause any practical difficulties---if they really bother you then you can instead use a queue created with a :ref:`manager `. @@ -657,7 +657,7 @@ Prevent :meth:`join_thread` from blocking. In particular, this prevents the background thread from being joined automatically when the process - exits -- see :meth:`join_thread`. + exits---see :meth:`join_thread`. A better name for this method might be ``allow_exit_without_flush()``. It is likely to cause enqueued @@ -788,7 +788,7 @@ Connection objects allow the sending and receiving of picklable objects or strings. They can be thought of as message oriented connected sockets. -Connection objects are usually created using :func:`Pipe` -- see also +Connection objects are usually created using :func:`Pipe`\ ---see also :ref:`multiprocessing-listeners-clients`. .. class:: Connection @@ -876,7 +876,7 @@ using :meth:`Connection.send` and :meth:`Connection.recv`. .. versionadded:: 3.3 - Connection objects now support the context manager protocol -- see + Connection objects now support the context manager protocol---see :ref:`typecontextmanager`. :meth:`__enter__` returns the connection object, and :meth:`__exit__` calls :meth:`close`. @@ -928,7 +928,7 @@ :mod:`threading` module. Note that one can also create synchronization primitives by using a manager -object -- see :ref:`multiprocessing-managers`. +object---see :ref:`multiprocessing-managers`. .. class:: Barrier(parties[, action[, timeout]]) @@ -1071,7 +1071,7 @@ Otherwise *size_or_initializer* is a sequence which is used to initialize the array and whose length determines the length of the array. - Note that setting and getting an element is potentially non-atomic -- use + Note that setting and getting an element is potentially non-atomic---use :func:`Array` instead to make sure that access is automatically synchronized using a lock. @@ -1083,12 +1083,12 @@ ctypes type or a one character typecode of the kind used by the :mod:`array` module. *\*args* is passed on to the constructor for the type. - Note that setting and getting the value is potentially non-atomic -- use + Note that setting and getting the value is potentially non-atomic---use :func:`Value` instead to make sure that access is automatically synchronized using a lock. Note that an array of :data:`ctypes.c_char` has ``value`` and ``raw`` - attributes which allow one to use it to store and retrieve strings -- see + attributes which allow one to use it to store and retrieve strings---see documentation for :mod:`ctypes`. .. function:: Array(typecode_or_type, size_or_initializer, *, lock=True) @@ -1320,7 +1320,7 @@ The address used by the manager. .. versionchanged:: 3.3 - Manager objects support the context manager protocol -- see + Manager objects support the context manager protocol---see :ref:`typecontextmanager`. :meth:`__enter__` starts the server process (if it has not already started) and then returns the manager object. :meth:`__exit__` calls :meth:`shutdown`. @@ -1608,7 +1608,7 @@ in the manager's process. The returned value will be a copy of the result of the call or a proxy to - a new shared object -- see documentation for the *method_to_typeid* + a new shared object---see documentation for the *method_to_typeid* argument of :meth:`BaseManager.register`. If an exception is raised by the call, then is re-raised by @@ -1800,7 +1800,7 @@ :meth:`terminate` before using :meth:`join`. .. versionadded:: 3.3 - Pool objects now support the context manager protocol -- see + Pool objects now support the context manager protocol---see :ref:`typecontextmanager`. :meth:`__enter__` returns the pool object, and :meth:`__exit__` calls :meth:`terminate`. @@ -1971,7 +1971,7 @@ unavailable then it is ``None``. .. versionadded:: 3.3 - Listener objects now support the context manager protocol -- see + Listener objects now support the context manager protocol---see :ref:`typecontextmanager`. :meth:`__enter__` returns the listener object, and :meth:`__exit__` calls :meth:`close`. @@ -2149,7 +2149,7 @@ to the root logger. Note that on Windows child processes will only inherit the level of the - parent process's logger -- any other customization of the logger will not be + parent process's logger---any other customization of the logger will not be inherited. .. currentmodule:: multiprocessing @@ -2354,7 +2354,7 @@ os.close(sys.stdin.fileno()) - in the :meth:`multiprocessing.Process._bootstrap` method --- this resulted + in the :meth:`multiprocessing.Process._bootstrap` method---this resulted in issues with processes-in-processes. This has been changed to:: sys.stdin.close() @@ -2390,7 +2390,7 @@ Ensure that all arguments to :meth:`Process.__init__` are picklable. This means, in particular, that bound or unbound methods cannot be used directly - as the ``target`` argument on Windows --- just define a function and use + as the ``target`` argument on Windows---just define a function and use that instead. Also, if you subclass :class:`Process` then make sure that instances will be diff -r afe119a3619f Doc/library/netrc.rst --- a/Doc/library/netrc.rst +++ b/Doc/library/netrc.rst @@ -1,5 +1,5 @@ -:mod:`netrc` --- netrc file processing +:mod:`netrc`\ ---netrc file processing ====================================== .. module:: netrc diff -r afe119a3619f Doc/library/nis.rst --- a/Doc/library/nis.rst +++ b/Doc/library/nis.rst @@ -1,5 +1,5 @@ -:mod:`nis` --- Interface to Sun's NIS (Yellow Pages) +:mod:`nis`\ ---Interface to Sun's NIS (Yellow Pages) ==================================================== .. module:: nis diff -r afe119a3619f Doc/library/nntplib.rst --- a/Doc/library/nntplib.rst +++ b/Doc/library/nntplib.rst @@ -1,4 +1,4 @@ -:mod:`nntplib` --- NNTP protocol client +:mod:`nntplib`\ ---NNTP protocol client ======================================= .. module:: nntplib diff -r afe119a3619f Doc/library/numbers.rst --- a/Doc/library/numbers.rst +++ b/Doc/library/numbers.rst @@ -1,4 +1,4 @@ -:mod:`numbers` --- Numeric abstract base classes +:mod:`numbers`\ ---Numeric abstract base classes ================================================ .. module:: numbers diff -r afe119a3619f Doc/library/operator.rst --- a/Doc/library/operator.rst +++ b/Doc/library/operator.rst @@ -1,4 +1,4 @@ -:mod:`operator` --- Standard operators as functions +:mod:`operator`\ ---Standard operators as functions =================================================== .. module:: operator diff -r afe119a3619f Doc/library/optparse.rst --- a/Doc/library/optparse.rst +++ b/Doc/library/optparse.rst @@ -1,4 +1,4 @@ -:mod:`optparse` --- Parser for command line options +:mod:`optparse`\ ---Parser for command line options =================================================== .. module:: optparse @@ -1325,7 +1325,7 @@ ``values`` a :class:`optparse.Values` object to store option arguments in (default: a - new instance of :class:`Values`) -- if you give an existing object, the + new instance of :class:`Values`)\ ---if you give an existing object, the option defaults will not be initialized on it and the return values are diff -r afe119a3619f Doc/library/os.path.rst --- a/Doc/library/os.path.rst +++ b/Doc/library/os.path.rst @@ -1,4 +1,4 @@ -:mod:`os.path` --- Common pathname manipulations +:mod:`os.path`\ ---Common pathname manipulations ================================================ .. module:: os.path @@ -192,7 +192,7 @@ system where a different file system has been mounted. The function checks whether *path*'s parent, :file:`path/..`, is on a different device than *path*, or whether :file:`path/..` and *path* point to the same i-node on the same - device --- this should detect mount points for all Unix and POSIX variants. + device---this should detect mount points for all Unix and POSIX variants. .. function:: join(path1[, path2[, ...]]) diff -r afe119a3619f Doc/library/os.rst --- a/Doc/library/os.rst +++ b/Doc/library/os.rst @@ -1,4 +1,4 @@ -:mod:`os` --- Miscellaneous operating system interfaces +:mod:`os`\ ---Miscellaneous operating system interfaces ======================================================= .. module:: os @@ -573,11 +573,11 @@ Returns information identifying the current operating system. The return value is an object with five attributes: - * :attr:`sysname` - operating system name - * :attr:`nodename` - name of machine on network (implementation-defined) - * :attr:`release` - operating system release - * :attr:`version` - operating system version - * :attr:`machine` - hardware identifier + * :attr:`sysname`\ ---operating system name + * :attr:`nodename`\ ---name of machine on network (implementation-defined) + * :attr:`release`\ ---operating system release + * :attr:`version`\ ---operating system version + * :attr:`machine`\ ---hardware identifier For backwards compatibility, this object is also iterable, behaving like a five-tuple containing :attr:`sysname`, :attr:`nodename`, @@ -797,7 +797,7 @@ Apply, test or remove a POSIX lock on an open file descriptor. *fd* is an open file descriptor. - *cmd* specifies the command to use - one of :data:`F_LOCK`, :data:`F_TLOCK`, + *cmd* specifies the command to use---one of :data:`F_LOCK`, :data:`F_TLOCK`, :data:`F_ULOCK` or :data:`F_TEST`. *len* specifies the section of the file to lock. @@ -1570,7 +1570,7 @@ are deleted (for example with :func:`os.unlink`). Generally, FIFOs are used as rendezvous between "client" and "server" type processes: the server opens the FIFO for reading, and the client opens it for writing. Note that :func:`mkfifo` - doesn't open the FIFO --- it just creates the rendezvous point. + doesn't open the FIFO---it just creates the rendezvous point. Availability: Unix. @@ -1774,39 +1774,39 @@ The return value is an object whose attributes correspond roughly to the members of the :c:type:`stat` structure, namely: - * :attr:`st_mode` - protection bits, - * :attr:`st_ino` - inode number, - * :attr:`st_dev` - device, - * :attr:`st_nlink` - number of hard links, - * :attr:`st_uid` - user id of owner, - * :attr:`st_gid` - group id of owner, - * :attr:`st_size` - size of file, in bytes, - * :attr:`st_atime` - time of most recent access expressed in seconds, - * :attr:`st_mtime` - time of most recent content modification + * :attr:`st_mode`\ ---protection bits, + * :attr:`st_ino`\ ---inode number, + * :attr:`st_dev`\ ---device, + * :attr:`st_nlink`\ ---number of hard links, + * :attr:`st_uid`\ ---user id of owner, + * :attr:`st_gid`\ ---group id of owner, + * :attr:`st_size`\ ---size of file, in bytes, + * :attr:`st_atime`\ ---time of most recent access expressed in seconds, + * :attr:`st_mtime`\ ---time of most recent content modification expressed in seconds, - * :attr:`st_ctime` - platform dependent; time of most recent metadata + * :attr:`st_ctime`\ ---platform dependent; time of most recent metadata change on Unix, or the time of creation on Windows, expressed in seconds - * :attr:`st_atime_ns` - time of most recent access + * :attr:`st_atime_ns`\ ---time of most recent access expressed in nanoseconds as an integer, - * :attr:`st_mtime_ns` - time of most recent content modification + * :attr:`st_mtime_ns`\ ---time of most recent content modification expressed in nanoseconds as an integer, - * :attr:`st_ctime_ns` - platform dependent; time of most recent metadata + * :attr:`st_ctime_ns`\ ---platform dependent; time of most recent metadata change on Unix, or the time of creation on Windows, expressed in nanoseconds as an integer On some Unix systems (such as Linux), the following attributes may also be available: - * :attr:`st_blocks` - number of blocks allocated for file - * :attr:`st_blksize` - filesystem blocksize - * :attr:`st_rdev` - type of device if an inode device - * :attr:`st_flags` - user defined flags for file + * :attr:`st_blocks`\ ---number of blocks allocated for file + * :attr:`st_blksize`\ ---filesystem blocksize + * :attr:`st_rdev`\ ---type of device if an inode device + * :attr:`st_flags`\ ---user defined flags for file On other Unix systems (such as FreeBSD), the following attributes may be available (but may be only filled out if root tries to use them): - * :attr:`st_gen` - file generation number - * :attr:`st_birthtime` - time of file creation + * :attr:`st_gen`\ ---file generation number + * :attr:`st_birthtime`\ ---time of file creation On Mac OS systems, the following attributes may also be available: @@ -2794,11 +2794,11 @@ Returns the current global process times. The return value is an object with five attributes: - * :attr:`user` - user time - * :attr:`system` - system time - * :attr:`children_user` - user time of all child processes - * :attr:`children_system` - system time of all child processes - * :attr:`elapsed` - elapsed real time since a fixed point in the past + * :attr:`user`\ ---user time + * :attr:`system`\ ---system time + * :attr:`children_user`\ ---user time of all child processes + * :attr:`children_system`\ ---system time of all child processes + * :attr:`elapsed`\ ---elapsed real time since a fixed point in the past For backwards compatibility, this object also behaves like a five-tuple containing :attr:`user`, :attr:`system`, :attr:`children_user`, @@ -3233,8 +3233,8 @@ The character used by the operating system to separate pathname components. This is ``'/'`` for POSIX and ``'\\'`` for Windows. Note that knowing this - is not sufficient to be able to parse or concatenate pathnames --- use - :func:`os.path.split` and :func:`os.path.join` --- but it is occasionally + is not sufficient to be able to parse or concatenate pathnames---use + :func:`os.path.split` and :func:`os.path.join`\ ---but it is occasionally useful. Also available via :mod:`os.path`. diff -r afe119a3619f Doc/library/ossaudiodev.rst --- a/Doc/library/ossaudiodev.rst +++ b/Doc/library/ossaudiodev.rst @@ -1,4 +1,4 @@ -:mod:`ossaudiodev` --- Access to OSS-compatible audio devices +:mod:`ossaudiodev`\ ---Access to OSS-compatible audio devices ============================================================= .. module:: ossaudiodev @@ -151,8 +151,8 @@ Write the Python string *data* to the audio device and return the number of bytes written. If the audio device is in blocking mode (the default), the entire string is always written (again, this is different from usual Unix device - semantics). If the device is in non-blocking mode, some data may not be written - ---see :meth:`writeall`. + semantics). If the device is in non-blocking mode, some data may not be + written---see :meth:`writeall`. .. method:: oss_audio_device.writeall(data) diff -r afe119a3619f Doc/library/parser.rst --- a/Doc/library/parser.rst +++ b/Doc/library/parser.rst @@ -1,4 +1,4 @@ -:mod:`parser` --- Access Python parse trees +:mod:`parser`\ ---Access Python parse trees =========================================== .. module:: parser diff -r afe119a3619f Doc/library/pdb.rst --- a/Doc/library/pdb.rst +++ b/Doc/library/pdb.rst @@ -1,6 +1,6 @@ .. _debugger: -:mod:`pdb` --- The Python Debugger +:mod:`pdb`\ ---The Python Debugger ================================== .. module:: pdb @@ -20,7 +20,7 @@ module: bdb module: cmd -The debugger is extensible -- it is actually defined as the class :class:`Pdb`. +The debugger is extensible---it is actually defined as the class :class:`Pdb`. This is currently undocumented but easily understood by reading the source. The extension interface uses the modules :mod:`bdb` and :mod:`cmd`. @@ -372,7 +372,7 @@ frame. This lets you jump back and execute code again, or jump forward to skip code that you don't want to run. - It should be noted that not all jumps are allowed -- for instance it is not + It should be noted that not all jumps are allowed---for instance it is not possible to jump into the middle of a :keyword:`for` loop or out of a :keyword:`finally` clause. diff -r afe119a3619f Doc/library/pickle.rst --- a/Doc/library/pickle.rst +++ b/Doc/library/pickle.rst @@ -1,4 +1,4 @@ -:mod:`pickle` --- Python object serialization +:mod:`pickle`\ ---Python object serialization ============================================= .. index:: diff -r afe119a3619f Doc/library/pickletools.rst --- a/Doc/library/pickletools.rst +++ b/Doc/library/pickletools.rst @@ -1,4 +1,4 @@ -:mod:`pickletools` --- Tools for pickle developers +:mod:`pickletools`\ ---Tools for pickle developers ================================================== .. module:: pickletools diff -r afe119a3619f Doc/library/pipes.rst --- a/Doc/library/pipes.rst +++ b/Doc/library/pipes.rst @@ -1,4 +1,4 @@ -:mod:`pipes` --- Interface to shell pipelines +:mod:`pipes`\ ---Interface to shell pipelines ============================================= .. module:: pipes @@ -10,8 +10,8 @@ -------------- -The :mod:`pipes` module defines a class to abstract the concept of a *pipeline* ---- a sequence of converters from one file to another. +The :mod:`pipes` module defines a class to abstract the concept of a +*pipeline*\ ---a sequence of converters from one file to another. Because the module uses :program:`/bin/sh` command lines, a POSIX or compatible shell for :func:`os.system` and :func:`os.popen` is required. diff -r afe119a3619f Doc/library/pkgutil.rst --- a/Doc/library/pkgutil.rst +++ b/Doc/library/pkgutil.rst @@ -1,4 +1,4 @@ -:mod:`pkgutil` --- Package extension utility +:mod:`pkgutil`\ ---Package extension utility ============================================ .. module:: pkgutil diff -r afe119a3619f Doc/library/platform.rst --- a/Doc/library/platform.rst +++ b/Doc/library/platform.rst @@ -1,4 +1,4 @@ -:mod:`platform` --- Access to underlying platform's identifying data +:mod:`platform`\ ---Access to underlying platform's identifying data ===================================================================== .. module:: platform diff -r afe119a3619f Doc/library/plistlib.rst --- a/Doc/library/plistlib.rst +++ b/Doc/library/plistlib.rst @@ -1,4 +1,4 @@ -:mod:`plistlib` --- Generate and parse Mac OS X ``.plist`` files +:mod:`plistlib`\ ---Generate and parse Mac OS X ``.plist`` files ================================================================ .. module:: plistlib @@ -30,7 +30,7 @@ Values can be strings, integers, floats, booleans, tuples, lists, dictionaries (but only with string keys), :class:`Data` or :class:`datetime.datetime` -objects. String values (including dictionary keys) have to be unicode strings -- +objects. String values (including dictionary keys) have to be unicode strings --- they will be written out as UTF-8. The ```` plist type is supported through the :class:`Data` class. This is @@ -51,9 +51,9 @@ binary) file object. Return the unpacked root object (which usually is a dictionary). - The XML data is parsed using the Expat parser from :mod:`xml.parsers.expat` - -- see its documentation for possible exceptions on ill-formed XML. - Unknown elements will simply be ignored by the plist parser. + The XML data is parsed using the Expat parser from + :mod:`xml.parsers.expat`\ ---see its documentation for possible exceptions on + ill-formed XML. Unknown elements will simply be ignored by the plist parser. .. function:: writePlist(rootObject, pathOrFile) diff -r afe119a3619f Doc/library/poplib.rst --- a/Doc/library/poplib.rst +++ b/Doc/library/poplib.rst @@ -1,4 +1,4 @@ -:mod:`poplib` --- POP3 protocol client +:mod:`poplib`\ ---POP3 protocol client ====================================== .. module:: poplib @@ -43,7 +43,7 @@ This is a subclass of :class:`POP3` that connects to the server over an SSL encrypted socket. If *port* is not specified, 995, the standard POP3-over-SSL - port is used. *keyfile* and *certfile* are also optional - they can contain a + port is used. *keyfile* and *certfile* are also optional---they can contain a PEM formatted private key and certificate chain file for the SSL connection. *timeout* works as in the :class:`POP3` constructor. *context* parameter is a :class:`ssl.SSLContext` object which allows bundling SSL configuration diff -r afe119a3619f Doc/library/posix.rst --- a/Doc/library/posix.rst +++ b/Doc/library/posix.rst @@ -1,4 +1,4 @@ -:mod:`posix` --- The most common POSIX system calls +:mod:`posix`\ ---The most common POSIX system calls =================================================== .. module:: posix diff -r afe119a3619f Doc/library/pprint.rst --- a/Doc/library/pprint.rst +++ b/Doc/library/pprint.rst @@ -1,4 +1,4 @@ -:mod:`pprint` --- Data pretty printer +:mod:`pprint`\ ---Data pretty printer ===================================== .. module:: pprint diff -r afe119a3619f Doc/library/pty.rst --- a/Doc/library/pty.rst +++ b/Doc/library/pty.rst @@ -1,4 +1,4 @@ -:mod:`pty` --- Pseudo-terminal utilities +:mod:`pty`\ ---Pseudo-terminal utilities ======================================== .. module:: pty diff -r afe119a3619f Doc/library/pwd.rst --- a/Doc/library/pwd.rst +++ b/Doc/library/pwd.rst @@ -1,4 +1,4 @@ -:mod:`pwd` --- The password database +:mod:`pwd`\ ---The password database ==================================== .. module:: pwd diff -r afe119a3619f Doc/library/py_compile.rst --- a/Doc/library/py_compile.rst +++ b/Doc/library/py_compile.rst @@ -1,4 +1,4 @@ -:mod:`py_compile` --- Compile Python source files +:mod:`py_compile`\ ---Compile Python source files ================================================= .. module:: py_compile diff -r afe119a3619f Doc/library/pyclbr.rst --- a/Doc/library/pyclbr.rst +++ b/Doc/library/pyclbr.rst @@ -1,4 +1,4 @@ -:mod:`pyclbr` --- Python class browser support +:mod:`pyclbr`\ ---Python class browser support ============================================== .. module:: pyclbr diff -r afe119a3619f Doc/library/pydoc.rst --- a/Doc/library/pydoc.rst +++ b/Doc/library/pydoc.rst @@ -1,4 +1,4 @@ -:mod:`pydoc` --- Documentation generator and online help system +:mod:`pydoc`\ ---Documentation generator and online help system =============================================================== .. module:: pydoc diff -r afe119a3619f Doc/library/pyexpat.rst --- a/Doc/library/pyexpat.rst +++ b/Doc/library/pyexpat.rst @@ -1,4 +1,4 @@ -:mod:`xml.parsers.expat` --- Fast XML parsing using Expat +:mod:`xml.parsers.expat`\ ---Fast XML parsing using Expat ========================================================= .. module:: xml.parsers.expat diff -r afe119a3619f Doc/library/queue.rst --- a/Doc/library/queue.rst +++ b/Doc/library/queue.rst @@ -1,4 +1,4 @@ -:mod:`queue` --- A synchronized queue class +:mod:`queue`\ ---A synchronized queue class =========================================== .. module:: queue diff -r afe119a3619f Doc/library/quopri.rst --- a/Doc/library/quopri.rst +++ b/Doc/library/quopri.rst @@ -1,4 +1,4 @@ -:mod:`quopri` --- Encode and decode MIME quoted-printable data +:mod:`quopri`\ ---Encode and decode MIME quoted-printable data ============================================================== .. module:: quopri diff -r afe119a3619f Doc/library/random.rst --- a/Doc/library/random.rst +++ b/Doc/library/random.rst @@ -1,4 +1,4 @@ -:mod:`random` --- Generate pseudo-random numbers +:mod:`random`\ ---Generate pseudo-random numbers ================================================ .. module:: random @@ -36,7 +36,7 @@ Class :class:`Random` can also be subclassed if you want to use a different basic generator of your own devising: in that case, override the :meth:`random`, :meth:`seed`, :meth:`getstate`, and :meth:`setstate` methods. -Optionally, a new generator can supply a :meth:`getrandbits` method --- this +Optionally, a new generator can supply a :meth:`getrandbits` method---this allows :meth:`randrange` to produce selections over an arbitrarily large range. The :mod:`random` module also provides the :class:`SystemRandom` class which diff -r afe119a3619f Doc/library/re.rst --- a/Doc/library/re.rst +++ b/Doc/library/re.rst @@ -1,4 +1,4 @@ -:mod:`re` --- Regular expression operations +:mod:`re`\ ---Regular expression operations =========================================== .. module:: re diff -r afe119a3619f Doc/library/readline.rst --- a/Doc/library/readline.rst +++ b/Doc/library/readline.rst @@ -1,4 +1,4 @@ -:mod:`readline` --- GNU readline interface +:mod:`readline`\ ---GNU readline interface ========================================== .. module:: readline diff -r afe119a3619f Doc/library/reprlib.rst --- a/Doc/library/reprlib.rst +++ b/Doc/library/reprlib.rst @@ -1,4 +1,4 @@ -:mod:`reprlib` --- Alternate :func:`repr` implementation +:mod:`reprlib`\ ---Alternate :func:`repr` implementation ======================================================== .. module:: reprlib diff -r afe119a3619f Doc/library/resource.rst --- a/Doc/library/resource.rst +++ b/Doc/library/resource.rst @@ -1,4 +1,4 @@ -:mod:`resource` --- Resource usage information +:mod:`resource`\ ---Resource usage information ============================================== .. module:: resource @@ -80,7 +80,7 @@ The Unix man page for :manpage:`getrlimit(2)` lists the available resources. Note that not all systems use the same symbol or same value to denote the same -resource. This module does not attempt to mask platform differences --- symbols +resource. This module does not attempt to mask platform differences---symbols not defined for a platform will not be available from this module on that platform. diff -r afe119a3619f Doc/library/rlcompleter.rst --- a/Doc/library/rlcompleter.rst +++ b/Doc/library/rlcompleter.rst @@ -1,4 +1,4 @@ -:mod:`rlcompleter` --- Completion function for GNU readline +:mod:`rlcompleter`\ ---Completion function for GNU readline =========================================================== .. module:: rlcompleter diff -r afe119a3619f Doc/library/runpy.rst --- a/Doc/library/runpy.rst +++ b/Doc/library/runpy.rst @@ -1,4 +1,4 @@ -:mod:`runpy` --- Locating and executing Python modules +:mod:`runpy`\ ---Locating and executing Python modules ====================================================== .. module:: runpy @@ -14,7 +14,7 @@ line switch that allows scripts to be located using the Python module namespace rather than the filesystem. -Note that this is *not* a sandbox module - all code is executed in the +Note that this is *not* a sandbox module---all code is executed in the current process, and any side effects (such as cached imports of other modules) will remain in place after the functions have returned. @@ -47,7 +47,7 @@ The special global variables ``__name__``, ``__file__``, ``__cached__``, ``__loader__`` and ``__package__`` are set in the globals dictionary before the module - code is executed (Note that this is a minimal set of variables - other + code is executed (Note that this is a minimal set of variables---other variables may be set implicitly as an interpreter implementation detail). ``__name__`` is set to *run_name* if this optional argument is not @@ -110,7 +110,7 @@ The special global variables ``__name__``, ``__file__``, ``__loader__`` and ``__package__`` are set in the globals dictionary before the module - code is executed (Note that this is a minimal set of variables - other + code is executed (Note that this is a minimal set of variables---other variables may be set implicitly as an interpreter implementation detail). ``__name__`` is set to *run_name* if this optional argument is not @@ -143,12 +143,12 @@ .. seealso:: - :pep:`338` - Executing modules as scripts + :pep:`338`\ ---Executing modules as scripts PEP written and implemented by Nick Coghlan. - :pep:`366` - Main module explicit relative imports + :pep:`366`\ ---Main module explicit relative imports PEP written and implemented by Nick Coghlan. - :ref:`using-on-general` - CPython command line details + :ref:`using-on-general`\ ---CPython command line details The :func:`importlib.import_module` function diff -r afe119a3619f Doc/library/sched.rst --- a/Doc/library/sched.rst +++ b/Doc/library/sched.rst @@ -1,4 +1,4 @@ -:mod:`sched` --- Event scheduler +:mod:`sched`\ ---Event scheduler ================================ .. module:: sched @@ -17,7 +17,7 @@ .. class:: scheduler(timefunc=time.monotonic, delayfunc=time.sleep) The :class:`scheduler` class defines a generic interface to scheduling events. - It needs two functions to actually deal with the "outside world" --- *timefunc* + It needs two functions to actually deal with the "outside world"\ ---\ *timefunc* should be callable without arguments, and return a number (the "time", in any units whatsoever). If time.monotonic is not available, the *timefunc* default is time.time instead. The *delayfunc* function should be callable with one diff -r afe119a3619f Doc/library/select.rst --- a/Doc/library/select.rst +++ b/Doc/library/select.rst @@ -1,4 +1,4 @@ -:mod:`select` --- Waiting for I/O completion +:mod:`select`\ ---Waiting for I/O completion ============================================ .. module:: select @@ -190,7 +190,7 @@ Polls the set of registered file descriptors, and returns a possibly-empty list containing ``(fd, event)`` 2-tuples for the descriptors that have events or errors to report. *fd* is the file descriptor, and *event* is a bitmask with - bits set for the reported events for that descriptor --- :const:`POLLIN` for + bits set for the reported events for that descriptor---\ :const:`POLLIN` for waiting input, :const:`POLLOUT` to indicate that the descriptor can be written to, and so forth. An empty list indicates that the call timed out and no file descriptors had any events to report. If *timeout* is given, it specifies the @@ -344,7 +344,7 @@ Polls the set of registered file descriptors, and returns a possibly-empty list containing ``(fd, event)`` 2-tuples for the descriptors that have events or errors to report. *fd* is the file descriptor, and *event* is a bitmask with - bits set for the reported events for that descriptor --- :const:`POLLIN` for + bits set for the reported events for that descriptor---\ :const:`POLLIN` for waiting input, :const:`POLLOUT` to indicate that the descriptor can be written to, and so forth. An empty list indicates that the call timed out and no file descriptors had any events to report. If *timeout* is given, it specifies the diff -r afe119a3619f Doc/library/shelve.rst --- a/Doc/library/shelve.rst +++ b/Doc/library/shelve.rst @@ -1,4 +1,4 @@ -:mod:`shelve` --- Python object persistence +:mod:`shelve`\ ---Python object persistence =========================================== .. module:: shelve @@ -13,7 +13,7 @@ A "shelf" is a persistent, dictionary-like object. The difference with "dbm" databases is that the values (not the keys!) in a shelf can be essentially -arbitrary Python objects --- anything that the :mod:`pickle` module can handle. +arbitrary Python objects---anything that the :mod:`pickle` module can handle. This includes most class instances, recursive data types, and objects containing lots of shared sub-objects. The keys are ordinary strings. diff -r afe119a3619f Doc/library/shlex.rst --- a/Doc/library/shlex.rst +++ b/Doc/library/shlex.rst @@ -1,4 +1,4 @@ -:mod:`shlex` --- Simple lexical analysis +:mod:`shlex`\ ---Simple lexical analysis ======================================== .. module:: shlex diff -r afe119a3619f Doc/library/shutil.rst --- a/Doc/library/shutil.rst +++ b/Doc/library/shutil.rst @@ -1,4 +1,4 @@ -:mod:`shutil` --- High-level file operations +:mod:`shutil`\ ---High-level file operations ============================================ .. module:: shutil diff -r afe119a3619f Doc/library/signal.rst --- a/Doc/library/signal.rst +++ b/Doc/library/signal.rst @@ -1,4 +1,4 @@ -:mod:`signal` --- Set handlers for asynchronous events +:mod:`signal`\ ---Set handlers for asynchronous events ====================================================== .. module:: signal diff -r afe119a3619f Doc/library/site.rst --- a/Doc/library/site.rst +++ b/Doc/library/site.rst @@ -1,4 +1,4 @@ -:mod:`site` --- Site-specific configuration hook +:mod:`site`\ ---Site-specific configuration hook ================================================ .. module:: site @@ -241,4 +241,4 @@ .. seealso:: - :pep:`370` -- Per user site-packages directory + :pep:`370`\ ---Per user site-packages directory diff -r afe119a3619f Doc/library/smtpd.rst --- a/Doc/library/smtpd.rst +++ b/Doc/library/smtpd.rst @@ -1,4 +1,4 @@ -:mod:`smtpd` --- SMTP Server +:mod:`smtpd`\ ---SMTP Server ============================ .. module:: smtpd diff -r afe119a3619f Doc/library/smtplib.rst --- a/Doc/library/smtplib.rst +++ b/Doc/library/smtplib.rst @@ -1,4 +1,4 @@ -:mod:`smtplib` --- SMTP protocol client +:mod:`smtplib`\ ---SMTP protocol client ======================================= .. module:: smtplib @@ -166,11 +166,11 @@ .. seealso:: - :rfc:`821` - Simple Mail Transfer Protocol + :rfc:`821`\ ---Simple Mail Transfer Protocol Protocol definition for SMTP. This document covers the model, operating procedure, and protocol details for SMTP. - :rfc:`1869` - SMTP Service Extensions + :rfc:`1869`\ ---SMTP Service Extensions Definition of the ESMTP extensions for SMTP. This describes a framework for extending SMTP with new commands, supporting dynamic discovery of the commands provided by the server, and defines a few additional commands. diff -r afe119a3619f Doc/library/sndhdr.rst --- a/Doc/library/sndhdr.rst +++ b/Doc/library/sndhdr.rst @@ -1,4 +1,4 @@ -:mod:`sndhdr` --- Determine type of sound file +:mod:`sndhdr`\ ---Determine type of sound file ============================================== .. module:: sndhdr diff -r afe119a3619f Doc/library/socket.rst --- a/Doc/library/socket.rst +++ b/Doc/library/socket.rst @@ -1,4 +1,4 @@ -:mod:`socket` --- Low-level networking interface +:mod:`socket`\ ---Low-level networking interface ================================================ .. module:: socket @@ -734,7 +734,7 @@ .. method:: socket.bind(address) Bind the socket to *address*. The socket must not already be bound. (The format - of *address* depends on the address family --- see above.) + of *address* depends on the address family---see above.) .. method:: socket.close() @@ -753,7 +753,7 @@ .. method:: socket.connect(address) Connect to a remote socket at *address*. (The format of *address* depends on the - address family --- see above.) + address family---see above.) .. method:: socket.connect_ex(address) @@ -789,7 +789,7 @@ Return the remote address to which the socket is connected. This is useful to find out the port number of a remote IPv4/v6 socket, for instance. (The format - of the address returned depends on the address family --- see above.) On some + of the address returned depends on the address family---see above.) On some systems this function is not supported. @@ -797,7 +797,7 @@ Return the socket's own address. This is useful to find out the port number of an IPv4/v6 socket, for instance. (The format of the address returned depends on - the address family --- see above.) + the address family---see above.) .. method:: socket.getsockopt(level, optname[, buflen]) @@ -878,7 +878,7 @@ where *bytes* is a bytes object representing the data received and *address* is the address of the socket sending the data. See the Unix manual page :manpage:`recv(2)` for the meaning of the optional argument *flags*; it defaults - to zero. (The format of *address* depends on the address family --- see above.) + to zero. (The format of *address* depends on the address family---see above.) .. method:: socket.recvmsg(bufsize[, ancbufsize[, flags]]) @@ -991,7 +991,7 @@ the number of bytes received and *address* is the address of the socket sending the data. See the Unix manual page :manpage:`recv(2)` for the meaning of the optional argument *flags*; it defaults to zero. (The format of *address* - depends on the address family --- see above.) + depends on the address family---see above.) .. method:: socket.recv_into(buffer[, nbytes[, flags]]) @@ -1029,7 +1029,7 @@ Send data to the socket. The socket should not be connected to a remote socket, since the destination socket is specified by *address*. The optional *flags* argument has the same meaning as for :meth:`recv` above. Return the number of - bytes sent. (The format of *address* depends on the address family --- see + bytes sent. (The format of *address* depends on the address family---see above.) diff -r afe119a3619f Doc/library/socketserver.rst --- a/Doc/library/socketserver.rst +++ b/Doc/library/socketserver.rst @@ -1,4 +1,4 @@ -:mod:`socketserver` --- A framework for network servers +:mod:`socketserver`\ ---A framework for network servers ======================================================= .. module:: socketserver @@ -71,7 +71,7 @@ +-----------+ +--------------------+ Note that :class:`UnixDatagramServer` derives from :class:`UDPServer`, not from -:class:`UnixStreamServer` --- the only difference between an IP and a Unix +:class:`UnixStreamServer`\ ---the only difference between an IP and a Unix stream server is the address family, which is simply repeated in both Unix server classes. @@ -101,7 +101,7 @@ On the other hand, if you are building an HTTP server where all data is stored externally (for instance, in the file system), a synchronous class will -essentially render the service "deaf" while one request is being handled -- +essentially render the service "deaf" while one request is being handled --- which may be for a very long time if a client is slow to receive all the data it has requested. Here a threading or forking server is appropriate. diff -r afe119a3619f Doc/library/spwd.rst --- a/Doc/library/spwd.rst +++ b/Doc/library/spwd.rst @@ -1,4 +1,4 @@ -:mod:`spwd` --- The shadow password database +:mod:`spwd`\ ---The shadow password database ============================================ .. module:: spwd diff -r afe119a3619f Doc/library/sqlite3.rst --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -1,4 +1,4 @@ -:mod:`sqlite3` --- DB-API 2.0 interface for SQLite databases +:mod:`sqlite3`\ ---DB-API 2.0 interface for SQLite databases ============================================================ .. module:: sqlite3 @@ -92,14 +92,14 @@ .. seealso:: http://code.google.com/p/pysqlite/ - The pysqlite web page -- sqlite3 is developed externally under the name + The pysqlite web page---sqlite3 is developed externally under the name "pysqlite". http://www.sqlite.org The SQLite web page; the documentation describes the syntax and the available data types for the supported SQL dialect. - :pep:`249` - Database API Specification 2.0 + :pep:`249`\ ---Database API Specification 2.0 PEP written by Marc-André Lemburg. diff -r afe119a3619f Doc/library/ssl.rst --- a/Doc/library/ssl.rst +++ b/Doc/library/ssl.rst @@ -1,4 +1,4 @@ -:mod:`ssl` --- TLS/SSL wrapper for socket objects +:mod:`ssl`\ ---TLS/SSL wrapper for socket objects ================================================= .. module:: ssl @@ -350,12 +350,12 @@ :meth:`SSLContext.set_default_verify_paths`. The return value is a :term:`named tuple` ``DefaultVerifyPaths``: - * :attr:`cafile` - resolved path to cafile or None if the file doesn't exist, - * :attr:`capath` - resolved path to capath or None if the directory doesn't exist, - * :attr:`openssl_cafile_env` - OpenSSL's environment key that points to a cafile, - * :attr:`openssl_cafile` - hard coded path to a cafile, - * :attr:`openssl_capath_env` - OpenSSL's environment key that points to a capath, - * :attr:`openssl_capath` - hard coded path to a capath directory + * :attr:`cafile`\ ---resolved path to cafile or None if the file doesn't exist, + * :attr:`capath`\ ---resolved path to capath or None if the directory doesn't exist, + * :attr:`openssl_cafile_env`\ ---OpenSSL's environment key that points to a cafile, + * :attr:`openssl_cafile`\ ---hard coded path to a cafile, + * :attr:`openssl_capath_env`\ ---OpenSSL's environment key that points to a capath, + * :attr:`openssl_capath`\ ---hard coded path to a capath directory .. versionadded:: 3.4 @@ -903,7 +903,7 @@ Register a callback function that will be called after the TLS Client Hello handshake message has been received by the SSL/TLS server when the TLS client specifies a server name indication. The server name indication mechanism - is specified in :rfc:`6066` section 3 - Server Name Indication. + is specified in :rfc:`6066` section 3---Server Name Indication. Only one callback can be set per ``SSLContext``. If *server_name_callback* is ``None`` then the callback is disabled. Calling this function a diff -r afe119a3619f Doc/library/stat.rst --- a/Doc/library/stat.rst +++ b/Doc/library/stat.rst @@ -1,4 +1,4 @@ -:mod:`stat` --- Interpreting :func:`stat` results +:mod:`stat`\ ---Interpreting :func:`stat` results ================================================= .. module:: stat diff -r afe119a3619f Doc/library/stdtypes.rst --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -62,7 +62,7 @@ .. index:: single: true -All other values are considered true --- so objects of many types are always +All other values are considered true---so objects of many types are always true. .. index:: @@ -79,7 +79,7 @@ .. _boolean: -Boolean Operations --- :keyword:`and`, :keyword:`or`, :keyword:`not` +Boolean Operations---\ :keyword:`and`, :keyword:`or`, :keyword:`not` ==================================================================== .. index:: pair: Boolean; operations @@ -207,7 +207,7 @@ .. _typesnumeric: -Numeric Types --- :class:`int`, :class:`float`, :class:`complex` +Numeric Types---\ :class:`int`, :class:`float`, :class:`complex` ================================================================ .. index:: @@ -799,7 +799,7 @@ .. _typesseq: -Sequence Types --- :class:`list`, :class:`tuple`, :class:`range` +Sequence Types---\ :class:`list`, :class:`tuple`, :class:`range` ================================================================ There are three basic sequence types: lists, tuples, and range objects. @@ -1145,7 +1145,7 @@ .. method:: list.sort(*, key=None, reverse=None) This method sorts the list in place, using only ``<`` comparisons - between items. Exceptions are not suppressed - if any comparison operations + between items. Exceptions are not suppressed---if any comparison operations fail, the entire sort operation will fail (and the list will likely be left in a partially modified state). @@ -1168,9 +1168,9 @@ explicitly request a new sorted list instance). The :meth:`sort` method is guaranteed to be stable. A sort is stable if it - guarantees not to change the relative order of elements that compare equal - --- this is helpful for sorting in multiple passes (for example, sort by - department, then by salary grade). + guarantees not to change the relative order of elements that compare + equal---this is helpful for sorting in multiple passes (for example, sort + by department, then by salary grade). .. impl-detail:: @@ -1352,7 +1352,7 @@ .. _textseq: -Text Sequence Type --- :class:`str` +Text Sequence Type---\ :class:`str` =================================== Textual data in Python is handled with :class:`str` objects, or :dfn:`strings`. @@ -1364,7 +1364,7 @@ * Double quotes: ``"allows embedded 'single' quotes"``. * Triple quoted: ``'''Three single quotes'''``, ``"""Three double quotes"""`` -Triple quoted strings may span multiple lines - all associated whitespace will +Triple quoted strings may span multiple lines---all associated whitespace will be included in the string literal. String literals that are part of a single expression and have only whitespace @@ -2031,7 +2031,7 @@ +---------+---------------------------------------------------------------------+ A length modifier (``h``, ``l``, or ``L``) may be present, but is ignored as it -is not necessary for Python -- so e.g. ``%ld`` is identical to ``%d``. +is not necessary for Python---so e.g. ``%ld`` is identical to ``%d``. The conversion types are: @@ -2044,7 +2044,7 @@ +------------+-----------------------------------------------------+-------+ | ``'o'`` | Signed octal value. | \(1) | +------------+-----------------------------------------------------+-------+ -| ``'u'`` | Obsolete type -- it is identical to ``'d'``. | \(7) | +| ``'u'`` | Obsolete type---it is identical to ``'d'``. | \(7) | +------------+-----------------------------------------------------+-------+ | ``'x'`` | Signed hexadecimal (lowercase). | \(2) | +------------+-----------------------------------------------------+-------+ @@ -2131,7 +2131,7 @@ .. _binaryseq: -Binary Sequence Types --- :class:`bytes`, :class:`bytearray`, :class:`memoryview` +Binary Sequence Types---\ :class:`bytes`, :class:`bytearray`, :class:`memoryview` ================================================================================= .. index:: @@ -2210,7 +2210,7 @@ built-in binary data type) and Unicode strings were permitted. This was a backwards compatibility workaround to account for the fact that Python originally only supported 8-bit text, and Unicode text was a later - addition. In Python 3.x, those implicit conversions are gone - conversions + addition. In Python 3.x, those implicit conversions are gone---conversions between 8-bit binary data and Unicode text must be explicit, and bytes and string objects will always compare unequal. @@ -2786,7 +2786,7 @@ .. _types-set: -Set Types --- :class:`set`, :class:`frozenset` +Set Types---\ :class:`set`, :class:`frozenset` ============================================== .. index:: object: set @@ -2804,10 +2804,10 @@ other sequence-like behavior. There are currently two built-in set types, :class:`set` and :class:`frozenset`. -The :class:`set` type is mutable --- the contents can be changed using methods +The :class:`set` type is mutable---the contents can be changed using methods like :meth:`add` and :meth:`remove`. Since it is mutable, it has no hash value and cannot be used as either a dictionary key or as an element of another set. -The :class:`frozenset` type is immutable and :term:`hashable` --- its contents cannot be +The :class:`frozenset` type is immutable and :term:`hashable`\ ---its contents cannot be altered after it is created; it can therefore be used as a dictionary key or as an element of another set. @@ -2983,7 +2983,7 @@ .. _typesmapping: -Mapping Types --- :class:`dict` +Mapping Types---\ :class:`dict` =============================== .. index:: @@ -3303,7 +3303,7 @@ during execution of this method will replace any exception that occurred in the body of the :keyword:`with` statement. - The exception passed in should never be reraised explicitly - instead, this + The exception passed in should never be reraised explicitly---instead, this method should return a false value to indicate that the method completed successfully and does not want to suppress the raised exception. This allows context management code (such as ``contextlib.nested``) to easily detect whether diff -r afe119a3619f Doc/library/string.rst --- a/Doc/library/string.rst +++ b/Doc/library/string.rst @@ -1,4 +1,4 @@ -:mod:`string` --- Common string operations +:mod:`string`\ ---Common string operations ========================================== .. module:: string @@ -377,7 +377,7 @@ displayed after the decimal point for a floating point value formatted with ``'f'`` and ``'F'``, or before and after the decimal point for a floating point value formatted with ``'g'`` or ``'G'``. For non-number types the field -indicates the maximum field size - in other words, how many characters will be +indicates the maximum field size---in other words, how many characters will be used from the field content. The *precision* is not allowed for integer values. Finally, the *type* determines how the data should be presented. @@ -711,17 +711,17 @@ placeholder syntax, delimiter character, or the entire regular expression used to parse template strings. To do this, you can override these class attributes: -* *delimiter* -- This is the literal string describing a placeholder introducing +* *delimiter*\ ---This is the literal string describing a placeholder introducing delimiter. The default value is ``$``. Note that this should *not* be a regular expression, as the implementation will call :meth:`re.escape` on this string as needed. -* *idpattern* -- This is the regular expression describing the pattern for +* *idpattern*\ ---This is the regular expression describing the pattern for non-braced placeholders (the braces will be added automatically as appropriate). The default value is the regular expression ``[_a-z][_a-z0-9]*``. -* *flags* -- The regular expression flags that will be applied when compiling +* *flags*\ ---The regular expression flags that will be applied when compiling the regular expression used for recognizing substitutions. The default value is ``re.IGNORECASE``. Note that ``re.VERBOSE`` will always be added to the flags, so custom *idpattern*\ s must follow conventions for verbose regular @@ -735,16 +735,16 @@ groups correspond to the rules given above, along with the invalid placeholder rule: -* *escaped* -- This group matches the escape sequence, e.g. ``$$``, in the +* *escaped*\ ---This group matches the escape sequence, e.g. ``$$``, in the default pattern. -* *named* -- This group matches the unbraced placeholder name; it should not +* *named*\ ---This group matches the unbraced placeholder name; it should not include the delimiter in capturing group. -* *braced* -- This group matches the brace enclosed placeholder name; it should +* *braced*\ ---This group matches the brace enclosed placeholder name; it should not include either the delimiter or braces in the capturing group. -* *invalid* -- This group matches any other delimiter pattern (usually a single +* *invalid*\ ---This group matches any other delimiter pattern (usually a single delimiter), and it should appear last in the regular expression. diff -r afe119a3619f Doc/library/stringprep.rst --- a/Doc/library/stringprep.rst +++ b/Doc/library/stringprep.rst @@ -1,4 +1,4 @@ -:mod:`stringprep` --- Internet String Preparation +:mod:`stringprep`\ ---Internet String Preparation ================================================= .. module:: stringprep diff -r afe119a3619f Doc/library/struct.rst --- a/Doc/library/struct.rst +++ b/Doc/library/struct.rst @@ -1,4 +1,4 @@ -:mod:`struct` --- Interpret bytes as packed binary data +:mod:`struct`\ ---Interpret bytes as packed binary data ======================================================= .. module:: struct diff -r afe119a3619f Doc/library/subprocess.rst --- a/Doc/library/subprocess.rst +++ b/Doc/library/subprocess.rst @@ -1,4 +1,4 @@ -:mod:`subprocess` --- Subprocess management +:mod:`subprocess`\ ---Subprocess management =========================================== .. module:: subprocess @@ -19,7 +19,7 @@ .. seealso:: - :pep:`324` -- PEP proposing the subprocess module + :pep:`324`\ ---PEP proposing the subprocess module Using the :mod:`subprocess` Module @@ -38,7 +38,7 @@ The arguments shown above are merely the most common ones, described below in :ref:`frequently-used-arguments` (hence the use of keyword-only notation in the abbreviated signature). The full function signature is largely the - same as that of the :class:`Popen` constructor - this function passes all + same as that of the :class:`Popen` constructor---this function passes all supplied arguments other than *timeout* directly through to that interface. The *timeout* argument is passed to :meth:`Popen.wait`. If the timeout @@ -81,7 +81,7 @@ The arguments shown above are merely the most common ones, described below in :ref:`frequently-used-arguments` (hence the use of keyword-only notation in the abbreviated signature). The full function signature is largely the - same as that of the :class:`Popen` constructor - this function passes all + same as that of the :class:`Popen` constructor---this function passes all supplied arguments other than *timeout* directly through to that interface. The *timeout* argument is passed to :meth:`Popen.wait`. If the timeout @@ -128,7 +128,7 @@ The arguments shown above are merely the most common ones, described below in :ref:`frequently-used-arguments` (hence the use of keyword-only notation in the abbreviated signature). The full function signature is largely the - same as that of the :class:`Popen` constructor - this functions passes all + same as that of the :class:`Popen` constructor---this functions passes all supplied arguments other than *input* and *timeout* directly through to that interface. In addition, *stdout* is not permitted as an argument, as it is used internally to collect the output from the subprocess. diff -r afe119a3619f Doc/library/sunau.rst --- a/Doc/library/sunau.rst +++ b/Doc/library/sunau.rst @@ -1,4 +1,4 @@ -:mod:`sunau` --- Read and write Sun AU files +:mod:`sunau`\ ---Read and write Sun AU files ============================================ .. module:: sunau diff -r afe119a3619f Doc/library/symbol.rst --- a/Doc/library/symbol.rst +++ b/Doc/library/symbol.rst @@ -1,4 +1,4 @@ -:mod:`symbol` --- Constants used with Python parse trees +:mod:`symbol`\ ---Constants used with Python parse trees ======================================================== .. module:: symbol diff -r afe119a3619f Doc/library/symtable.rst --- a/Doc/library/symtable.rst +++ b/Doc/library/symtable.rst @@ -1,4 +1,4 @@ -:mod:`symtable` --- Access to the compiler's symbol tables +:mod:`symtable`\ ---Access to the compiler's symbol tables ========================================================== .. module:: symtable diff -r afe119a3619f Doc/library/sys.rst --- a/Doc/library/sys.rst +++ b/Doc/library/sys.rst @@ -1,4 +1,4 @@ -:mod:`sys` --- System-specific parameters and functions +:mod:`sys`\ ---System-specific parameters and functions ======================================================= .. module:: sys @@ -692,9 +692,9 @@ .. function:: intern(string) - Enter *string* in the table of "interned" strings and return the interned string - -- which is *string* itself or a copy. Interning strings is useful to gain a - little performance on dictionary lookup -- if the keys in a dictionary are + Enter *string* in the table of "interned" strings and return the interned + string---which is *string* itself or a copy. Interning strings is useful to gain a + little performance on dictionary lookup---if the keys in a dictionary are interned, and the lookup key is interned, the key comparisons (after hashing) can be done by a pointer compare instead of a string compare. Normally, the names used in Python programs are automatically interned, and the dictionaries @@ -1211,5 +1211,5 @@ .. rubric:: Citations -.. [C99] ISO/IEC 9899:1999. "Programming languages -- C." A public draft of this standard is available at http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1256.pdf . +.. [C99] ISO/IEC 9899:1999. "Programming languages---C." A public draft of this standard is available at http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1256.pdf . diff -r afe119a3619f Doc/library/sysconfig.rst --- a/Doc/library/sysconfig.rst +++ b/Doc/library/sysconfig.rst @@ -1,4 +1,4 @@ -:mod:`sysconfig` --- Provide access to Python's configuration information +:mod:`sysconfig`\ ---Provide access to Python's configuration information ========================================================================= .. module:: sysconfig @@ -189,7 +189,7 @@ - win-amd64 (64bit Windows on AMD64 (aka x86_64, Intel64, EM64T, etc) - win-ia64 (64bit Windows on Itanium) - - win32 (all others - specifically, sys.platform is returned) + - win32 (all others---specifically, sys.platform is returned) Mac OS X can return: diff -r afe119a3619f Doc/library/syslog.rst --- a/Doc/library/syslog.rst +++ b/Doc/library/syslog.rst @@ -1,4 +1,4 @@ -:mod:`syslog` --- Unix syslog library routines +:mod:`syslog`\ ---Unix syslog library routines ============================================== .. module:: syslog @@ -40,7 +40,7 @@ The optional *ident* keyword argument is a string which is prepended to every message, and defaults to ``sys.argv[0]`` with leading path components stripped. The optional *logoption* keyword argument (default is 0) is a bit - field -- see below for possible values to combine. The optional *facility* + field---see below for possible values to combine. The optional *facility* keyword argument (default is :const:`LOG_USER`) sets the default facility for messages which do not have a facility explicitly encoded. diff -r afe119a3619f Doc/library/tabnanny.rst --- a/Doc/library/tabnanny.rst +++ b/Doc/library/tabnanny.rst @@ -1,4 +1,4 @@ -:mod:`tabnanny` --- Detection of ambiguous indentation +:mod:`tabnanny`\ ---Detection of ambiguous indentation ====================================================== .. module:: tabnanny diff -r afe119a3619f Doc/library/tarfile.rst --- a/Doc/library/tarfile.rst +++ b/Doc/library/tarfile.rst @@ -1,4 +1,4 @@ -:mod:`tarfile` --- Read and write tar archive files +:mod:`tarfile`\ ---Read and write tar archive files =================================================== .. module:: tarfile diff -r afe119a3619f Doc/library/telnetlib.rst --- a/Doc/library/telnetlib.rst +++ b/Doc/library/telnetlib.rst @@ -1,4 +1,4 @@ -:mod:`telnetlib` --- Telnet client +:mod:`telnetlib`\ ---Telnet client ================================== .. module:: telnetlib @@ -46,7 +46,7 @@ .. seealso:: - :rfc:`854` - Telnet Protocol Specification + :rfc:`854`\ ---Telnet Protocol Specification Definition of the Telnet protocol. diff -r afe119a3619f Doc/library/tempfile.rst --- a/Doc/library/tempfile.rst +++ b/Doc/library/tempfile.rst @@ -1,4 +1,4 @@ -:mod:`tempfile` --- Generate temporary files and directories +:mod:`tempfile`\ ---Generate temporary files and directories ============================================================ .. sectionauthor:: Zack Weinberg diff -r afe119a3619f Doc/library/termios.rst --- a/Doc/library/termios.rst +++ b/Doc/library/termios.rst @@ -1,4 +1,4 @@ -:mod:`termios` --- POSIX style tty control +:mod:`termios`\ ---POSIX style tty control ========================================== .. module:: termios diff -r afe119a3619f Doc/library/test.rst --- a/Doc/library/test.rst +++ b/Doc/library/test.rst @@ -1,4 +1,4 @@ -:mod:`test` --- Regression tests package for Python +:mod:`test`\ ---Regression tests package for Python =================================================== .. module:: test @@ -188,7 +188,7 @@ regression tests. -:mod:`test.support` --- Utilities for the Python test suite +:mod:`test.support`\ ---Utilities for the Python test suite =========================================================== .. module:: test.support diff -r afe119a3619f Doc/library/textwrap.rst --- a/Doc/library/textwrap.rst +++ b/Doc/library/textwrap.rst @@ -1,4 +1,4 @@ -:mod:`textwrap` --- Text wrapping and filling +:mod:`textwrap`\ ---Text wrapping and filling ============================================= .. module:: textwrap diff -r afe119a3619f Doc/library/threading.rst --- a/Doc/library/threading.rst +++ b/Doc/library/threading.rst @@ -1,4 +1,4 @@ -:mod:`threading` --- Thread-based parallelism +:mod:`threading`\ ---Thread-based parallelism ============================================= .. module:: threading @@ -87,7 +87,7 @@ stack space for the interpreter itself. Note that some platforms may have particular restrictions on values for the stack size, such as requiring a minimum stack size > 32 KiB or requiring allocation in multiples of the system - memory page size - platform documentation should be referred to for more + memory page size---platform documentation should be referred to for more information (4 KiB pages are common; using multiples of 4096 for the stack size is the suggested approach in the absence of more specific information). Availability: Windows, systems with POSIX threads. @@ -157,7 +157,7 @@ method in a separate thread of control. Once the thread's activity is started, the thread is considered 'alive'. It -stops being alive when its :meth:`~Thread.run` method terminates -- either +stops being alive when its :meth:`~Thread.run` method terminates---either normally, or by raising an unhandled exception. The :meth:`~Thread.is_alive` method tests whether the thread is alive. @@ -245,15 +245,15 @@ .. method:: join(timeout=None) Wait until the thread terminates. This blocks the calling thread until - the thread whose :meth:`~Thread.join` method is called terminates -- either - normally or through an unhandled exception --, or until the optional + the thread whose :meth:`~Thread.join` method is called terminates---either + normally or through an unhandled exception---or until the optional timeout occurs. When the *timeout* argument is present and not ``None``, it should be a floating point number specifying a timeout for the operation in seconds (or fractions thereof). As :meth:`~Thread.join` always returns ``None``, you must call :meth:`~Thread.is_alive` after :meth:`~Thread.join` to - decide whether a timeout happened -- if the thread is still alive, the + decide whether a timeout happened---if the thread is still alive, the :meth:`~Thread.join` call timed out. When the *timeout* argument is not present or ``None``, the operation will @@ -822,7 +822,7 @@ ------------- This class represents an action that should be run only after a certain amount -of time has passed --- a timer. :class:`Timer` is a subclass of :class:`Thread` +of time has passed---a timer. :class:`Timer` is a subclass of :class:`Thread` and as such also functions as an example of creating custom threads. Timers are started, as with threads, by calling their :meth:`start` method. The @@ -900,7 +900,7 @@ provided, it is used in preference to any that was supplied to the class constructor. - The return value is an integer in the range 0 to *parties* -- 1, different + The return value is an integer in the range 0 to *parties*\ ---1, different for each thread. This can be used to select a thread to do some special housekeeping, e.g.:: diff -r afe119a3619f Doc/library/time.rst --- a/Doc/library/time.rst +++ b/Doc/library/time.rst @@ -1,4 +1,4 @@ -:mod:`time` --- Time access and conversions +:mod:`time`\ ---Time access and conversions =========================================== .. module:: time diff -r afe119a3619f Doc/library/timeit.rst --- a/Doc/library/timeit.rst +++ b/Doc/library/timeit.rst @@ -1,4 +1,4 @@ -:mod:`timeit` --- Measure execution time of small code snippets +:mod:`timeit`\ ---Measure execution time of small code snippets =============================================================== .. module:: timeit diff -r afe119a3619f Doc/library/tkinter.rst --- a/Doc/library/tkinter.rst +++ b/Doc/library/tkinter.rst @@ -1,4 +1,4 @@ -:mod:`tkinter` --- Python interface to Tcl/Tk +:mod:`tkinter`\ ---Python interface to Tcl/Tk ============================================= .. module:: tkinter @@ -355,7 +355,7 @@ _tkinter (C) These commands and their arguments will be passed to a C function in the - :mod:`_tkinter` - note the underscore - extension module. + :mod:`_tkinter`\ ---note the underscore---extension module. Tk Widgets (C and Tcl) This C function is able to make calls into other C modules, including the C @@ -456,10 +456,10 @@ The packer is one of Tk's geometry-management mechanisms. Geometry managers are used to specify the relative positioning of the positioning of widgets -within their container - their mutual *master*. In contrast to the more +within their container---their mutual *master*. In contrast to the more cumbersome *placer* (which is used less commonly, and we do not cover here), the -packer takes qualitative relationship specification - *above*, *to the left of*, -*filling*, etc - and works everything out to determine the exact placement +packer takes qualitative relationship specification---\ *above*, *to the left of*, +*filling*, etc---and works everything out to determine the exact placement coordinates for you. The size of any *master* widget is determined by the size of the "slave widgets" @@ -500,10 +500,10 @@ Legal values: ``'x'``, ``'y'``, ``'both'``, ``'none'``. ipadx and ipady - A distance - designating internal padding on each side of the slave widget. + A distance---designating internal padding on each side of the slave widget. padx and pady - A distance - designating external padding on each side of the slave widget. + A distance---designating external padding on each side of the slave widget. side Legal values are: ``'left'``, ``'right'``, ``'top'``, ``'bottom'``. diff -r afe119a3619f Doc/library/tkinter.scrolledtext.rst --- a/Doc/library/tkinter.scrolledtext.rst +++ b/Doc/library/tkinter.scrolledtext.rst @@ -1,4 +1,4 @@ -:mod:`tkinter.scrolledtext` --- Scrolled Text Widget +:mod:`tkinter.scrolledtext`\ ---Scrolled Text Widget ==================================================== .. module:: tkinter.scrolledtext diff -r afe119a3619f Doc/library/tkinter.tix.rst --- a/Doc/library/tkinter.tix.rst +++ b/Doc/library/tkinter.tix.rst @@ -1,4 +1,4 @@ -:mod:`tkinter.tix` --- Extension widgets for Tk +:mod:`tkinter.tix`\ ---Extension widgets for Tk =============================================== .. module:: tkinter.tix diff -r afe119a3619f Doc/library/tkinter.ttk.rst --- a/Doc/library/tkinter.ttk.rst +++ b/Doc/library/tkinter.ttk.rst @@ -1,4 +1,4 @@ -:mod:`tkinter.ttk` --- Tk themed widgets +:mod:`tkinter.ttk`\ ---Tk themed widgets ======================================== .. module:: tkinter.ttk diff -r afe119a3619f Doc/library/token.rst --- a/Doc/library/token.rst +++ b/Doc/library/token.rst @@ -1,4 +1,4 @@ -:mod:`token` --- Constants used with Python parse trees +:mod:`token`\ ---Constants used with Python parse trees ======================================================= .. module:: token diff -r afe119a3619f Doc/library/tokenize.rst --- a/Doc/library/tokenize.rst +++ b/Doc/library/tokenize.rst @@ -1,4 +1,4 @@ -:mod:`tokenize` --- Tokenizer for Python source +:mod:`tokenize`\ ---Tokenizer for Python source =============================================== .. module:: tokenize diff -r afe119a3619f Doc/library/trace.rst --- a/Doc/library/trace.rst +++ b/Doc/library/trace.rst @@ -1,4 +1,4 @@ -:mod:`trace` --- Trace or track Python statement execution +:mod:`trace`\ ---Trace or track Python statement execution ========================================================== .. module:: trace diff -r afe119a3619f Doc/library/traceback.rst --- a/Doc/library/traceback.rst +++ b/Doc/library/traceback.rst @@ -1,4 +1,4 @@ -:mod:`traceback` --- Print or retrieve a stack traceback +:mod:`traceback`\ ---Print or retrieve a stack traceback ======================================================== .. module:: traceback @@ -13,7 +13,7 @@ .. index:: object: traceback -The module uses traceback objects --- this is the object type that is stored in +The module uses traceback objects---this is the object type that is stored in the :data:`sys.last_traceback` variable and returned as the third item from :func:`sys.exc_info`. diff -r afe119a3619f Doc/library/tty.rst --- a/Doc/library/tty.rst +++ b/Doc/library/tty.rst @@ -1,4 +1,4 @@ -:mod:`tty` --- Terminal control functions +:mod:`tty`\ ---Terminal control functions ========================================= .. module:: tty diff -r afe119a3619f Doc/library/turtle.rst --- a/Doc/library/turtle.rst +++ b/Doc/library/turtle.rst @@ -1,5 +1,5 @@ ================================= -:mod:`turtle` --- Turtle graphics +:mod:`turtle`\ ---Turtle graphics ================================= .. module:: turtle @@ -426,7 +426,7 @@ .. function:: home() - Move turtle to the origin -- coordinates (0,0) -- and set its heading to + Move turtle to the origin---coordinates (0,0)\ ---and set its heading to its start-orientation (which depends on the mode, see :func:`mode`). .. doctest:: @@ -455,7 +455,7 @@ :param steps: an integer (or ``None``) Draw a circle with given *radius*. The center is *radius* units left of - the turtle; *extent* -- an angle -- determines which part of the circle + the turtle; *extent*\ ---an angle---determines which part of the circle is drawn. If *extent* is not given, draw the entire circle. If *extent* is not a full circle, one endpoint of the arc is the current pen position. Draw the arc in counterclockwise direction if *radius* is @@ -635,7 +635,7 @@ Return the angle between the line from turtle position to position specified by (x,y), the vector or the other turtle. This depends on the turtle's start - orientation which depends on the mode - "standard"/"world" or "logo"). + orientation which depends on the mode---"standard"/"world" or "logo"). .. doctest:: @@ -766,14 +766,14 @@ pd() down() - Pull the pen down -- drawing when moving. + Pull the pen down---drawing when moving. .. function:: penup() pu() up() - Pull the pen up -- no drawing when moving. + Pull the pen up---no drawing when moving. .. function:: pensize(width=None) @@ -1053,7 +1053,7 @@ :param align: one of the strings "left", "center" or right" :param font: a triple (fontname, fontsize, fonttype) - Write text - the string representation of *arg* - at the current turtle + Write text---the string representation of *arg*\ ---at the current turtle position according to *align* ("left", "center" or right") and with the given font. If *move* is True, the pen is moved to the bottom-right corner of the text. By default, *move* is False. @@ -1306,7 +1306,7 @@ :param fun: a function with two arguments which will be called with the coordinates of the clicked point on the canvas :param num: number of the mouse-button, defaults to 1 (left mouse button) - :param add: ``True`` or ``False`` -- if ``True``, a new binding will be + :param add: ``True`` or ``False``\ ---if ``True``, a new binding will be added, otherwise it will replace a former binding Bind *fun* to mouse-click events on this turtle. If *fun* is ``None``, @@ -1327,7 +1327,7 @@ :param fun: a function with two arguments which will be called with the coordinates of the clicked point on the canvas :param num: number of the mouse-button, defaults to 1 (left mouse button) - :param add: ``True`` or ``False`` -- if ``True``, a new binding will be + :param add: ``True`` or ``False``\ ---if ``True``, a new binding will be added, otherwise it will replace a former binding Bind *fun* to mouse-button-release events on this turtle. If *fun* is @@ -1351,7 +1351,7 @@ :param fun: a function with two arguments which will be called with the coordinates of the clicked point on the canvas :param num: number of the mouse-button, defaults to 1 (left mouse button) - :param add: ``True`` or ``False`` -- if ``True``, a new binding will be + :param add: ``True`` or ``False``\ ---if ``True``, a new binding will be added, otherwise it will replace a former binding Bind *fun* to mouse-move events on this turtle. If *fun* is ``None``, @@ -1732,7 +1732,7 @@ :param fun: a function with two arguments which will be called with the coordinates of the clicked point on the canvas :param num: number of the mouse-button, defaults to 1 (left mouse button) - :param add: ``True`` or ``False`` -- if ``True``, a new binding will be + :param add: ``True`` or ``False``\ ---if ``True``, a new binding will be added, otherwise it will replace a former binding Bind *fun* to mouse-click events on this screen. If *fun* is ``None``, @@ -1775,10 +1775,10 @@ .. function:: mainloop() done() - Starts event loop - calling Tkinter's mainloop function. + Starts event loop---calling Tkinter's mainloop function. Must be the last statement in a turtle graphics program. Must *not* be used if a script is run from within IDLE in -n mode - (No subprocess) - for interactive use of turtle graphics. :: + (No subprocess)\ ---for interactive use of turtle graphics. :: >>> screen.mainloop() @@ -2132,7 +2132,7 @@ Help on method penup in module turtle: penup(self) unbound turtle.Turtle method - Pull the pen up -- no drawing when moving. + Pull the pen up---no drawing when moving. Aliases: penup | pu | up @@ -2165,7 +2165,7 @@ Help on function penup in module turtle: penup() - Pull the pen up -- no drawing when moving. + Pull the pen up---no drawing when moving. Aliases: penup | pu | up diff -r afe119a3619f Doc/library/types.rst --- a/Doc/library/types.rst +++ b/Doc/library/types.rst @@ -1,4 +1,4 @@ -:mod:`types` --- Dynamic type creation and names for built-in types +:mod:`types`\ ---Dynamic type creation and names for built-in types =================================================================== .. module:: types @@ -57,7 +57,7 @@ :ref:`metaclasses` Full details of the class creation process supported by these functions - :pep:`3115` - Metaclasses in Python 3000 + :pep:`3115`\ ---Metaclasses in Python 3000 Introduced the ``__prepare__`` namespace hook diff -r afe119a3619f Doc/library/unicodedata.rst --- a/Doc/library/unicodedata.rst +++ b/Doc/library/unicodedata.rst @@ -1,4 +1,4 @@ -:mod:`unicodedata` --- Unicode Database +:mod:`unicodedata`\ ---Unicode Database ======================================= .. module:: unicodedata diff -r afe119a3619f Doc/library/unittest.mock-examples.rst --- a/Doc/library/unittest.mock-examples.rst +++ b/Doc/library/unittest.mock-examples.rst @@ -1,4 +1,4 @@ -:mod:`unittest.mock` --- getting started +:mod:`unittest.mock`\ ---getting started ======================================== .. moduleauthor:: Michael Foord @@ -131,7 +131,7 @@ Often you want to track more than a single call to a method. The :attr:`~Mock.mock_calls` attribute records all calls -to child attributes of the mock - and also to their children. +to child attributes of the mock---and also to their children. >>> mock = MagicMock() >>> mock.method() @@ -261,7 +261,7 @@ implementation of your mocks rather than your real code. Suppose you have a class that implements `some_method`. In a test for another class, you provide a mock of this object that *also* provides `some_method`. If later -you refactor the first class, so that it no longer has `some_method` - then +you refactor the first class, so that it no longer has `some_method`\ ---then your tests will continue to pass even though your code is now broken! `Mock` allows you to provide an object as a specification for the mock, diff -r afe119a3619f Doc/library/unittest.mock.rst --- a/Doc/library/unittest.mock.rst +++ b/Doc/library/unittest.mock.rst @@ -1,5 +1,5 @@ -:mod:`unittest.mock` --- mock object library +:mod:`unittest.mock`\ ---mock object library ============================================ .. module:: unittest.mock @@ -751,7 +751,7 @@ Mock objects are callable. The call will return the value set as the :attr:`~Mock.return_value` attribute. The default return value is a new Mock object; it is created the first time the return value is accessed (either -explicitly or by calling the Mock) - but it is stored and the same one +explicitly or by calling the Mock)\ ---but it is stored and the same one returned each time. Calls made to the object will be recorded in the attributes @@ -2232,7 +2232,7 @@ attributes or methods on it. As `None` is *never* going to be useful as a spec, and probably indicates a member that will normally of some other type, `autospec` doesn't use a spec for members that are set to `None`. These will -just be ordinary mocks (well - `MagicMocks`): +just be ordinary mocks (well---\ `MagicMocks`): >>> class Something: ... member = None @@ -2246,7 +2246,7 @@ spec rather than the class. The other is to create a subclass of the production class and add the defaults to the subclass without affecting the production class. Both of these require you to use an alternative object as -the spec. Thankfully `patch` supports this - you can simply pass the +the spec. Thankfully `patch` supports this---you can simply pass the alternative object as the `autospec` argument: >>> class Something: @@ -2264,5 +2264,5 @@ .. [#] This only applies to classes or already instantiated objects. Calling a mocked class to create a mock instance *does not* create a real instance. - It is only attribute lookups - along with calls to `dir` - that are done. - + It is only attribute lookups---along with calls to `dir`\ ---that are done. + diff -r afe119a3619f Doc/library/unittest.rst --- a/Doc/library/unittest.rst +++ b/Doc/library/unittest.rst @@ -1,4 +1,4 @@ -:mod:`unittest` --- Unit testing framework +:mod:`unittest`\ ---Unit testing framework ========================================== .. module:: unittest @@ -312,7 +312,7 @@ Organizing test code -------------------- -The basic building blocks of unit testing are :dfn:`test cases` --- single +The basic building blocks of unit testing are :dfn:`test cases`\ ---single scenarios that must be set up and checked for correctness. In :mod:`unittest`, test cases are represented by :class:`unittest.TestCase` instances. To make your own test cases you must write subclasses of @@ -1148,7 +1148,7 @@ equal. *function* must take two positional arguments and a third msg=None keyword argument just as :meth:`assertEqual` does. It must raise :data:`self.failureException(msg) ` when inequality - between the first two parameters is detected -- possibly providing useful + between the first two parameters is detected---possibly providing useful information and explaining the inequalities in details in the error message. diff -r afe119a3619f Doc/library/urllib.error.rst --- a/Doc/library/urllib.error.rst +++ b/Doc/library/urllib.error.rst @@ -1,4 +1,4 @@ -:mod:`urllib.error` --- Exception classes raised by urllib.request +:mod:`urllib.error`\ ---Exception classes raised by urllib.request ================================================================== .. module:: urllib.error diff -r afe119a3619f Doc/library/urllib.parse.rst --- a/Doc/library/urllib.parse.rst +++ b/Doc/library/urllib.parse.rst @@ -1,4 +1,4 @@ -:mod:`urllib.parse` --- Parse URLs into components +:mod:`urllib.parse`\ ---Parse URLs into components ================================================== .. module:: urllib.parse @@ -436,8 +436,8 @@ Replace special characters in *string* using the ``%xx`` escape. Letters, digits, and the characters ``'_.-'`` are never quoted. By default, this function is intended for quoting the path section of URL. The optional *safe* - parameter specifies additional ASCII characters that should not be quoted - --- its default value is ``'/'``. + parameter specifies additional ASCII characters that should not be + quoted---its default value is ``'/'``. *string* may be either a :class:`str` or a :class:`bytes`. @@ -546,26 +546,26 @@ .. seealso:: - :rfc:`3986` - Uniform Resource Identifiers + :rfc:`3986`\ ---Uniform Resource Identifiers This is the current standard (STD66). Any changes to urllib.parse module should conform to this. Certain deviations could be observed, which are mostly for backward compatibility purposes and for certain de-facto parsing requirements as commonly observed in major browsers. - :rfc:`2732` - Format for Literal IPv6 Addresses in URL's. + :rfc:`2732`\ ---Format for Literal IPv6 Addresses in URL's. This specifies the parsing requirements of IPv6 URLs. - :rfc:`2396` - Uniform Resource Identifiers (URI): Generic Syntax + :rfc:`2396`\ ---Uniform Resource Identifiers (URI): Generic Syntax Document describing the generic syntactic requirements for both Uniform Resource Names (URNs) and Uniform Resource Locators (URLs). - :rfc:`2368` - The mailto URL scheme. + :rfc:`2368`\ ---The mailto URL scheme. Parsing requirements for mailto url schemes. - :rfc:`1808` - Relative Uniform Resource Locators + :rfc:`1808`\ ---Relative Uniform Resource Locators This Request For Comments includes the rules for joining an absolute and a relative URL, including a fair number of "Abnormal Examples" which govern the treatment of border cases. - :rfc:`1738` - Uniform Resource Locators (URL) + :rfc:`1738`\ ---Uniform Resource Locators (URL) This specifies the formal syntax and semantics of absolute URLs. diff -r afe119a3619f Doc/library/urllib.request.rst --- a/Doc/library/urllib.request.rst +++ b/Doc/library/urllib.request.rst @@ -1,4 +1,4 @@ -:mod:`urllib.request` --- Extensible library for opening URLs +:mod:`urllib.request`\ ---Extensible library for opening URLs ============================================================= .. module:: urllib.request @@ -9,7 +9,7 @@ The :mod:`urllib.request` module defines functions and classes which help in -opening URLs (mostly HTTP) in a complex world --- basic and digest +opening URLs (mostly HTTP) in a complex world---basic and digest authentication, redirections, cookies and more. @@ -72,14 +72,14 @@ returns a :class:`urllib.response.addinfourl` object which can work as :term:`context manager` and has methods such as - * :meth:`~urllib.response.addinfourl.geturl` --- return the URL of the resource retrieved, + * :meth:`~urllib.response.addinfourl.geturl`\ ---return the URL of the resource retrieved, commonly used to determine if a redirect was followed - * :meth:`~urllib.response.addinfourl.info` --- return the meta-information of the page, such as headers, + * :meth:`~urllib.response.addinfourl.info`\ ---return the meta-information of the page, such as headers, in the form of an :func:`email.message_from_string` instance (see `Quick Reference to HTTP Headers `_) - * :meth:`~urllib.response.addinfourl.getcode` -- return the HTTP status code of the response. + * :meth:`~urllib.response.addinfourl.getcode`\ ---return the HTTP status code of the response. Raises :exc:`URLError` on errors. @@ -189,7 +189,7 @@ *headers* should be a dictionary, and will be treated as if :meth:`add_header` was called with each key and value as arguments. This is often used to "spoof" the ``User-Agent`` header, which is - used by a browser to identify itself -- some HTTP servers only + used by a browser to identify itself---some HTTP servers only allow requests coming from common browsers as opposed to scripts. For example, Mozilla Firefox may identify itself as ``"Mozilla/5.0 (X11; U; Linux i686) Gecko/20071127 Firefox/2.0.0.11"``, while @@ -233,7 +233,7 @@ .. class:: BaseHandler() - This is the base class for all registered handlers --- and handles only the + This is the base class for all registered handlers---and handles only the simple mechanics of registration. @@ -529,19 +529,19 @@ are searched, and added to the possible chains (note that HTTP errors are a special case). - * :meth:`protocol_open` --- signal that the handler knows how to open *protocol* + * :meth:`protocol_open`\ ---signal that the handler knows how to open *protocol* URLs. - * :meth:`http_error_type` --- signal that the handler knows how to handle HTTP + * :meth:`http_error_type`\ ---signal that the handler knows how to handle HTTP errors with HTTP error code *type*. - * :meth:`protocol_error` --- signal that the handler knows how to handle errors + * :meth:`protocol_error`\ ---signal that the handler knows how to handle errors from (non-\ ``http``) *protocol*. - * :meth:`protocol_request` --- signal that the handler knows how to pre-process + * :meth:`protocol_request`\ ---signal that the handler knows how to pre-process *protocol* requests. - * :meth:`protocol_response` --- signal that the handler knows how to + * :meth:`protocol_response`\ ---signal that the handler knows how to post-process *protocol* responses. @@ -1422,7 +1422,7 @@ -:mod:`urllib.response` --- Response classes used by urllib +:mod:`urllib.response`\ ---Response classes used by urllib ========================================================== .. module:: urllib.response diff -r afe119a3619f Doc/library/urllib.robotparser.rst --- a/Doc/library/urllib.robotparser.rst +++ b/Doc/library/urllib.robotparser.rst @@ -1,4 +1,4 @@ -:mod:`urllib.robotparser` --- Parser for robots.txt +:mod:`urllib.robotparser`\ ---Parser for robots.txt ==================================================== .. module:: urllib.robotparser diff -r afe119a3619f Doc/library/urllib.rst --- a/Doc/library/urllib.rst +++ b/Doc/library/urllib.rst @@ -1,4 +1,4 @@ -:mod:`urllib` --- URL handling modules +:mod:`urllib`\ ---URL handling modules ====================================== ``urllib`` is a package that collects several modules for working with URLs: diff -r afe119a3619f Doc/library/uu.rst --- a/Doc/library/uu.rst +++ b/Doc/library/uu.rst @@ -1,4 +1,4 @@ -:mod:`uu` --- Encode and decode uuencode files +:mod:`uu`\ ---Encode and decode uuencode files ============================================== .. module:: uu diff -r afe119a3619f Doc/library/uuid.rst --- a/Doc/library/uuid.rst +++ b/Doc/library/uuid.rst @@ -1,4 +1,4 @@ -:mod:`uuid` --- UUID objects according to RFC 4122 +:mod:`uuid`\ ---UUID objects according to RFC 4122 ================================================== .. module:: uuid @@ -208,7 +208,7 @@ .. seealso:: - :rfc:`4122` - A Universally Unique IDentifier (UUID) URN Namespace + :rfc:`4122`\ ---A Universally Unique IDentifier (UUID) URN Namespace This specification defines a Uniform Resource Name namespace for UUIDs, the internal format of UUIDs, and methods of generating UUIDs. diff -r afe119a3619f Doc/library/venv.rst --- a/Doc/library/venv.rst +++ b/Doc/library/venv.rst @@ -1,4 +1,4 @@ -:mod:`venv` --- Creation of virtual environments +:mod:`venv`\ ---Creation of virtual environments ================================================ .. module:: venv @@ -40,7 +40,7 @@ other files which indicate that it is a venv. Common installation tools such as ``Distribute`` and ``pip`` work as - expected with venvs - i.e. when a venv is active, they install Python + expected with venvs---i.e. when a venv is active, they install Python packages into the venv without needing to be told to do so explicitly. Of course, you need to install them into the venv first: this could be done by running ``distribute_setup.py`` with the venv activated, @@ -76,19 +76,19 @@ The :class:`EnvBuilder` class accepts the following keyword arguments on instantiation: - * ``system_site_packages`` -- a Boolean value indicating that the system Python + * ``system_site_packages``\ ---a Boolean value indicating that the system Python site-packages should be available to the environment (defaults to ``False``). - * ``clear`` -- a Boolean value which, if True, will delete the contents of + * ``clear``\ ---a Boolean value which, if True, will delete the contents of any existing target directory, before creating the environment. - * ``symlinks`` -- a Boolean value indicating whether to attempt to symlink the + * ``symlinks``\ ---a Boolean value indicating whether to attempt to symlink the Python binary (and any necessary DLLs or other binaries, e.g. ``pythonw.exe``), rather than copying. Defaults to ``True`` on Linux and Unix systems, but ``False`` on Windows. - * ``upgrade`` -- a Boolean value which, if True, will upgrade an existing - environment with the running Python - for use when that Python has been + * ``upgrade``\ ---a Boolean value which, if True, will upgrade an existing + environment with the running Python---for use when that Python has been upgraded in-place (defaults to ``False``). diff -r afe119a3619f Doc/library/warnings.rst --- a/Doc/library/warnings.rst +++ b/Doc/library/warnings.rst @@ -1,4 +1,4 @@ -:mod:`warnings` --- Warning control +:mod:`warnings`\ ---Warning control =================================== .. index:: single: warnings diff -r afe119a3619f Doc/library/wave.rst --- a/Doc/library/wave.rst +++ b/Doc/library/wave.rst @@ -1,4 +1,4 @@ -:mod:`wave` --- Read and write WAV files +:mod:`wave`\ ---Read and write WAV files ======================================== .. module:: wave diff -r afe119a3619f Doc/library/weakref.rst --- a/Doc/library/weakref.rst +++ b/Doc/library/weakref.rst @@ -1,4 +1,4 @@ -:mod:`weakref` --- Weak references +:mod:`weakref`\ ---Weak references ================================== .. module:: weakref @@ -57,7 +57,7 @@ weak reference. Most programs should find that using one of these weak container types -or :class:`finalize` is all they need -- it's not usually necessary to +or :class:`finalize` is all they need---it's not usually necessary to create your own weak references directly. The low-level machinery is exposed by the :mod:`weakref` module for the benefit of advanced uses. @@ -334,7 +334,7 @@ .. seealso:: - :pep:`0205` - Weak References + :pep:`0205`\ ---Weak References The proposal and rationale for this feature, including links to earlier implementations and information about similar features in other languages. diff -r afe119a3619f Doc/library/webbrowser.rst --- a/Doc/library/webbrowser.rst +++ b/Doc/library/webbrowser.rst @@ -1,4 +1,4 @@ -:mod:`webbrowser` --- Convenient Web-browser controller +:mod:`webbrowser`\ ---Convenient Web-browser controller ======================================================= .. module:: webbrowser @@ -155,7 +155,7 @@ only makes sense to use if KDE is running. Some way of reliably detecting KDE would be nice; the :envvar:`KDEDIR` variable is not sufficient. Note also that the name "kfm" is used even when using the :program:`konqueror` command with KDE - 2 --- the implementation selects the best strategy for running Konqueror. + 2---the implementation selects the best strategy for running Konqueror. (2) Only on Windows platforms. diff -r afe119a3619f Doc/library/winreg.rst --- a/Doc/library/winreg.rst +++ b/Doc/library/winreg.rst @@ -1,4 +1,4 @@ -:mod:`winreg` -- Windows registry access +:mod:`winreg`\ ---Windows registry access ========================================= .. module:: winreg @@ -267,7 +267,7 @@ A call to :func:`LoadKey` fails if the calling process does not have the :const:`SE_RESTORE_PRIVILEGE` privilege. Note that privileges are different - from permissions -- see the `RegLoadKey documentation + from permissions---see the `RegLoadKey documentation `__ for more details. @@ -381,7 +381,7 @@ If *key* represents a key on a remote computer, the path described by *file_name* is relative to the remote computer. The caller of this method must possess the :const:`SeBackupPrivilege` security privilege. Note that - privileges are different than permissions -- see the + privileges are different than permissions---see the `Conflicts Between User Rights and Permissions documentation `__ for more details. @@ -425,7 +425,7 @@ *value_name* is a string that names the subkey with which the value is associated. - *reserved* can be anything -- zero is always passed to the API. + *reserved* can be anything---zero is always passed to the API. *type* is an integer that specifies the type of the data. See :ref:`Value Types ` for the available types. @@ -688,7 +688,7 @@ All registry functions in this module which accept a handle object also accept an integer, however, use of the handle object is encouraged. -Handle objects provide semantics for :meth:`__bool__` -- thus :: +Handle objects provide semantics for :meth:`__bool__`\ ---thus :: if handle: print("Yes") diff -r afe119a3619f Doc/library/winsound.rst --- a/Doc/library/winsound.rst +++ b/Doc/library/winsound.rst @@ -1,4 +1,4 @@ -:mod:`winsound` --- Sound-playing interface for Windows +:mod:`winsound`\ ---Sound-playing interface for Windows ======================================================= .. module:: winsound diff -r afe119a3619f Doc/library/wsgiref.rst --- a/Doc/library/wsgiref.rst +++ b/Doc/library/wsgiref.rst @@ -1,4 +1,4 @@ -:mod:`wsgiref` --- WSGI Utilities and Reference Implementation +:mod:`wsgiref`\ ---WSGI Utilities and Reference Implementation ============================================================== .. module:: wsgiref @@ -30,8 +30,8 @@ .. XXX If you're just trying to write a web application... -:mod:`wsgiref.util` -- WSGI environment utilities -------------------------------------------------- +:mod:`wsgiref.util`\ ---WSGI environment utilities +-------------------------------------------------- .. module:: wsgiref.util :synopsis: WSGI environment utilities. @@ -173,8 +173,8 @@ -:mod:`wsgiref.headers` -- WSGI response header tools ----------------------------------------------------- +:mod:`wsgiref.headers`\ ---WSGI response header tools +----------------------------------------------------- .. module:: wsgiref.headers :synopsis: WSGI response header tools. @@ -251,8 +251,8 @@ Content-Disposition: attachment; filename="bud.gif" -:mod:`wsgiref.simple_server` -- a simple WSGI HTTP server ---------------------------------------------------------- +:mod:`wsgiref.simple_server`\ ---a simple WSGI HTTP server +---------------------------------------------------------- .. module:: wsgiref.simple_server :synopsis: A simple WSGI HTTP server. @@ -362,7 +362,7 @@ interface. -:mod:`wsgiref.validate` --- WSGI conformance checker +:mod:`wsgiref.validate`\ ---WSGI conformance checker ---------------------------------------------------- .. module:: wsgiref.validate @@ -430,8 +430,8 @@ httpd.serve_forever() -:mod:`wsgiref.handlers` -- server/gateway base classes ------------------------------------------------------- +:mod:`wsgiref.handlers`\ ---server/gateway base classes +------------------------------------------------------- .. module:: wsgiref.handlers :synopsis: WSGI server/gateway base classes. @@ -731,7 +731,7 @@ strings, returning a new dictionary. This function is used by :class:`CGIHandler` and :class:`IISCGIHandler` in place of directly using ``os.environ``, which is not necessarily WSGI-compliant on all platforms - and web servers using Python 3 -- specifically, ones where the OS's + and web servers using Python 3---specifically, ones where the OS's actual environment is Unicode (i.e. Windows), or ones where the environment is bytes, but the system encoding used by Python to decode it is anything other than ISO-8859-1 (e.g. Unix systems using UTF-8). diff -r afe119a3619f Doc/library/xdrlib.rst --- a/Doc/library/xdrlib.rst +++ b/Doc/library/xdrlib.rst @@ -1,4 +1,4 @@ -:mod:`xdrlib` --- Encode and decode XDR data +:mod:`xdrlib`\ ---Encode and decode XDR data ============================================ .. module:: xdrlib @@ -36,11 +36,11 @@ .. seealso:: - :rfc:`1014` - XDR: External Data Representation Standard + :rfc:`1014`\ ---XDR: External Data Representation Standard This RFC defined the encoding of data which was XDR at the time this module was originally written. It has apparently been obsoleted by :rfc:`1832`. - :rfc:`1832` - XDR: External Data Representation Standard + :rfc:`1832`\ ---XDR: External Data Representation Standard Newer RFC that provides a revised definition of XDR. diff -r afe119a3619f Doc/library/xml.dom.minidom.rst --- a/Doc/library/xml.dom.minidom.rst +++ b/Doc/library/xml.dom.minidom.rst @@ -1,4 +1,4 @@ -:mod:`xml.dom.minidom` --- Minimal DOM implementation +:mod:`xml.dom.minidom`\ ---Minimal DOM implementation ===================================================== .. module:: xml.dom.minidom diff -r afe119a3619f Doc/library/xml.dom.pulldom.rst --- a/Doc/library/xml.dom.pulldom.rst +++ b/Doc/library/xml.dom.pulldom.rst @@ -1,4 +1,4 @@ -:mod:`xml.dom.pulldom` --- Support for building partial DOM trees +:mod:`xml.dom.pulldom`\ ---Support for building partial DOM trees ================================================================= .. module:: xml.dom.pulldom diff -r afe119a3619f Doc/library/xml.dom.rst --- a/Doc/library/xml.dom.rst +++ b/Doc/library/xml.dom.rst @@ -1,4 +1,4 @@ -:mod:`xml.dom` --- The Document Object Model API +:mod:`xml.dom`\ ---The Document Object Model API ================================================ .. module:: xml.dom diff -r afe119a3619f Doc/library/xml.etree.elementtree.rst --- a/Doc/library/xml.etree.elementtree.rst +++ b/Doc/library/xml.etree.elementtree.rst @@ -1,4 +1,4 @@ -:mod:`xml.etree.ElementTree` --- The ElementTree XML API +:mod:`xml.etree.ElementTree`\ ---The ElementTree XML API ======================================================== .. module:: xml.etree.ElementTree @@ -30,7 +30,7 @@ ^^^^^^^^^^^^^^^^^^^^^ XML is an inherently hierarchical data format, and the most natural way to -represent it is with a tree. ``ET`` has two classes for this purpose - +represent it is with a tree. ``ET`` has two classes for this purpose --- :class:`ElementTree` represents the whole XML document as a tree, and :class:`Element` represents a single node in this tree. Interactions with the whole document (reading and writing to/from files) are usually done diff -r afe119a3619f Doc/library/xml.rst --- a/Doc/library/xml.rst +++ b/Doc/library/xml.rst @@ -72,7 +72,7 @@ billion laughs / exponential entity expansion - The `Billion Laughs`_ attack -- also known as exponential entity expansion -- + The `Billion Laughs`_ attack---also known as exponential entity expansion --- uses multiple levels of nested entities. Each entity refers to another entity several times, the final entity definition contains a small string. Eventually the small string is expanded to several gigabytes. The exponential expansion diff -r afe119a3619f Doc/library/xml.sax.handler.rst --- a/Doc/library/xml.sax.handler.rst +++ b/Doc/library/xml.sax.handler.rst @@ -1,4 +1,4 @@ -:mod:`xml.sax.handler` --- Base classes for SAX handlers +:mod:`xml.sax.handler`\ ---Base classes for SAX handlers ======================================================== .. module:: xml.sax.handler diff -r afe119a3619f Doc/library/xml.sax.reader.rst --- a/Doc/library/xml.sax.reader.rst +++ b/Doc/library/xml.sax.reader.rst @@ -1,4 +1,4 @@ -:mod:`xml.sax.xmlreader` --- Interface for XML parsers +:mod:`xml.sax.xmlreader`\ ---Interface for XML parsers ====================================================== .. module:: xml.sax.xmlreader @@ -97,7 +97,7 @@ .. method:: XMLReader.parse(source) Process an input source, producing SAX events. The *source* object can be a - system identifier (a string identifying the input source -- typically a file + system identifier (a string identifying the input source---typically a file name or an URL), a file-like object, or an :class:`InputSource` object. When :meth:`parse` returns, the input is completely processed, and the parser object can be discarded or reset. As a limitation, the current implementation only diff -r afe119a3619f Doc/library/xml.sax.rst --- a/Doc/library/xml.sax.rst +++ b/Doc/library/xml.sax.rst @@ -1,4 +1,4 @@ -:mod:`xml.sax` --- Support for SAX2 parsers +:mod:`xml.sax`\ ---Support for SAX2 parsers =========================================== .. module:: xml.sax @@ -80,7 +80,7 @@ subclassed to provide additional functionality or to add localization. Note that although the handlers defined in the :class:`ErrorHandler` interface receive instances of this exception, it is not required to actually raise the - exception --- it is also useful as a container for information. + exception---it is also useful as a container for information. When instantiated, *msg* should be a human-readable description of the error. The optional *exception* parameter, if given, should be ``None`` or an exception diff -r afe119a3619f Doc/library/xml.sax.utils.rst --- a/Doc/library/xml.sax.utils.rst +++ b/Doc/library/xml.sax.utils.rst @@ -1,4 +1,4 @@ -:mod:`xml.sax.saxutils` --- SAX Utilities +:mod:`xml.sax.saxutils`\ ---SAX Utilities ========================================= .. module:: xml.sax.saxutils diff -r afe119a3619f Doc/library/xmlrpc.client.rst --- a/Doc/library/xmlrpc.client.rst +++ b/Doc/library/xmlrpc.client.rst @@ -1,4 +1,4 @@ -:mod:`xmlrpc.client` --- XML-RPC client access +:mod:`xmlrpc.client`\ ---XML-RPC client access ============================================== .. module:: xmlrpc.client diff -r afe119a3619f Doc/library/xmlrpc.rst --- a/Doc/library/xmlrpc.rst +++ b/Doc/library/xmlrpc.rst @@ -1,4 +1,4 @@ -:mod:`xmlrpc` --- XMLRPC server and client modules +:mod:`xmlrpc`\ ---XMLRPC server and client modules ================================================== XML-RPC is a Remote Procedure Call method that uses XML passed via HTTP as a diff -r afe119a3619f Doc/library/xmlrpc.server.rst --- a/Doc/library/xmlrpc.server.rst +++ b/Doc/library/xmlrpc.server.rst @@ -1,4 +1,4 @@ -:mod:`xmlrpc.server` --- Basic XML-RPC servers +:mod:`xmlrpc.server`\ ---Basic XML-RPC servers ============================================== .. module:: xmlrpc.server diff -r afe119a3619f Doc/library/zipfile.rst --- a/Doc/library/zipfile.rst +++ b/Doc/library/zipfile.rst @@ -1,4 +1,4 @@ -:mod:`zipfile` --- Work with ZIP archives +:mod:`zipfile`\ ---Work with ZIP archives ========================================= .. module:: zipfile @@ -301,7 +301,7 @@ *arcname* (by default, this will be the same as *filename*, but without a drive letter and with leading path separators removed). If given, *compress_type* overrides the value given for the *compression* parameter to the constructor for - the new entry. The archive must be open with mode ``'w'`` or ``'a'`` -- calling + the new entry. The archive must be open with mode ``'w'`` or ``'a'``\ ---calling :meth:`write` on a ZipFile created with mode ``'r'`` will raise a :exc:`RuntimeError`. Calling :meth:`write` on a closed ZipFile will raise a :exc:`RuntimeError`. @@ -330,7 +330,7 @@ name it will be given in the archive, or a :class:`ZipInfo` instance. If it's an instance, at least the filename, date, and time must be given. If it's a name, the date and time is set to the current date and time. The archive must be - opened with mode ``'w'`` or ``'a'`` -- calling :meth:`writestr` on a ZipFile + opened with mode ``'w'`` or ``'a'``\ ---calling :meth:`writestr` on a ZipFile created with mode ``'r'`` will raise a :exc:`RuntimeError`. Calling :meth:`writestr` on a closed ZipFile will raise a :exc:`RuntimeError`. diff -r afe119a3619f Doc/library/zipimport.rst --- a/Doc/library/zipimport.rst +++ b/Doc/library/zipimport.rst @@ -1,4 +1,4 @@ -:mod:`zipimport` --- Import modules from Zip archives +:mod:`zipimport`\ ---Import modules from Zip archives ===================================================== .. module:: zipimport @@ -34,12 +34,12 @@ Documentation on the ZIP file format by Phil Katz, the creator of the format and algorithms used. - :pep:`273` - Import Modules from Zip Archives + :pep:`273`\ ---Import Modules from Zip Archives Written by James C. Ahlstrom, who also provided an implementation. Python 2.3 follows the specification in PEP 273, but uses an implementation written by Just van Rossum that uses the import hooks described in PEP 302. - :pep:`302` - New Import Hooks + :pep:`302`\ ---New Import Hooks The PEP to add the import hooks that help this module work. @@ -144,7 +144,7 @@ Examples -------- -Here is an example that imports a module from a ZIP archive - note that the +Here is an example that imports a module from a ZIP archive---note that the :mod:`zipimport` module is not explicitly used. :: $ unzip -l example.zip diff -r afe119a3619f Doc/library/zlib.rst --- a/Doc/library/zlib.rst +++ b/Doc/library/zlib.rst @@ -1,4 +1,4 @@ -:mod:`zlib` --- Compression compatible with :program:`gzip` +:mod:`zlib`\ ---Compression compatible with :program:`gzip` =========================================================== .. module:: zlib @@ -63,7 +63,7 @@ Returns a compression object, to be used for compressing data streams that won't fit into memory at once. - *level* is the compression level -- an integer from ``0`` to ``9``. A value + *level* is the compression level---an integer from ``0`` to ``9``. A value of ``1`` is fastest and produces the least compression, while a value of ``9`` is slowest and produces the most. ``0`` is no compression. The default value is ``6``. diff -r afe119a3619f Doc/reference/compound_stmts.rst --- a/Doc/reference/compound_stmts.rst +++ b/Doc/reference/compound_stmts.rst @@ -334,7 +334,7 @@ executed in the :keyword:`try` suite of a :keyword:`try`...\ :keyword:`finally` statement, the :keyword:`finally` clause is also executed 'on the way out.' A :keyword:`continue` statement is illegal in the :keyword:`finally` clause. (The -reason is a problem with the current implementation --- this restriction may be +reason is a problem with the current implementation---this restriction may be lifted in the future). Additional information on exceptions can be found in section :ref:`exceptions`, @@ -412,7 +412,7 @@ .. seealso:: - :pep:`0343` - The "with" statement + :pep:`0343`\ ---The "with" statement The specification, background, and examples for the Python :keyword:`with` statement. @@ -491,7 +491,7 @@ omitted from a call, in which case the parameter's default value is substituted. If a parameter has a default value, all following parameters up until the "``*``" must also have a default -value --- this is a syntactic restriction that is not expressed by the grammar. +value---this is a syntactic restriction that is not expressed by the grammar. **Default parameter values are evaluated from left to right when the function definition is executed.** This means that the expression is evaluated once, when @@ -554,7 +554,7 @@ .. seealso:: - :pep:`3107` - Function Annotations + :pep:`3107`\ ---Function Annotations The original specification for function annotations. @@ -632,8 +632,8 @@ .. seealso:: - :pep:`3115` - Metaclasses in Python 3 - :pep:`3129` - Class Decorators + :pep:`3115`\ ---Metaclasses in Python 3 + :pep:`3129`\ ---Class Decorators .. rubric:: Footnotes diff -r afe119a3619f Doc/reference/datamodel.rst --- a/Doc/reference/datamodel.rst +++ b/Doc/reference/datamodel.rst @@ -64,7 +64,7 @@ Objects are never explicitly destroyed; however, when they become unreachable they may be garbage-collected. An implementation is allowed to postpone garbage -collection or omit it altogether --- it is a matter of implementation quality +collection or omit it altogether---it is a matter of implementation quality how garbage collection is implemented, as long as no objects are collected that are still reachable. @@ -479,7 +479,7 @@ +-------------------------+-------------------------------+-----------+ | :attr:`__globals__` | A reference to the dictionary | Read-only | | | that holds the function's | | - | | global variables --- the | | + | | global variables---the | | | | global namespace of the | | | | module in which the function | | | | was defined. | | @@ -929,7 +929,7 @@ Special writable attributes: :attr:`f_trace`, if not ``None``, is a function called at the start of each source code line (this is used by the debugger); - :attr:`f_lineno` is the current line number of the frame --- writing to this + :attr:`f_lineno` is the current line number of the frame---writing to this from within a trace function jumps to the given line (only for the bottom-most frame). A debugger can implement a Jump command (aka Set Next Statement) by writing to f_lineno. @@ -1107,7 +1107,7 @@ .. note:: - ``del x`` doesn't directly call ``x.__del__()`` --- the former decrements + ``del x`` doesn't directly call ``x.__del__()``\ ---the former decrements the reference count for ``x`` by one, and the latter is only called when ``x``'s reference count reaches zero. Some common situations that may prevent the reference count of an object from going to zero include: @@ -1643,7 +1643,7 @@ .. seealso:: - :pep:`3115` - Metaclasses in Python 3000 + :pep:`3115`\ ---Metaclasses in Python 3000 Introduced the ``__prepare__`` namespace hook @@ -1684,7 +1684,7 @@ .. seealso:: - :pep:`3135` - New super + :pep:`3135`\ ---New super Describes the implicit ``__class__`` closure reference @@ -1761,7 +1761,7 @@ .. seealso:: - :pep:`3119` - Introducing Abstract Base Classes + :pep:`3119`\ ---Introducing Abstract Base Classes Includes the specification for customizing :func:`isinstance` and :func:`issubclass` behavior through :meth:`__instancecheck__` and :meth:`__subclasscheck__`, with motivation for this functionality in the @@ -2116,7 +2116,7 @@ .. seealso:: - :pep:`0343` - The "with" statement + :pep:`0343`\ ---The "with" statement The specification, background, and examples for the Python :keyword:`with` statement. diff -r afe119a3619f Doc/reference/executionmodel.rst --- a/Doc/reference/executionmodel.rst +++ b/Doc/reference/executionmodel.rst @@ -50,7 +50,7 @@ definition occurs in a function block, the scope extends to any blocks contained within the defining one, unless a contained block introduces a different binding for the name. The scope of names defined in a class block is limited to the -class block; it does not extend to the code blocks of methods -- this includes +class block; it does not extend to the code blocks of methods---this includes comprehensions and generator expressions since they are implemented using a function scope. This means that the following will fail:: @@ -160,7 +160,7 @@ If a variable is referenced in an enclosing scope, it is illegal to delete the name. An error will be reported at compile time. -If the wild card form of import --- ``import *`` --- is used in a function and +If the wild card form of import---\ ``import *``\ ---is used in a function and the function contains or is a nested block with free variables, the compiler will raise a :exc:`SyntaxError`. diff -r afe119a3619f Doc/reference/expressions.rst --- a/Doc/reference/expressions.rst +++ b/Doc/reference/expressions.rst @@ -150,7 +150,7 @@ Note that tuples are not formed by the parentheses, but rather by use of the comma operator. The exception is the empty tuple, for which parentheses *are* -required --- allowing unparenthesized "nothing" in expressions would cause +required---allowing unparenthesized "nothing" in expressions would cause ambiguities and allow common typos to pass uncaught. @@ -477,14 +477,14 @@ .. seealso:: - :pep:`0255` - Simple Generators + :pep:`0255`\ ---Simple Generators The proposal for adding generators and the :keyword:`yield` statement to Python. - :pep:`0342` - Coroutines via Enhanced Generators + :pep:`0342`\ ---Coroutines via Enhanced Generators The proposal to enhance the API and syntax of generators, making them usable as simple coroutines. - :pep:`0380` - Syntax for Delegating to a Subgenerator + :pep:`0380`\ ---Syntax for Delegating to a Subgenerator The proposal to introduce the :token:`yield_from` syntax, making delegation to sub-generators easy. @@ -727,7 +727,7 @@ A consequence of this is that although the ``*expression`` syntax may appear *after* some keyword arguments, it is processed *before* the keyword arguments -(and the ``**expression`` argument, if any -- see below). So:: +(and the ``**expression`` argument, if any---see below). So:: >>> def f(a, b): ... print(a, b) @@ -1316,7 +1316,7 @@ the same box have the same precedence. Unless the syntax is explicitly given, operators are binary. Operators in the same box group left to right (except for comparisons, including tests, which all have the same precedence and chain from -left to right --- see section :ref:`comparisons` --- and exponentiation, which +left to right---see section :ref:`comparisons`\ ---and exponentiation, which groups from right to left). diff -r afe119a3619f Doc/reference/import.rst --- a/Doc/reference/import.rst +++ b/Doc/reference/import.rst @@ -44,7 +44,7 @@ .. versionchanged:: 3.3 The import system has been updated to fully implement the second phase - of :pep:`302`. There is no longer any implicit import machinery - the full + of :pep:`302`. There is no longer any implicit import machinery---the full import system is exposed through :data:`sys.meta_path`. In addition, native namespace package support has been implemented (see :pep:`420`). @@ -216,7 +216,7 @@ two conceptual objects, :term:`finders ` and :term:`loaders `. A finder's job is to determine whether it can find the named module using whatever strategy it knows about. Objects that implement both of these -interfaces are referred to as :term:`importers ` - they return +interfaces are referred to as :term:`importers `\ ---they return themselves when they find that they can load the requested module. Python includes a number of default finders and importers. The first one @@ -555,7 +555,7 @@ machinery begins the :term:`import path` search by calling the path based finder's :meth:`find_module()` method as described previously. When the ``path`` argument to :meth:`find_module()` is given, it will be a -list of string paths to traverse - typically a package's ``__path__`` +list of string paths to traverse---typically a package's ``__path__`` attribute for an import within that package. If the ``path`` argument is ``None``, this indicates a top level import and :data:`sys.path` is used. diff -r afe119a3619f Doc/reference/introduction.rst --- a/Doc/reference/introduction.rst +++ b/Doc/reference/introduction.rst @@ -17,11 +17,11 @@ language. On the other hand, if you are using Python and wonder what the precise rules about a particular area of the language are, you should definitely be able to find them here. If you would like to see a more formal definition of the -language, maybe you could volunteer your time --- or invent a cloning machine +language, maybe you could volunteer your time---or invent a cloning machine :-). It is dangerous to add too many implementation details to a language reference -document --- the implementation may change, and other implementations of the +document---the implementation may change, and other implementations of the same language may work differently. On the other hand, CPython is the one Python implementation in widespread use (although alternate implementations continue to gain support), and its particular quirks are sometimes worth being diff -r afe119a3619f Doc/reference/lexical_analysis.rst --- a/Doc/reference/lexical_analysis.rst +++ b/Doc/reference/lexical_analysis.rst @@ -48,7 +48,7 @@ A physical line is a sequence of characters terminated by an end-of-line sequence. In source files, any of the standard platform line termination -sequences can be used - the Unix form using ASCII LF (linefeed), the Windows +sequences can be used---the Unix form using ASCII LF (linefeed), the Windows form using the ASCII sequence CR LF (return followed by linefeed), or the old Macintosh form using the ASCII CR (return) character. All of these forms can be used equally, regardless of platform. @@ -238,7 +238,7 @@ return r # error: inconsistent dedent (Actually, the first three errors are detected by the parser; only the last -error is found by the lexical analyzer --- the indentation of ``return r`` does +error is found by the lexical analyzer---the indentation of ``return r`` does not match a level popped off the stack.) @@ -300,18 +300,18 @@ The Unicode category codes mentioned above stand for: -* *Lu* - uppercase letters -* *Ll* - lowercase letters -* *Lt* - titlecase letters -* *Lm* - modifier letters -* *Lo* - other letters -* *Nl* - letter numbers -* *Mn* - nonspacing marks -* *Mc* - spacing combining marks -* *Nd* - decimal numbers -* *Pc* - connector punctuations -* *Other_ID_Start* - explicit list of characters in `PropList.txt `_ to support backwards compatibility -* *Other_ID_Continue* - likewise +* *Lu*\ ---uppercase letters +* *Ll*\ ---lowercase letters +* *Lt*\ ---titlecase letters +* *Lm*\ ---modifier letters +* *Lo*\ ---other letters +* *Nl*\ ---letter numbers +* *Mn*\ ---nonspacing marks +* *Mc*\ ---spacing combining marks +* *Nd*\ ---decimal numbers +* *Pc*\ ---connector punctuations +* *Other_ID_Start*\ ---explicit list of characters in `PropList.txt `_ to support backwards compatibility +* *Other_ID_Continue*\ ---likewise All identifiers are converted into the normal form NFKC while parsing; comparison of identifiers is based on NFKC. diff -r afe119a3619f Doc/reference/simple_stmts.rst --- a/Doc/reference/simple_stmts.rst +++ b/Doc/reference/simple_stmts.rst @@ -248,7 +248,7 @@ .. seealso:: - :pep:`3132` - Extended Iterable Unpacking + :pep:`3132`\ ---Extended Iterable Unpacking The specification for the ``*target`` feature. @@ -349,7 +349,7 @@ .. productionlist:: pass_stmt: "pass" -:keyword:`pass` is a null operation --- when it is executed, nothing happens. +:keyword:`pass` is a null operation---when it is executed, nothing happens. It is useful as a placeholder when a statement is required syntactically, but no code needs to be executed, for example:: @@ -481,14 +481,14 @@ .. seealso:: - :pep:`0255` - Simple Generators + :pep:`0255`\ ---Simple Generators The proposal for adding generators and the :keyword:`yield` statement to Python. - :pep:`0342` - Coroutines via Enhanced Generators + :pep:`0342`\ ---Coroutines via Enhanced Generators The proposal to enhance the API and syntax of generators, making them usable as simple coroutines. - :pep:`0380` - Syntax for Delegating to a Subgenerator + :pep:`0380`\ ---Syntax for Delegating to a Subgenerator The proposal to introduce the :token:`yield_from` syntax, making delegation to sub-generators easy. @@ -738,7 +738,7 @@ library modules which were imported and used within the module). The :keyword:`from` form with ``*`` may only occur in a module scope. The wild -card form of import --- ``import *`` --- is only allowed at the module level. +card form of import---\ ``import *``\ ---is only allowed at the module level. Attempting to use it in class or function definitions will raise a :exc:`SyntaxError`. @@ -827,7 +827,7 @@ Code compiled by calls to the built-in functions :func:`exec` and :func:`compile` that occur in a module :mod:`M` containing a future statement will, by default, use the new syntax or semantics associated with the future statement. This can -be controlled by optional arguments to :func:`compile` --- see the documentation +be controlled by optional arguments to :func:`compile`\ ---see the documentation of that function for details. A future statement typed at an interactive interpreter prompt will take effect @@ -838,7 +838,7 @@ .. seealso:: - :pep:`236` - Back to the __future__ + :pep:`236`\ ---Back to the __future__ The original proposal for the __future__ mechanism. @@ -921,5 +921,5 @@ .. seealso:: - :pep:`3104` - Access to Names in Outer Scopes + :pep:`3104`\ ---Access to Names in Outer Scopes The specification for the :keyword:`nonlocal` statement. diff -r afe119a3619f Doc/tutorial/appetite.rst --- a/Doc/tutorial/appetite.rst +++ b/Doc/tutorial/appetite.rst @@ -36,7 +36,7 @@ Python allows you to split your program into modules that can be reused in other Python programs. It comes with a large collection of standard modules that you -can use as the basis of your programs --- or as examples to start learning to +can use as the basis of your programs---or as examples to start learning to program in Python. Some of these modules provide things like file I/O, system calls, sockets, and even interfaces to graphical user interface toolkits like Tk. diff -r afe119a3619f Doc/tutorial/classes.rst --- a/Doc/tutorial/classes.rst +++ b/Doc/tutorial/classes.rst @@ -45,7 +45,7 @@ This is usually used to the benefit of the program, since aliases behave like pointers in some respects. For example, passing an object is cheap since only a pointer is passed by the implementation; and if a function modifies an object -passed as an argument, the caller will see the change --- this eliminates the +passed as an argument, the caller will see the change---this eliminates the need for two different argument passing mechanisms as in Pascal. @@ -73,7 +73,7 @@ different modules may both define a function ``maximize`` without confusion --- users of the modules must prefix it with the module name. -By the way, I use the word *attribute* for any name following a dot --- for +By the way, I use the word *attribute* for any name following a dot---for example, in the expression ``z.real``, ``real`` is an attribute of the object ``z``. Strictly speaking, references to names in modules are attribute references: in the expression ``modname.funcname``, ``modname`` is a module @@ -132,14 +132,14 @@ It is important to realize that scopes are determined textually: the global scope of a function defined in a module is that module's namespace, no matter from where or by what alias the function is called. On the other hand, the -actual search for names is done dynamically, at run time --- however, the +actual search for names is done dynamically, at run time---however, the language definition is evolving towards static name resolution, at "compile" time, so don't rely on dynamic name resolution! (In fact, local variables are already determined statically.) -A special quirk of Python is that -- if no :keyword:`global` statement is in -effect -- assignments to names always go into the innermost scope. Assignments -do not copy data --- they just bind names to objects. The same is true for +A special quirk of Python is that---if no :keyword:`global` statement is in +effect---assignments to names always go into the innermost scope. Assignments +do not copy data---they just bind names to objects. The same is true for deletions: the statement ``del x`` removes the binding of ``x`` from the namespace referenced by the local scope. In fact, all operations that introduce new names use the local scope: in particular, :keyword:`import` statements and @@ -226,13 +226,13 @@ definition in a branch of an :keyword:`if` statement, or inside a function.) In practice, the statements inside a class definition will usually be function -definitions, but other statements are allowed, and sometimes useful --- we'll +definitions, but other statements are allowed, and sometimes useful---we'll come back to this later. The function definitions inside a class normally have a peculiar form of argument list, dictated by the calling conventions for -methods --- again, this is explained later. +methods---again, this is explained later. When a class definition is entered, a new namespace is created, and used as the -local scope --- thus, all assignments to local variables go into this new +local scope---thus, all assignments to local variables go into this new namespace. In particular, function definitions bind the name of the new function here. @@ -341,7 +341,7 @@ all attributes of a class that are function objects define corresponding methods of its instances. So in our example, ``x.f`` is a valid method reference, since ``MyClass.f`` is a function, but ``x.i`` is not, since -``MyClass.i`` is not. But ``x.f`` is not the same thing as ``MyClass.f`` --- it +``MyClass.i`` is not. But ``x.f`` is not the same thing as ``MyClass.f``\ ---it is a *method object*, not a function object. @@ -368,7 +368,7 @@ ``x.f()`` was called without an argument above, even though the function definition for :meth:`f` specified an argument. What happened to the argument? Surely Python raises an exception when a function that requires an argument is -called without any --- even if the argument isn't actually used... +called without any---even if the argument isn't actually used... Actually, you may have guessed the answer: the special thing about methods is that the object is passed as the first argument of the function. In our @@ -405,12 +405,12 @@ Data attributes may be referenced by methods as well as by ordinary users ("clients") of an object. In other words, classes are not usable to implement pure abstract data types. In fact, nothing in Python makes it possible to -enforce data hiding --- it is all based upon convention. (On the other hand, +enforce data hiding---it is all based upon convention. (On the other hand, the Python implementation, written in C, can completely hide implementation details and control access to an object if necessary; this can be used by extensions to Python written in C.) -Clients should use data attributes with care --- clients may mess up invariants +Clients should use data attributes with care---clients may mess up invariants maintained by the methods by stamping on their data attributes. Note that clients may add data attributes of their own to an instance object without affecting the validity of the methods, as long as name conflicts are avoided --- @@ -444,7 +444,7 @@ Now ``f``, ``g`` and ``h`` are all attributes of class :class:`C` that refer to function objects, and consequently they are all methods of instances of -:class:`C` --- ``h`` being exactly equivalent to ``g``. Note that this practice +:class:`C`\ ---\ ``h`` being exactly equivalent to ``g``. Note that this practice usually only serves to confuse the reader of a program. Methods may call other methods by using method attributes of the ``self`` @@ -686,7 +686,7 @@ raise Class() A class in an :keyword:`except` clause is compatible with an exception if it is -the same class or a base class thereof (but not the other way around --- an +the same class or a base class thereof (but not the other way around---an except clause listing a derived class is not compatible with a base class). For example, the following code will print B, C, D in that order:: @@ -708,7 +708,7 @@ print("B") Note that if the except clauses were reversed (with ``except B`` first), it -would have printed B, B, B --- the first matching except clause is triggered. +would have printed B, B, B---the first matching except clause is triggered. When an error message is printed for an unhandled exception, the exception's class name is printed, then a colon and a space, and finally the instance diff -r afe119a3619f Doc/tutorial/datastructures.rst --- a/Doc/tutorial/datastructures.rst +++ b/Doc/tutorial/datastructures.rst @@ -101,7 +101,7 @@ [-1, 1, 66.25, 333, 333, 1234.5] You might have noticed that methods like ``insert``, ``remove`` or ``sort`` that -modify the list have no return value printed -- they return ``None``. [1]_ This +modify the list have no return value printed---they return ``None``. [1]_ This is a design principle for all mutable data structures in Python. @@ -687,4 +687,4 @@ .. [2] Calling ``d.keys()`` will return a :dfn:`dictionary view` object. It supports operations like membership test and iteration, but its contents - are not independent of the original dictionary -- it is only a *view*. + are not independent of the original dictionary---it is only a *view*. diff -r afe119a3619f Doc/tutorial/interpreter.rst --- a/Doc/tutorial/interpreter.rst +++ b/Doc/tutorial/interpreter.rst @@ -177,7 +177,7 @@ By default, Python source files are treated as encoded in UTF-8. In that encoding, characters of most languages in the world can be used simultaneously -in string literals, identifiers and comments --- although the standard library +in string literals, identifiers and comments---although the standard library only uses ASCII characters for identifiers, a convention that any portable code should follow. To display all these characters properly, your editor must recognize that the file is UTF-8, and it must use a font that supports all the diff -r afe119a3619f Doc/tutorial/introduction.rst --- a/Doc/tutorial/introduction.rst +++ b/Doc/tutorial/introduction.rst @@ -119,7 +119,7 @@ 113.06 This variable should be treated as read-only by the user. Don't explicitly -assign a value to it --- you would create an independent local variable with the +assign a value to it---you would create an independent local variable with the same name masking the built-in variable with its magic behavior. In addition to :class:`int` and :class:`float`, Python supports other types of @@ -318,7 +318,7 @@ >>> word[42:] '' -Python strings cannot be changed --- they are :term:`immutable`. +Python strings cannot be changed---they are :term:`immutable`. Therefore, assigning to an indexed position in the string results in an error:: >>> word[0] = 'J' diff -r afe119a3619f Doc/tutorial/modules.rst --- a/Doc/tutorial/modules.rst +++ b/Doc/tutorial/modules.rst @@ -116,7 +116,7 @@ For efficiency reasons, each module is only imported once per interpreter session. Therefore, if you change your modules, you must restart the - interpreter -- or, if it's just one module you want to test interactively, + interpreter---or, if it's just one module you want to test interactively, use :func:`imp.reload`, e.g. ``import imp; imp.reload(modulename)``. diff -r afe119a3619f Doc/tutorial/stdlib2.rst --- a/Doc/tutorial/stdlib2.rst +++ b/Doc/tutorial/stdlib2.rst @@ -1,8 +1,8 @@ .. _tut-brieftourtwo: -********************************************* -Brief Tour of the Standard Library -- Part II -********************************************* +********************************************** +Brief Tour of the Standard Library---Part II +********************************************** This second tour covers more advanced modules that support professional programming needs. These modules rarely occur in small scripts. @@ -88,7 +88,7 @@ The :meth:`substitute` method raises a :exc:`KeyError` when a placeholder is not supplied in a dictionary or a keyword argument. For mail-merge style applications, user supplied data may be incomplete and the -:meth:`safe_substitute` method may be more appropriate --- it will leave +:meth:`safe_substitute` method may be more appropriate---it will leave placeholders unchanged if data is missing:: >>> t = Template('Return the $item to $owner.') diff -r afe119a3619f Doc/tutorial/whatnow.rst --- a/Doc/tutorial/whatnow.rst +++ b/Doc/tutorial/whatnow.rst @@ -66,5 +66,5 @@ and may already contain the solution for your problem. .. Postings figure based on average of last six months activity as - reported by www.egroups.com; Jan. 2000 - June 2000: 21272 msgs / 182 + reported by www.egroups.com; Jan. 2000---June 2000: 21272 msgs / 182 days = 116.9 msgs / day and steadily increasing. (XXX up to date figures?) diff -r afe119a3619f Doc/using/cmdline.rst --- a/Doc/using/cmdline.rst +++ b/Doc/using/cmdline.rst @@ -55,7 +55,7 @@ In non-interactive mode, the entire input is parsed before it is executed. An interface option terminates the list of options consumed by the interpreter, -all consecutive arguments will end up in :data:`sys.argv` -- note that the first +all consecutive arguments will end up in :data:`sys.argv`\ ---note that the first element, subscript zero (``sys.argv[0]``), is a string reflecting the program's source. @@ -109,7 +109,7 @@ :func:`runpy.run_module` Equivalent functionality directly available to Python code - :pep:`338` -- Executing modules as scripts + :pep:`338`\ ---Executing modules as scripts .. versionchanged:: 3.1 @@ -261,7 +261,7 @@ .. seealso:: - :pep:`370` -- Per user site-packages directory + :pep:`370`\ ---Per user site-packages directory .. cmdoption:: -S @@ -345,9 +345,9 @@ thus equivalent to an omitted line number. .. seealso:: - :mod:`warnings` -- the warnings module + :mod:`warnings`\ ---the warnings module - :pep:`230` -- Warning framework + :pep:`230`\ ---Warning framework :envvar:`PYTHONWARNINGS` @@ -540,7 +540,7 @@ .. seealso:: - :pep:`370` -- Per user site-packages directory + :pep:`370`\ ---Per user site-packages directory .. envvar:: PYTHONUSERBASE @@ -552,7 +552,7 @@ .. seealso:: - :pep:`370` -- Per user site-packages directory + :pep:`370`\ ---Per user site-packages directory .. envvar:: PYTHONEXECUTABLE diff -r afe119a3619f Doc/using/scripts.rst --- a/Doc/using/scripts.rst +++ b/Doc/using/scripts.rst @@ -5,7 +5,7 @@ .. _scripts-pyvenv: -pyvenv - Creating virtual environments +pyvenv---Creating virtual environments -------------------------------------- .. include:: venv-create.inc diff -r afe119a3619f Doc/using/windows.rst --- a/Doc/using/windows.rst +++ b/Doc/using/windows.rst @@ -263,7 +263,7 @@ From the command-line ^^^^^^^^^^^^^^^^^^^^^ -You should ensure the launcher is on your PATH - depending on how it was +You should ensure the launcher is on your PATH---depending on how it was installed it may already be there, but check just in case it is not. From a command-prompt, execute the following command: @@ -273,11 +273,11 @@ py You should find that the latest version of Python 2.x you have installed is -started - it can be exited as normal, and any additional command-line +started---it can be exited as normal, and any additional command-line arguments specified will be sent directly to Python. If you have multiple versions of Python 2.x installed (e.g., 2.6 and 2.7) you -will have noticed that Python 2.7 was started - to launch Python 2.6, try the +will have noticed that Python 2.7 was started---to launch Python 2.6, try the command: :: @@ -295,7 +295,7 @@ From a script ^^^^^^^^^^^^^ -Let's create a test Python script - create a file called ``hello.py`` with the +Let's create a test Python script---create a file called ``hello.py`` with the following contents :: @@ -384,7 +384,7 @@ Customization via INI files ^^^^^^^^^^^^^^^^^^^^^^^^^^^ - Two .ini files will be searched by the launcher - ``py.ini`` in the + Two .ini files will be searched by the launcher---\ ``py.ini`` in the current user's "application data" directory (i.e. the directory returned by calling the Windows function SHGetFolderPath with CSIDL_LOCAL_APPDATA) and ``py.ini`` in the same directory as the launcher. The same .ini @@ -410,7 +410,7 @@ ``#!python3`` has a version qualifier which specifies only a major version. If no version qualifiers are found in a command, the environment variable -``PY_PYTHON`` can be set to specify the default version qualifier - the default +``PY_PYTHON`` can be set to specify the default version qualifier---the default value is "2". Note this value could specify just a major version (e.g. "2") or a major.minor qualifier (e.g. "2.6"), or even major.minor-32. @@ -425,7 +425,7 @@ On 64-bit Windows with both 32-bit and 64-bit implementations of the same (major.minor) Python version installed, the 64-bit version will always be preferred. This will be true for both 32-bit and 64-bit implementations of the -launcher - a 32-bit launcher will prefer to execute a 64-bit Python installation +launcher---a 32-bit launcher will prefer to execute a 64-bit Python installation of the specified version if available. This is so the behavior of the launcher can be predicted knowing only what versions are installed on the PC and without regard to the order in which they were installed (i.e., without knowing @@ -588,7 +588,7 @@ MinGW gcc under Windows" or "Installing Python extension with distutils and without Microsoft Visual C++" by Sébastien Sauvage, 2003 - `MingW -- Python extensions `_ + `MingW---Python extensions `_ by Trent Apted et al, 2007 @@ -605,7 +605,7 @@ `A Python for Windows Tutorial `_ by Amanda Birmingham, 2004 - :pep:`397` - Python launcher for Windows + :pep:`397`\ ---Python launcher for Windows The proposal for the launcher to be included in the Python distribution. diff -r afe119a3619f Doc/whatsnew/2.0.rst --- a/Doc/whatsnew/2.0.rst +++ b/Doc/whatsnew/2.0.rst @@ -727,7 +727,7 @@ exceptions was translated from Python to a built-in C module, written by Barry Warsaw and Fredrik Lundh. -.. Commented out for now -- I don't think anyone will care. +.. Commented out for now---I don't think anyone will care. The pattern and match objects provided by SRE are C types, not Python class instances as in 1.5. This means you can no longer inherit from \class{RegexObject} or \class{MatchObject}, but that shouldn't be much @@ -810,7 +810,7 @@ Distutils: Making Modules Easy to Install ========================================= -Before Python 2.0, installing modules was a tedious affair -- there was no way +Before Python 2.0, installing modules was a tedious affair---there was no way to figure out automatically where Python is installed, or what compiler options to use for extension modules. Software authors had to go through an arduous ritual of editing Makefiles and configuration files, which only really work on @@ -827,7 +827,7 @@ will be recognized, C extension modules will be compiled, and the distribution installed into the proper directory. Optional command-line arguments provide more control over the installation process, the distutils package offers many -places to override defaults -- separating the build from the install, building +places to override defaults---separating the build from the install, building or installing in non-default directories, and more. In order to use the Distutils, you need to write a :file:`setup.py` script. For diff -r afe119a3619f Doc/whatsnew/2.1.rst --- a/Doc/whatsnew/2.1.rst +++ b/Doc/whatsnew/2.1.rst @@ -120,7 +120,7 @@ .. seealso:: - :pep:`227` - Statically Nested Scopes + :pep:`227`\ ---Statically Nested Scopes Written and implemented by Jeremy Hylton. .. ====================================================================== @@ -150,7 +150,7 @@ .. seealso:: - :pep:`236` - Back to the :mod:`__future__` + :pep:`236`\ ---Back to the :mod:`__future__` Written by Tim Peters, and primarily implemented by Jeremy Hylton. .. ====================================================================== @@ -219,7 +219,7 @@ .. seealso:: - :pep:`207` - Rich Comparisions + :pep:`207`\ ---Rich Comparisions Written by Guido van Rossum, heavily based on earlier work by David Ascher, and implemented by Guido van Rossum. @@ -231,8 +231,8 @@ Over its 10 years of existence, Python has accumulated a certain number of obsolete modules and features along the way. It's difficult to know when a -feature is safe to remove, since there's no way of knowing how much code uses it ---- perhaps no programs depend on the feature, or perhaps many do. To enable +feature is safe to remove, since there's no way of knowing how much code uses +it---perhaps no programs depend on the feature, or perhaps many do. To enable removing old features in a more structured way, a warning framework was added. When the Python developers want to get rid of a feature, it will first trigger a warning in the next version of Python. The following Python version can then @@ -286,13 +286,13 @@ .. seealso:: - :pep:`5` - Guidelines for Language Evolution + :pep:`5`\ ---Guidelines for Language Evolution Written by Paul Prescod, to specify procedures to be followed when removing old features from Python. The policy described in this PEP hasn't been officially adopted, but the eventual policy probably won't be too different from Prescod's proposal. - :pep:`230` - Warning Framework + :pep:`230`\ ---Warning Framework Written and implemented by Guido van Rossum. .. ====================================================================== @@ -332,7 +332,7 @@ .. seealso:: - :pep:`229` - Using Distutils to Build Python + :pep:`229`\ ---Using Distutils to Build Python Written and implemented by A.M. Kuchling. .. ====================================================================== @@ -398,7 +398,7 @@ return retval The :mod:`weakref` module also allows creating proxy objects which behave like -weak references --- an object referenced only by proxy objects is deallocated -- +weak references---an object referenced only by proxy objects is deallocated --- but instead of requiring an explicit call to retrieve the object, the proxy transparently forwards all operations to the object as long as the object still exists. If the object is deallocated, attempting to use a proxy will cause a @@ -413,7 +413,7 @@ .. seealso:: - :pep:`205` - Weak References + :pep:`205`\ ---Weak References Written and implemented by Fred L. Drake, Jr. .. ====================================================================== @@ -451,7 +451,7 @@ .. seealso:: - :pep:`232` - Function Attributes + :pep:`232`\ ---Function Attributes Written and implemented by Barry Warsaw. .. ====================================================================== @@ -499,7 +499,7 @@ .. seealso:: - :pep:`217` - Display Hook for Interactive Use + :pep:`217`\ ---Display Hook for Interactive Use Written and implemented by Moshe Zadka. .. ====================================================================== @@ -529,7 +529,7 @@ .. seealso:: - :pep:`208` - Reworking the Coercion Model + :pep:`208`\ ---Reworking the Coercion Model Written and implemented by Neil Schemenauer, heavily based upon earlier work by Marc-André Lemburg. Read this to understand the fine points of how numeric operations will now be processed at the C level. @@ -567,10 +567,10 @@ .. seealso:: - :pep:`241` - Metadata for Python Software Packages + :pep:`241`\ ---Metadata for Python Software Packages Written and implemented by A.M. Kuchling. - :pep:`243` - Module Repository Upload Mechanism + :pep:`243`\ ---Module Repository Upload Mechanism Written by Sean Reifschneider, this draft PEP describes a proposed mechanism for uploading Python packages to a central server. diff -r afe119a3619f Doc/whatsnew/2.2.rst --- a/Doc/whatsnew/2.2.rst +++ b/Doc/whatsnew/2.2.rst @@ -120,8 +120,8 @@ This means that :keyword:`class` statements that don't have any base classes are always classic classes in Python 2.2. (Actually you can also change this by -setting a module-level variable named :attr:`__metaclass__` --- see :pep:`253` -for the details --- but it's easier to just subclass :keyword:`object`.) +setting a module-level variable named :attr:`__metaclass__`\ ---see :pep:`253` +for the details---but it's easier to just subclass :keyword:`object`.) The type objects for the built-in types are available as built-ins, named using a clever trick. Python has always had built-in functions named :func:`int`, @@ -531,7 +531,7 @@ .. seealso:: - :pep:`234` - Iterators + :pep:`234`\ ---Iterators Written by Ka-Ping Yee and GvR; implemented by the Python Labs crew, mostly by GvR and Tim Peters. @@ -658,7 +658,7 @@ .. seealso:: - :pep:`255` - Simple Generators + :pep:`255`\ ---Simple Generators Written by Neil Schemenauer, Tim Peters, Magnus Lie Hetland. Implemented mostly by Neil Schemenauer and Tim Peters, with other fixes from the Python Labs crew. @@ -698,7 +698,7 @@ .. seealso:: - :pep:`237` - Unifying Long Integers and Integers + :pep:`237`\ ---Unifying Long Integers and Integers Written by Moshe Zadka and Guido van Rossum. Implemented mostly by Guido van Rossum. @@ -767,7 +767,7 @@ .. seealso:: - :pep:`238` - Changing the Division Operator + :pep:`238`\ ---Changing the Division Operator Written by Moshe Zadka and Guido van Rossum. Implemented by Guido van Rossum.. .. ====================================================================== @@ -829,7 +829,7 @@ .. seealso:: - :pep:`261` - Support for 'wide' Unicode characters + :pep:`261`\ ---Support for 'wide' Unicode characters Written by Paul Prescod. .. ====================================================================== @@ -924,7 +924,7 @@ .. seealso:: - :pep:`227` - Statically Nested Scopes + :pep:`227`\ ---Statically Nested Scopes Written and implemented by Jeremy Hylton. .. ====================================================================== diff -r afe119a3619f Doc/whatsnew/2.3.rst --- a/Doc/whatsnew/2.3.rst +++ b/Doc/whatsnew/2.3.rst @@ -113,7 +113,7 @@ .. seealso:: - :pep:`218` - Adding a Built-In Set Object Type + :pep:`218`\ ---Adding a Built-In Set Object Type PEP written by Greg V. Wilson. Implemented by Greg V. Wilson, Alex Martelli, and GvR. @@ -244,7 +244,7 @@ .. seealso:: - :pep:`255` - Simple Generators + :pep:`255`\ ---Simple Generators Written by Neil Schemenauer, Tim Peters, Magnus Lie Hetland. Implemented mostly by Neil Schemenauer and Tim Peters, with other fixes from the Python Labs crew. @@ -278,7 +278,7 @@ .. seealso:: - :pep:`263` - Defining Python Source Code Encodings + :pep:`263`\ ---Defining Python Source Code Encodings Written by Marc-André Lemburg and Martin von Löwis; implemented by Suzuki Hisao and Martin von Löwis. @@ -323,7 +323,7 @@ .. seealso:: - :pep:`273` - Import Modules from Zip Archives + :pep:`273`\ ---Import Modules from Zip Archives Written by James C. Ahlstrom, who also provided an implementation. Python 2.3 follows the specification in :pep:`273`, but uses an implementation written by Just van Rossum that uses the import hooks described in :pep:`302`. See section @@ -359,7 +359,7 @@ .. seealso:: - :pep:`277` - Unicode file name support for Windows NT + :pep:`277`\ ---Unicode file name support for Windows NT Written by Neil Hodgson; implemented by Neil Hodgson, Martin von Löwis, and Mark Hammond. @@ -398,7 +398,7 @@ .. seealso:: - :pep:`278` - Universal Newline Support + :pep:`278`\ ---Universal Newline Support Written and implemented by Jack Jansen. .. ====================================================================== @@ -430,7 +430,7 @@ .. seealso:: - :pep:`279` - The enumerate() built-in function + :pep:`279`\ ---The enumerate() built-in function Written and implemented by Raymond D. Hettinger. .. ====================================================================== @@ -536,7 +536,7 @@ .. seealso:: - :pep:`282` - A Logging System + :pep:`282`\ ---A Logging System Written by Vinay Sajip and Trent Mick; implemented by Vinay Sajip. .. ====================================================================== @@ -608,7 +608,7 @@ .. seealso:: - :pep:`285` - Adding a bool type + :pep:`285`\ ---Adding a bool type Written and implemented by GvR. .. ====================================================================== @@ -640,7 +640,7 @@ .. seealso:: - :pep:`293` - Codec Error Handling Callbacks + :pep:`293`\ ---Codec Error Handling Callbacks Written and implemented by Walter Dörwald. .. ====================================================================== @@ -689,7 +689,7 @@ .. seealso:: - :pep:`301` - Package Index and Metadata for Distutils + :pep:`301`\ ---Package Index and Metadata for Distutils Written and implemented by Richard Jones. .. ====================================================================== @@ -755,7 +755,7 @@ .. seealso:: - :pep:`302` - New Import Hooks + :pep:`302`\ ---New Import Hooks Written by Just van Rossum and Paul Moore. Implemented by Just van Rossum. .. ====================================================================== @@ -800,7 +800,7 @@ .. seealso:: - :pep:`305` - CSV File API + :pep:`305`\ ---CSV File API Written and implemented by Kevin Altis, Dave Cole, Andrew McNamara, Skip Montanaro, Cliff Wells. @@ -844,7 +844,7 @@ .. seealso:: - :pep:`307` - Extensions to the pickle protocol + :pep:`307`\ ---Extensions to the pickle protocol Written and implemented by Guido van Rossum and Tim Peters. .. ====================================================================== diff -r afe119a3619f Doc/whatsnew/2.4.rst --- a/Doc/whatsnew/2.4.rst +++ b/Doc/whatsnew/2.4.rst @@ -79,7 +79,7 @@ .. seealso:: - :pep:`218` - Adding a Built-In Set Object Type + :pep:`218`\ ---Adding a Built-In Set Object Type Originally proposed by Greg Wilson and ultimately implemented by Raymond Hettinger. @@ -104,7 +104,7 @@ .. seealso:: - :pep:`237` - Unifying Long Integers and Integers + :pep:`237`\ ---Unifying Long Integers and Integers Original PEP written by Moshe Zadka and GvR. The changes for 2.4 were implemented by Kalle Svensson. @@ -161,7 +161,7 @@ .. seealso:: - :pep:`289` - Generator Expressions + :pep:`289`\ ---Generator Expressions Proposed by Raymond Hettinger and implemented by Jiwon Seo with early efforts steered by Hye-Shik Chang. @@ -208,7 +208,7 @@ .. seealso:: - :pep:`292` - Simpler String Substitutions + :pep:`292`\ ---Simpler String Substitutions Written and implemented by Barry Warsaw. .. ====================================================================== @@ -332,7 +332,7 @@ .. seealso:: - :pep:`318` - Decorators for Functions, Methods and Classes + :pep:`318`\ ---Decorators for Functions, Methods and Classes Written by Kevin D. Smith, Jim Jewett, and Skip Montanaro. Several people wrote patches implementing function decorators, but the one that was actually checked in was patch #979728, written by Mark Russell. @@ -373,7 +373,7 @@ .. seealso:: - :pep:`322` - Reverse Iteration + :pep:`322`\ ---Reverse Iteration Written and implemented by Raymond Hettinger. .. ====================================================================== @@ -461,7 +461,7 @@ .. seealso:: - :pep:`324` - subprocess - New process module + :pep:`324`\ ---subprocess---New process module Written and implemented by Peter Åstrand, with assistance from Fredrik Lundh and others. @@ -679,7 +679,7 @@ .. seealso:: - :pep:`327` - Decimal Data Type + :pep:`327`\ ---Decimal Data Type Written by Facundo Batista and implemented by Facundo Batista, Eric Price, Raymond Hettinger, Aahz, and Tim Peters. @@ -725,7 +725,7 @@ .. seealso:: - :pep:`328` - Imports: Multi-Line and Absolute/Relative + :pep:`328`\ ---Imports: Multi-Line and Absolute/Relative Written by Aahz. Multi-line imports were implemented by Dima Dorfman. .. ====================================================================== @@ -764,7 +764,7 @@ .. seealso:: - :pep:`331` - Locale-Independent Float/String Conversions + :pep:`331`\ ---Locale-Independent Float/String Conversions Written by Christian R. Reis, and implemented by Gustavo Carneiro. .. ====================================================================== diff -r afe119a3619f Doc/whatsnew/2.5.rst --- a/Doc/whatsnew/2.5.rst +++ b/Doc/whatsnew/2.5.rst @@ -119,7 +119,7 @@ .. seealso:: - :pep:`308` - Conditional Expressions + :pep:`308`\ ---Conditional Expressions PEP written by Guido van Rossum and Raymond D. Hettinger; implemented by Thomas Wouters. @@ -197,7 +197,7 @@ .. seealso:: - :pep:`309` - Partial Function Application + :pep:`309`\ ---Partial Function Application PEP proposed and written by Peter Harris; implemented by Hye-Shik Chang and Nick Coghlan, with adaptations by Raymond Hettinger. @@ -244,7 +244,7 @@ .. seealso:: - :pep:`314` - Metadata for Python Software Packages v1.1 + :pep:`314`\ ---Metadata for Python Software Packages v1.1 PEP proposed and written by A.M. Kuchling, Richard Jones, and Fred Drake; implemented by Richard Jones and Fred Drake. @@ -327,7 +327,7 @@ .. seealso:: - :pep:`328` - Imports: Multi-Line and Absolute/Relative + :pep:`328`\ ---Imports: Multi-Line and Absolute/Relative PEP written by Aahz; implemented by Thomas Wouters. http://codespeak.net/py/current/doc/index.html @@ -356,7 +356,7 @@ .. seealso:: - :pep:`338` - Executing modules as scripts + :pep:`338`\ ---Executing modules as scripts PEP written and implemented by Nick Coghlan. .. ====================================================================== @@ -404,7 +404,7 @@ .. seealso:: - :pep:`341` - Unifying try-except and try-finally + :pep:`341`\ ---Unifying try-except and try-finally PEP written by Georg Brandl; implementation by Thomas Lee. .. ====================================================================== @@ -540,7 +540,7 @@ .. seealso:: - :pep:`342` - Coroutines via Enhanced Generators + :pep:`342`\ ---Coroutines via Enhanced Generators PEP written by Guido van Rossum and Phillip J. Eby; implemented by Phillip J. Eby. Includes examples of some fancier uses of generators as coroutines. @@ -795,7 +795,7 @@ .. seealso:: - :pep:`343` - The "with" statement + :pep:`343`\ ---The "with" statement PEP written by Guido van Rossum and Nick Coghlan; implemented by Mike Bland, Guido van Rossum, and Neal Norwitz. The PEP shows the code generated for a ':keyword:`with`' statement, which can be helpful in learning how the statement @@ -859,7 +859,7 @@ .. seealso:: - :pep:`352` - Required Superclass for Exceptions + :pep:`352`\ ---Required Superclass for Exceptions PEP written by Brett Cannon and Guido van Rossum; implemented by Brett Cannon. .. ====================================================================== @@ -880,8 +880,8 @@ in an :c:type:`int`. The C compilers for most 64-bit platforms still define :c:type:`int` as a 32-bit type, so that meant that lists could only hold up to ``2**31 - 1`` = 2147483647 items. (There are actually a few different -programming models that 64-bit C compilers can use -- see -http://www.unix.org/version2/whatsnew/lp64_wp.html for a discussion -- but the +programming models that 64-bit C compilers can use---see +http://www.unix.org/version2/whatsnew/lp64_wp.html for a discussion---but the most commonly available model leaves :c:type:`int` as 32 bits.) A limit of 2147483647 items doesn't really matter on a 32-bit platform because @@ -918,7 +918,7 @@ .. seealso:: - :pep:`353` - Using ssize_t as the index type + :pep:`353`\ ---Using ssize_t as the index type PEP written and implemented by Martin von Löwis. .. ====================================================================== @@ -961,7 +961,7 @@ .. seealso:: - :pep:`357` - Allowing Any Object to be Used for Slicing + :pep:`357`\ ---Allowing Any Object to be Used for Slicing PEP written and implemented by Travis Oliphant. .. ====================================================================== @@ -2027,7 +2027,7 @@ The documentation for the :mod:`sqlite3` module. - :pep:`249` - Database API Specification 2.0 + :pep:`249`\ ---Database API Specification 2.0 PEP written by Marc-André Lemburg. .. ====================================================================== @@ -2067,7 +2067,7 @@ http://www.wsgi.org A central web site for WSGI-related resources. - :pep:`333` - Python Web Server Gateway Interface v1.0 + :pep:`333`\ ---Python Web Server Gateway Interface v1.0 PEP written by Phillip J. Eby. .. ====================================================================== diff -r afe119a3619f Doc/whatsnew/2.6.rst --- a/Doc/whatsnew/2.6.rst +++ b/Doc/whatsnew/2.6.rst @@ -485,7 +485,7 @@ .. seealso:: - :pep:`343` - The "with" statement + :pep:`343`\ ---The "with" statement PEP written by Guido van Rossum and Nick Coghlan; implemented by Mike Bland, Guido van Rossum, and Neal Norwitz. The PEP shows the code generated for a ':keyword:`with`' statement, which can be helpful in learning how the statement @@ -549,7 +549,7 @@ .. seealso:: - :pep:`370` - Per-user ``site-packages`` Directory + :pep:`370`\ ---Per-user ``site-packages`` Directory PEP written and implemented by Christian Heimes. @@ -705,7 +705,7 @@ The documentation for the :mod:`multiprocessing` module. - :pep:`371` - Addition of the multiprocessing package + :pep:`371`\ ---Addition of the multiprocessing package PEP written by Jesse Noller and Richard Oudkerk; implemented by Richard Oudkerk and Jesse Noller. @@ -848,7 +848,7 @@ :ref:`formatstrings` The reference documentation for format fields. - :pep:`3101` - Advanced String Formatting + :pep:`3101`\ ---Advanced String Formatting PEP written by Talin. Implemented by Eric Smith. .. ====================================================================== @@ -883,7 +883,7 @@ .. seealso:: - :pep:`3105` - Make print a function + :pep:`3105`\ ---Make print a function PEP written by Georg Brandl. .. ====================================================================== @@ -934,7 +934,7 @@ .. seealso:: - :pep:`3110` - Catching Exceptions in Python 3000 + :pep:`3110`\ ---Catching Exceptions in Python 3000 PEP written and implemented by Collin Winter. .. ====================================================================== @@ -1018,7 +1018,7 @@ .. seealso:: - :pep:`3112` - Bytes literals in Python 3000 + :pep:`3112`\ ---Bytes literals in Python 3000 PEP written by Jason Orendorff; backported to 2.6 by Christian Heimes. .. ====================================================================== @@ -1098,7 +1098,7 @@ .. seealso:: - :pep:`3116` - New I/O + :pep:`3116`\ ---New I/O PEP written by Daniel Stutzbach, Mike Verdone, and Guido van Rossum. Code by Guido van Rossum, Georg Brandl, Walter Doerwald, Jeremy Hylton, Martin von Löwis, Tony Lownds, and others. @@ -1151,7 +1151,7 @@ .. seealso:: - :pep:`3118` - Revising the buffer protocol + :pep:`3118`\ ---Revising the buffer protocol PEP written by Travis Oliphant and Carl Banks; implemented by Travis Oliphant. @@ -1298,7 +1298,7 @@ .. seealso:: - :pep:`3119` - Introducing Abstract Base Classes + :pep:`3119`\ ---Introducing Abstract Base Classes PEP written by Guido van Rossum and Talin. Implemented by Guido van Rossum. Backported to 2.6 by Benjamin Aranguren, with Alex Martelli. @@ -1351,7 +1351,7 @@ .. seealso:: - :pep:`3127` - Integer Literal Support and Syntax + :pep:`3127`\ ---Integer Literal Support and Syntax PEP written by Patrick Maupin; backported to 2.6 by Eric Smith. @@ -1379,7 +1379,7 @@ .. seealso:: - :pep:`3129` - Class Decorators + :pep:`3129`\ ---Class Decorators PEP written by Collin Winter. .. ====================================================================== @@ -1428,7 +1428,7 @@ .. seealso:: - :pep:`3141` - A Type Hierarchy for Numbers + :pep:`3141`\ ---A Type Hierarchy for Numbers PEP written by Jeffrey Yasskin. `Scheme's numerical tower `__, from the Guile manual. diff -r afe119a3619f Doc/whatsnew/2.7.rst --- a/Doc/whatsnew/2.7.rst +++ b/Doc/whatsnew/2.7.rst @@ -259,7 +259,7 @@ .. seealso:: - :pep:`372` - Adding an ordered dictionary to collections + :pep:`372`\ ---Adding an ordered dictionary to collections PEP written by Armin Ronacher and Raymond Hettinger; implemented by Raymond Hettinger. @@ -298,7 +298,7 @@ .. seealso:: - :pep:`378` - Format Specifier for Thousands Separator + :pep:`378`\ ---Format Specifier for Thousands Separator PEP written by Raymond Hettinger; implemented by Eric Smith. PEP 389: The argparse Module for Parsing Command Lines @@ -396,7 +396,7 @@ Part of the Python documentation, describing how to convert code that uses :mod:`optparse`. - :pep:`389` - argparse - New Command Line Parsing Module + :pep:`389`\ ---argparse---New Command Line Parsing Module PEP written and implemented by Steven Bethard. PEP 391: Dictionary-Based Configuration For Logging @@ -495,7 +495,7 @@ .. seealso:: - :pep:`391` - Dictionary-Based Configuration For Logging + :pep:`391`\ ---Dictionary-Based Configuration For Logging PEP written and implemented by Vinay Sajip. PEP 3106: Dictionary Views @@ -555,7 +555,7 @@ .. seealso:: - :pep:`3106` - Revamping dict.keys(), .values() and .items() + :pep:`3106`\ ---Revamping dict.keys(), .values() and .items() PEP written by Guido van Rossum. Backported to 2.7 by Alexandre Vassalotti; :issue:`1967`. @@ -605,7 +605,7 @@ .. seealso:: - :pep:`3137` - Immutable Bytes and Mutable Buffer + :pep:`3137`\ ---Immutable Bytes and Mutable Buffer PEP written by Guido van Rossum. Implemented by Travis Oliphant, Antoine Pitrou and others. Backported to 2.7 by Antoine Pitrou; :issue:`2396`. @@ -738,8 +738,8 @@ The auto-numbering takes the fields from left to right, so the first ``{...}`` specifier will use the first argument to :meth:`str.format`, the next specifier will use the next argument, and so on. You can't mix auto-numbering - and explicit numbering -- either number all of your specifier fields or none - of them -- but you can mix auto-numbering and named fields, as in the second + and explicit numbering---either number all of your specifier fields or none + of them---but you can mix auto-numbering and named fields, as in the second example above. (Contributed by Eric Smith; :issue:`5237`.) Complex numbers now correctly support usage with :func:`format`, @@ -2017,8 +2017,8 @@ * Deprecated: using an element as a Boolean (i.e., ``if elem:``) would return true if the element had any children, or false if there were - no children. This behaviour is confusing -- ``None`` is false, but - so is a childless element? -- so it will now trigger a + no children. This behaviour is confusing---\ ``None`` is false, but + so is a childless element?---so it will now trigger a :exc:`FutureWarning`. In your code, you should be explicit: write ``len(elem) != 0`` if you're interested in the number of children, or ``elem is not None``. diff -r afe119a3619f Doc/whatsnew/3.0.rst --- a/Doc/whatsnew/3.0.rst +++ b/Doc/whatsnew/3.0.rst @@ -56,7 +56,7 @@ *intentionally backwards incompatible* Python release. There are more changes than in a typical release, and more that are important for all Python users. Nevertheless, after digesting the changes, you'll find -that Python really hasn't changed all that much -- by and large, we're +that Python really hasn't changed all that much---by and large, we're mostly fixing well-known annoyances and warts, and removing a lot of old cruft. @@ -185,7 +185,7 @@ > None`` or ``len <= len`` are no longer valid, and e.g. ``None < None`` raises :exc:`TypeError` instead of returning ``False``. A corollary is that sorting a heterogeneous list - no longer makes sense -- all the elements must be comparable to each + no longer makes sense---all the elements must be comparable to each other. Note that this does not apply to the ``==`` and ``!=`` operators: objects of different incomparable types always compare unequal to each other. @@ -634,7 +634,7 @@ * Cleanup of the :class:`array.array` type: the :meth:`read` and :meth:`write` methods are gone; use :meth:`fromfile` and :meth:`tofile` instead. Also, the ``'c'`` typecode for array is - gone -- use either ``'b'`` for bytes or ``'u'`` for Unicode + gone---use either ``'b'`` for bytes or ``'u'`` for Unicode characters. * Cleanup of the :mod:`operator` module: removed @@ -771,8 +771,8 @@ * :pep:`3114`: the standard :meth:`next` method has been renamed to :meth:`~iterator.__next__`. -* The :meth:`__oct__` and :meth:`__hex__` special methods are removed - -- :func:`oct` and :func:`hex` use :meth:`__index__` now to convert +* The :meth:`__oct__` and :meth:`__hex__` special methods are + removed---\ :func:`oct` and :func:`hex` use :meth:`__index__` now to convert the argument to an integer. * Removed support for :attr:`__members__` and :attr:`__methods__`. @@ -840,7 +840,7 @@ * Removed :func:`reload`. Use :func:`imp.reload`. -* Removed. :meth:`dict.has_key` -- use the :keyword:`in` operator +* Removed. :meth:`dict.has_key`\ ---use the :keyword:`in` operator instead. .. ====================================================================== diff -r afe119a3619f Doc/whatsnew/3.1.rst --- a/Doc/whatsnew/3.1.rst +++ b/Doc/whatsnew/3.1.rst @@ -75,7 +75,7 @@ .. seealso:: - :pep:`372` - Ordered Dictionaries + :pep:`372`\ ---Ordered Dictionaries PEP written by Armin Ronacher and Raymond Hettinger. Implementation written by Raymond Hettinger. @@ -107,7 +107,7 @@ .. seealso:: - :pep:`378` - Format Specifier for Thousands Separator + :pep:`378`\ ---Format Specifier for Thousands Separator PEP written by Raymond Hettinger and implemented by Eric Smith and Mark Dickinson. diff -r afe119a3619f Doc/whatsnew/3.2.rst --- a/Doc/whatsnew/3.2.rst +++ b/Doc/whatsnew/3.2.rst @@ -10,7 +10,7 @@ * Anyone can add text to this document. Do not spend very much time on the wording of your changes, because your text will probably get rewritten. (Note, during release candidate phase or just before - a beta release, please use the tracker instead -- this helps avoid + a beta release, please use the tracker instead---this helps avoid merge conflicts. If you must add a suggested entry directly, please put it in an XXX comment and the maintainer will take notice). @@ -54,7 +54,7 @@ .. seealso:: - :pep:`392` - Python 3.2 Release Schedule + :pep:`392`\ ---Python 3.2 Release Schedule PEP 384: Defining a Stable ABI @@ -77,7 +77,7 @@ .. seealso:: - :pep:`384` - Defining a Stable ABI + :pep:`384`\ ---Defining a Stable ABI PEP written by Martin von Löwis. @@ -167,7 +167,7 @@ .. seealso:: - :pep:`389` - New Command Line Parsing Module + :pep:`389`\ ---New Command Line Parsing Module PEP written by Steven Bethard. :ref:`upgrading-optparse-code` for details on the differences from :mod:`optparse`. @@ -221,7 +221,7 @@ .. seealso:: - :pep:`391` - Dictionary Based Configuration for Logging + :pep:`391`\ ---Dictionary Based Configuration for Logging PEP written by Vinay Sajip. @@ -272,7 +272,7 @@ .. seealso:: - :pep:`3148` - Futures -- Execute Computations Asynchronously + :pep:`3148`\ ---Futures---Execute Computations Asynchronously PEP written by Brian Quinlan. :ref:`Code for Threaded Parallel URL reads`, an @@ -344,7 +344,7 @@ .. seealso:: - :pep:`3147` - PYC Repository Directories + :pep:`3147`\ ---PYC Repository Directories PEP written by Barry Warsaw. @@ -375,7 +375,7 @@ .. seealso:: - :pep:`3149` - ABI Version Tagged .so Files + :pep:`3149`\ ---ABI Version Tagged .so Files PEP written by Barry Warsaw. @@ -422,7 +422,7 @@ .. seealso:: - :pep:`3333` - Python Web Server Gateway Interface v1.0.1 + :pep:`3333`\ ---Python Web Server Gateway Interface v1.0.1 PEP written by Phillip Eby. @@ -1765,7 +1765,7 @@ :meth:`~unittest.TestCase.assertRegexpMatches` which was misnamed because the test uses :func:`re.search`, not :func:`re.match`. Other methods using regular expressions are now named using short form "Regex" in preference to - "Regexp" -- this matches the names used in other unittest implementations, + "Regexp"\ ---this matches the names used in other unittest implementations, matches Python's old name for the :mod:`re` module, and it has unambiguous camel-casing. @@ -2529,7 +2529,7 @@ * :c:macro:`PyEval_CallObject` is now only available in macro form. The function declaration, which was kept for backwards compatibility reasons, is - now removed -- the macro was introduced in 1997 (:issue:`8276`). + now removed---the macro was introduced in 1997 (:issue:`8276`). * There is a new function :c:func:`PyLong_AsLongLongAndOverflow` which is analogous to :c:func:`PyLong_AsLongAndOverflow`. They both serve to diff -r afe119a3619f Doc/whatsnew/3.3.rst --- a/Doc/whatsnew/3.3.rst +++ b/Doc/whatsnew/3.3.rst @@ -48,11 +48,11 @@ .. seealso:: - :pep:`398` - Python 3.3 Release Schedule - - -Summary -- Release highlights -============================= + :pep:`398`\ ---Python 3.3 Release Schedule + + +Summary---Release highlights +============================== .. This section singles out the most important changes in Python 3.3. Brevity is key. @@ -115,7 +115,7 @@ .. seealso:: - :pep:`405` - Python Virtual Environments + :pep:`405`\ ---Python Virtual Environments PEP written by Carl Meyer; implementation by Carl Meyer and Vinay Sajip @@ -129,7 +129,7 @@ .. seealso:: - :pep:`420` - Implicit Namespace Packages + :pep:`420`\ ---Implicit Namespace Packages PEP written by Eric V. Smith; implementation by Eric V. Smith and Barry Warsaw @@ -200,7 +200,7 @@ .. seealso:: - :pep:`3118` - Revising the Buffer Protocol + :pep:`3118`\ ---Revising the Buffer Protocol .. _pep-393: @@ -219,7 +219,7 @@ On the C API side, PEP 393 is fully backward compatible. The legacy API should remain available at least five years. Applications using the legacy -API will not fully benefit of the memory reduction, or - worse - may use +API will not fully benefit of the memory reduction, or---worse---may use a bit more memory, because Python may have to maintain two versions of each string (in the legacy format and in the new efficient storage). @@ -267,8 +267,8 @@ * non-BMP strings (``U+10000-U+10FFFF``) use 4 bytes per codepoint. The net effect is that for most applications, memory usage of string -storage should decrease significantly - especially compared to former -wide unicode builds - as, in many cases, strings will be pure ASCII +storage should decrease significantly---especially compared to former +wide unicode builds---as, in many cases, strings will be pure ASCII even in international contexts (because many strings store non-human language data, such as XML fragments, HTTP headers, JSON-encoded data, etc.). We also hope that it will, for the same reasons, increase CPU @@ -279,7 +279,7 @@ .. seealso:: - :pep:`393` - Flexible String Representation + :pep:`393`\ ---Flexible String Representation PEP written by Martin von Löwis; implementation by Torsten Becker and Martin von Löwis. @@ -312,7 +312,7 @@ .. seealso:: - :pep:`397` - Python Launcher for Windows + :pep:`397`\ ---Python Launcher for Windows PEP written by Mark Hammond and Martin v. Löwis; implementation by Vinay Sajip. @@ -389,7 +389,7 @@ .. seealso:: - :pep:`3151` - Reworking the OS and IO Exception Hierarchy + :pep:`3151`\ ---Reworking the OS and IO Exception Hierarchy PEP written and implemented by Antoine Pitrou @@ -459,7 +459,7 @@ .. seealso:: - :pep:`380` - Syntax for Delegating to a Subgenerator + :pep:`380`\ ---Syntax for Delegating to a Subgenerator PEP written by Greg Ewing; implementation by Greg Ewing, integrated into 3.3 by Renaud Blanch, Ryan Kelly and Nick Coghlan; documentation by Zbigniew Jędrzejewski-Szmek and Nick Coghlan @@ -524,7 +524,7 @@ .. seealso:: - :pep:`409` - Suppressing exception context + :pep:`409`\ ---Suppressing exception context PEP written by Ethan Furman; implemented by Ethan Furman and Nick Coghlan. @@ -542,7 +542,7 @@ .. seealso:: - :pep:`414` - Explicit Unicode literals + :pep:`414`\ ---Explicit Unicode literals PEP written by Armin Ronacher. @@ -603,7 +603,7 @@ .. seealso:: - :pep:`3155` - Qualified name for classes and functions + :pep:`3155`\ ---Qualified name for classes and functions PEP written and implemented by Antoine Pitrou. @@ -619,7 +619,7 @@ .. seealso:: - :pep:`412` - Key-Sharing Dictionary + :pep:`412`\ ---Key-Sharing Dictionary PEP written and implemented by Mark Shannon. @@ -637,7 +637,7 @@ .. seealso:: - :pep:`362`: - Function Signature Object + :pep:`362`:\ ---Function Signature Object PEP written by Brett Cannon, Yury Selivanov, Larry Hastings, Jiwon Seo; implemented by Yury Selivanov. @@ -675,7 +675,7 @@ .. seealso:: - :pep:`421` - Adding sys.implementation + :pep:`421`\ ---Adding sys.implementation PEP written and implemented by Eric Snow. @@ -683,10 +683,10 @@ Using importlib as the Implementation of Import =============================================== -:issue:`2377` - Replace __import__ w/ importlib.__import__ -:issue:`13959` - Re-implement parts of :mod:`imp` in pure Python -:issue:`14605` - Make import machinery explicit -:issue:`14646` - Require loaders set __loader__ and __package__ +:issue:`2377`\ ---Replace __import__ w/ importlib.__import__ +:issue:`13959`\ ---Re-implement parts of :mod:`imp` in pure Python +:issue:`14605`\ ---Make import machinery explicit +:issue:`14646`\ ---Require loaders set __loader__ and __package__ The :func:`__import__` function is now powered by :func:`importlib.__import__`. This work leads to the completion of "phase 2" of :pep:`302`. There are @@ -1091,7 +1091,7 @@ decimal ------- -:issue:`7652` - integrate fast native decimal arithmetic. +:issue:`7652`\ ---integrate fast native decimal arithmetic. C-module and libmpdec written by Stefan Krah. The new C version of the decimal module integrates the high speed libmpdec diff -r afe119a3619f Doc/whatsnew/3.4.rst --- a/Doc/whatsnew/3.4.rst +++ b/Doc/whatsnew/3.4.rst @@ -18,7 +18,7 @@ time of the original release will remain largely unknown to the community for years, even if they're added later. We also know from experience that other priorities can arise, and the maintainer will run out of time to do - updates - in such cases, end users will be much better served by partial + updates---in such cases, end users will be much better served by partial notifications that at least give a hint about new features to investigate. @@ -75,11 +75,11 @@ .. seealso:: - .. :pep:`4XX` - Python 3.4 Release Schedule + .. :pep:`4XX`\ ---Python 3.4 Release Schedule -Summary -- Release highlights -============================= +Summary---Release highlights +============================== .. This section singles out the most important changes in Python 3.4. Brevity is key.