Merged revisions 67154,67157-67159,67162-67163,67166,67175-67176,67189,67224-67225,67243 via svnmerge from

svn+ssh://pythondev@svn.python.org/python/trunk

........
  r67154 | hirokazu.yamamoto | 2008-11-08 04:46:17 +0100 (Sat, 08 Nov 2008) | 1 line

  Issue #4071: ntpath.abspath returned an empty string for long unicode path.
........
  r67157 | georg.brandl | 2008-11-08 12:47:44 +0100 (Sat, 08 Nov 2008) | 2 lines

  Don't use "HOWTO" as the title for all howto .tex files.
........
  r67158 | georg.brandl | 2008-11-08 12:48:20 +0100 (Sat, 08 Nov 2008) | 2 lines

  Update "Documenting" a bit. Concentrate on Python-specifics.
........
  r67159 | georg.brandl | 2008-11-08 13:52:25 +0100 (Sat, 08 Nov 2008) | 2 lines

  Fix warning.
........
  r67162 | benjamin.peterson | 2008-11-08 17:55:33 +0100 (Sat, 08 Nov 2008) | 1 line

  a few compile() and ast doc improvements
........
  r67163 | benjamin.peterson | 2008-11-08 18:04:18 +0100 (Sat, 08 Nov 2008) | 1 line

  move context clue to versionchanged tag
........
  r67166 | benjamin.peterson | 2008-11-08 18:07:06 +0100 (Sat, 08 Nov 2008) | 1 line

  clarify what was added
........
  r67175 | benjamin.peterson | 2008-11-09 02:44:32 +0100 (Sun, 09 Nov 2008) | 1 line

  update link
........
  r67176 | benjamin.peterson | 2008-11-09 02:52:32 +0100 (Sun, 09 Nov 2008) | 1 line

  fix comment
........
  r67189 | benjamin.peterson | 2008-11-11 22:56:06 +0100 (Tue, 11 Nov 2008) | 1 line

  use correct name
........
  r67224 | georg.brandl | 2008-11-15 09:10:04 +0100 (Sat, 15 Nov 2008) | 2 lines

  #4324: fix getlocale() argument.
........
  r67225 | brett.cannon | 2008-11-15 23:33:25 +0100 (Sat, 15 Nov 2008) | 1 line

  Clarify the docs for the 'strict' argument to httplib.HTTPConnection.
........
  r67243 | benjamin.peterson | 2008-11-17 22:39:05 +0100 (Mon, 17 Nov 2008) | 1 line

  a few fixes on the download page
........

Doc/conf.py

@@ -128,7 +128,7 @@ latex_documents = [
 ]
 # Collect all HOWTOs individually
 latex_documents.extend(('howto/' + fn[:-4], 'howto-' + fn[:-4] + '.tex',
-                        'HOWTO', _stdauthor, 'howto')
+                        '', _stdauthor, 'howto')
                        for fn in os.listdir('howto')
                        if fn.endswith('.rst') and fn != 'index.rst')
 

Doc/documenting/index.rst

@@ -8,7 +8,7 @@
 The Python language has a substantial body of documentation, much of it
 contributed by various authors. The markup used for the Python documentation is
 `reStructuredText`_, developed by the `docutils`_ project, amended by custom
-directives and using a toolset named *Sphinx* to postprocess the HTML output.
+directives and using a toolset named `Sphinx`_ to postprocess the HTML output.
 
 This document describes the style guide for our documentation, the custom
 reStructuredText markup introduced to support Python documentation and how it
@@ -16,6 +16,7 @@ should be used, as well as the Sphinx build system.
 
 .. _reStructuredText: http://docutils.sf.net/rst.html
 .. _docutils: http://docutils.sf.net/
+.. _Sphinx: http://sphinx.pocoo.org/
 
 If you're interested in contributing to Python's documentation, there's no need
 to write reStructuredText if you're not so inclined; plain text contributions
@@ -28,7 +29,3 @@ are more than welcome as well.
    rest.rst
    markup.rst
    fromlatex.rst
-   sphinx.rst
-
-.. XXX add credits, thanks etc.
-

Doc/documenting/markup.rst

@@ -8,24 +8,11 @@ markup.  This section contains the reference material for these facilities.
 Documentation for "standard" reST constructs is not included here, though
 they are used in the Python documentation.
 
-File-wide metadata
+.. note::
-------------------
 
