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/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/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`. diff -r afe119a3619f Doc/c-api/intro.rst --- a/Doc/c-api/intro.rst +++ b/Doc/c-api/intro.rst @@ -181,7 +181,7 @@ reference is no longer needed. Ownership can also be transferred, meaning that the code that receives ownership of the reference then becomes responsible for eventually decref'ing it by calling :c:func:`Py_DECREF` or :c:func:`Py_XDECREF` -when it's no longer needed---or passing on this responsibility (usually to its +when it's no longer needed --- or passing on this responsibility (usually to its caller). When a function passes ownership of a reference on to its caller, the caller is said to receive a *new* reference. When no ownership is transferred, the caller is said to *borrow* the reference. Nothing needs to be done for a 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,9 +231,9 @@ a Unicode object (not checked). .. versionchanged:: 3.3 - This macro is now inefficient -- because in many cases the + 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 + --- 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`. @@ -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 @@ -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 | @@ -350,7 +350,7 @@ default compilers are "traditional Unix interface" (:class:`UnixCCompiler` class) and Visual C++ (:class:`MSVCCompiler` class). Note that it's perfectly possible to ask for a Unix compiler object under Windows, and a Microsoft - compiler object under Unix---if you supply a value for *compiler*, *plat* is + compiler object under Unix --- if you supply a value for *compiler*, *plat* is ignored. .. % Is the posix/nt only thing still true? Mac OS X seems to work, and @@ -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 @@ -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. @@ -1576,7 +1576,7 @@ | *strip_comments* | strip from ``'#'`` to end-of- | true | | | line, as well as any | | | | whitespace leading up to the | | - | | ``'#'``\ ---unless it is | | + | | ``'#'`` --- unless it is | | | | escaped by a backslash | | +------------------+--------------------------------+---------+ | *lstrip_ws* | strip leading whitespace from | false | @@ -1814,7 +1814,7 @@ ================================================================ .. 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 diff -r afe119a3619f Doc/distutils/builtdist.rst --- a/Doc/distutils/builtdist.rst +++ b/Doc/distutils/builtdist.rst @@ -17,7 +17,7 @@ users, it's a Debian package; and so forth. Obviously, no one person will be able to create built distributions for every platform under the sun, so the Distutils are designed to enable module developers to concentrate on their -specialty---writing code and creating source distributions---while an +specialty --- writing code and creating source distributions --- while an intermediary species called *packagers* springs up to turn source distributions into built distributions for as many platforms as there are packagers. @@ -50,7 +50,7 @@ distributions relative to :file:`{prefix}`.) Obviously, for pure Python distributions, this isn't any simpler than just -running ``python setup.py install``\ ---but for non-pure distributions, which +running ``python setup.py install`` --- but for non-pure distributions, which include extensions that would need to be compiled, it can mean the difference between someone being able to use your extensions or not. And creating "smart" built distributions, such as an RPM package or an executable installer for @@ -63,8 +63,8 @@ python setup.py bdist --format=zip -would, when run on a Unix system, create :file:`Distutils-1.0.{plat}.zip`\ ----again, this archive would be unpacked from the root directory to install the +would, when run on a Unix system, create :file:`Distutils-1.0.{plat}.zip` +--- again, this archive would be unpacked from the root directory to install the Distutils. The available formats for built distributions are: @@ -236,7 +236,7 @@ Obviously, supplying even a few of these options on the command-line would be tedious and error-prone, so it's usually best to put them in the setup -configuration file, :file:`setup.cfg`\ ---see section :ref:`setup-config`. If +configuration file, :file:`setup.cfg` --- see section :ref:`setup-config`. If you distribute or package many Python module distributions, you might want to put options that apply to all of them in your personal Distutils configuration file (:file:`~/.pydistutils.cfg`). @@ -259,12 +259,12 @@ If you wish, you can separate these three steps. You can use the :option:`--spec-only` option to make :command:`bdist_rpm` just create the :file:`.spec` file and exit; in this case, the :file:`.spec` file will be -written to the "distribution directory"---normally :file:`dist/`, but +written to the "distribution directory" --- normally :file:`dist/`, but customizable with the :option:`--dist-dir` option. (Normally, the :file:`.spec` file winds up deep in the "build tree," in a temporary directory created by :command:`bdist_rpm`.) -.. % \XXX{this isn't implemented yet---is it needed?!} +.. % \XXX{this isn't implemented yet --- is it needed?!} .. % You can also specify a custom \file{.spec} file with the .. % \longprogramopt{spec-file} option; used in conjunction with .. % \longprogramopt{spec-only}, this gives you an opportunity to customize @@ -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/configfile.rst --- a/Doc/distutils/configfile.rst +++ b/Doc/distutils/configfile.rst @@ -7,14 +7,14 @@ Often, it's not possible to write down everything needed to build a distribution *a priori*: you may need to get some information from the user, or from the user's system, in order to proceed. As long as that information is fairly -simple---a list of directories to search for C header files or libraries, for -example---then providing a configuration file, :file:`setup.cfg`, for users to +simple --- a list of directories to search for C header files or libraries, for +example --- then providing a configuration file, :file:`setup.cfg`, for users to edit is a cheap and easy way to solicit it. Configuration files also let you provide default values for any command option, which the installer can then override either on the command-line or by editing the config file. The setup configuration file is a useful middle-ground between the setup script ----which, ideally, would be opaque to installers [#]_---and the command-line to +--- which, ideally, would be opaque to installers [#]_ --- and the command-line to the setup script, which is outside of your control and entirely up to the installer. In fact, :file:`setup.cfg` (and any other Distutils configuration files present on the target system) are processed after the contents of the @@ -69,7 +69,7 @@ Note that an option spelled :option:`--foo-bar` on the command-line is spelled :option:`foo_bar` in configuration files. -For example, say you want your extensions to be built "in-place"---that is, you +For example, say you want your extensions to be built "in-place" --- that is, you have an extension :mod:`pkg.ext`, and you want the compiled extension file (:file:`ext.so` on Unix, say) to be put in the same source directory as your pure Python modules :mod:`pkg.mod1` and :mod:`pkg.mod2`. You can always use the @@ -87,7 +87,7 @@ This will affect all builds of this module distribution, whether or not you explicitly specify :command:`build_ext`. If you include :file:`setup.cfg` in -your source distribution, it will also affect end-user builds---which is +your source distribution, it will also affect end-user builds --- which is probably a bad idea for this option, since always building extensions in-place would break installation of the module distribution. In certain peculiar cases, though, modules are built right in their installation directory, so this is diff -r afe119a3619f Doc/distutils/introduction.rst --- a/Doc/distutils/introduction.rst +++ b/Doc/distutils/introduction.rst @@ -95,8 +95,8 @@ will unpack into a directory :file:`foo-1.0`. If an end-user wishes to install your :mod:`foo` module, all she has to do is -download :file:`foo-1.0.tar.gz` (or :file:`.zip`), unpack it, and---from the -:file:`foo-1.0` directory---run :: +download :file:`foo-1.0.tar.gz` (or :file:`.zip`), unpack it, and --- from the +:file:`foo-1.0` directory --- run :: python setup.py install diff -r afe119a3619f Doc/distutils/setupscript.rst --- a/Doc/distutils/setupscript.rst +++ b/Doc/distutils/setupscript.rst @@ -110,7 +110,7 @@ ========================== For a small module distribution, you might prefer to list all modules rather -than listing packages---especially the case of a single module that goes in the +than listing packages --- especially the case of a single module that goes in the "root package" (i.e., no package at all). This simplest case was shown in section :ref:`distutils-simple-example`; here is a slightly more involved example:: @@ -258,7 +258,7 @@ Python header files are installed (on a standard Unix installation) to :file:`/usr/local/include/python1.5/Numerical`. (The exact location will differ according to your platform and Python installation.) Since the Python include -directory---\ :file:`/usr/local/include/python1.5` in this case---is always +directory --- :file:`/usr/local/include/python1.5` in this case --- is always included in the search path when building Python extensions, the best approach is to write C code like :: @@ -274,8 +274,8 @@ Extension(..., include_dirs=[incdir]), ) -Even though this is quite portable---it will work on any Python installation, -regardless of platform---it's probably easier to just write your C code in the +Even though this is quite portable --- it will work on any Python installation, +regardless of platform --- it's probably easier to just write your C code in the sensible way. You can define and undefine pre-processor macros with the ``define_macros`` and diff -r afe119a3619f Doc/distutils/sourcedist.rst --- a/Doc/distutils/sourcedist.rst +++ b/Doc/distutils/sourcedist.rst @@ -70,7 +70,7 @@ * all C source files mentioned in the :option:`ext_modules` or :option:`libraries` options ( - .. XXX getting C library sources currently broken---no + .. XXX getting C library sources currently broken --- no :meth:`get_source_files` method in :file:`build_clib.py`! * scripts identified by the :option:`scripts` option @@ -160,7 +160,7 @@ #. include all Python source files in the :file:`distutils` and :file:`distutils/command` subdirectories (because packages corresponding to those two directories were mentioned in the :option:`packages` option in the - setup script---see section :ref:`setup-script`) + setup script --- see section :ref:`setup-script`) #. include :file:`README.txt`, :file:`setup.py`, and :file:`setup.cfg` (standard files) @@ -174,7 +174,7 @@ under :file:`examples`, #. exclude all files in the sub-trees starting at directories matching - :file:`examples/sample?/build`\ ---this may exclude files included by the + :file:`examples/sample?/build` --- this may exclude files included by the previous two steps, so it's important that the ``prune`` command in the manifest template comes after the ``recursive-include`` command diff -r afe119a3619f Doc/extending/extending.rst --- a/Doc/extending/extending.rst +++ b/Doc/extending/extending.rst @@ -1073,7 +1073,7 @@ .. 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. diff -r afe119a3619f Doc/extending/newtypes.rst --- a/Doc/extending/newtypes.rst +++ b/Doc/extending/newtypes.rst @@ -51,8 +51,8 @@ PyObject_HEAD } noddy_NoddyObject; -This is what a Noddy object will contain---in this case, nothing more than what -every Python object contains---a refcount and a pointer to a type object. +This is what a Noddy object will contain --- in this case, nothing more than what +every Python object contains --- a refcount and a pointer to a type object. These are the fields the ``PyObject_HEAD`` macro brings in. The reason for the macro is to standardize the layout and to enable special debugging fields in debug builds. Note that there is no semicolon after the ``PyObject_HEAD`` @@ -859,7 +859,7 @@ 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. +--- 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 +879,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 +893,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! :: @@ -909,7 +909,7 @@ Here you can put a string (or its address) that you want returned when the Python script references ``obj.__doc__`` to retrieve the doc string. -Now we come to the basic type methods---the ones most extension types will +Now we come to the basic type methods --- the ones most extension types will implement. 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. @@ -112,7 +112,7 @@ 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 +--- 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. @@ -120,7 +120,7 @@ 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 @@ -766,7 +766,7 @@ 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 +--- ``0`` or ``errno.EISCONN`` indicate that you're connected --- or you can pass this socket to select to check if it's writable. .. note:: diff -r afe119a3619f Doc/faq/programming.rst --- a/Doc/faq/programming.rst +++ b/Doc/faq/programming.rst @@ -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/curses.rst --- a/Doc/howto/curses.rst +++ b/Doc/howto/curses.rst @@ -36,8 +36,8 @@ The curses library provides fairly basic functionality, providing the programmer with an abstraction of a display containing multiple non-overlapping windows of text. The contents of a window can be -changed in various ways---adding text, erasing it, changing its -appearance---and the curses library will figure out what control codes +changed in various ways --- adding text, erasing it, changing its +appearance --- and the curses library will figure out what control codes need to be sent to the terminal to produce the right output. curses doesn't provide many user-interface concepts such as buttons, checkboxes, or dialogs; if you need such features, consider a user interface library such as 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,8 +1211,8 @@ .. _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 of queues, for example a ZeroMQ 'publish' socket. In the example below,the @@ -1251,8 +1251,8 @@ 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 of queues, for example a ZeroMQ 'subscribe' socket. Here's an example:: @@ -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/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. @@ -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 `_. @@ -504,7 +504,7 @@ 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` + --- ``ProxyHandler`` (if a proxy setting such as an :envvar:`http_proxy` environment variable is set), ``UnknownHandler``, ``HTTPHandler``, ``HTTPDefaultErrorHandler``, ``HTTPRedirectHandler``, ``FTPHandler``, ``FileHandler``, ``DataHandler``, ``HTTPErrorProcessor``. @@ -514,7 +514,7 @@ 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. @@ -225,7 +225,7 @@ ``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 +--- 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``, @@ -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 @@ -69,7 +69,7 @@ In that case, you would download the installer appropriate to your platform and do the obvious thing with it: run it if it's an executable installer, ``rpm --install`` it if it's an RPM, etc. You don't need to run Python or a setup -script, you don't need to compile anything---you might not even need to read any +script, you don't need to compile anything --- you might not even need to read any instructions (although it's always a good idea to do so anyway). Of course, things will not always be that easy. You might be interested in a @@ -154,10 +154,10 @@ -------------------- Running ``setup.py install`` builds and installs all modules in one run. If you -prefer to work incrementally---especially useful if you want to customize the -build process, or if things are going wrong---you can use the setup script to do +prefer to work incrementally --- especially useful if you want to customize the +build process, or if things are going wrong --- you can use the setup script to do one thing at a time. This is particularly helpful when the build and install -will be done by different users---for example, you might want to build a module +will be done by different users --- for example, you might want to build a module distribution and hand it off to a system administrator for installation (or do it yourself, with super-user privileges). @@ -168,7 +168,7 @@ python setup.py install If you do this, you will notice that running the :command:`install` command -first runs the :command:`build` command, which---in this case---quickly notices +first runs the :command:`build` command, which --- in this case --- quickly notices that it has nothing to do, since everything in the :file:`build` directory is up-to-date. @@ -204,7 +204,7 @@ where ```` expands to a brief description of the current OS/hardware platform and Python version. The first form, with just a :file:`lib` directory, -is used for "pure module distributions"---that is, module distributions that +is used for "pure module distributions" --- that is, module distributions that include only pure Python modules. If a module distribution contains any extensions (modules written in C/C++), then the second form, with two ```` directories, is used. In that case, the :file:`temp.{plat}` directory holds @@ -228,8 +228,8 @@ :file:`build/lib` (or :file:`build/lib.{plat}`) to your chosen installation directory. -If you don't choose an installation directory---i.e., if you just run ``setup.py -install``\ ---then the :command:`install` command installs to the standard +If you don't choose an installation directory --- i.e., if you just run ``setup.py +install`` --- then the :command:`install` command installs to the standard location for third-party Python modules. This location varies by platform and by how you built/installed Python itself. On Unix (and Mac OS X, which is also Unix-based), it also depends on whether the module distribution being installed @@ -420,7 +420,7 @@ perform the build/install (i.e., to run the setup script), but install modules into the third-party module directory of a different Python installation (or something that looks like a different Python installation). If this sounds a -trifle unusual, it is---that's why the user and home schemes come before. However, +trifle unusual, it is --- that's why the user and home schemes come before. However, there are at least two known cases where the prefix scheme will be useful. First, consider that many Linux distributions put Python in :file:`/usr`, rather @@ -538,7 +538,7 @@ These override options can be relative, absolute, or explicitly defined in terms of one of the installation base directories. -(There are two installation base directories, and they are normally the same--- +(There are two installation base directories, and they are normally the same --- they only differ when you use the Unix "prefix scheme" and supply different ``--prefix`` and ``--exec-prefix`` options; using ``--install-lib`` will override values computed or given for ``--install-purelib`` and @@ -546,7 +546,7 @@ difference between Python and extension modules.) For example, say you're installing a module distribution to your home directory -under Unix---but you want scripts to go in :file:`~/scripts` rather than +under Unix --- but you want scripts to go in :file:`~/scripts` rather than :file:`~/bin`. As you might expect, you can override this directory with the :option:`--install-scripts` option; in this case, it makes most sense to supply a relative path, which will be interpreted relative to the installation base @@ -569,7 +569,7 @@ If you maintain Python on Windows, you might want third-party modules to live in a subdirectory of :file:`{prefix}`, rather than right in :file:`{prefix}` itself. This is almost as easy as customizing the script installation directory ----you just have to remember that there are two types of modules to worry about, +--- you just have to remember that there are two types of modules to worry about, Python and extension modules, which can conveniently be both controlled by one option:: @@ -602,7 +602,7 @@ --install-scripts=scripts --install-data=data -``$PLAT`` is not (necessarily) an environment variable---it will be expanded by +``$PLAT`` is not (necessarily) an environment variable --- it will be expanded by the Distutils as it parses your command line options, just as it does when parsing your configuration file(s). @@ -650,7 +650,7 @@ files to prevent inadvertently installing projects outside of the virtual environment. -.. XXX need some Windows examples---when would custom installation schemes be +.. XXX need some Windows examples --- when would custom installation schemes be needed on those platforms? @@ -803,7 +803,7 @@ prefix" is :file:`C:\\Python`, so the system configuration file is normally :file:`C:\\Python\\Lib\\distutils\\distutils.cfg`. Under Python 1.5.2, the default prefix was :file:`C:\\Program Files\\Python`, and the Distutils were not - part of the standard library---so the system configuration file would be + part of the standard library --- so the system configuration file would be :file:`C:\\Program Files\\Python\\distutils\\distutils.cfg` in a standard Python 1.5.2 installation under Windows. 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/_thread.rst --- a/Doc/library/_thread.rst +++ b/Doc/library/_thread.rst @@ -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. diff -r afe119a3619f Doc/library/abc.rst --- a/Doc/library/abc.rst +++ b/Doc/library/abc.rst @@ -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/argparse.rst --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -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/asynchat.rst --- a/Doc/library/asynchat.rst +++ b/Doc/library/asynchat.rst @@ -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/base64.rst --- a/Doc/library/base64.rst +++ b/Doc/library/base64.rst @@ -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/cgi.rst --- a/Doc/library/cgi.rst +++ b/Doc/library/cgi.rst @@ -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 diff -r afe119a3619f Doc/library/code.rst --- a/Doc/library/code.rst +++ b/Doc/library/code.rst @@ -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 @@ -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 diff -r afe119a3619f Doc/library/concurrent.futures.rst --- a/Doc/library/concurrent.futures.rst +++ b/Doc/library/concurrent.futures.rst @@ -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 @@ -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 @@ -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/csv.rst --- a/Doc/library/csv.rst +++ b/Doc/library/csv.rst @@ -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. diff -r afe119a3619f Doc/library/ctypes.rst --- a/Doc/library/ctypes.rst +++ b/Doc/library/ctypes.rst @@ -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/decimal.rst --- a/Doc/library/decimal.rst +++ b/Doc/library/decimal.rst @@ -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 diff -r afe119a3619f Doc/library/difflib.rst --- a/Doc/library/difflib.rst +++ b/Doc/library/difflib.rst @@ -215,7 +215,7 @@ 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 + --- 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. diff -r afe119a3619f Doc/library/doctest.rst --- a/Doc/library/doctest.rst +++ b/Doc/library/doctest.rst @@ -1777,7 +1777,7 @@ documentation. When writing a docstring, choose docstring examples with care. There's an art to -this that needs to be learned---it may not be natural at first. Examples should +this that needs to be learned --- it may not be natural at first. Examples should add genuine value to the documentation. A good example can often be worth many words. If done with care, the examples will be invaluable for your users, and will pay back the time it takes to collect them many times over as the years go 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.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/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/fcntl.rst --- a/Doc/library/fcntl.rst +++ b/Doc/library/fcntl.rst @@ -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 diff -r afe119a3619f Doc/library/ftplib.rst --- a/Doc/library/ftplib.rst +++ b/Doc/library/ftplib.rst @@ -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/html.rst --- a/Doc/library/html.rst +++ b/Doc/library/html.rst @@ -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.cookiejar.rst --- a/Doc/library/http.cookiejar.rst +++ b/Doc/library/http.cookiejar.rst @@ -12,7 +12,7 @@ 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 +--- :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 @@ -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 @@ -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. diff -r afe119a3619f Doc/library/imaplib.rst --- a/Doc/library/imaplib.rst +++ b/Doc/library/imaplib.rst @@ -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) @@ -178,7 +178,7 @@ 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/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. @@ -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 @@ -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/io.rst --- a/Doc/library/io.rst +++ b/Doc/library/io.rst @@ -242,7 +242,7 @@ :class:`IOBase` is also a context manager and therefore supports the :keyword:`with` statement. In this example, *file* is closed after the - :keyword:`with` statement's suite is finished---even if an exception occurs:: + :keyword:`with` statement's suite is finished --- even if an exception occurs:: with open('spam.txt', 'w') as file: file.write('Spam and eggs!') @@ -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 @@ -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/logging.config.rst --- a/Doc/library/logging.config.rst +++ b/Doc/library/logging.config.rst @@ -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 @@ -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 @@ -656,7 +656,7 @@ 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 + --- 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 @@ -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 @@ -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/mailbox.rst --- a/Doc/library/mailbox.rst +++ b/Doc/library/mailbox.rst @@ -472,7 +472,7 @@ .. method:: lock() unlock() - Three locking mechanisms are used---dot locking and, if available, the + Three locking mechanisms are used --- dot locking and, if available, the :c:func:`flock` and :c:func:`lockf` system calls. @@ -586,7 +586,7 @@ .. method:: lock() unlock() - Three locking mechanisms are used---dot locking and, if available, the + Three locking mechanisms are used --- dot locking and, if available, the :c:func:`flock` and :c:func:`lockf` system calls. For MH mailboxes, locking the mailbox means locking the :file:`.mh_sequences` file and, only for the duration of any operations that affect them, locking individual message @@ -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 `_ @@ -684,7 +684,7 @@ .. method:: lock() unlock() - Three locking mechanisms are used---dot locking and, if available, the + Three locking mechanisms are used --- dot locking and, if available, the :c:func:`flock` and :c:func:`lockf` system calls. @@ -735,7 +735,7 @@ .. method:: lock() unlock() - Three locking mechanisms are used---dot locking and, if available, the + Three locking mechanisms are used --- dot locking and, if available, the :c:func:`flock` and :c:func:`lockf` system calls. diff -r afe119a3619f Doc/library/marshal.rst --- a/Doc/library/marshal.rst +++ b/Doc/library/marshal.rst @@ -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. 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 @@ -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 diff -r afe119a3619f Doc/library/optparse.rst --- a/Doc/library/optparse.rst +++ b/Doc/library/optparse.rst @@ -188,7 +188,7 @@ program should be able to run just fine with no options whatsoever. (Pick a random program from the Unix or GNU toolsets. Can it run without any options at all and still make sense? The main exceptions are ``find``, ``tar``, and -``dd``\ ---all of which are mutant oddballs that have been rightly criticized +``dd`` --- all of which are mutant oddballs that have been rightly criticized for their non-standard syntax and confusing interfaces.) Lots of people want their programs to have "required options". Think about it. @@ -224,16 +224,16 @@ A good user interface should have as few absolute requirements as possible. If your program requires 17 distinct pieces of information in order to run successfully, it doesn't much matter *how* you get that information from the -user---most people will give up and walk away before they successfully run the +user --- most people will give up and walk away before they successfully run the program. This applies whether the user interface is a command-line, a configuration file, or a GUI: if you make that many demands on your users, most of them will simply give up. In short, try to minimize the amount of information that users are absolutely -required to supply---use sensible defaults whenever possible. Of course, you +required to supply --- use sensible defaults whenever possible. Of course, you also want to make your programs reasonably flexible. That's what options are for. Again, it doesn't matter if they are entries in a config file, widgets in -the "Preferences" dialog of a GUI, or command-line options---the more options +the "Preferences" dialog of a GUI, or command-line options --- the more options you implement, the more flexible your program is, and the more complicated its implementation becomes. Too much flexibility has drawbacks as well, of course; too many options can overwhelm users and make your code much harder to maintain. @@ -289,7 +289,7 @@ :meth:`parse_args` returns two values: -* ``options``, an object containing values for all of your options---e.g. if +* ``options``, an object containing values for all of your options --- e.g. if ``--file`` takes a single string argument, then ``options.file`` will be the filename supplied by the user, or ``None`` if the user did not supply that option @@ -311,7 +311,7 @@ command line. There is a fixed set of actions hard-coded into :mod:`optparse`; adding new actions is an advanced topic covered in section :ref:`optparse-extending-optparse`. Most actions tell :mod:`optparse` to store -a value in some variable---for example, take a string from the command line and +a value in some variable --- for example, take a string from the command line and store it in an attribute of ``options``. If you don't specify an option action, :mod:`optparse` defaults to ``store``. @@ -378,8 +378,8 @@ Handling boolean (flag) options ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Flag options---set a variable to true or false when a particular option is seen ----are quite common. :mod:`optparse` supports them with two separate actions, +Flag options --- set a variable to true or false when a particular option is seen +--- are quite common. :mod:`optparse` supports them with two separate actions, ``store_true`` and ``store_false``. For example, you might have a ``verbose`` flag that is turned on with ``-v`` and off with ``-q``:: @@ -387,7 +387,7 @@ parser.add_option("-q", action="store_false", dest="verbose") Here we have two different options with the same destination, which is perfectly -OK. (It just means you have to be a bit careful when setting default values--- +OK. (It just means you have to be a bit careful when setting default values --- see below.) When :mod:`optparse` encounters ``-v`` on the command line, it sets @@ -524,7 +524,7 @@ default: ``"Usage: %prog [options]"``, which is fine if your script doesn't take any positional arguments. -* every option defines a help string, and doesn't worry about line-wrapping--- +* every option defines a help string, and doesn't worry about line-wrapping --- :mod:`optparse` takes care of wrapping lines and making the help output look good. @@ -536,7 +536,7 @@ Here, "MODE" is called the meta-variable: it stands for the argument that the user is expected to supply to ``-m``/``--mode``. By default, :mod:`optparse` converts the destination variable name to uppercase and uses - that for the meta-variable. Sometimes, that's not what you want---for + that for the meta-variable. Sometimes, that's not what you want --- for example, the ``--filename`` option explicitly sets ``metavar="FILE"``, resulting in this automatically-generated option description:: @@ -549,7 +549,7 @@ way to make your help text a lot clearer and more useful for end users. * options that have a default value can include ``%default`` in the help - string---\ :mod:`optparse` will replace it with :func:`str` of the option's + string --- :mod:`optparse` will replace it with :func:`str` of the option's default value. If an option has no default value (or the default value is ``None``), ``%default`` expands to ``none``. @@ -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 @@ -1564,7 +1564,7 @@ ``callback`` is a function (or other callable object), so you must have already defined ``my_callback()`` when you create this callback option. In this simple case, :mod:`optparse` doesn't even know if ``-c`` takes any arguments, -which usually means that the option takes no arguments---the mere presence of +which usually means that the option takes no arguments --- the mere presence of ``-c`` on the command-line is all it needs to know. In some circumstances, though, you might want your callback to consume an arbitrary number of command-line arguments. This is where writing callbacks gets tricky; @@ -1618,7 +1618,7 @@ ``opt_str`` is the option string seen on the command-line that's triggering the callback. (If an abbreviated long option was used, ``opt_str`` will be the full, - canonical option string---e.g. if the user puts ``--foo`` on the + canonical option string --- e.g. if the user puts ``--foo`` on the command-line as an abbreviation for ``--foobar``, then ``opt_str`` will be ``"--foobar"``.) @@ -1730,7 +1730,7 @@ Callback example 4: check arbitrary condition ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Of course, you could put any condition in there---you're not limited to checking +Of course, you could put any condition in there --- you're not limited to checking the values of already-defined options. For example, if you have options that should not be called when the moon is full, all you have to do is this:: diff -r afe119a3619f Doc/library/os.rst --- a/Doc/library/os.rst +++ b/Doc/library/os.rst @@ -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. @@ -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`, diff -r afe119a3619f Doc/library/ossaudiodev.rst --- a/Doc/library/ossaudiodev.rst +++ b/Doc/library/ossaudiodev.rst @@ -152,7 +152,7 @@ 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`. + --- see :meth:`writeall`. .. method:: oss_audio_device.writeall(data) @@ -221,9 +221,9 @@ .. method:: oss_audio_device.setfmt(format) - Try to set the current audio format to *format*---see :meth:`getfmts` for a + Try to set the current audio format to *format* --- see :meth:`getfmts` for a list. Returns the audio format that the device was set to, which may not be the - requested format. May also be used to return the current audio format---do this + requested format. May also be used to return the current audio format --- do this by passing an "audio format" of :const:`AFMT_QUERY`. @@ -284,8 +284,8 @@ .. method:: oss_audio_device.setparameters(format, nchannels, samplerate[, strict=False]) - Set the key audio sampling parameters---sample format, number of channels, and - sampling rate---in one method call. *format*, *nchannels*, and *samplerate* + Set the key audio sampling parameters --- sample format, number of channels, and + sampling rate --- in one method call. *format*, *nchannels*, and *samplerate* should be as specified in the :meth:`setfmt`, :meth:`channels`, and :meth:`speed` methods. If *strict* is true, :meth:`setparameters` checks to see if each parameter was actually set to the requested value, and raises @@ -368,7 +368,7 @@ This method returns a bitmask specifying the available mixer controls ("Control" being a specific mixable "channel", such as :const:`SOUND_MIXER_PCM` or :const:`SOUND_MIXER_SYNTH`). This bitmask indicates a subset of all available - mixer controls---the :const:`SOUND_MIXER_\*` constants defined at module level. + mixer controls --- the :const:`SOUND_MIXER_\*` constants defined at module level. To determine if, for example, the current mixer object supports a PCM mixer, use the following Python code:: @@ -378,7 +378,7 @@ ... code ... For most purposes, the :const:`SOUND_MIXER_VOLUME` (master volume) and - :const:`SOUND_MIXER_PCM` controls should suffice---but code that uses the mixer + :const:`SOUND_MIXER_PCM` controls should suffice --- but code that uses the mixer should be flexible when it comes to choosing mixer controls. On the Gravis Ultrasound, for example, :const:`SOUND_MIXER_VOLUME` does not exist. diff -r afe119a3619f Doc/library/pdb.rst --- a/Doc/library/pdb.rst +++ b/Doc/library/pdb.rst @@ -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/plistlib.rst --- a/Doc/library/plistlib.rst +++ b/Doc/library/plistlib.rst @@ -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 @@ -52,7 +52,7 @@ 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. + --- see its documentation for possible exceptions on ill-formed XML. Unknown elements will simply be ignored by the plist parser. diff -r afe119a3619f Doc/library/poplib.rst --- a/Doc/library/poplib.rst +++ b/Doc/library/poplib.rst @@ -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/runpy.rst --- a/Doc/library/runpy.rst +++ b/Doc/library/runpy.rst @@ -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/site.rst --- a/Doc/library/site.rst +++ b/Doc/library/site.rst @@ -241,4 +241,4 @@ .. seealso:: - :pep:`370` -- Per user site-packages directory + :pep:`370` --- Per user site-packages directory diff -r afe119a3619f Doc/library/smtplib.rst --- a/Doc/library/smtplib.rst +++ b/Doc/library/smtplib.rst @@ -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/socketserver.rst --- a/Doc/library/socketserver.rst +++ b/Doc/library/socketserver.rst @@ -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/sqlite3.rst --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -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 @@ -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 @@ -81,8 +81,8 @@ .. function:: S_IMODE(mode) - Return the portion of the file's mode that can be set by :func:`os.chmod`\ - ---that is, the file's permission bits, plus the sticky bit, set-group-id, and + Return the portion of the file's mode that can be set by :func:`os.chmod` + --- that is, the file's permission bits, plus the sticky bit, set-group-id, and set-user-id bits (on systems that support them). diff -r afe119a3619f Doc/library/stdtypes.rst --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -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). @@ -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) | +------------+-----------------------------------------------------+-------+ @@ -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. @@ -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 @@ -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/subprocess.rst --- a/Doc/library/subprocess.rst +++ b/Doc/library/subprocess.rst @@ -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/sys.rst --- a/Doc/library/sys.rst +++ b/Doc/library/sys.rst @@ -693,8 +693,8 @@ .. 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 + --- 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 @@ -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 @@ -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/telnetlib.rst --- a/Doc/library/telnetlib.rst +++ b/Doc/library/telnetlib.rst @@ -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/threading.rst --- a/Doc/library/threading.rst +++ b/Doc/library/threading.rst @@ -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 @@ -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/tkinter.rst --- a/Doc/library/tkinter.rst +++ b/Doc/library/tkinter.rst @@ -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/turtle.rst --- a/Doc/library/turtle.rst +++ b/Doc/library/turtle.rst @@ -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 @@ -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/unittest.mock-examples.rst --- a/Doc/library/unittest.mock-examples.rst +++ b/Doc/library/unittest.mock-examples.rst @@ -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 @@ -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 @@ -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.parse.rst --- a/Doc/library/urllib.parse.rst +++ b/Doc/library/urllib.parse.rst @@ -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 @@ -79,7 +79,7 @@ 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 diff -r afe119a3619f Doc/library/uuid.rst --- a/Doc/library/uuid.rst +++ b/Doc/library/uuid.rst @@ -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 @@ -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/weakref.rst --- a/Doc/library/weakref.rst +++ b/Doc/library/weakref.rst @@ -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/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/wsgiref.rst --- a/Doc/library/wsgiref.rst +++ b/Doc/library/wsgiref.rst @@ -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. @@ -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 @@ -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.etree.elementtree.rst --- a/Doc/library/xml.etree.elementtree.rst +++ b/Doc/library/xml.etree.elementtree.rst @@ -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.reader.rst --- a/Doc/library/xml.sax.reader.rst +++ b/Doc/library/xml.sax.reader.rst @@ -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/zipfile.rst --- a/Doc/library/zipfile.rst +++ b/Doc/library/zipfile.rst @@ -160,7 +160,7 @@ ZipFile is also a context manager and therefore supports the :keyword:`with` statement. In the example, *myzip* is closed after the - :keyword:`with` statement's suite is finished---even if an exception occurs:: + :keyword:`with` statement's suite is finished --- even if an exception occurs:: with ZipFile('spam.zip', 'w') as myzip: myzip.write('eggs.txt') @@ -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 @@ -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. @@ -73,7 +73,7 @@ Search for a module specified by *fullname*. *fullname* must be the fully qualified (dotted) module name. It returns the zipimporter instance itself if the module was found, or :const:`None` if it wasn't. The optional - *path* argument is ignored---it's there for compatibility with the + *path* argument is ignored --- it's there for compatibility with the importer protocol. @@ -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 @@ -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 @@ -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. @@ -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 @@ -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:: diff -r afe119a3619f Doc/reference/expressions.rst --- a/Doc/reference/expressions.rst +++ b/Doc/reference/expressions.rst @@ -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) @@ -759,7 +759,7 @@ exception. How this value is computed depends on the type of the callable object. -If it is--- +If it is --- a user-defined function: .. index:: 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/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. @@ -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. @@ -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. @@ -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/classes.rst --- a/Doc/tutorial/classes.rst +++ b/Doc/tutorial/classes.rst @@ -137,8 +137,8 @@ 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 +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 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/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. 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,8 +5,8 @@ .. _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. @@ -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 @@ -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 @@ -772,7 +772,7 @@ :meth:`~iterator.__next__`. * The :meth:`__oct__` and :meth:`__hex__` special methods are removed - -- :func:`oct` and :func:`hex` use :meth:`__index__` now to convert + --- :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.