[Python-3000-checkins] r57114 - in python/branches/py3k/Doc: Makefile documenting/markup.rst library/aifc.rst library/codeop.rst library/fileinput.rst library/logging.rst library/marshal.rst library/mimetools.rst library/multifile.rst library/rfc822.rst library/shutil.rst library/stringprep.rst library/unicodedata.rst library/zipfile.rst reference/expressions.rst tools/sphinx-build.py
guido.van.rossum
python-3000-checkins at python.org
Fri Aug 17 02:24:55 CEST 2007
Author: guido.van.rossum
Date: Fri Aug 17 02:24:54 2007
New Revision: 57114
Modified:
python/branches/py3k/Doc/Makefile
python/branches/py3k/Doc/documenting/markup.rst
python/branches/py3k/Doc/library/aifc.rst
python/branches/py3k/Doc/library/codeop.rst
python/branches/py3k/Doc/library/fileinput.rst
python/branches/py3k/Doc/library/logging.rst
python/branches/py3k/Doc/library/marshal.rst
python/branches/py3k/Doc/library/mimetools.rst
python/branches/py3k/Doc/library/multifile.rst
python/branches/py3k/Doc/library/rfc822.rst
python/branches/py3k/Doc/library/shutil.rst
python/branches/py3k/Doc/library/stringprep.rst
python/branches/py3k/Doc/library/unicodedata.rst
python/branches/py3k/Doc/library/zipfile.rst
python/branches/py3k/Doc/reference/expressions.rst
python/branches/py3k/Doc/tools/sphinx-build.py
Log:
Manually patched a few things that didn't get merged in, but should.
Modified: python/branches/py3k/Doc/Makefile
==============================================================================
--- python/branches/py3k/Doc/Makefile (original)
+++ python/branches/py3k/Doc/Makefile Fri Aug 17 02:24:54 2007
@@ -4,9 +4,9 @@
#
# You can set these variables from the command line.
-PYTHON ?= python
-SVNROOT ?= http://svn.python.org/projects
-SPHINXOPTS ?=
+PYTHON = python
+SVNROOT = http://svn.python.org/projects
+SPHINXOPTS =
ALLSPHINXOPTS = -b$(BUILDER) -dbuild/doctrees $(SPHINXOPTS) . build/$(BUILDER)
@@ -55,7 +55,7 @@
htmlhelp: BUILDER = htmlhelp
htmlhelp: build
@echo "Build finished; now you can run HTML Help Workshop with the" \
- "build/hhp/pydoc.hhp project file."
+ "build/htmlhelp/pydoc.hhp project file."
clean:
-rm -rf build/*
Modified: python/branches/py3k/Doc/documenting/markup.rst
==============================================================================
--- python/branches/py3k/Doc/documenting/markup.rst (original)
+++ python/branches/py3k/Doc/documenting/markup.rst Fri Aug 17 02:24:54 2007
@@ -79,6 +79,9 @@
The ``synopsis`` option should consist of one sentence describing the
module's purpose -- it is currently only used in the Global Module Index.
+ The ``deprecated`` option can be given (with no value) to mark a module as
+ deprecated; it will be designated as such in various locations then.
+
.. describe:: moduleauthor
The ``moduleauthor`` directive, which can appear multiple times, names the
@@ -333,6 +336,13 @@
``:func:`foo.filter``` clearly refers to the ``filter`` function in the ``foo``
module.
+Normally, names in these roles are searched first without any further
+qualification, then with the current module name prepended, then with the
+current module and class name (if any) prepended. If you prefix the name with a
+dot, this order is reversed. For example, in the documentation of the
+:mod:`codecs` module, ``:func:`open``` always refers to the built-in function,
+while ``:func:`.open``` refers to :func:`codecs.open`.
+
A similar heuristic is used to determine whether the name is an attribute of
the currently documented class.
Modified: python/branches/py3k/Doc/library/aifc.rst
==============================================================================
--- python/branches/py3k/Doc/library/aifc.rst (original)
+++ python/branches/py3k/Doc/library/aifc.rst Fri Aug 17 02:24:54 2007
@@ -16,9 +16,10 @@
samples in a file. AIFF-C is a newer version of the format that includes the
ability to compress the audio data.
-**Caveat:** Some operations may only work under IRIX; these will raise
-:exc:`ImportError` when attempting to import the :mod:`cl` module, which is only
-available on IRIX.
+.. warning::
+
+ Some operations may only work under IRIX; these will raise :exc:`ImportError`
+ when attempting to import the :mod:`cl` module, which is only available on IRIX.
Audio files have a number of parameters that describe the audio data. The
sampling rate or frame rate is the number of times per second the sound is
Modified: python/branches/py3k/Doc/library/codeop.rst
==============================================================================
--- python/branches/py3k/Doc/library/codeop.rst (original)
+++ python/branches/py3k/Doc/library/codeop.rst Fri Aug 17 02:24:54 2007
@@ -46,11 +46,13 @@
(``'single'``, the default) or as an expression (``'eval'``). Any other value
will cause :exc:`ValueError` to be raised.
- **Caveat:** It is possible (but not likely) that the parser stops parsing with a
- successful outcome before reaching the end of the source; in this case, trailing
- symbols may be ignored instead of causing an error. For example, a backslash
- followed by two newlines may be followed by arbitrary garbage. This will be
- fixed once the API for the parser is better.
+ .. warning::
+
+ It is possible (but not likely) that the parser stops parsing with a
+ successful outcome before reaching the end of the source; in this case,
+ trailing symbols may be ignored instead of causing an error. For example,
+ a backslash followed by two newlines may be followed by arbitrary garbage.
+ This will be fixed once the API for the parser is better.
.. class:: Compile()
Modified: python/branches/py3k/Doc/library/fileinput.rst
==============================================================================
--- python/branches/py3k/Doc/library/fileinput.rst (original)
+++ python/branches/py3k/Doc/library/fileinput.rst Fri Aug 17 02:24:54 2007
@@ -149,10 +149,12 @@
it is deleted when the output file is closed. In-place filtering is disabled
when standard input is read.
-**Caveat:** The current implementation does not work for MS-DOS 8+3 filesystems.
+.. warning::
+
+ The current implementation does not work for MS-DOS 8+3 filesystems.
-The two following opening hooks are provided by this module:
+The two following opening hooks are provided by this module:
.. function:: hook_compressed(filename, mode)
Modified: python/branches/py3k/Doc/library/logging.rst
==============================================================================
--- python/branches/py3k/Doc/library/logging.rst (original)
+++ python/branches/py3k/Doc/library/logging.rst Fri Aug 17 02:24:54 2007
@@ -536,7 +536,7 @@
Finds the caller's source filename and line number. Returns the filename, line
number and function name as a 3-element tuple.
- .. versionchanged:: 2.5
+ .. versionchanged:: 2.4
The function name was added. In earlier versions, the filename and line number
were returned as a 2-element tuple..
Modified: python/branches/py3k/Doc/library/marshal.rst
==============================================================================
--- python/branches/py3k/Doc/library/marshal.rst (original)
+++ python/branches/py3k/Doc/library/marshal.rst Fri Aug 17 02:24:54 2007
@@ -42,14 +42,16 @@
themselves supported; and recursive lists and dictionaries should not be written
(they will cause infinite loops).
-**Caveat:** On machines where C's ``long int`` type has more than 32 bits (such
-as the DEC Alpha), it is possible to create plain Python integers that are
-longer than 32 bits. If such an integer is marshaled and read back in on a
-machine where C's ``long int`` type has only 32 bits, a Python long integer
-object is returned instead. While of a different type, the numeric value is the
-same. (This behavior is new in Python 2.2. In earlier versions, all but the
-least-significant 32 bits of the value were lost, and a warning message was
-printed.)
+.. warning::
+
+ On machines where C's ``long int`` type has more than 32 bits (such as the
+ DEC Alpha), it is possible to create plain Python integers that are longer
+ than 32 bits. If such an integer is marshaled and read back in on a machine
+ where C's ``long int`` type has only 32 bits, a Python long integer object
+ is returned instead. While of a different type, the numeric value is the
+ same. (This behavior is new in Python 2.2. In earlier versions, all but the
+ least-significant 32 bits of the value were lost, and a warning message was
+ printed.)
There are functions that read/write files as well as functions operating on
strings.
Modified: python/branches/py3k/Doc/library/mimetools.rst
==============================================================================
--- python/branches/py3k/Doc/library/mimetools.rst (original)
+++ python/branches/py3k/Doc/library/mimetools.rst Fri Aug 17 02:24:54 2007
@@ -4,6 +4,7 @@
.. module:: mimetools
:synopsis: Tools for parsing MIME-style message bodies.
+ :deprecated:
.. deprecated:: 2.3
Modified: python/branches/py3k/Doc/library/multifile.rst
==============================================================================
--- python/branches/py3k/Doc/library/multifile.rst (original)
+++ python/branches/py3k/Doc/library/multifile.rst Fri Aug 17 02:24:54 2007
@@ -4,6 +4,7 @@
.. module:: multifile
:synopsis: Support for reading files which contain distinct parts, such as some MIME data.
+ :deprecated:
.. sectionauthor:: Eric S. Raymond <esr at snark.thyrsus.com>
Modified: python/branches/py3k/Doc/library/rfc822.rst
==============================================================================
--- python/branches/py3k/Doc/library/rfc822.rst (original)
+++ python/branches/py3k/Doc/library/rfc822.rst Fri Aug 17 02:24:54 2007
@@ -4,6 +4,7 @@
.. module:: rfc822
:synopsis: Parse 2822 style mail messages.
+ :deprecated:
.. deprecated:: 2.3
Modified: python/branches/py3k/Doc/library/shutil.rst
==============================================================================
--- python/branches/py3k/Doc/library/shutil.rst (original)
+++ python/branches/py3k/Doc/library/shutil.rst Fri Aug 17 02:24:54 2007
@@ -17,9 +17,11 @@
collections of files. In particular, functions are provided which support file
copying and removal.
-**Caveat:** On MacOS, the resource fork and other metadata are not used. For
-file copies, this means that resources will be lost and file type and creator
-codes will not be correct.
+.. warning::
+
+ On MacOS, the resource fork and other metadata are not used. For file copies,
+ this means that resources will be lost and file type and creator codes will
+ not be correct.
.. function:: copyfile(src, dst)
Modified: python/branches/py3k/Doc/library/stringprep.rst
==============================================================================
--- python/branches/py3k/Doc/library/stringprep.rst (original)
+++ python/branches/py3k/Doc/library/stringprep.rst Fri Aug 17 02:24:54 2007
@@ -4,6 +4,7 @@
.. module:: stringprep
:synopsis: String preparation, as per RFC 3453
+ :deprecated:
.. moduleauthor:: Martin v. Löwis <martin at v.loewis.de>
.. sectionauthor:: Martin v. Löwis <martin at v.loewis.de>
Modified: python/branches/py3k/Doc/library/unicodedata.rst
==============================================================================
--- python/branches/py3k/Doc/library/unicodedata.rst (original)
+++ python/branches/py3k/Doc/library/unicodedata.rst Fri Aug 17 02:24:54 2007
@@ -107,7 +107,7 @@
based on the definition of canonical equivalence and compatibility equivalence.
In Unicode, several characters can be expressed in various way. For example, the
character U+00C7 (LATIN CAPITAL LETTER C WITH CEDILLA) can also be expressed as
- the sequence U+0043 (LATIN CAPITAL LETTER C) U+0327 (COMBINING CEDILLA).
+ the sequence U+0327 (COMBINING CEDILLA) U+0043 (LATIN CAPITAL LETTER C).
For each character, there are two normal forms: normal form C and normal form D.
Normal form D (NFD) is also known as canonical decomposition, and translates
@@ -126,6 +126,10 @@
(NFKC) first applies the compatibility decomposition, followed by the canonical
composition.
+ Even if two unicode strings are normalized and look the same to
+ a human reader, if one has combining characters and the other
+ doesn't, they may not compare equal.
+
.. versionadded:: 2.3
In addition, the module exposes the following constant:
Modified: python/branches/py3k/Doc/library/zipfile.rst
==============================================================================
--- python/branches/py3k/Doc/library/zipfile.rst (original)
+++ python/branches/py3k/Doc/library/zipfile.rst Fri Aug 17 02:24:54 2007
@@ -168,11 +168,11 @@
.. note::
If the ZipFile was created by passing in a file-like object as the first
- argument to the constructor, then the object returned by :meth:`open` shares the
+ argument to the constructor, then the object returned by :meth:`.open` shares the
ZipFile's file pointer. Under these circumstances, the object returned by
- :meth:`open` should not be used after any additional operations are performed
+ :meth:`.open` should not be used after any additional operations are performed
on the ZipFile object. If the ZipFile was created by passing in a string (the
- filename) as the first argument to the constructor, then :meth:`open` will
+ filename) as the first argument to the constructor, then :meth:`.open` will
create a new file object that will be held by the ZipExtFile, allowing it to
operate independently of the ZipFile.
Modified: python/branches/py3k/Doc/reference/expressions.rst
==============================================================================
--- python/branches/py3k/Doc/reference/expressions.rst (original)
+++ python/branches/py3k/Doc/reference/expressions.rst Fri Aug 17 02:24:54 2007
@@ -987,7 +987,7 @@
* Strings are compared lexicographically using the numeric equivalents (the
result of the built-in function :func:`ord`) of their characters. Unicode and
- 8-bit strings are fully interoperable in this behavior.
+ 8-bit strings are fully interoperable in this behavior. [#]_
* Tuples and lists are compared lexicographically using comparison of
corresponding elements. This means that to compare equal, each element must
@@ -1272,6 +1272,12 @@
cases, Python returns the latter result, in order to preserve that
``divmod(x,y)[0] * y + x % y`` be very close to ``x``.
+.. [#] While comparisons between unicode strings make sense at the byte
+ level, they may be counter-intuitive to users. For example, the
+ strings ``u"\u00C7"`` and ``u"\u0327\u0043"`` compare differently,
+ even though they both represent the same unicode character (LATIN
+ CAPTITAL LETTER C WITH CEDILLA).
+
.. [#] The implementation computes this efficiently, without constructing lists or
sorting.
Modified: python/branches/py3k/Doc/tools/sphinx-build.py
==============================================================================
--- python/branches/py3k/Doc/tools/sphinx-build.py (original)
+++ python/branches/py3k/Doc/tools/sphinx-build.py Fri Aug 17 02:24:54 2007
@@ -10,5 +10,14 @@
import sys
if __name__ == '__main__':
+
+ if sys.version_info[:3] < (2, 5, 0):
+ print >>sys.stderr, """\
+Error: Sphinx needs to be executed with Python 2.5 or newer.
+(If you run this from the Makefile, you can set the PYTHON variable
+to the path of an alternative interpreter executable.)
+"""
+ sys.exit(1)
+
from sphinx import main
sys.exit(main(sys.argv))
More information about the Python-3000-checkins
mailing list