-reST has the concept of "field lists"; these are a sequence of fields marked up
+   This is just an overview of Sphinx' extended markup capabilities; full
-like this::
+   coverage can be found in `its own documentation
-
+   <http://sphinx.pocoo.org/contents.html>`_.
-   :Field name: Field content
-
-A field list at the very top of a file is parsed as the "docinfo", which in
-normal documents can be used to record the author, date of publication and
-other metadata.  In Sphinx, the docinfo is used as metadata, too, but not
-displayed in the output.
-
-At the moment, only one metadata field is recognized:
-
-``nocomments``
-   If set, the web application won't display a comment form for a page generated
-   from this source file.
 
 
 Meta-information markup
@@ -88,7 +75,6 @@ As you can see, the module-specific markup consists of two directives, the
    authors of the module code, just like ``sectionauthor`` names the author(s)
    of a piece of documentation.  It too does not result in any output currently.
 
-
 .. note::
 
    It is important to make the section title of a module-describing file
@@ -272,7 +258,7 @@ Syntax highlighting is handled in a smart way:
   This language is used until the next ``highlightlang`` directive is
   encountered.
 
-* The valid values for the highlighting language are:
+* The values normally used for the highlighting language are:
 
   * ``python`` (the default)
   * ``c``
@@ -799,7 +785,7 @@ Substitutions
 -------------
 
 The documentation system provides three substitutions that are defined by default.
-They are set in the build configuration file, see :ref:`doc-build-config`.
+They are set in the build configuration file :file:`conf.py`.
 
 .. describe:: |release|
 

Doc/documenting/rest.rst

@@ -67,12 +67,6 @@ autonumbered using a ``#`` sign::
    #. This is a numbered list.
    #. It has two items too.
 
-Note that Sphinx disables the use of enumerated lists introduced by alphabetic
-or roman numerals, such as ::
-
-   A. First item
-   B. Second item
-   
 
 Nested lists are possible, but be aware that they must be separated from the
 parent list items by blank lines::
@@ -247,5 +241,3 @@ There are some problems one commonly runs into while authoring reST documents:
 * **Separation of inline markup:** As said above, inline markup spans must be
   separated from the surrounding text by non-word characters, you have to use
   an escaped space to get around that.
-
-.. XXX more?

Doc/documenting/sphinx.rst

@@ -1,76 +0,0 @@
-.. highlightlang:: rest
-
-The Sphinx build system
-=======================
-
-.. XXX: intro...
-
-.. _doc-build-config:
-
-The build configuration file
-----------------------------
-
-The documentation root, that is the ``Doc`` subdirectory of the source
-distribution, contains a file named ``conf.py``.  This file is called the "build
-configuration file", and it contains several variables that are read and used
-during a build run.
-
-These variables are:
-
-version : string
-   A string that is used as a replacement for the ``|version|`` reST
-   substitution.  It should be the Python version the documentation refers to.
-   This consists only of the major and minor version parts, e.g. ``2.5``, even
-   for version 2.5.1.
-
-release : string
-   A string that is used as a replacement for the ``|release|`` reST
-   substitution.  It should be the full version string including
-   alpha/beta/release candidate tags, e.g. ``2.5.2b3``.
-
-Both ``release`` and ``version`` can be ``'auto'``, which means that they are
-determined at runtime from the ``Include/patchlevel.h`` file, if a complete
-Python source distribution can be found, or else from the interpreter running
-Sphinx.
-
-today_fmt : string
-   A ``strftime`` format that is used to format a replacement for the
-   ``|today|`` reST substitution.
-
-today : string
-   A string that can contain a date that should be written to the documentation
-   output literally.  If this is nonzero, it is used instead of
-   ``strftime(today_fmt)``.
-
-unused_files : list of strings
-   A list of reST filenames that are to be disregarded during building.  This
-   could be docs for temporarily disabled modules or documentation that's not
-   yet ready for public consumption.
-
-add_function_parentheses : bool
-   If true, ``()`` will be appended to the content of ``:func:``, ``:meth:`` and
-   ``:cfunc:`` cross-references.
-
-add_module_names : bool
-   If true, the current module name will be prepended to all description unit
-   titles (such as ``.. function::``).
-
-Builder-specific variables
-^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-html_download_base_url : string
-   The base URL for download links on the download page.
-
-html_last_updated_fmt : string
-   If this is not an empty string, it will be given to ``time.strftime()`` and
-   written to each generated output file after "last updated on:".
-
-html_use_smartypants : bool
-   If true, use SmartyPants to convert quotes and dashes to the typographically
-   correct entities.
-
-latex_paper_size : "letter" or "a4"
-   The paper size option for the LaTeX document class.
-
-latex_font_size : "10pt", "11pt" or "12pt"
-   The font size option for the LaTeX document class.

Doc/documenting/style.rst

@@ -66,5 +66,5 @@ Unix
     1970s.
 
 
