Merged revisions 85450-85455,85460-85465 via svnmerge from
svn+ssh://svn.python.org/python/branches/py3k
........
r85450 | georg.brandl | 2010-10-14 08:35:53 +0200 (Do, 14 Okt 2010) | 1 line
#7642: update to os.system() docs.
........
r85451 | georg.brandl | 2010-10-14 08:41:42 +0200 (Do, 14 Okt 2010) | 1 line
#3865: add note about benchmarking with profilers, and move licensing stuff to bottom of document.
........
r85452 | georg.brandl | 2010-10-14 08:43:22 +0200 (Do, 14 Okt 2010) | 1 line
#10046: small correction to atexit docs.
........
r85453 | georg.brandl | 2010-10-14 08:46:08 +0200 (Do, 14 Okt 2010) | 1 line
#6825: small correction to split() docs.
........
r85454 | georg.brandl | 2010-10-14 08:48:47 +0200 (Do, 14 Okt 2010) | 1 line
Mention 2to3.
........
r85455 | georg.brandl | 2010-10-14 08:59:45 +0200 (Do, 14 Okt 2010) | 1 line
#1710703: write zipfile structures also in the case of closing a new, but empty, archive.
........
r85460 | georg.brandl | 2010-10-14 09:24:28 +0200 (Do, 14 Okt 2010) | 1 line
#9964: fix running test_import under -O or -OO.
........
r85461 | georg.brandl | 2010-10-14 09:29:08 +0200 (Do, 14 Okt 2010) | 1 line
#9964: fix lib2to3 fixer fix_operator when running under -OO.
........
r85462 | georg.brandl | 2010-10-14 09:32:52 +0200 (Do, 14 Okt 2010) | 1 line
#9964: fix running test_xml_etree under -OO.
........
r85463 | georg.brandl | 2010-10-14 09:34:56 +0200 (Do, 14 Okt 2010) | 1 line
Better check for "any optimize option given".
........
r85464 | georg.brandl | 2010-10-14 09:42:27 +0200 (Do, 14 Okt 2010) | 1 line
#9964: fix running test_compileall under -O and -OO.
........
r85465 | georg.brandl | 2010-10-14 10:08:56 +0200 (Do, 14 Okt 2010) | 1 line
#9964: fix running test_cmd_line_script under -O and -OO.
........
diff --git a/Doc/library/atexit.rst b/Doc/library/atexit.rst
index db90218..104c730 100644
--- a/Doc/library/atexit.rst
+++ b/Doc/library/atexit.rst
@@ -12,8 +12,8 @@
interpreter termination.
Note: the functions registered via this module are not called when the program
-is killed by a signal, when a Python fatal internal error is detected, or when
-:func:`os._exit` is called.
+is killed by a signal not handled by Python, when a Python fatal internal error
+is detected, or when :func:`os._exit` is called.
.. function:: register(func, *args, **kargs)
diff --git a/Doc/library/os.path.rst b/Doc/library/os.path.rst
index 3e60e9e..fdc45b9 100644
--- a/Doc/library/os.path.rst
+++ b/Doc/library/os.path.rst
@@ -258,14 +258,14 @@
.. function:: split(path)
- Split the pathname *path* into a pair, ``(head, tail)`` where *tail* is the last
- pathname component and *head* is everything leading up to that. The *tail* part
- will never contain a slash; if *path* ends in a slash, *tail* will be empty. If
- there is no slash in *path*, *head* will be empty. If *path* is empty, both
- *head* and *tail* are empty. Trailing slashes are stripped from *head* unless
- it is the root (one or more slashes only). In nearly all cases, ``join(head,
- tail)`` equals *path* (the only exception being when there were multiple slashes
- separating *head* from *tail*).
+ Split the pathname *path* into a pair, ``(head, tail)`` where *tail* is the
+ last pathname component and *head* is everything leading up to that. The
+ *tail* part will never contain a slash; if *path* ends in a slash, *tail*
+ will be empty. If there is no slash in *path*, *head* will be empty. If
+ *path* is empty, both *head* and *tail* are empty. Trailing slashes are
+ stripped from *head* unless it is the root (one or more slashes only). In
+ all cases, ``join(head, tail)`` returns a path to the same location as *path*
+ (but the strings may differ).
.. function:: splitdrive(path)
diff --git a/Doc/library/os.rst b/Doc/library/os.rst
index 9680d7a..371a902 100644
--- a/Doc/library/os.rst
+++ b/Doc/library/os.rst
@@ -1760,25 +1760,25 @@
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:`sys.stdin`, etc. are not reflected in the environment of the
- executed command.
+ Changes to :data:`sys.stdin`, etc. are not reflected in the environment of
+ the executed command. If *command* generates any output, it will be sent to
+ the interpreter standard output stream.
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
- of the return value of the C :cfunc:`system` function, so the return value of
- the Python function is system-dependent.
+ format specified for :func:`wait`. Note that POSIX does not specify the
+ meaning of the return value of the C :cfunc:`system` function, so the return
+ value of the Python function is system-dependent.
- On Windows, the return value is that returned by the system shell after running
- *command*, given by the Windows environment variable :envvar:`COMSPEC`: on
- :program:`command.com` systems (Windows 95, 98 and ME) this is always ``0``; on
- :program:`cmd.exe` systems (Windows NT, 2000 and XP) this is the exit status of
- the command run; on systems using a non-native shell, consult your shell
- documentation.
+ On Windows, the return value is that returned by the system shell after
+ running *command*. The shell is given by the Windows environment variable
+ :envvar:`COMSPEC`: it is usually :program:`cmd.exe`, which returns the exit
+ status of the command run; on systems using a non-native shell, consult your
+ shell documentation.
- The :mod:`subprocess` module provides more powerful facilities for spawning new
- processes and retrieving their results; using that module is preferable to using
- this function. Use the :mod:`subprocess` module. Check especially the
- :ref:`subprocess-replacements` section.
+ The :mod:`subprocess` module provides more powerful facilities for spawning
+ new processes and retrieving their results; using that module is preferable
+ to using this function. See the :ref:`subprocess-replacements` section in
+ the :mod:`subprocess` documentation for some helpful recipes.
Availability: Unix, Windows.
diff --git a/Doc/library/profile.rst b/Doc/library/profile.rst
index e66ceaf..c5e5dd5 100644
--- a/Doc/library/profile.rst
+++ b/Doc/library/profile.rst
@@ -10,29 +10,6 @@
.. module:: profile
:synopsis: Python source profiler.
-.. index:: single: InfoSeek Corporation
-
-Copyright © 1994, by InfoSeek Corporation, all rights reserved.
-
-Written by James Roskind. [#]_
-
-Permission to use, copy, modify, and distribute this Python software and its
-associated documentation for any purpose (subject to the restriction in the
-following sentence) without fee is hereby granted, provided that the above
-copyright notice appears in all copies, and that both that copyright notice and
-this permission notice appear in supporting documentation, and that the name of
-InfoSeek not be used in advertising or publicity pertaining to distribution of
-the software without specific, written prior permission. This permission is
-explicitly restricted to the copying and modification of the software to remain
-in Python, compiled Python, or other languages (such as C) wherein the modified
-or derived code is exclusively imported into a Python module.
-
-INFOSEEK CORPORATION DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
-INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT
-SHALL INFOSEEK CORPORATION BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL
-DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
-WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING
-OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.. _profiler-introduction:
@@ -43,33 +20,38 @@
single: deterministic profiling
single: profiling, deterministic
-A :dfn:`profiler` is a program that describes the run time performance
-of a program, providing a variety of statistics. This documentation
-describes the profiler functionality provided in the modules
-:mod:`cProfile`, :mod:`profile` and :mod:`pstats`. This profiler
-provides :dfn:`deterministic profiling` of Python programs. It also
-provides a series of report generation tools to allow users to rapidly
-examine the results of a profile operation.
+A :dfn:`profiler` is a program that describes the run time performance of a
+program, providing a variety of statistics. This documentation describes the
+profiler functionality provided in the modules :mod:`cProfile`, :mod:`profile`
+and :mod:`pstats`. This profiler provides :dfn:`deterministic profiling` of
+Python programs. It also provides a series of report generation tools to allow
+users to rapidly examine the results of a profile operation.
The Python standard library provides two different profilers:
-#. :mod:`cProfile` is recommended for most users; it's a C extension
- with reasonable overhead
- that makes it suitable for profiling long-running programs.
- Based on :mod:`lsprof`,
- contributed by Brett Rosen and Ted Czotter.
+1. :mod:`cProfile` is recommended for most users; it's a C extension with
+ reasonable overhead that makes it suitable for profiling long-running
+ programs. Based on :mod:`lsprof`, contributed by Brett Rosen and Ted
+ Czotter.
-#. :mod:`profile`, a pure Python module whose interface is imitated by
- :mod:`cProfile`. Adds significant overhead to profiled programs.
- If you're trying to extend
- the profiler in some way, the task might be easier with this module.
- Copyright © 1994, by InfoSeek Corporation.
+2. :mod:`profile`, a pure Python module whose interface is imitated by
+ :mod:`cProfile`. Adds significant overhead to profiled programs. If you're
+ trying to extend the profiler in some way, the task might be easier with this
+ module. Copyright © 1994, by InfoSeek Corporation.
The :mod:`profile` and :mod:`cProfile` modules export the same interface, so
they are mostly interchangeable; :mod:`cProfile` has a much lower overhead but
-is newer and might not be available on all systems.
-:mod:`cProfile` is really a compatibility layer on top of the internal
-:mod:`_lsprof` module.
+is newer and might not be available on all systems. :mod:`cProfile` is really a
+compatibility layer on top of the internal :mod:`_lsprof` module.
+
+.. note::
+
+ The profiler modules are designed to provide an execution profile for a given
+ program, not for benchmarking purposes (for that, there is :mod:`timeit` for
+ resonably accurate results). This particularly applies to benchmarking
+ Python code against C code: the profilers introduce overhead for Python code,
+ but not for C-level functions, and so the C code would seem faster than any
+ Python one.
.. _profile-instant:
@@ -608,8 +590,26 @@
best results with a custom timer, it might be necessary to hard-code it in the C
source of the internal :mod:`_lsprof` module.
-.. rubric:: Footnotes
-.. [#] Updated and converted to LaTeX by Guido van Rossum. Further updated by Armin
- Rigo to integrate the documentation for the new :mod:`cProfile` module of Python
- 2.5.
+Copyright and License Notices
+=============================
+
+Copyright © 1994, by InfoSeek Corporation, all rights reserved.
+
+Permission to use, copy, modify, and distribute this Python software and its
+associated documentation for any purpose (subject to the restriction in the
+following sentence) without fee is hereby granted, provided that the above
+copyright notice appears in all copies, and that both that copyright notice and
+this permission notice appear in supporting documentation, and that the name of
+InfoSeek not be used in advertising or publicity pertaining to distribution of
+the software without specific, written prior permission. This permission is
+explicitly restricted to the copying and modification of the software to remain
+in Python, compiled Python, or other languages (such as C) wherein the modified
+or derived code is exclusively imported into a Python module.
+
+INFOSEEK CORPORATION DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
+INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT
+SHALL INFOSEEK CORPORATION BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL
+DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
+WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING
+OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
diff --git a/Doc/library/zipfile.rst b/Doc/library/zipfile.rst
index 3ab78ab..5a168c0 100644
--- a/Doc/library/zipfile.rst
+++ b/Doc/library/zipfile.rst
@@ -120,6 +120,10 @@
because the default :program:`zip` and :program:`unzip` commands on Unix (the
InfoZIP utilities) don't support these extensions.
+ If the file is created with mode ``'a'`` or ``'w'`` and then
+ :meth:`close`\ d without adding any files to the archive, the appropriate
+ ZIP structures for an empty archive will be written to the file.
+
.. method:: ZipFile.close()