diff options
50 files changed, 370 insertions, 233 deletions
diff --git a/Demo/comparisons/sortingtest.py b/Demo/comparisons/sortingtest.py index 464eb5c8e5..f9ed854109 100755 --- a/Demo/comparisons/sortingtest.py +++ b/Demo/comparisons/sortingtest.py @@ -24,7 +24,6 @@ # - Handles blank input lines correctly import re -import string import sys def main(): @@ -32,18 +31,13 @@ def main(): def makekey(item, prog=prog): match = prog.match(item) if match: - var, num = match.group(1, 2) - return string.atoi(num), var + var, num = match.groups() + return int(num), var else: # Bad input -- pretend it's a var with value 0 return 0, item - while 1: - line = sys.stdin.readline() - if not line: - break - items = line.split() - items = list(map(makekey, items)) - items.sort() + for line in sys.stdin: + items = sorted(makekey(item) for item in line.split()) for num, var in items: print("%s=%s" % (var, num), end=' ') print() diff --git a/Doc/distutils/apiref.rst b/Doc/distutils/apiref.rst index af19111dfb..cdb32d3eac 100644 --- a/Doc/distutils/apiref.rst +++ b/Doc/distutils/apiref.rst @@ -1976,9 +1976,9 @@ it so that it's implementing the class :class:`peel_banana`, a subclass of Subclasses of :class:`Command` must define the following methods. -.. method:: Command.initialize_options()(S) +.. method:: Command.initialize_options() - et default values for all the options that this command supports. Note that + Set default values for all the options that this command supports. Note that these defaults may be overridden by other commands, by the setup script, by config files, or by the command-line. Thus, this is not the place to code dependencies between options; generally, :meth:`initialize_options` diff --git a/Doc/documenting/markup.rst b/Doc/documenting/markup.rst index 421971a614..eed51d2fe2 100644 --- a/Doc/documenting/markup.rst +++ b/Doc/documenting/markup.rst @@ -626,6 +626,24 @@ units as well as normal text: -------------- +.. describe:: impl-detail + + This directive is used to mark CPython-specific information. Use either with + a block content or a single sentence as an argument, i.e. either :: + + .. impl-detail:: + + This describes some implementation detail. + + More explanation. + + or :: + + .. impl-detail:: This shortly mentions an implementation detail. + + "\ **CPython implementation detail:**\ " is automatically prepended to the + content. + .. describe:: seealso Many sections include a list of references to module documentation or diff --git a/Doc/faq/design.rst b/Doc/faq/design.rst index aacb476cdc..94afaff14e 100644 --- a/Doc/faq/design.rst +++ b/Doc/faq/design.rst @@ -396,12 +396,13 @@ calls into the Python run-time system, even for seemingly simple operations like ``x+1``. Several projects described in the Python newsgroup or at past `Python -conferences <http://python.org/community/workshops/>`_ have shown that this approach is feasible, -although the speedups reached so far are only modest (e.g. 2x). Jython uses the -same strategy for compiling to Java bytecode. (Jim Hugunin has demonstrated -that in combination with whole-program analysis, speedups of 1000x are feasible -for small demo programs. See the proceedings from the `1997 Python conference -<http://python.org/community/workshops/1997-10/proceedings/>`_ for more information.) +conferences <http://python.org/community/workshops/>`_ have shown that this +approach is feasible, although the speedups reached so far are only modest +(e.g. 2x). Jython uses the same strategy for compiling to Java bytecode. (Jim +Hugunin has demonstrated that in combination with whole-program analysis, +speedups of 1000x are feasible for small demo programs. See the proceedings +from the `1997 Python conference +<http://python.org/workshops/1997-10/proceedings/>`_ for more information.) Internally, Python source code is always translated into a bytecode representation, and this bytecode is then executed by the Python virtual diff --git a/Doc/faq/extending.rst b/Doc/faq/extending.rst index 3389877d45..f01b0a0bfa 100644 --- a/Doc/faq/extending.rst +++ b/Doc/faq/extending.rst @@ -48,7 +48,7 @@ Python's C API. If you need to interface to some C or C++ library for which no Python extension currently exists, you can try wrapping the library's data types and functions with a tool such as `SWIG <http://www.swig.org>`_. `SIP -<http://www.riverbankcomputing.co.uk/sip/>`_, `CXX +<http://www.riverbankcomputing.co.uk/software/sip/>`__, `CXX <http://cxx.sourceforge.net/>`_ `Boost <http://www.boost.org/libs/python/doc/index.html>`_, or `Weave <http://www.scipy.org/site_content/weave>`_ are also alternatives for wrapping diff --git a/Doc/faq/general.rst b/Doc/faq/general.rst index 758c26e563..67935f4346 100644 --- a/Doc/faq/general.rst +++ b/Doc/faq/general.rst @@ -164,9 +164,10 @@ Sphinx-formatted documentation, Python library modules, example programs, and several useful pieces of freely distributable software. The source will compile and run out of the box on most UNIX platforms. -Consult the `Developer FAQ -<http://www.python.org/dev/devfaq.html#subversion-svn>`__ for more information -on getting the source code and compiling it. +.. XXX update link once the dev faq is relocated + +Consult the `Developer FAQ <http://www.python.org/dev/faq/>`__ for more +information on getting the source code and compiling it. How do I get documentation on Python? @@ -176,7 +177,7 @@ How do I get documentation on Python? The standard documentation for the current stable version of Python is available at http://docs.python.org/. PDF, plain text, and downloadable HTML versions are -also available at http://docs.python.org/download/. +also available at http://docs.python.org/download.html. The documentation is written in reStructuredText and processed by `the Sphinx documentation tool <http://sphinx.pocoo.org/>`__. The reStructuredText source @@ -220,8 +221,10 @@ releases are announced on the comp.lang.python and comp.lang.python.announce newsgroups and on the Python home page at http://www.python.org/; an RSS feed of news is available. +.. XXX update link once the dev faq is relocated + You can also access the development version of Python through Subversion. See -http://www.python.org/dev/devfaq.html#subversion-svn for details. +http://www.python.org/dev/faq/ for details. How do I submit bug reports and patches for Python? diff --git a/Doc/faq/gui.rst b/Doc/faq/gui.rst index d3cf779356..4761b7d334 100644 --- a/Doc/faq/gui.rst +++ b/Doc/faq/gui.rst @@ -45,11 +45,12 @@ Qt ''' There are bindings available for the Qt toolkit (`PyQt -<http://www.riverbankcomputing.co.uk/pyqt/>`_) and for KDE (PyKDE). If you're -writing open source software, you don't need to pay for PyQt, but if you want to -write proprietary applications, you must buy a PyQt license from `Riverbank -Computing <http://www.riverbankcomputing.co.uk>`_ and a Qt license from -`Trolltech <http://www.trolltech.com>`_. +<http://www.riverbankcomputing.co.uk/software/pyqt/>`_) and for KDE (PyKDE). If +you're writing open source software, you don't need to pay for PyQt, but if you +want to write proprietary applications, you must buy a PyQt license from +`Riverbank Computing <http://www.riverbankcomputing.co.uk>`_ and (up to Qt 4.4; +Qt 4.5 upwards is licensed under the LGPL license) a Qt license from `Trolltech +<http://www.trolltech.com>`_. Gtk+ '''' diff --git a/Doc/faq/library.rst b/Doc/faq/library.rst index db69449d7e..88fcf0ef28 100644 --- a/Doc/faq/library.rst +++ b/Doc/faq/library.rst @@ -16,14 +16,10 @@ Check :ref:`the Library Reference <library-index>` to see if there's a relevant standard library module. (Eventually you'll learn what's in the standard library and will able to skip this step.) -Search the `Python Package Index <http://pypi.python.org/pypi>`_. - -Next, check the `Vaults of Parnassus <http://www.vex.net/parnassus/>`_, an older -index of packages. - -Finally, try `Google <http://www.google.com>`_ or other Web search engine. -Searching for "Python" plus a keyword or two for your topic of interest will -usually find something helpful. +For third-party packages, search the `Python Package Index +<http://pypi.python.org/pypi>`_ or try `Google <http://www.google.com>`_ or +another Web search engine. Searching for "Python" plus a keyword or two for +your topic of interest will usually find something helpful. Where is the math.py (socket.py, regex.py, etc.) source file? @@ -181,11 +177,10 @@ in Python. How do I create documentation from doc strings? ----------------------------------------------- -.. XXX mention Sphinx/epydoc - The :mod:`pydoc` module can create HTML from the doc strings in your Python -source code. An alternative is `pythondoc -<http://starship.python.net/crew/danilo/pythondoc/>`_. +source code. An alternative for creating API documentation purely from +docstrings is `epydoc <http://epydoc.sf.net/>`_. `Sphinx +<http://sphinx.pocoo.org>`_ can also include docstring content. How do I get a single keypress at a time? @@ -237,7 +232,7 @@ The :mod:`threading` module builds convenient abstractions on top of the low-level primitives provided by the :mod:`_thread` module. Aahz has a set of slides from his threading tutorial that are helpful; see -http://starship.python.net/crew/aahz/OSCON2001/. +http://www.pythoncraft.com/OSCON2001/. None of my threads seem to run: why? @@ -397,6 +392,7 @@ Can't we get rid of the Global Interpreter Lock? ------------------------------------------------ .. XXX mention multiprocessing +.. XXX link to dbeazley's talk about GIL? The Global Interpreter Lock (GIL) is often seen as a hindrance to Python's deployment on high-end multiprocessor server machines, because a multi-threaded @@ -583,7 +579,7 @@ substituted for standard input and output. You will have to use pseudo ttys ("ptys") instead of pipes. Or you can use a Python interface to Don Libes' "expect" library. A Python extension that interfaces to expect is called "expy" and available from http://expectpy.sourceforge.net. A pure Python solution that -works like expect is ` pexpect <http://pexpect.sourceforge.net>`_. +works like expect is `pexpect <http://pypi.python.org/pypi/pexpect/>`_. How do I access the serial (RS232) port? diff --git a/Doc/faq/programming.rst b/Doc/faq/programming.rst index 7d32939754..faa3b80975 100644 --- a/Doc/faq/programming.rst +++ b/Doc/faq/programming.rst @@ -67,8 +67,8 @@ plug-ins to add a custom feature. In addition to the bug checking that PyChecker performs, Pylint offers some additional features such as checking line length, whether variable names are well-formed according to your coding standard, whether declared interfaces are fully implemented, and more. -http://www.logilab.org/projects/pylint/documentation provides a full list of -Pylint's features. +http://www.logilab.org/card/pylint_manual provides a full list of Pylint's +features. How can I create a stand-alone binary from a Python script? @@ -1141,7 +1141,7 @@ use a list comprehension:: A = [[None] * w for i in range(h)] Or, you can use an extension that provides a matrix datatype; `Numeric Python -<http://www.pfdubois.com/numpy/>`_ is the best known. +<http://numpy.scipy.org/>`_ is the best known. How do I apply a method to a sequence of objects? diff --git a/Doc/faq/windows.rst b/Doc/faq/windows.rst index 1f40137389..eb1d3acd03 100644 --- a/Doc/faq/windows.rst +++ b/Doc/faq/windows.rst @@ -389,10 +389,10 @@ need):: .py :REG_SZ: c:\<path to python>\python.exe -u %s %s This line will allow you to call your script with a simple reference like: -http://yourserver/scripts/yourscript.py provided "scripts" is an "executable" -directory for your server (which it usually is by default). The "-u" flag -specifies unbuffered and binary mode for stdin - needed when working with binary -data. +``http://yourserver/scripts/yourscript.py`` provided "scripts" is an +"executable" directory for your server (which it usually is by default). The +:option:`-u` flag specifies unbuffered and binary mode for stdin - needed when +working with binary data. In addition, it is recommended that using ".py" may not be a good idea for the file extensions when used in this context (you might want to reserve ``*.py`` @@ -517,7 +517,7 @@ Why doesn't os.popen()/win32pipe.popen() work on Win9x? There is a bug in Win9x that prevents os.popen/win32pipe.popen* from working. The good news is there is a way to work around this problem. The Microsoft Knowledge Base article that you need to lookup is: Q150956. You will -find links to the knowledge base at: http://www.microsoft.com/kb. +find links to the knowledge base at: http://support.microsoft.com/. PyRun_SimpleFile() crashes on Windows but not on Unix; why? @@ -604,4 +604,4 @@ Tim Peters: we can't fix it). David A Burton has written a little program to fix this. Go to -http://www.burtonsys.com/download.html and click on "ctl3dfix.zip". +http://www.burtonsys.com/downloads.html and click on "ctl3dfix.zip". diff --git a/Doc/howto/unicode.rst b/Doc/howto/unicode.rst index 49576cd08f..0f829f39af 100644 --- a/Doc/howto/unicode.rst +++ b/Doc/howto/unicode.rst @@ -403,7 +403,7 @@ These are grouped into categories such as "Letter", "Number", "Punctuation", or from the above output, ``'Ll'`` means 'Letter, lowercase', ``'No'`` means "Number, other", ``'Mn'`` is "Mark, nonspacing", and ``'So'`` is "Symbol, other". See -<http://www.unicode.org/Public/UNIDATA/UCD.html#General_Category_Values> for a +<http://unicode.org/Public/5.1.0/ucd/UCD.html#General_Category_Values> for a list of category codes. References diff --git a/Doc/howto/webservers.rst b/Doc/howto/webservers.rst index 2440b30654..d005103ea4 100644 --- a/Doc/howto/webservers.rst +++ b/Doc/howto/webservers.rst @@ -270,8 +270,7 @@ Depending on the web server you need to have a special module. * lighttpd ships its own `FastCGI module <http://trac.lighttpd.net/trac/wiki/Docs%3AModFastCGI>`_ as well as an `SCGI module <http://trac.lighttpd.net/trac/wiki/Docs%3AModSCGI>`_. -* nginx also supports `FastCGI - <http://wiki.codemongers.com/NginxSimplePythonFCGI>`_. +* nginx also supports `FastCGI <http://wiki.nginx.org/NginxSimplePythonFCGI>`_. Once you have installed and configured the module, you can test it with the following WSGI-application:: @@ -525,7 +524,7 @@ the text of a wiki page. As always, there are different ways to store informations on a web server. Often relational database engines like `MySQL <http://www.mysql.com/>`_ or -`PostgreSQL <http://http://www.postgresql.org/>`_ are used due to their good +`PostgreSQL <http://www.postgresql.org/>`_ are used due to their good performance handling very large databases consisting of up to millions of entries. These are *queried* using a language called `SQL <http://en.wikipedia.org/wiki/SQL>`_. Python programmers in general do not like @@ -629,7 +628,7 @@ which make it possible to write web sites nearly without any Python code. It has a big, international community which has created many sites using Django. There are also quite a lot of add-on projects which extend Django's normal functionality. This is partly due to Django's well written `online -documentation <http://doc.djangoproject.com/>`_ and the `Django book +documentation <http://docs.djangoproject.com/>`_ and the `Django book <http://www.djangobook.com/>`_. diff --git a/Doc/install/index.rst b/Doc/install/index.rst index 36460610f6..075129166e 100644 --- a/Doc/install/index.rst +++ b/Doc/install/index.rst @@ -937,7 +937,8 @@ following steps. These compilers require some special libraries. This task is more complex than for Borland's C++, because there is no program to convert the library. First you have to create a list of symbols which the Python DLL exports. (You can find -a good program for this task at http://www.emmestech.com/software/cygwin/pexports-0.43/download_pexports.html) +a good program for this task at +http://www.emmestech.com/software/pexports-0.43/download_pexports.html). .. I don't understand what the next line means. --amk .. (inclusive the references on data structures.) diff --git a/Doc/library/codecs.rst b/Doc/library/codecs.rst index 8ab66c7300..a7e383177e 100644 --- a/Doc/library/codecs.rst +++ b/Doc/library/codecs.rst @@ -53,7 +53,7 @@ It defines the following functions: *incrementalencoder* and *incrementaldecoder*: These have to be factory functions providing the following interface: - ``factory(errors='strict')`` + ``factory(errors='strict')`` The factory functions must return objects providing the interfaces defined by the base classes :class:`IncrementalEncoder` and :class:`IncrementalDecoder`, @@ -62,21 +62,25 @@ It defines the following functions: *streamreader* and *streamwriter*: These have to be factory functions providing the following interface: - ``factory(stream, errors='strict')`` + ``factory(stream, errors='strict')`` The factory functions must return objects providing the interfaces defined by the base classes :class:`StreamWriter` and :class:`StreamReader`, respectively. Stream codecs can maintain state. - Possible values for errors are ``'strict'`` (raise an exception in case of an - encoding error), ``'replace'`` (replace malformed data with a suitable - replacement marker, such as ``'?'``), ``'ignore'`` (ignore malformed data and - continue without further notice), ``'xmlcharrefreplace'`` (replace with the - appropriate XML character reference (for encoding only)), - ``'backslashreplace'`` (replace with backslashed escape sequences (for - encoding only)), ``'surrogateescape'`` (replace with surrogate U+DCxx, see - :pep:`383`) as well as any other error handling name defined via - :func:`register_error`. + Possible values for errors are + + * ``'strict'``: raise an exception in case of an encoding error + * ``'replace'``: replace malformed data with a suitable replacement marker, + such as ``'?'`` or ``'\ufffd'`` + * ``'ignore'``: ignore malformed data and continue without further notice + * ``'xmlcharrefreplace'``: replace with the appropriate XML character + reference (for encoding only) + * ``'backslashreplace'``: replace with backslashed escape sequences (for + encoding only + * ``'surrogateescape'``: replace with surrogate U+DCxx, see :pep:`383` + + as well as any other error handling name defined via :func:`register_error`. In case a search function cannot find a given encoding, it should return ``None``. @@ -173,27 +177,33 @@ functions which use :func:`lookup` for the codec lookup: .. function:: strict_errors(exception) - Implements the ``strict`` error handling. + Implements the ``strict`` error handling: each encoding or decoding error + raises a :exc:`UnicodeError`. .. function:: replace_errors(exception) - Implements the ``replace`` error handling. + Implements the ``replace`` error handling: malformed data is replaced with a + suitable replacement character such as ``'?'`` in bytestrings and + ``'\ufffd'`` in Unicode strings. .. function:: ignore_errors(exception) - Implements the ``ignore`` error handling. + Implements the ``ignore`` error handling: malformed data is ignored and + encoding or decoding is continued without further notice. .. function:: xmlcharrefreplace_errors(exception) - Implements the ``xmlcharrefreplace`` error handling. + Implements the ``xmlcharrefreplace`` error handling (for encoding only): the + unencodable character is replaced by an appropriate XML character reference. .. function:: backslashreplace_errors(exception) - Implements the ``backslashreplace`` error handling. + Implements the ``backslashreplace`` error handling (for encoding only): the + unencodable character is replaced by a backslashed escape sequence. To simplify working with encoded files or stream, the module also defines these utility functions: diff --git a/Doc/library/configparser.rst b/Doc/library/configparser.rst index a5d3a77597..1d097f942e 100644 --- a/Doc/library/configparser.rst +++ b/Doc/library/configparser.rst @@ -301,12 +301,23 @@ RawConfigParser Objects .. method:: RawConfigParser.optionxform(option) - Transforms the option name *option* as found in an input file or as passed in by - client code to the form that should be used in the internal structures. The - default implementation returns a lower-case version of *option*; subclasses may - override this or client code can set an attribute of this name on instances to - affect this behavior. Setting this to :func:`str`, for example, would make - option names case sensitive. + Transforms the option name *option* as found in an input file or as passed in + by client code to the form that should be used in the internal structures. + The default implementation returns a lower-case version of *option*; + subclasses may override this or client code can set an attribute of this name + on instances to affect this behavior. + + You don't necessarily need to subclass a ConfigParser to use this method, you + can also re-set it on an instance, to a function that takes a string + argument. Setting it to ``str``, for example, would make option names case + sensitive:: + + cfgparser = ConfigParser() + ... + cfgparser.optionxform = str + + Note that when reading configuration files, whitespace around the + option names are stripped before :meth:`optionxform` is called. .. _configparser-objects: diff --git a/Doc/library/curses.rst b/Doc/library/curses.rst index 4ea7afe8e1..f9ba0d624b 100644 --- a/Doc/library/curses.rst +++ b/Doc/library/curses.rst @@ -4,10 +4,10 @@ .. module:: curses :synopsis: An interface to the curses library, providing portable terminal handling. + :platform: Unix .. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il> .. sectionauthor:: Eric Raymond <esr@thyrsus.com> - The :mod:`curses` module provides an interface to the curses library, the de-facto standard for portable advanced terminal handling. diff --git a/Doc/library/datetime.rst b/Doc/library/datetime.rst index c1d3113144..2b9800576a 100644 --- a/Doc/library/datetime.rst +++ b/Doc/library/datetime.rst @@ -233,7 +233,7 @@ Supported operations: | | (-*t1.days*, -*t1.seconds*, | | | -*t1.microseconds*), and to *t1*\* -1. (1)(4) | +--------------------------------+-----------------------------------------------+ -| ``abs(t)`` | equivalent to +*t* when ``t.days >= 0``, and | +| ``abs(t)`` | equivalent to +\ *t* when ``t.days >= 0``, and| | | to -*t* when ``t.days < 0``. (2) | +--------------------------------+-----------------------------------------------+ diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index 3dfbff11a3..6008e97edb 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -499,8 +499,10 @@ are always available. They are listed here in alphabetical order. Return the "identity" of an object. This is an integer which is guaranteed to be unique and constant for this object during its lifetime. - Two objects with non-overlapping lifetimes may have the same :func:`id` value. - (Implementation note: this is the address of the object.) + Two objects with non-overlapping lifetimes may have the same :func:`id` + value. + + .. impl-detail:: This is the address of the object. .. function:: input([prompt]) diff --git a/Doc/library/getopt.rst b/Doc/library/getopt.rst index 7f6b6703ae..a3603840b8 100644 --- a/Doc/library/getopt.rst +++ b/Doc/library/getopt.rst @@ -36,12 +36,13 @@ exception: *longopts*, if specified, must be a list of strings with the names of the long options which should be supported. The leading ``'--'`` characters should not be included in the option name. Long options which require an - argument should be followed by an equal sign (``'='``). To accept only long - options, *shortopts* should be an empty string. Long options on the command line - can be recognized so long as they provide a prefix of the option name that - matches exactly one of the accepted options. For example, if *longopts* is - ``['foo', 'frob']``, the option :option:`--fo` will match as :option:`--foo`, - but :option:`--f` will not match uniquely, so :exc:`GetoptError` will be raised. + argument should be followed by an equal sign (``'='``). Optional arguments + are not supported. To accept only long options, *shortopts* should be an + empty string. Long options on the command line can be recognized so long as + they provide a prefix of the option name that matches exactly one of the + accepted options. For example, if *longopts* is ``['foo', 'frob']``, the + option :option:`--fo` will match as :option:`--foo`, but :option:`--f` will + not match uniquely, so :exc:`GetoptError` will be raised. The return value consists of two elements: the first is a list of ``(option, value)`` pairs; the second is the list of program arguments left after the diff --git a/Doc/library/inspect.rst b/Doc/library/inspect.rst index ad88e3dfa1..37a4f1ae68 100644 --- a/Doc/library/inspect.rst +++ b/Doc/library/inspect.rst @@ -290,18 +290,22 @@ attributes: Return true if the object is a getset descriptor. - getsets are attributes defined in extension modules via ``PyGetSetDef`` - structures. For Python implementations without such types, this method will - always return ``False``. + .. impl-detail:: + + getsets are attributes defined in extension modules via + :ctype:`PyGetSetDef` structures. For Python implementations without such + types, this method will always return ``False``. .. function:: ismemberdescriptor(object) Return true if the object is a member descriptor. - Member descriptors are attributes defined in extension modules via - ``PyMemberDef`` structures. For Python implementations without such types, - this method will always return ``False``. + .. impl-detail:: + + Member descriptors are attributes defined in extension modules via + :ctype:`PyMemberDef` structures. For Python implementations without such + types, this method will always return ``False``. .. _inspect-source: @@ -508,10 +512,12 @@ line. Return the frame object for the caller's stack frame. - This function relies on Python stack frame support in the interpreter, which - isn't guaranteed to exist in all implementations of Python. If running in - an implementation without Python stack frame support this function returns - ``None``. + .. impl-detail:: + + This function relies on Python stack frame support in the interpreter, + which isn't guaranteed to exist in all implementations of Python. If + running in an implementation without Python stack frame support this + function returns ``None``. .. function:: stack(context=1) diff --git a/Doc/library/mailbox.rst b/Doc/library/mailbox.rst index 0d4d056ccb..7409af5f15 100644 --- a/Doc/library/mailbox.rst +++ b/Doc/library/mailbox.rst @@ -595,7 +595,7 @@ Maildir, mbox, MH, Babyl, and MMDF. `nmh - Message Handling System <http://www.nongnu.org/nmh/>`_ Home page of :program:`nmh`, an updated version of the original :program:`mh`. - `MH & nmh: Email for Users & Programmers <http://www.ics.uci.edu/~mh/book/>`_ + `MH & nmh: Email for Users & Programmers <http://rand-mh.sourceforge.net/book/>`_ A GPL-licensed book on :program:`mh` and :program:`nmh`, with some information on the mailbox format. diff --git a/Doc/library/math.rst b/Doc/library/math.rst index db620cf275..fdd3a1fbd7 100644 --- a/Doc/library/math.rst +++ b/Doc/library/math.rst @@ -301,7 +301,7 @@ Constants The mathematical constant *e*. -.. note:: +.. impl-detail:: The :mod:`math` module consists mostly of thin wrappers around the platform C math library functions. Behavior in exceptional cases is loosely specified diff --git a/Doc/library/msilib.rst b/Doc/library/msilib.rst index 6fb7f05469..1e6946d328 100644 --- a/Doc/library/msilib.rst +++ b/Doc/library/msilib.rst @@ -394,10 +394,10 @@ Directory Objects .. seealso:: - `Directory Table <http://msdn.microsoft.com/library/en-us/msi/setup/directory_table.asp>`_ - `File Table <http://msdn.microsoft.com/library/en-us/msi/setup/file_table.asp>`_ - `Component Table <http://msdn.microsoft.com/library/en-us/msi/setup/component_table.asp>`_ - `FeatureComponents Table <http://msdn.microsoft.com/library/en-us/msi/setup/featurecomponents_table.asp>`_ + `Directory Table <http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/directory_table.asp>`_ + `File Table <http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/file_table.asp>`_ + `Component Table <http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/component_table.asp>`_ + `FeatureComponents Table <http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/featurecomponents_table.asp>`_ .. _features: @@ -422,7 +422,7 @@ Features .. seealso:: - `Feature Table <http://msdn.microsoft.com/library/en-us/msi/setup/feature_table.asp>`_ + `Feature Table <http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/feature_table.asp>`_ .. _msi-gui: @@ -516,13 +516,13 @@ to create MSI files with a user-interface for installing Python packages. .. seealso:: - `Dialog Table <http://msdn.microsoft.com/library/en-us/msi/setup/dialog_table.asp>`_ - `Control Table <http://msdn.microsoft.com/library/en-us/msi/setup/control_table.asp>`_ - `Control Types <http://msdn.microsoft.com/library/en-us/msi/setup/controls.asp>`_ - `ControlCondition Table <http://msdn.microsoft.com/library/en-us/msi/setup/controlcondition_table.asp>`_ - `ControlEvent Table <http://msdn.microsoft.com/library/en-us/msi/setup/controlevent_table.asp>`_ - `EventMapping Table <http://msdn.microsoft.com/library/en-us/msi/setup/eventmapping_table.asp>`_ - `RadioButton Table <http://msdn.microsoft.com/library/en-us/msi/setup/radiobutton_table.asp>`_ + `Dialog Table <http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/dialog_table.asp>`_ + `Control Table <http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/control_table.asp>`_ + `Control Types <http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/controls.asp>`_ + `ControlCondition Table <http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/controlcondition_table.asp>`_ + `ControlEvent Table <http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/controlevent_table.asp>`_ + `EventMapping Table <http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/eventmapping_table.asp>`_ + `RadioButton Table <http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/radiobutton_table.asp>`_ .. _msi-tables: @@ -551,5 +551,3 @@ definitions. Currently, these definitions are based on MSI version 2.0. This module contains definitions for the UIText and ActionText tables, for the standard installer actions. - - diff --git a/Doc/library/os.rst b/Doc/library/os.rst index f3485cca57..c64c5adb76 100644 --- a/Doc/library/os.rst +++ b/Doc/library/os.rst @@ -1576,9 +1576,9 @@ written in Python, such as a mail server's external command delivery program. .. function:: system(command) Execute the command (a string) in a subshell. This is implemented by calling - the Standard C function :cfunc:`system`, and has the same limitations. Changes - to :data:`os.environ`, :data:`sys.stdin`, etc. are not reflected in the - environment of the executed command. + the Standard C function :cfunc:`system`, and has the same limitations. + Changes to :data:`sys.stdin`, etc. are not reflected in the environment of the + executed command. On Unix, the return value is the exit status of the process encoded in the format specified for :func:`wait`. Note that POSIX does not specify the meaning diff --git a/Doc/library/othergui.rst b/Doc/library/othergui.rst index 471076ca46..1f4aed73d1 100644 --- a/Doc/library/othergui.rst +++ b/Doc/library/othergui.rst @@ -43,7 +43,7 @@ also available for Python: `PythonCAD <http://www.pythoncad.org/>`_. An online `tutorial <http://www.pygtk.org/pygtk2tutorial/index.html>`_ is available. - `PyQt <http://www.riverbankcomputing.co.uk/pyqt/index.php>`_ + `PyQt <http://www.riverbankcomputing.co.uk/software/pyqt/>`_ PyQt is a :program:`sip`\ -wrapped binding to the Qt toolkit. Qt is an extensive C++ GUI application development framework that is available for Unix, Windows and Mac OS X. :program:`sip` is a tool diff --git a/Doc/library/platform.rst b/Doc/library/platform.rst index 7be6d7bd9c..f4ef6805a1 100644 --- a/Doc/library/platform.rst +++ b/Doc/library/platform.rst @@ -94,7 +94,7 @@ Cross Platform .. function:: python_implementation() Returns a string identifying the Python implementation. Possible return values - are: 'CPython', 'IronPython', 'Jython' + are: 'CPython', 'IronPython', 'Jython'. .. function:: python_revision() diff --git a/Doc/library/signal.rst b/Doc/library/signal.rst index 4251702dc8..c6a3fe42bd 100644 --- a/Doc/library/signal.rst +++ b/Doc/library/signal.rst @@ -157,13 +157,14 @@ The :mod:`signal` module defines the following functions: The old values are returned as a tuple: (delay, interval). - Attempting to pass an invalid interval timer will cause a - :exc:`ItimerError`. + Attempting to pass an invalid interval timer will cause an + :exc:`ItimerError`. Availability: Unix. .. function:: getitimer(which) Returns current value of a given interval timer specified by *which*. + Availability: Unix. .. function:: set_wakeup_fd(fd) @@ -184,7 +185,7 @@ The :mod:`signal` module defines the following functions: Change system call restart behaviour: if *flag* is :const:`False`, system calls will be restarted when interrupted by signal *signalnum*, otherwise - system calls will be interrupted. Returns nothing. Availability: Unix (see + system calls will be interrupted. Returns nothing. Availability: Unix (see the man page :manpage:`siginterrupt(3)` for further information). Note that installing a signal handler with :func:`signal` will reset the diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index 8cc52c2128..2f5d93d60d 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -772,13 +772,15 @@ Notes: If *k* is ``None``, it is treated like ``1``. (6) - If *s* and *t* are both strings, some Python implementations such as CPython can - usually perform an in-place optimization for assignments of the form ``s=s+t`` - or ``s+=t``. When applicable, this optimization makes quadratic run-time much - less likely. This optimization is both version and implementation dependent. - For performance sensitive code, it is preferable to use the :meth:`str.join` - method which assures consistent linear concatenation performance across versions - and implementations. + .. impl-detail:: + + If *s* and *t* are both strings, some Python implementations such as + CPython can usually perform an in-place optimization for assignments of + the form ``s = s + t`` or ``s += t``. When applicable, this optimization + makes quadratic run-time much less likely. This optimization is both + version and implementation dependent. For performance sensitive code, it + is preferable to use the :meth:`str.join` method which assures consistent + linear concatenation performance across versions and implementations. .. _string-methods: @@ -951,12 +953,12 @@ functions based on regular expressions. least one cased character, false otherwise. -.. method:: str.join(seq) +.. method:: str.join(iterable) - Return a string which is the concatenation of the strings in the sequence - *seq*. A :exc:`TypeError` will be raised if there are any non-string values - in *seq*, including :class:`bytes` objects. The separator between elements - is the string providing this method. + Return a string which is the concatenation of the strings in the + :term:`iterable` *iterable*. A :exc:`TypeError` will be raised if there are + any non-string values in *seq*, including :class:`bytes` objects. The + separator between elements is the string providing this method. .. method:: str.ljust(width[, fillchar]) @@ -1510,14 +1512,17 @@ Notes: that compare equal --- this is helpful for sorting in multiple passes (for example, sort by department, then by salary grade). - While a list is being sorted, the effect of attempting to mutate, or even - inspect, the list is undefined. The C implementation - makes the list appear empty for the duration, and raises :exc:`ValueError` if it - can detect that the list has been mutated during a sort. + .. impl-detail:: + + While a list is being sorted, the effect of attempting to mutate, or even + inspect, the list is undefined. The C implementation of Python makes the + list appear empty for the duration, and raises :exc:`ValueError` if it can + detect that the list has been mutated during a sort. (8) :meth:`sort` is not supported by :class:`bytearray` objects. + .. _bytes-methods: Bytes and Byte Array Methods diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst index 9c2c0195d0..82e978e450 100644 --- a/Doc/library/sys.rst +++ b/Doc/library/sys.rst @@ -352,8 +352,10 @@ always available. that is deeper than the call stack, :exc:`ValueError` is raised. The default for *depth* is zero, returning the frame at the top of the call stack. - This function should be used for internal and specialized purposes only. It - is not guaranteed to exist in all implementations of Python. + .. impl-detail:: + + This function should be used for internal and specialized purposes only. + It is not guaranteed to exist in all implementations of Python. .. function:: getprofile() @@ -373,12 +375,12 @@ always available. Get the trace function as set by :func:`settrace`. - .. note:: + .. impl-detail:: The :func:`gettrace` function is intended only for implementing debuggers, - profilers, coverage tools and the like. Its behavior is part of the - implementation platform, rather than part of the language definition, - and thus may not be available in all Python implementations. + profilers, coverage tools and the like. Its behavior is part of the + implementation platform, rather than part of the language definition, and + thus may not be available in all Python implementations. .. function:: getwindowsversion() @@ -750,12 +752,12 @@ always available. For more information on code and frame objects, refer to :ref:`types`. - .. note:: + .. impl-detail:: The :func:`settrace` function is intended only for implementing debuggers, - profilers, coverage tools and the like. Its behavior is part of the - implementation platform, rather than part of the language definition, and thus - may not be available in all Python implementations. + profilers, coverage tools and the like. Its behavior is part of the + implementation platform, rather than part of the language definition, and + thus may not be available in all Python implementations. .. function:: settscdump(on_flag) diff --git a/Doc/library/types.rst b/Doc/library/types.rst index 8ae9f88b2c..7caecaf4f6 100644 --- a/Doc/library/types.rst +++ b/Doc/library/types.rst @@ -77,5 +77,8 @@ The module defines the following names: as ``datetime.timedelta.days``. This type is used as descriptor for simple C data members which use standard conversion functions; it has the same purpose as the :class:`property` type, but for classes defined in extension modules. - In other implementations of Python, this type may be identical to - ``GetSetDescriptorType``. + + .. impl-detail:: + + In other implementations of Python, this type may be identical to + ``GetSetDescriptorType``. diff --git a/Doc/library/weakref.rst b/Doc/library/weakref.rst index 06a432d047..685d2079eb 100644 --- a/Doc/library/weakref.rst +++ b/Doc/library/weakref.rst @@ -72,9 +72,10 @@ support weak references but can add support through subclassing:: obj = Dict(red=1, green=2, blue=3) # this object is weak referenceable -Other built-in types such as :class:`tuple` and :class:`int` do not support -weak references even when subclassed (those types implemented as a -:ctype:`PyVarObject`). +.. impl-detail:: + + Other built-in types such as :class:`tuple` and :class:`long` do not support + weak references even when subclassed. Extension types can easily be made to support weak references; see :ref:`weakref-support`. diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst index 971c06e643..36fc575bc0 100644 --- a/Doc/reference/datamodel.rst +++ b/Doc/reference/datamodel.rst @@ -59,13 +59,16 @@ Objects are never explicitly destroyed; however, when they become unreachable they may be garbage-collected. An implementation is allowed to postpone garbage collection or omit it altogether --- it is a matter of implementation quality how garbage collection is implemented, as long as no objects are collected that -are still reachable. (Implementation note: CPython currently uses a -reference-counting scheme with (optional) delayed detection of cyclically linked -garbage, which collects most objects as soon as they become unreachable, but is -not guaranteed to collect garbage containing circular references. See the -documentation of the :mod:`gc` module for information on controlling the -collection of cyclic garbage. Other implementations act differently and CPython -may change.) +are still reachable. + +.. impl-detail:: + + CPython currently uses a reference-counting scheme with (optional) delayed + detection of cyclically linked garbage, which collects most objects as soon + as they become unreachable, but is not guaranteed to collect garbage + containing circular references. See the documentation of the :mod:`gc` + module for information on controlling the collection of cyclic garbage. + Other implementations act differently and CPython may change. Note that the use of the implementation's tracing or debugging facilities may keep objects alive that would normally be collectable. Also note that catching @@ -1469,15 +1472,15 @@ Notes on using *__slots__* *__slots__*; otherwise, the class attribute would overwrite the descriptor assignment. +* The action of a *__slots__* declaration is limited to the class where it is + defined. As a result, subclasses will have a *__dict__* unless they also define + *__slots__* (which must only contain names of any *additional* slots). + * If a class defines a slot also defined in a base class, the instance variable defined by the base class slot is inaccessible (except by retrieving its descriptor directly from the base class). This renders the meaning of the program undefined. In the future, a check may be added to prevent this. -* The action of a *__slots__* declaration is limited to the class where it is - defined. As a result, subclasses will have a *__dict__* unless they also define - *__slots__*. - * Nonempty *__slots__* does not work for classes derived from "variable-length" built-in types such as :class:`int`, :class:`str` and :class:`tuple`. @@ -1714,12 +1717,16 @@ implemented as an iteration through a sequence. However, container objects can supply the following special method with a more efficient implementation, which also does not require the object be a sequence. - .. method:: object.__contains__(self, item) - Called to implement membership test operators. Should return true if *item* is - in *self*, false otherwise. For mapping objects, this should consider the keys - of the mapping rather than the values or the key-item pairs. + Called to implement membership test operators. Should return true if *item* + is in *self*, false otherwise. For mapping objects, this should consider the + keys of the mapping rather than the values or the key-item pairs. + + For objects that don't define :meth:`__contains__`, the membership test first + tries iteration via :meth:`__iter__`, then the old sequence iteration + protocol via :meth:`__getitem__`, see :ref:`this section in the language + reference <membership-test-details>`. .. _numeric-types: diff --git a/Doc/reference/executionmodel.rst b/Doc/reference/executionmodel.rst index 68ee654175..90791d2247 100644 --- a/Doc/reference/executionmodel.rst +++ b/Doc/reference/executionmodel.rst @@ -129,7 +129,7 @@ the built-in module :mod:`builtins`; when in any other module, itself. ``__builtins__`` can be set to a user-created dictionary to create a weak form of restricted execution. -.. note:: +.. impl-detail:: Users should not touch ``__builtins__``; it is strictly an implementation detail. Users wanting to override values in the built-in namespace should diff --git a/Doc/reference/expressions.rst b/Doc/reference/expressions.rst index cdb802a73e..d074ebb922 100644 --- a/Doc/reference/expressions.rst +++ b/Doc/reference/expressions.rst @@ -639,13 +639,13 @@ slots for which no default value is specified, a :exc:`TypeError` exception is raised. Otherwise, the list of filled slots is used as the argument list for the call. -.. note:: +.. impl-detail:: - An implementation may provide built-in functions whose positional parameters do - not have names, even if they are 'named' for the purpose of documentation, and - which therefore cannot be supplied by keyword. In CPython, this is the case for - functions implemented in C that use :cfunc:`PyArg_ParseTuple` to parse their - arguments. + An implementation may provide built-in functions whose positional parameters + do not have names, even if they are 'named' for the purpose of documentation, + and which therefore cannot be supplied by keyword. In CPython, this is the + case for functions implemented in C that use :cfunc:`PyArg_ParseTuple` to + parse their arguments. If there are more positional arguments than there are formal parameter slots, a :exc:`TypeError` exception is raised, unless a formal parameter using the syntax @@ -1053,6 +1053,8 @@ cross-type comparison is not supported, the comparison method returns supported cross-type comparisons and unsupported comparisons. For example, ``Decimal(2) == 2`` and `2 == float(2)`` but ``Decimal(2) != float(2)``. +.. _membership-test-details: + The operators :keyword:`in` and :keyword:`not in` test for membership. ``x in s`` evaluates to true if *x* is a member of *s*, and false otherwise. ``x not in s`` returns the negation of ``x in s``. All built-in sequences and set types @@ -1069,7 +1071,12 @@ return ``True``. For user-defined classes which define the :meth:`__contains__` method, ``x in y`` is true if and only if ``y.__contains__(x)`` is true. -For user-defined classes which do not define :meth:`__contains__` and do define +For user-defined classes which do not define :meth:`__contains__` but do define +:meth:`__iter__`, ``x in y`` is true if some value ``z`` with ``x == z`` is +produced while iterating over ``y``. If an exception is raised during the +iteration, it is as if :keyword:`in` raised that exception. + +Lastly, the old-style iteration protocol is tried: if a class defines :meth:`__getitem__`, ``x in y`` is true if and only if there is a non-negative integer index *i* such that ``x == y[i]``, and all lower integer indices do not raise :exc:`IndexError` exception. (If any other exception is raised, it is as diff --git a/Doc/reference/simple_stmts.rst b/Doc/reference/simple_stmts.rst index a8ec495206..b1be34a8f2 100644 --- a/Doc/reference/simple_stmts.rst +++ b/Doc/reference/simple_stmts.rst @@ -236,9 +236,11 @@ Assignment of an object to a single target is recursively defined as follows. from the length of the assigned sequence, thus changing the length of the target sequence, if the object allows it. -(In the current implementation, the syntax for targets is taken to be the same -as for expressions, and invalid syntax is rejected during the code generation -phase, causing less detailed error messages.) +.. impl-detail:: + + In the current implementation, the syntax for targets is taken to be the same + as for expressions, and invalid syntax is rejected during the code generation + phase, causing less detailed error messages. WARNING: Although the definition of assignment implies that overlaps between the left-hand side and the right-hand side are 'safe' (for example ``a, b = b, a`` @@ -937,9 +939,11 @@ Names listed in a :keyword:`global` statement must not be defined as formal parameters or in a :keyword:`for` loop control target, :keyword:`class` definition, function definition, or :keyword:`import` statement. -(The current implementation does not enforce the latter two restrictions, but -programs should not abuse this freedom, as future implementations may enforce -them or silently change the meaning of the program.) +.. impl-detail:: + + The current implementation does not enforce the latter two restrictions, but + programs should not abuse this freedom, as future implementations may enforce + them or silently change the meaning of the program. .. index:: builtin: exec diff --git a/Doc/tools/sphinxext/pyspecific.py b/Doc/tools/sphinxext/pyspecific.py index adfeb6a9e8..d2cca847e9 100644 --- a/Doc/tools/sphinxext/pyspecific.py +++ b/Doc/tools/sphinxext/pyspecific.py @@ -35,6 +35,8 @@ from sphinx.locale import versionlabels HTMLTranslator.visit_versionmodified = new_visit_versionmodified +# Support for marking up and linking to bugs.python.org issues + def issue_role(typ, rawtext, text, lineno, inliner, options={}, content=[]): issue = utils.unescape(text) text = 'issue ' + issue @@ -42,6 +44,34 @@ def issue_role(typ, rawtext, text, lineno, inliner, options={}, content=[]): return [refnode], [] +# Support for marking up implementation details + +from sphinx.util.compat import Directive + +class ImplementationDetail(Directive): + + has_content = True + required_arguments = 0 + optional_arguments = 1 + final_argument_whitespace = True + + def run(self): + pnode = nodes.compound(classes=['impl-detail']) + content = self.content + add_text = nodes.strong('CPython implementation detail:', + 'CPython implementation detail:') + if self.arguments: + n, m = self.state.inline_text(self.arguments[0], self.lineno) + pnode.append(nodes.paragraph('', '', *(n + m))) + self.state.nested_parse(content, self.content_offset, pnode) + if pnode.children and isinstance(pnode[0], nodes.paragraph): + pnode[0].insert(0, add_text) + pnode[0].insert(1, nodes.Text(' ')) + else: + pnode.insert(0, nodes.paragraph('', '', add_text)) + return [pnode] + + # Support for building "topic help" for pydoc pydoc_topic_labels = [ @@ -108,10 +138,12 @@ class PydocTopicsBuilder(Builder): finally: f.close() + # Support for checking for suspicious markup import suspicious + # Support for documenting Opcodes import re @@ -134,6 +166,7 @@ def parse_opcode_signature(env, sig, signode): def setup(app): app.add_role('issue', issue_role) + app.add_directive('impl-detail', ImplementationDetail) app.add_builder(PydocTopicsBuilder) app.add_builder(suspicious.CheckSuspiciousMarkupBuilder) app.add_description_unit('opcode', 'opcode', '%s (opcode)', diff --git a/Doc/tools/sphinxext/static/basic.css b/Doc/tools/sphinxext/static/basic.css index 03b0ba3424..aeb13816d1 100644 --- a/Doc/tools/sphinxext/static/basic.css +++ b/Doc/tools/sphinxext/static/basic.css @@ -345,6 +345,21 @@ p.deprecated { background-color: #ffa } +.impl-detail { + margin-top: 10px; + margin-bottom: 10px; + padding: 7px; + border: 1px solid #ccc; +} + +.impl-detail .compound-first { + margin-top: 0; +} + +.impl-detail .compound-last { + margin-bottom: 0; +} + /* -- code displays --------------------------------------------------------- */ pre { @@ -405,7 +420,7 @@ span.eqno { div.document, div.documentwrapper, div.bodywrapper { - margin: 0; + margin: 0 !important; width: 100%; } diff --git a/Doc/tutorial/index.rst b/Doc/tutorial/index.rst index 8a1a8fb6a7..7d0bfc2f94 100644 --- a/Doc/tutorial/index.rst +++ b/Doc/tutorial/index.rst @@ -28,18 +28,17 @@ features of the Python language and system. It helps to have a Python interpreter handy for hands-on experience, but all examples are self-contained, so the tutorial can be read off-line as well. -For a description of standard objects and modules, see the Python Library -Reference document. The Python Reference Manual gives a more formal definition -of the language. To write extensions in C or C++, read Extending and Embedding -the Python Interpreter and Python/C API Reference. There are also several books -covering Python in depth. +For a description of standard objects and modules, see :ref:`library-index`. +:ref:`reference-index` gives a more formal definition of the language. To write +extensions in C or C++, read :ref:`extending-index` and +:ref:`c-api-index`. There are also several books covering Python in depth. This tutorial does not attempt to be comprehensive and cover every single feature, or even every commonly used feature. Instead, it introduces many of Python's most noteworthy features, and will give you a good idea of the language's flavor and style. After reading it, you will be able to read and write Python modules and programs, and you will be ready to learn more about the -various Python library modules described in the Python Library Reference. +various Python library modules described in :ref:`library-index`. The :ref:`glossary` is also worth going through. diff --git a/Doc/using/cmdline.rst b/Doc/using/cmdline.rst index ad8f8c6d71..ccdfe330fb 100644 --- a/Doc/using/cmdline.rst +++ b/Doc/using/cmdline.rst @@ -8,7 +8,7 @@ Command line and environment The CPython interpreter scans the command line and the environment for various settings. -.. note:: +.. impl-detail:: Other implementations' command line schemes may differ. See :ref:`implementations` for further resources. diff --git a/Doc/using/windows.rst b/Doc/using/windows.rst index 99fc674635..7961a60c0a 100644 --- a/Doc/using/windows.rst +++ b/Doc/using/windows.rst @@ -67,7 +67,7 @@ key features: `ActivePython <http://www.activestate.com/Products/activepython/>`_ Installer with multi-platform compatibility, documentation, PyWin32 -`Python Enthought Edition <http://code.enthought.com/enthon/>`_ +`Enthought Python Distribution <http://www.enthought.com/products/epd.php>`_ Popular modules (such as PyWin32) with their respective documentation, tool suite for building extensible python applications @@ -221,8 +221,7 @@ utilities for: * Win32 API calls * Registry * Event log -* `Microsoft Foundation Classes <http://msdn.microsoft.com/library/ - en-us/vclib/html/_mfc_Class_Library_Reference_Introduction.asp>`_ (MFC) +* `Microsoft Foundation Classes <http://msdn.microsoft.com/en-us/library/fe1cf721%28VS.80%29.aspx>`_ (MFC) user interfaces `PythonWin <http://web.archive.org/web/20060524042422/ @@ -299,7 +298,7 @@ For extension modules, consult :ref:`building-on-windows`. MinGW gcc under Windows" or "Installing Python extension with distutils and without Microsoft Visual C++" by Sébastien Sauvage, 2003 - `MingW -- Python extensions <http://www.mingw.org/MinGWiki/index.php/Python%20extensions>`_ + `MingW -- Python extensions <http://oldwiki.mingw.org/index.php/Python%20extensions>`_ by Trent Apted et al, 2007 diff --git a/Doc/whatsnew/2.0.rst b/Doc/whatsnew/2.0.rst index f5326d7592..5fd53d165e 100644 --- a/Doc/whatsnew/2.0.rst +++ b/Doc/whatsnew/2.0.rst @@ -572,8 +572,7 @@ Work has been done on porting Python to 64-bit Windows on the Itanium processor, mostly by Trent Mick of ActiveState. (Confusingly, ``sys.platform`` is still ``'win32'`` on Win64 because it seems that for ease of porting, MS Visual C++ treats code as 32 bit on Itanium.) PythonWin also supports Windows CE; see the -Python CE page at http://starship.python.net/crew/mhammond/ce/ for more -information. +Python CE page at http://pythonce.sourceforge.net/ for more information. Another new platform is Darwin/MacOS X; initial support for it is in Python 2.0. Dynamic loading works, if you specify "configure --with-dyld --with-suffix=.x". @@ -1041,8 +1040,8 @@ sent over a socket. When compiling Python, you can edit :file:`Modules/Setup` to include SSL support, which adds an additional function to the :mod:`socket` module: :func:`socket.ssl(socket, keyfile, certfile)`, which takes a socket object and returns an SSL socket. The :mod:`httplib` and :mod:`urllib` modules -were also changed to support "https://" URLs, though no one has implemented FTP -or SMTP over SSL. +were also changed to support ``https://`` URLs, though no one has implemented +FTP or SMTP over SSL. The :mod:`httplib` module has been rewritten by Greg Stein to support HTTP/1.1. Backward compatibility with the 1.5 version of :mod:`httplib` is provided, diff --git a/Doc/whatsnew/2.2.rst b/Doc/whatsnew/2.2.rst index acdba831f0..31e8dd0940 100644 --- a/Doc/whatsnew/2.2.rst +++ b/Doc/whatsnew/2.2.rst @@ -30,7 +30,7 @@ understand the complete implementation and design rationale for a change, refer to the PEP for a particular new feature. -.. seealso:: +.. seealso (now defunct) http://www.unixreview.com/documents/s=1356/urm0109h/0109h.htm "What's So Special About Python 2.2?" is also about the new 2.2 features, and @@ -49,14 +49,14 @@ amazing new capabilities. Before beginning this, the longest and most complicated section of this article, I'll provide an overview of the changes and offer some comments. -A long time ago I wrote a Web page (http://www.amk.ca/python/writing/warts.html) -listing flaws in Python's design. One of the most significant flaws was that -it's impossible to subclass Python types implemented in C. In particular, it's -not possible to subclass built-in types, so you can't just subclass, say, lists -in order to add a single useful method to them. The :mod:`UserList` module -provides a class that supports all of the methods of lists and that can be -subclassed further, but there's lots of C code that expects a regular Python -list and won't accept a :class:`UserList` instance. +A long time ago I wrote a Web page listing flaws in Python's design. One of the +most significant flaws was that it's impossible to subclass Python types +implemented in C. In particular, it's not possible to subclass built-in types, +so you can't just subclass, say, lists in order to add a single useful method to +them. The :mod:`UserList` module provides a class that supports all of the +methods of lists and that can be subclassed further, but there's lots of C code +that expects a regular Python list and won't accept a :class:`UserList` +instance. Python 2.2 fixes this, and in the process adds some exciting new capabilities. A brief summary: diff --git a/Doc/whatsnew/2.3.rst b/Doc/whatsnew/2.3.rst index fd0f77fe0d..3894f8744a 100644 --- a/Doc/whatsnew/2.3.rst +++ b/Doc/whatsnew/2.3.rst @@ -1855,10 +1855,10 @@ and bundle it with the source of your extension. .. seealso:: - http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/python/python/dist/src/Objects/obmalloc.c - For the full details of the pymalloc implementation, see the comments at the top - of the file :file:`Objects/obmalloc.c` in the Python source code. The above - link points to the file within the SourceForge CVS browser. + http://svn.python.org/view/python/trunk/Objects/obmalloc.c + For the full details of the pymalloc implementation, see the comments at + the top of the file :file:`Objects/obmalloc.c` in the Python source code. + The above link points to the file within the python.org SVN browser. .. ====================================================================== diff --git a/Doc/whatsnew/2.4.rst b/Doc/whatsnew/2.4.rst index 9e438ac761..27e412e411 100644 --- a/Doc/whatsnew/2.4.rst +++ b/Doc/whatsnew/2.4.rst @@ -680,9 +680,6 @@ includes a quick-start tutorial and a reference. Written by Facundo Batista and implemented by Facundo Batista, Eric Price, Raymond Hettinger, Aahz, and Tim Peters. - http://research.microsoft.com/~hollasch/cgindex/coding/ieeefloat.html - A more detailed overview of the IEEE-754 representation. - http://www.lahey.com/float.htm The article uses Fortran code to illustrate many of the problems that floating- point inaccuracy can cause. @@ -756,7 +753,7 @@ API that perform ASCII-only conversions, ignoring the locale setting: :ctype:`double` to an ASCII string. The code for these functions came from the GLib library -(http://developer.gnome.org/arch/gtk/glib.html), whose developers kindly +(http://library.gnome.org/devel/glib/stable/), whose developers kindly relicensed the relevant functions and donated them to the Python Software Foundation. The :mod:`locale` module can now change the numeric locale, letting extensions such as GTK+ produce the correct results. diff --git a/Doc/whatsnew/2.6.rst b/Doc/whatsnew/2.6.rst index cc8a29a76a..27d8e5cccd 100644 --- a/Doc/whatsnew/2.6.rst +++ b/Doc/whatsnew/2.6.rst @@ -1828,7 +1828,7 @@ changes, or look through the Subversion logs for all the details. The :mod:`bsddb.dbshelve` module now uses the highest pickling protocol available, instead of restricting itself to protocol 1. - (Contributed by W. Barnes; :issue:`1551443`.) + (Contributed by W. Barnes.) * The :mod:`cgi` module will now read variables from the query string of an HTTP POST request. This makes it possible to use form actions @@ -2977,7 +2977,7 @@ Changes to Python's build process and to the C API include: * The BerkeleyDB module now has a C API object, available as ``bsddb.db.api``. This object can be used by other C extensions that wish to use the :mod:`bsddb` module for their own purposes. - (Contributed by Duncan Grisby; :issue:`1551895`.) + (Contributed by Duncan Grisby.) * The new buffer interface, previously described in `the PEP 3118 section <#pep-3118-revised-buffer-protocol>`__, diff --git a/Lib/threading.py b/Lib/threading.py index 3014ff16f8..88101b0cb5 100644 --- a/Lib/threading.py +++ b/Lib/threading.py @@ -119,7 +119,7 @@ class _RLock(_Verbose): def release(self): if self._owner is not current_thread(): - raise RuntimeError("cannot release un-aquired lock") + raise RuntimeError("cannot release un-acquired lock") self._count = count = self._count - 1 if not count: self._owner = None @@ -211,7 +211,7 @@ class _Condition(_Verbose): def wait(self, timeout=None): if not self._is_owned(): - raise RuntimeError("cannot wait on un-aquired lock") + raise RuntimeError("cannot wait on un-acquired lock") waiter = _allocate_lock() waiter.acquire() self._waiters.append(waiter) @@ -253,7 +253,7 @@ class _Condition(_Verbose): def notify(self, n=1): if not self._is_owned(): - raise RuntimeError("cannot notify on un-aquired lock") + raise RuntimeError("cannot notify on un-acquired lock") __waiters = self._waiters waiters = __waiters[:n] if not waiters: diff --git a/Lib/warnings.py b/Lib/warnings.py index 5df3f49474..9de2c6737b 100644 --- a/Lib/warnings.py +++ b/Lib/warnings.py @@ -32,7 +32,14 @@ def filterwarnings(action, message="", category=Warning, module="", lineno=0, append=False): """Insert an entry into the list of warnings filters (at the front). - Use assertions to check that all arguments have the right type.""" + 'action' -- one of "error", "ignore", "always", "default", "module", + or "once" + 'message' -- a regex that the warning message must match + 'category' -- a class that the warning must be a subclass of + 'module' -- a regex that the module name must match + 'lineno' -- an integer line number, 0 matches all warnings + 'append' -- if true, append to the list of filters + """ import re assert action in ("error", "ignore", "always", "default", "module", "once"), "invalid action: %r" % (action,) @@ -53,6 +60,11 @@ def simplefilter(action, category=Warning, lineno=0, append=False): """Insert a simple entry into the list of warnings filters (at the front). A simple filter matches all modules and messages. + 'action' -- one of "error", "ignore", "always", "default", "module", + or "once" + 'category' -- a class that the warning must be a subclass of + 'lineno' -- an integer line number, 0 matches all warnings + 'append' -- if true, append to the list of filters """ assert action in ("error", "ignore", "always", "default", "module", "once"), "invalid action: %r" % (action,) diff --git a/Modules/_ctypes/_ctypes.c b/Modules/_ctypes/_ctypes.c index 169585b47c..21961aeb2f 100644 --- a/Modules/_ctypes/_ctypes.c +++ b/Modules/_ctypes/_ctypes.c @@ -1865,16 +1865,15 @@ PyCSimpleType_new(PyTypeObject *type, PyObject *args, PyObject *kwds) } fmt = _ctypes_get_fielddesc(proto_str); if (fmt == NULL) { - Py_DECREF((PyObject *)result); PyErr_Format(PyExc_ValueError, "_type_ '%s' not supported", proto_str); - return NULL; + goto error; } stgdict = (StgDictObject *)PyObject_CallObject( (PyObject *)&PyCStgDict_Type, NULL); if (!stgdict) - return NULL; + goto error; stgdict->ffi_type_pointer = *fmt->pffi_type; stgdict->align = fmt->pffi_type->alignment; @@ -1889,6 +1888,7 @@ PyCSimpleType_new(PyTypeObject *type, PyObject *args, PyObject *kwds) #endif if (stgdict->format == NULL) { Py_DECREF(result); + Py_DECREF(proto); Py_DECREF((PyObject *)stgdict); return NULL; } diff --git a/Objects/unicodeobject.c b/Objects/unicodeobject.c index 767bed0776..c9808e1cc6 100644 --- a/Objects/unicodeobject.c +++ b/Objects/unicodeobject.c @@ -7710,10 +7710,10 @@ unicode_isprintable(PyObject *self) } PyDoc_STRVAR(join__doc__, - "S.join(sequence) -> str\n\ + "S.join(iterable) -> str\n\ \n\ Return a string which is the concatenation of the strings in the\n\ -sequence. The separator between elements is S."); +iterable. The separator between elements is S."); static PyObject* unicode_join(PyObject *self, PyObject *data) diff --git a/Python/codecs.c b/Python/codecs.c index d1915f181d..e6ffa0d3f9 100644 --- a/Python/codecs.c +++ b/Python/codecs.c @@ -957,7 +957,9 @@ static int _PyCodecRegistry_Init(void) { "strict_errors", strict_errors, - METH_O + METH_O, + PyDoc_STR("Implements the 'strict' error handling, which " + "raises a UnicodeError on coding errors.") } }, { @@ -965,7 +967,9 @@ static int _PyCodecRegistry_Init(void) { "ignore_errors", ignore_errors, - METH_O + METH_O, + PyDoc_STR("Implements the 'ignore' error handling, which " + "ignores malformed data and continues.") } }, { @@ -973,7 +977,9 @@ static int _PyCodecRegistry_Init(void) { "replace_errors", replace_errors, - METH_O + METH_O, + PyDoc_STR("Implements the 'replace' error handling, which " + "replaces malformed data with a replacement marker.") } }, { @@ -981,7 +987,10 @@ static int _PyCodecRegistry_Init(void) { "xmlcharrefreplace_errors", xmlcharrefreplace_errors, - METH_O + METH_O, + PyDoc_STR("Implements the 'xmlcharrefreplace' error handling, " + "which replaces an unencodable character with the " + "appropriate XML character reference.") } }, { @@ -989,7 +998,10 @@ static int _PyCodecRegistry_Init(void) { "backslashreplace_errors", backslashreplace_errors, - METH_O + METH_O, + PyDoc_STR("Implements the 'backslashreplace' error handling, " + "which replaces an unencodable character with a " + "backslashed escape sequence.") } }, { |