-.. _Apple Publications Style Guide: http://developer.apple.com/documentation/UserExperience/Conceptual/APStyleGuide/AppleStyleGuide2006.pdf
+.. _Apple Publications Style Guide: http://developer.apple.com/documentation/UserExperience/Conceptual/APStyleGuide/APSG_2008.pdf
 

Doc/library/ast.rst

@@ -21,13 +21,12 @@ abstract syntax grammar.  The abstract syntax itself might change with each
 Python release; this module helps to find out programmatically what the current
 grammar looks like.
 
-An abstract syntax tree can be generated by passing :data:`_ast.PyCF_ONLY_AST`
+An abstract syntax tree can be generated by passing :data:`ast.PyCF_ONLY_AST` as
-as a flag to the :func:`compile` builtin function, or using the :func:`parse`
+a flag to the :func:`compile` builtin function, or using the :func:`parse`
 helper provided in this module.  The result will be a tree of objects whose
-classes all inherit from :class:`ast.AST`.
+classes all inherit from :class:`ast.AST`.  An abstract syntax tree can be
+compiled into a Python code object using the built-in :func:`compile` function.
 
-A modified abstract syntax tree can be compiled into a Python code object using
-the built-in :func:`compile` function.
 
 Node classes
 ------------
@@ -126,7 +125,7 @@ and classes for traversing abstract syntax trees:
 .. function:: parse(expr, filename='<unknown>', mode='exec')
 
    Parse an expression into an AST node.  Equivalent to ``compile(expr,
-   filename, mode, PyCF_ONLY_AST)``.
+   filename, mode, ast.PyCF_ONLY_AST)``.
 
    
 .. function:: literal_eval(node_or_string)

Doc/library/functions.rst

@@ -199,15 +199,8 @@ available.  They are listed here in alphabetical order.
 
    Compile the *source* into a code or AST object.  Code objects can be executed
    by an :keyword:`exec` statement or evaluated by a call to :func:`eval`.
-   *source* can either be a string or an AST object.  Refer to the :mod:`_ast`
+   *source* can either be a string or an AST object.  Refer to the :mod:`ast`
-   module documentation for information on how to compile into and from AST
+   module documentation for information on how to work with AST objects.
-   objects.
-
-   When compiling a string with multi-line statements, two caveats apply: line
-   endings must be represented by a single newline character (``'\n'``), and the
-   input must be terminated by at least one newline character.  If line endings
-   are represented by ``'\r\n'``, use the string :meth:`replace` method to
-   change them into ``'\n'``.
 
    The *filename* argument should give the file from which the code was read;
    pass some recognizable value if it wasn't read from a file (``'<string>'`` is
@@ -219,15 +212,15 @@ available.  They are listed here in alphabetical order.
    interactive statement (in the latter case, expression statements that
    evaluate to something else than ``None`` will be printed).
 
-   The optional arguments *flags* and *dont_inherit* (which are new in Python 2.2)
+   The optional arguments *flags* and *dont_inherit* control which future
-   control which future statements (see :pep:`236`) affect the compilation of
+   statements (see :pep:`236`) affect the compilation of *source*.  If neither
-   *source*.  If neither is present (or both are zero) the code is compiled with
+   is present (or both are zero) the code is compiled with those future
-   those future statements that are in effect in the code that is calling compile.
+   statements that are in effect in the code that is calling compile.  If the
-   If the *flags* argument is given and *dont_inherit* is not (or is zero) then the
+   *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 to
+   the *flags* argument is it -- the future statements in effect around the call
-   compile are ignored.
+   to compile are ignored.
 
    Future statements are specified by bits which can be bitwise ORed together to
    specify multiple statements.  The bitfield required to specify a given feature
@@ -237,7 +230,18 @@ available.  They are listed here in alphabetical order.
    This function raises :exc:`SyntaxError` if the compiled source is invalid,
    and :exc:`TypeError` if the source contains null bytes.
 
-   .. versionadded:: 2.6
+   .. note::
+
+      When compiling a string with multi-line statements, line endings must be
+      represented by a single newline character (``'\n'``), and the input must
+      be terminated by at least one newline character.  If line endings are
+      represented by ``'\r\n'``, use :meth:`str.replace` to change them into
+      ``'\n'``.
+
+   .. versionchanged:: 2.3
+      The *flags* and *dont_inherit* arguments were added.
+
+   .. versionchanged:: 2.6
       Support for compiling AST objects.
 
 

Doc/library/httplib.rst

@@ -40,7 +40,8 @@ The module provides the following classes:
    server.  It should be instantiated passing it a host and optional port
    number.  If no port number is passed, the port is extracted from the host
    string if it has the form ``host:port``, else the default HTTP port (80) is
-   used.  When True, the optional parameter *strict* causes ``BadStatusLine`` to
+   used.  When True, the optional parameter *strict* (which defaults to a false
+   value) causes ``BadStatusLine`` to
    be raised if the status line can't be parsed as a valid HTTP/1.0 or 1.1
    status line.  If the optional *timeout* parameter is given, blocking
    operations (like connection attempts) will timeout after that many seconds

Doc/library/locale.rst

@@ -492,7 +492,7 @@ descriptions are taken from the corresponding description in the GNU C library.
 Example::
 
    >>> import locale
-   >>> loc = locale.getlocale(locale.LC_ALL) # get current locale
+   >>> loc = locale.getlocale() # get current locale
    >>> locale.setlocale(locale.LC_ALL, 'de_DE') # use German locale; name might vary with platform
    >>> locale.strcoll('f\xe4n', 'foo') # compare a string containing an umlaut 
    >>> locale.setlocale(locale.LC_ALL, '') # use user's preferred locale

Doc/library/multiprocessing.rst

@@ -1870,7 +1870,7 @@ handler type) for messages from different processes to get mixed up.
 Below is an example session with logging turned on::
 
     >>> import multiprocessing, logging
-    >>> logger = multiprocessing.getLogger()
+    >>> logger = multiprocessing.get_logger()
     >>> logger.setLevel(logging.INFO)
     >>> logger.warning('doomed')
     [WARNING/MainProcess] doomed

Doc/tools/sphinxext/download.html

@@ -14,7 +14,7 @@
 
 <p>To download an archive containing all the documents for this version of
 Python in one of various formats, follow one of links in this table. The numbers
-in the table are the size of the download files in Kilobytes.</p>
+in the table are the size of the download files in megabytes.</p>
 
 <table class="docutils">
   <tr><th>Format</th><th>Packed as .zip</th><th>Packed as .tar.bz2</th></tr>
@@ -54,7 +54,7 @@ platform. These are created on Unix using the InfoZIP zip program.</p>
 <h2>Problems</h2>
 
 <p>If you have comments or suggestions for the Python documentation, please send
-email to <a href="docs@python.org">docs@python.org</a>.</p>
+email to <a href="mailto:docs@python.org">docs@python.org</a>.</p>
 {% endif %}
 
 {% endblock %}

Lib/string.py

@@ -532,9 +532,8 @@ except ImportError:
 # the Formatter class
 # see PEP 3101 for details and purpose of this class
 
-# The hard parts are reused from the C implementation.  They're
+# The hard parts are reused from the C implementation.  They're exposed as "_"
-# exposed here via the sys module.  sys was chosen because it's always
+# prefixed methods of str and unicode.
-# available and doesn't have to be dynamically loaded.
 
 # The overall parser is implemented in str._formatter_parser.
 # The field name parser is implemented in str._formatter_field_name_split

Modules/posixmodule.c

@@ -2393,13 +2393,27 @@ posix__getfullpathname(PyObject *self, PyObject *args)
 	if (unicode_file_names()) {
 		PyUnicodeObject *po;
 		if (PyArg_ParseTuple(args, "U|:_getfullpathname", &po)) {
-			Py_UNICODE woutbuf[MAX_PATH*2];
+			Py_UNICODE *wpath = PyUnicode_AS_UNICODE(po);
+			Py_UNICODE woutbuf[MAX_PATH*2], *woutbufp = woutbuf;
 			Py_UNICODE *wtemp;
-			if (!GetFullPathNameW(PyUnicode_AS_UNICODE(po),
+			DWORD result;
-						sizeof(woutbuf)/sizeof(woutbuf[0]),
+			PyObject *v;
-						 woutbuf, &wtemp))
+			result = GetFullPathNameW(wpath,
-				return win32_error("GetFullPathName", "");
+						   sizeof(woutbuf)/sizeof(woutbuf[0]),
-			return PyUnicode_FromUnicode(woutbuf, wcslen(woutbuf));
+						    woutbuf, &wtemp);
+			if (result > sizeof(woutbuf)/sizeof(woutbuf[0])) {
+				woutbufp = malloc(result * sizeof(Py_UNICODE));
+				if (!woutbufp)
+					return PyErr_NoMemory();
+				result = GetFullPathNameW(wpath, result, woutbufp, &wtemp);
+			}
+			if (result)
+				v = PyUnicode_FromUnicode(woutbufp, wcslen(woutbufp));
+			else
+				v = win32_error_unicode("GetFullPathNameW", wpath);
+			if (woutbufp != woutbuf)
+				free(woutbufp);
+			return v;
 		}
 		/* Drop the argument parsing error as narrow strings
 		   are also valid. */