From d8654cf758c730af430026a5b20810bebceba4d7 Mon Sep 17 00:00:00 2001 From: Christian Heimes Date: Sun, 2 Dec 2007 15:22:16 +0000 Subject: Merged revisions 59259-59274 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r59260 | lars.gustaebel | 2007-12-01 22:02:12 +0100 (Sat, 01 Dec 2007) | 5 lines Issue #1531: Read fileobj from the current offset, do not seek to the start. (will backport to 2.5) ........ r59262 | georg.brandl | 2007-12-01 23:24:47 +0100 (Sat, 01 Dec 2007) | 4 lines Document PyEval_* functions from ceval.c. Credits to Michael Sloan from GHOP. ........ r59263 | georg.brandl | 2007-12-01 23:27:56 +0100 (Sat, 01 Dec 2007) | 2 lines Add a few refcount data entries. ........ r59264 | georg.brandl | 2007-12-01 23:38:48 +0100 (Sat, 01 Dec 2007) | 4 lines Add test suite for cmd module. Written by Michael Schneider for GHOP. ........ r59265 | georg.brandl | 2007-12-01 23:42:46 +0100 (Sat, 01 Dec 2007) | 3 lines Add examples to the ElementTree documentation. Written by h4wk.cz for GHOP. ........ r59266 | georg.brandl | 2007-12-02 00:12:45 +0100 (Sun, 02 Dec 2007) | 3 lines Add "Using Python on Windows" document, by Robert Lehmann. Written for GHOP. ........ r59271 | georg.brandl | 2007-12-02 15:34:34 +0100 (Sun, 02 Dec 2007) | 3 lines Add example to mmap docs. Written for GHOP by Rafal Rawicki. ........ r59272 | georg.brandl | 2007-12-02 15:37:29 +0100 (Sun, 02 Dec 2007) | 2 lines Convert bdb.rst line endings to Unix style. ........ r59274 | georg.brandl | 2007-12-02 15:58:50 +0100 (Sun, 02 Dec 2007) | 4 lines Add more entries to the glossary. Written by Jeff Wheeler for GHOP. ........ --- Doc/ACKS.txt | 2 + Doc/Makefile | 4 + Doc/README.txt | 3 + Doc/c-api/init.rst | 48 +++ Doc/c-api/utilities.rst | 49 +++ Doc/c-api/veryhigh.rst | 37 ++ Doc/data/refcounts.dat | 5 + Doc/distutils/extending.rst | 2 +- Doc/extending/extending.rst | 23 +- Doc/glossary.rst | 94 ++++- Doc/library/atexit.rst | 2 +- Doc/library/bdb.rst | 674 +++++++++++++++++----------------- Doc/library/codeop.rst | 4 +- Doc/library/contextlib.rst | 6 +- Doc/library/doctest.rst | 3 +- Doc/library/functions.rst | 12 +- Doc/library/functools.rst | 6 +- Doc/library/inspect.rst | 2 +- Doc/library/mmap.rst | 43 +++ Doc/library/operator.rst | 8 +- Doc/library/stdtypes.rst | 4 +- Doc/library/sys.rst | 24 +- Doc/library/timeit.rst | 11 +- Doc/library/weakref.rst | 32 +- Doc/library/windows.rst | 1 + Doc/library/xml.etree.elementtree.rst | 68 ++++ Doc/reference/compound_stmts.rst | 2 +- Doc/tutorial/stdlib2.rst | 4 +- Doc/using/cmdline.rst | 34 +- Doc/using/index.rst | 1 + Doc/using/windows.rst | 316 ++++++++++++++++ Lib/tarfile.py | 3 +- Lib/test/test_cmd.py | 186 ++++++++++ Lib/test/test_tarfile.py | 32 ++ Misc/ACKS | 1 + 35 files changed, 1314 insertions(+), 432 deletions(-) create mode 100644 Doc/using/windows.rst create mode 100644 Lib/test/test_cmd.py diff --git a/Doc/ACKS.txt b/Doc/ACKS.txt index 52aa794..56c5c3e 100644 --- a/Doc/ACKS.txt +++ b/Doc/ACKS.txt @@ -163,6 +163,7 @@ docs@python.org), and we'll be glad to correct the problem. * Justin Sheehy * Michael Simcich * Ionel Simionescu +* Michael Sloan * Gregory P. Smith * Roy Smith * Clay Spence @@ -185,6 +186,7 @@ docs@python.org), and we'll be glad to correct the problem. * Glyn Webster * Bob Weiner * Eddy Welbourne +* Jeff Wheeler * Mats Wichmann * Gerry Wiener * Timothy Wild diff --git a/Doc/Makefile b/Doc/Makefile index 917b8c8..84a297a 100644 --- a/Doc/Makefile +++ b/Doc/Makefile @@ -57,6 +57,10 @@ htmlhelp: build @echo "Build finished; now you can run HTML Help Workshop with the" \ "build/htmlhelp/pydoc.hhp project file." +latex: BUILDER = latex +latex: build + @echo "Build finished; the LaTeX files are in build/latex." + clean: -rm -rf build/* -rm -rf tools/sphinx diff --git a/Doc/README.txt b/Doc/README.txt index 6d979f4..9db4f4c 100644 --- a/Doc/README.txt +++ b/Doc/README.txt @@ -53,6 +53,9 @@ Available make targets are: To create the CHM file, you need to run the Microsoft HTML Help Workshop over the generated project (.hhp) file. + * "latex", which builds LaTeX source files that can be run with "pdflatex" + to produce PDF documents. + A "make update" updates the Subversion checkouts in `tools/`. diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst index 3467ed7..11cd551 100644 --- a/Doc/c-api/init.rst +++ b/Doc/c-api/init.rst @@ -615,6 +615,14 @@ supports the creation of additional interpreters (using deadlock ensues. (This function is available even when thread support is disabled at compile time.) + +.. cfunction:: void PyEval_ReInitThreads() + + This function is called from :cfunc:`PyOS_AfterFork` to ensure that newly + created child processes don't hold locks referring to threads which + are not running in the child process. + + The following macros are normally used without a trailing semicolon; look for example usage in the Python source distribution. @@ -876,6 +884,46 @@ in previous versions. :cfunc:`PyEval_SetProfile`, except the tracing function does receive line-number events. +.. cfunction:: PyObject* PyEval_GetCallStats(PyObject *self) + + Return a tuple of function call counts. There are constants defined for the + positions within the tuple: + + +-------------------------------+-------+ + | Name | Value | + +===============================+=======+ + | :const:`PCALL_ALL` | 0 | + +-------------------------------+-------+ + | :const:`PCALL_FUNCTION` | 1 | + +-------------------------------+-------+ + | :const:`PCALL_FAST_FUNCTION` | 2 | + +-------------------------------+-------+ + | :const:`PCALL_FASTER_FUNCTION`| 3 | + +-------------------------------+-------+ + | :const:`PCALL_METHOD` | 4 | + +-------------------------------+-------+ + | :const:`PCALL_BOUND_METHOD` | 5 | + +-------------------------------+-------+ + | :const:`PCALL_CFUNCTION` | 6 | + +-------------------------------+-------+ + | :const:`PCALL_TYPE` | 7 | + +-------------------------------+-------+ + | :const:`PCALL_GENERATOR` | 8 | + +-------------------------------+-------+ + | :const:`PCALL_OTHER` | 9 | + +-------------------------------+-------+ + | :const:`PCALL_POP` | 10 | + +-------------------------------+-------+ + + :const:`PCALL_FAST_FUNCTION` means no argument tuple needs to be created. + :const:`PCALL_FASTER_FUNCTION` means that the fast-path frame setup code is used. + + If there is a method call where the call can be optimized by changing + the argument tuple and calling the function directly, it gets recorded + twice. + + This function is only present if Python is compiled with :const:`CALL_PROFILE` + defined. .. _advanced-debugging: diff --git a/Doc/c-api/utilities.rst b/Doc/c-api/utilities.rst index 35bfe86..0dfb946 100644 --- a/Doc/c-api/utilities.rst +++ b/Doc/c-api/utilities.rst @@ -989,3 +989,52 @@ The following functions provide locale-independent string to number conversions. See the Unix man page :manpage:`atof(2)` for details. + +.. _reflection: + +Reflection +========== + +.. cfunction:: PyObject* PyEval_GetBuiltins() + + Return a dictionary of the builtins in the current execution frame, + or the interpreter of the thread state if no frame is currently executing. + + +.. cfunction:: PyObject* PyEval_GetLocals() + + Return a dictionary of the local variables in the current execution frame, + or *NULL* if no frame is currently executing. + + +.. cfunction:: PyObject* PyEval_GetGlobals() + + Return a dictionary of the global variables in the current execution frame, + or *NULL* if no frame is currently executing. + + +.. cfunction:: PyFrameObject* PyEval_GetFrame() + + Return the current thread state's frame, which is *NULL* if no frame is + currently executing. + + +.. cfunction:: int PyEval_GetRestricted() + + If there is a current frame and it is executing in restricted mode, return true, + otherwise false. + + +.. cfunction:: const char* PyEval_GetFuncName(PyObject *func) + + Return the name of *func* if it is a function, class or instance object, else the + name of *func*\s type. + + +.. cfunction:: const char* PyEval_GetFuncDesc(PyObject *func) + + Return a description string, depending on the type of *func*. + Return values include "()" for functions and methods, " constructor", + " instance", and " object". Concatenated with the result of + :cfunc:`PyEval_GetFuncName`, the result will be a description of + *func*. diff --git a/Doc/c-api/veryhigh.rst b/Doc/c-api/veryhigh.rst index 4b26da6..6a3f91d 100644 --- a/Doc/c-api/veryhigh.rst +++ b/Doc/c-api/veryhigh.rst @@ -229,6 +229,43 @@ the same library that the Python runtime is using. be parsed or compiled. +.. cfunction:: PyObject* PyEval_EvalCode(PyCodeObject *co, PyObject *globals, PyObject *locals) + + This is a simplified interface to :cfunc:`PyEval_EvalCodeEx`, with just + the code object, and the dictionaries of global and local variables. + The other arguments are set to *NULL*. + + +.. cfunction:: PyObject* PyEval_EvalCodeEx(PyCodeObject *co, PyObject *globals, PyObject *locals, PyObject **args, int argcount, PyObject **kws, int kwcount, PyObject **defs, int defcount, PyObject *closure) + + Evaluate a precompiled code object, given a particular environment for its + evaluation. This environment consists of dictionaries of global and local + variables, arrays of arguments, keywords and defaults, and a closure tuple of + cells. + + +.. cfunction:: PyObject* PyEval_EvalFrame(PyFrameObject *f) + + Evaluate an execution frame. This is a simplified interface to + PyEval_EvalFrameEx, for backward compatibility. + + +.. cfunction:: PyObject* PyEval_EvalFrameEx(PyFrameObject *f, int throwflag) + + This is the main, unvarnished function of Python interpretation. It is + literally 2000 lines long. The code object associated with the execution + frame *f* is executed, interpreting bytecode and executing calls as needed. + The additional *throwflag* parameter can mostly be ignored - if true, then + it causes an exception to immediately be thrown; this is used for the + :meth:`throw` methods of generator objects. + + +.. cfunction:: int PyEval_MergeCompilerFlags(PyCompilerFlags *cf) + + This function changes the flags of the current evaluation frame, and returns + true on success, false on failure. + + .. cvar:: int Py_eval_input .. index:: single: Py_CompileString() diff --git a/Doc/data/refcounts.dat b/Doc/data/refcounts.dat index 5c3fc99..a17a701 100644 --- a/Doc/data/refcounts.dat +++ b/Doc/data/refcounts.dat @@ -309,6 +309,11 @@ PyEval_AcquireLock:void::: PyEval_AcquireThread:void::: PyEval_AcquireThread:PyThreadState*:tstate:: +PyEval_GetBuiltins:PyObject*::0: +PyEval_GetLocals:PyObject*::0: +PyEval_GetGlobals:PyObject*::0: +PyEval_GetFrame:PyObject*::0: + PyEval_InitThreads:void::: PyEval_ReleaseLock:void::: diff --git a/Doc/distutils/extending.rst b/Doc/distutils/extending.rst index a2930c7..972ff02 100644 --- a/Doc/distutils/extending.rst +++ b/Doc/distutils/extending.rst @@ -1,4 +1,4 @@ -.. _extending: +.. _extending-distutils: ******************* Extending Distutils diff --git a/Doc/extending/extending.rst b/Doc/extending/extending.rst index 74d3f28..e9a3aaa 100644 --- a/Doc/extending/extending.rst +++ b/Doc/extending/extending.rst @@ -466,10 +466,10 @@ Later, when it is time to call the function, you call the C function :cfunc:`PyEval_CallObject`. This function has two arguments, both pointers to arbitrary Python objects: the Python function, and the argument list. The argument list must always be a tuple object, whose length is the number of -arguments. To call the Python function with no arguments, pass an empty tuple; -to call it with one argument, pass a singleton tuple. :cfunc:`Py_BuildValue` -returns a tuple when its format string consists of zero or more format codes -between parentheses. For example:: +arguments. To call the Python function with no arguments, pass in NULL, or +an empty tuple; to call it with one argument, pass a singleton tuple. +:cfunc:`Py_BuildValue` returns a tuple when its format string consists of zero +or more format codes between parentheses. For example:: int arg; PyObject *arglist; @@ -527,9 +527,22 @@ event code, you might use the following code:: Py_DECREF(result); Note the placement of ``Py_DECREF(arglist)`` immediately after the call, before -the error check! Also note that strictly spoken this code is not complete: +the error check! Also note that strictly speaking this code is not complete: :cfunc:`Py_BuildValue` may run out of memory, and this should be checked. +You may also call a function with keyword arguments by using +:cfunc:`PyEval_CallObjectWithKeywords`. As in the above example, we use +:cfunc:`Py_BuildValue` to construct the dictionary. :: + + PyObject *dict; + ... + dict = Py_BuildValue("{s:i}", "name", val); + result = PyEval_CallObjectWithKeywords(my_callback, NULL, dict); + Py_DECREF(dict); + if (result == NULL) + return NULL; /* Pass error back */ + /* Here maybe use the result */ + Py_DECREF(result); .. _parsetuple: diff --git a/Doc/glossary.rst b/Doc/glossary.rst index cb75f84..8c5cbcd 100644 --- a/Doc/glossary.rst +++ b/Doc/glossary.rst @@ -15,6 +15,17 @@ Glossary ``...`` The typical Python prompt of the interactive shell when entering code for an indented code block. + + argument + A value passed to a function or method, assigned to a name local to + the body. A function or method may have both positional arguments and + keyword arguments in its definition. Positional and keyword arguments + may be variable-length: ``*`` accepts or passes (if in the function + definition or call) several positional arguments in a list, while ``**`` + does the same for keyword arguments in a dictionary. + + Any expression may be used within the argument list, and the evaluated + value is passed to the local variable. BDFL Benevolent Dictator For Life, a.k.a. `Guido van Rossum @@ -44,6 +55,22 @@ Glossary advanced mathematical feature. If you're not aware of a need for them, it's almost certain you can safely ignore them. + decorator + A function returning another function, usually applied as a function + transformation using the ``@wrapper`` syntax. Common examples for + decorators are :func:`classmethod` and :func:`staticmethod`. + + The decorator syntax is merely syntactic sugar, the following two + function definitions are semantically equivalent:: + + def f(...): + ... + f = staticmethod(f) + + @staticmethod + def f(...): + ... + descriptor An object that defines the methods :meth:`__get__`, :meth:`__set__`, or :meth:`__delete__`. When a class attribute is a descriptor, its special @@ -81,10 +108,24 @@ Glossary statements. The technique contrasts with the :term:`LBYL` style that is common in many other languages such as C. + expression + A piece of syntax which can be evaluated to some value. In other words, + an expression is an accumulation of expression elements like literals, names, + attribute access, operators or function calls that all return a value. + In contrast to other languages, not all language constructs are expressions, + but there are also :term:`statement`\s that cannot be used as expressions, + such as :keyword:`print` or :keyword:`if`. Assignments are also not + expressions. + extension module A module written in C, using Python's C API to interact with the core and with user code. - + + function + A series of statements which returns some value to a caller. It can also + be passed zero or more arguments which may be used in the execution of + the body. See also :term:`argument` and :term:`method`. + __future__ A pseudo module which programmers can use to enable new language features which are not compatible with the current interpreter. For example, the @@ -228,6 +269,17 @@ Glossary More information can be found in :ref:`typeiter`. + keyword argument + Arguments which are preceded with a ``variable_name=`` in the call. + The variable name designates the local name in the function to which the + value is assigned. ``**`` is used to accept or pass a dictionary of + keyword arguments. See :term:`argument`. + + lambda + An anonymous inline function consisting of a single :term:`expression` + which is evaluated when the function is called. The syntax to create + a lambda function is ``lambda [arguments]: expression`` + LBYL Look before you leap. This coding style explicitly tests for pre-conditions before making calls or lookups. This style contrasts with @@ -258,6 +310,12 @@ Glossary singletons, and many other tasks. More information can be found in :ref:`metaclasses`. + + method + A function that is defined inside a class body. If called as an attribute + of an instance of that class, the method will get the instance object as + its first :term:`argument` (which is usually called ``self``). + See :term:`function` and :term:`nested scope`. mutable Mutable objects can change their value but keep their :func:`id`. See @@ -291,10 +349,32 @@ Glossary More information can be found in :ref:`newstyle`. + positional argument + The arguments assigned to local names inside a function or method, + determined by the order in which they were given in the call. ``*`` is + used to either accept multiple positional arguments (when in the + definition), or pass several arguments as a list to a function. See + :term:`argument`. + Python 3000 Nickname for the next major Python version, 3.0 (coined long ago when the release of version 3 was something in the distant future.) + Pythonic + An idea or piece of code which closely follows the most common idioms of + the Python language, rather than implementing code using concepts common + in other languages. For example, a common idiom in Python is the :keyword:`for` + loop structure; other languages don't have this easy keyword, so people + use a numerical counter instead:: + + for i in range(len(food)): + print food[i] + + As opposed to the cleaner, Pythonic method:: + + for piece in food: + print piece + reference count The number of places where a certain object is referenced to. When the reference count drops to zero, an object is deallocated. While reference @@ -317,6 +397,18 @@ Glossary mapping rather than a sequence because the lookups use arbitrary :term:`immutable` keys rather than integers. + slice + A list containing a portion of an indexed list-like object. A slice is + created using the subscript notation, ``[]`` with colons between numbers + when several are given, such as in ``variable_name[1:3:5]``. The bracket + (subscript) notation uses :class:`slice` objects internally (or in older + versions, :meth:`__getslice__` and :meth:`__setslice__`). + + statement + A statement is part of a suite (a "block" of code). A statement is either + an :term:`expression` or a one of several constructs with a keyword, such + as :keyword:`if`, :keyword:`while` or :keyword:`print`. + type The type of a Python object determines what kind of object it is; every object has a type. An object's type is accessible as its diff --git a/Doc/library/atexit.rst b/Doc/library/atexit.rst index f6c76de..abef2fe 100644 --- a/Doc/library/atexit.rst +++ b/Doc/library/atexit.rst @@ -88,7 +88,7 @@ passed along to the registered function when it is called:: # or: atexit.register(goodbye, adjective='nice', name='Donny') -Usage as a decorator:: +Usage as a :term:`decorator`:: import atexit diff --git a/Doc/library/bdb.rst b/Doc/library/bdb.rst index da5357b..a8a61f1 100644 --- a/Doc/library/bdb.rst +++ b/Doc/library/bdb.rst @@ -1,337 +1,337 @@ -:mod:`bdb` --- Debugger framework -================================= - -.. module:: bdb - :synopsis: Debugger framework. - -The :mod:`bdb` module handles basic debugger functions, like setting breakpoints -or managing execution via the debugger. - -The following exception is defined: - -.. exception:: BdbQuit - - Exception raised by the :class:`Bdb` class for quitting the debugger. - - -The :mod:`bdb` module also defines two classes: - -.. class:: Breakpoint(self, file, line[, temporary=0[, cond=None [, funcname=None]]]) - - This class implements temporary breakpoints, ignore counts, disabling and - (re-)enabling, and conditionals. - - Breakpoints are indexed by number through a list called :attr:`bpbynumber` - and by ``(file, line)`` pairs through :attr:`bplist`. The former points to a - single instance of class :class:`Breakpoint`. The latter points to a list of - such instances since there may be more than one breakpoint per line. - - When creating a breakpoint, its associated filename should be in canonical - form. If a *funcname* is defined, a breakpoint hit will be counted when the - first line of that function is executed. A conditional breakpoint always - counts a hit. - -:class:`Breakpoint` instances have the following methods: - -.. method:: Breakpoint.deleteMe() - - Delete the breakpoint from the list associated to a file/line. If it is the - last breakpoint in that position, it also deletes the entry for the - file/line. - -.. method:: Breakpoint.enable() - - Mark the breakpoint as enabled. - -.. method:: Breakpoint.disable() - - Mark the breakpoint as disabled. - -.. method:: Breakpoint.bpprint([out]) - - Print all the information about the breakpoint: - - * The breakpoint number. - * If it is temporary or not. - * Its file,line position. - * The condition that causes a break. - * If it must be ignored the next N times. - * The breakpoint hit count. - - -.. class:: Bdb() - - The :class:`Bdb` acts as a generic Python debugger base class. - - This class takes care of the details of the trace facility; a derived class - should implement user interaction. The standard debugger class - (:class:`pdb.Pdb`) is an example. - - -The following methods of :class:`Bdb` normally don't need to be overridden. - -.. method:: Bdb.canonic(filename) - - Auxiliary method for getting a filename in a canonical form, that is, as a - case-normalized (on case-insensitive filesystems) absolute path, stripped - of surrounding angle brackets. - -.. method:: Bdb.reset() - - Set the :attr:`botframe`, :attr:`stopframe`, :attr:`returnframe` and - :attr:`quitting` attributes with values ready to start debugging. - - -.. method:: Bdb.trace_dispatch(frame, event, arg) - - This function is installed as the trace function of debugged frames. Its - return value is the new trace function (in most cases, that is, itself). - - The default implementation decides how to dispatch a frame, depending on the - type of event (passed as a string) that is about to be executed. *event* can - be one of the following: - - * ``"line"``: A new line of code is going to be executed. - * ``"call"``: A function is about to be called, or another code block - entered. - * ``"return"``: A function or other code block is about to return. - * ``"exception"``: An exception has occurred. - * ``"c_call"``: A C function is about to be called. - * ``"c_return"``: A C function has returned. - * ``"c_exception"``: A C function has thrown an exception. - - For the Python events, specialized functions (see below) are called. For the - C events, no action is taken. - - The *arg* parameter depends on the previous event. - - For more information on trace functions, see :ref:`debugger-hooks`. For more - information on code and frame objects, refer to :ref:`types`. - -.. method:: Bdb.dispatch_line(frame) - - If the debugger should stop on the current line, invoke the :meth:`user_line` - method (which should be overridden in subclasses). Raise a :exc:`BdbQuit` - exception if the :attr:`Bdb.quitting` flag is set (which can be set from - :meth:`user_line`). Return a reference to the :meth:`trace_dispatch` method - for further tracing in that scope. - -.. method:: Bdb.dispatch_call(frame, arg) - - If the debugger should stop on this function call, invoke the - :meth:`user_call` method (which should be overridden in subclasses). Raise a - :exc:`BdbQuit` exception if the :attr:`Bdb.quitting` flag is set (which can - be set from :meth:`user_call`). Return a reference to the - :meth:`trace_dispatch` method for further tracing in that scope. - -.. method:: Bdb.dispatch_return(frame, arg) - - If the debugger should stop on this function return, invoke the - :meth:`user_return` method (which should be overridden in subclasses). Raise - a :exc:`BdbQuit` exception if the :attr:`Bdb.quitting` flag is set (which can - be set from :meth:`user_return`). Return a reference to the - :meth:`trace_dispatch` method for further tracing in that scope. - -.. method:: Bdb.dispatch_exception(frame, arg) - - If the debugger should stop at this exception, invokes the - :meth:`user_exception` method (which should be overridden in subclasses). - Raise a :exc:`BdbQuit` exception if the :attr:`Bdb.quitting` flag is set - (which can be set from :meth:`user_exception`). Return a reference to the - :meth:`trace_dispatch` method for further tracing in that scope. - -Normally derived classes don't override the following methods, but they may if -they want to redefine the definition of stopping and breakpoints. - -.. method:: Bdb.stop_here(frame) - - This method checks if the *frame* is somewhere below :attr:`botframe` in the - call stack. :attr:`botframe` is the frame in which debugging started. - -.. method:: Bdb.break_here(frame) - - This method checks if there is a breakpoint in the filename and line - belonging to *frame* or, at least, in the current function. If the - breakpoint is a temporary one, this method deletes it. - -.. method:: Bdb.break_anywhere(frame) - - This method checks if there is a breakpoint in the filename of the current - frame. - -Derived classes should override these methods to gain control over debugger -operation. - -.. method:: Bdb.user_call(frame, argument_list) - - This method is called from :meth:`dispatch_call` when there is the - possibility that a break might be necessary anywhere inside the called - function. - -.. method:: Bdb.user_line(frame) - - This method is called from :meth:`dispatch_line` when either - :meth:`stop_here` or :meth:`break_here` yields True. - -.. method:: Bdb.user_return(frame, return_value) - - This method is called from :meth:`dispatch_return` when :meth:`stop_here` - yields True. - -.. method:: Bdb.user_exception(frame, exc_info) - - This method is called from :meth:`dispatch_exception` when :meth:`stop_here` - yields True. - -.. method:: Bdb.do_clear(arg) - - Handle how a breakpoint must be removed when it is a temporary one. - - This method must be implemented by derived classes. - - -Derived classes and clients can call the following methods to affect the -stepping state. - -.. method:: Bdb.set_step() - - Stop after one line of code. - -.. method:: Bdb.set_next(frame) - - Stop on the next line in or below the given frame. - -.. method:: Bdb.set_return(frame) - - Stop when returning from the given frame. - -.. method:: Bdb.set_trace([frame]) - - Start debugging from *frame*. If *frame* is not specified, debugging starts - from caller's frame. - -.. method:: Bdb.set_continue() - - Stop only at breakpoints or when finished. If there are no breakpoints, set - the system trace function to None. - -.. method:: Bdb.set_quit() - - Set the :attr:`quitting` attribute to True. This raises :exc:`BdbQuit` in - the next call to one of the :meth:`dispatch_\*` methods. - - -Derived classes and clients can call the following methods to manipulate -breakpoints. These methods return a string containing an error message if -something went wrong, or ``None`` if all is well. - -.. method:: Bdb.set_break(filename, lineno[, temporary=0[, cond[, funcname]]]) - - Set a new breakpoint. If the *lineno* line doesn't exist for the *filename* - passed as argument, return an error message. The *filename* should be in - canonical form, as described in the :meth:`canonic` method. - -.. method:: Bdb.clear_break(filename, lineno) - - Delete the breakpoints in *filename* and *lineno*. If none were set, an - error message is returned. - -.. method:: Bdb.clear_bpbynumber(arg) - - Delete the breakpoint which has the index *arg* in the - :attr:`Breakpoint.bpbynumber`. If `arg` is not numeric or out of range, - return an error message. - -.. method:: Bdb.clear_all_file_breaks(filename) - - Delete all breakpoints in *filename*. If none were set, an error message is - returned. - -.. method:: Bdb.clear_all_breaks() - - Delete all existing breakpoints. - -.. method:: Bdb.get_break(filename, lineno) - - Check if there is a breakpoint for *lineno* of *filename*. - -.. method:: Bdb.get_breaks(filename, lineno) - - Return all breakpoints for *lineno* in *filename*, or an empty list if none - are set. - -.. method:: Bdb.get_file_breaks(filename) - - Return all breakpoints in *filename*, or an empty list if none are set. - -.. method:: Bdb.get_all_breaks() - - Return all breakpoints that are set. - - -Derived classes and clients can call the following methods to get a data -structure representing a stack trace. - -.. method:: Bdb.get_stack(f, t) - - Get a list of records for a frame and all higher (calling) and lower frames, - and the size of the higher part. - -.. method:: Bdb.format_stack_entry(frame_lineno, [lprefix=': ']) - - Return a string with information about a stack entry, identified by a - ``(frame, lineno)`` tuple: - - * The canonical form of the filename which contains the frame. - * The function name, or ``""``. - * The input arguments. - * The return value. - * The line of code (if it exists). - - -The following two methods can be called by clients to use a debugger to debug a -statement, given as a string. - -.. method:: Bdb.run(cmd, [globals, [locals]]) - - Debug a statement executed via the :func:`exec` function. *globals* - defaults to :attr:`__main__.__dict__`, *locals* defaults to *globals*. - -.. method:: Bdb.runeval(expr, [globals, [locals]]) - - Debug an expression executed via the :func:`eval` function. *globals* and - *locals* have the same meaning as in :meth:`run`. - -.. method:: Bdb.runctx(cmd, globals, locals) - - For backwards compatibility. Calls the :meth:`run` method. - -.. method:: Bdb.runcall(func, *args, **kwds) - - Debug a single function call, and return its result. - - -Finally, the module defines the following functions: - -.. function:: checkfuncname(b, frame) - - Check whether we should break here, depending on the way the breakpoint *b* - was set. - - If it was set via line number, it checks if ``b.line`` is the same as the one - in the frame also passed as argument. If the breakpoint was set via function - name, we have to check we are in the right frame (the right function) and if - we are in its first executable line. - -.. function:: effective(file, line, frame) - - Determine if there is an effective (active) breakpoint at this line of code. - Return breakpoint number or 0 if none. - - Called only if we know there is a breakpoint at this location. Returns the - breakpoint that was triggered and a flag that indicates if it is ok to delete - a temporary breakpoint. - -.. function:: set_trace() - - Starts debugging with a :class:`Bdb` instance from caller's frame. +:mod:`bdb` --- Debugger framework +================================= + +.. module:: bdb + :synopsis: Debugger framework. + +The :mod:`bdb` module handles basic debugger functions, like setting breakpoints +or managing execution via the debugger. + +The following exception is defined: + +.. exception:: BdbQuit + + Exception raised by the :class:`Bdb` class for quitting the debugger. + + +The :mod:`bdb` module also defines two classes: + +.. class:: Breakpoint(self, file, line[, temporary=0[, cond=None [, funcname=None]]]) + + This class implements temporary breakpoints, ignore counts, disabling and + (re-)enabling, and conditionals. + + Breakpoints are indexed by number through a list called :attr:`bpbynumber` + and by ``(file, line)`` pairs through :attr:`bplist`. The former points to a + single instance of class :class:`Breakpoint`. The latter points to a list of + such instances since there may be more than one breakpoint per line. + + When creating a breakpoint, its associated filename should be in canonical + form. If a *funcname* is defined, a breakpoint hit will be counted when the + first line of that function is executed. A conditional breakpoint always + counts a hit. + +:class:`Breakpoint` instances have the following methods: + +.. method:: Breakpoint.deleteMe() + + Delete the breakpoint from the list associated to a file/line. If it is the + last breakpoint in that position, it also deletes the entry for the + file/line. + +.. method:: Breakpoint.enable() + + Mark the breakpoint as enabled. + +.. method:: Breakpoint.disable() + + Mark the breakpoint as disabled. + +.. method:: Breakpoint.bpprint([out]) + + Print all the information about the breakpoint: + + * The breakpoint number. + * If it is temporary or not. + * Its file,line position. + * The condition that causes a break. + * If it must be ignored the next N times. + * The breakpoint hit count. + + +.. class:: Bdb() + + The :class:`Bdb` acts as a generic Python debugger base class. + + This class takes care of the details of the trace facility; a derived class + should implement user interaction. The standard debugger class + (:class:`pdb.Pdb`) is an example. + + +The following methods of :class:`Bdb` normally don't need to be overridden. + +.. method:: Bdb.canonic(filename) + + Auxiliary method for getting a filename in a canonical form, that is, as a + case-normalized (on case-insensitive filesystems) absolute path, stripped + of surrounding angle brackets. + +.. method:: Bdb.reset() + + Set the :attr:`botframe`, :attr:`stopframe`, :attr:`returnframe` and + :attr:`quitting` attributes with values ready to start debugging. + + +.. method:: Bdb.trace_dispatch(frame, event, arg) + + This function is installed as the trace function of debugged frames. Its + return value is the new trace function (in most cases, that is, itself). + + The default implementation decides how to dispatch a frame, depending on the + type of event (passed as a string) that is about to be executed. *event* can + be one of the following: + + * ``"line"``: A new line of code is going to be executed. + * ``"call"``: A function is about to be called, or another code block + entered. + * ``"return"``: A function or other code block is about to return. + * ``"exception"``: An exception has occurred. + * ``"c_call"``: A C function is about to be called. + * ``"c_return"``: A C function has returned. + * ``"c_exception"``: A C function has thrown an exception. + + For the Python events, specialized functions (see below) are called. For the + C events, no action is taken. + + The *arg* parameter depends on the previous event. + + For more information on trace functions, see :ref:`debugger-hooks`. For more + information on code and frame objects, refer to :ref:`types`. + +.. method:: Bdb.dispatch_line(frame) + + If the debugger should stop on the current line, invoke the :meth:`user_line` + method (which should be overridden in subclasses). Raise a :exc:`BdbQuit` + exception if the :attr:`Bdb.quitting` flag is set (which can be set from + :meth:`user_line`). Return a reference to the :meth:`trace_dispatch` method + for further tracing in that scope. + +.. method:: Bdb.dispatch_call(frame, arg) + + If the debugger should stop on this function call, invoke the + :meth:`user_call` method (which should be overridden in subclasses). Raise a + :exc:`BdbQuit` exception if the :attr:`Bdb.quitting` flag is set (which can + be set from :meth:`user_call`). Return a reference to the + :meth:`trace_dispatch` method for further tracing in that scope. + +.. method:: Bdb.dispatch_return(frame, arg) + + If the debugger should stop on this function return, invoke the + :meth:`user_return` method (which should be overridden in subclasses). Raise + a :exc:`BdbQuit` exception if the :attr:`Bdb.quitting` flag is set (which can + be set from :meth:`user_return`). Return a reference to the + :meth:`trace_dispatch` method for further tracing in that scope. + +.. method:: Bdb.dispatch_exception(frame, arg) + + If the debugger should stop at this exception, invokes the + :meth:`user_exception` method (which should be overridden in subclasses). + Raise a :exc:`BdbQuit` exception if the :attr:`Bdb.quitting` flag is set + (which can be set from :meth:`user_exception`). Return a reference to the + :meth:`trace_dispatch` method for further tracing in that scope. + +Normally derived classes don't override the following methods, but they may if +they want to redefine the definition of stopping and breakpoints. + +.. method:: Bdb.stop_here(frame) + + This method checks if the *frame* is somewhere below :attr:`botframe` in the + call stack. :attr:`botframe` is the frame in which debugging started. + +.. method:: Bdb.break_here(frame) + + This method checks if there is a breakpoint in the filename and line + belonging to *frame* or, at least, in the current function. If the + breakpoint is a temporary one, this method deletes it. + +.. method:: Bdb.break_anywhere(frame) + + This method checks if there is a breakpoint in the filename of the current + frame. + +Derived classes should override these methods to gain control over debugger +operation. + +.. method:: Bdb.user_call(frame, argument_list) + + This method is called from :meth:`dispatch_call` when there is the + possibility that a break might be necessary anywhere inside the called + function. + +.. method:: Bdb.user_line(frame) + + This method is called from :meth:`dispatch_line` when either + :meth:`stop_here` or :meth:`break_here` yields True. + +.. method:: Bdb.user_return(frame, return_value) + + This method is called from :meth:`dispatch_return` when :meth:`stop_here` + yields True. + +.. method:: Bdb.user_exception(frame, exc_info) + + This method is called from :meth:`dispatch_exception` when :meth:`stop_here` + yields True. + +.. method:: Bdb.do_clear(arg) + + Handle how a breakpoint must be removed when it is a temporary one. + + This method must be implemented by derived classes. + + +Derived classes and clients can call the following methods to affect the +stepping state. + +.. method:: Bdb.set_step() + + Stop after one line of code. + +.. method:: Bdb.set_next(frame) + + Stop on the next line in or below the given frame. + +.. method:: Bdb.set_return(frame) + + Stop when returning from the given frame. + +.. method:: Bdb.set_trace([frame]) + + Start debugging from *frame*. If *frame* is not specified, debugging starts + from caller's frame. + +.. method:: Bdb.set_continue() + + Stop only at breakpoints or when finished. If there are no breakpoints, set + the system trace function to None. + +.. method:: Bdb.set_quit() + + Set the :attr:`quitting` attribute to True. This raises :exc:`BdbQuit` in + the next call to one of the :meth:`dispatch_\*` methods. + + +Derived classes and clients can call the following methods to manipulate +breakpoints. These methods return a string containing an error message if +something went wrong, or ``None`` if all is well. + +.. method:: Bdb.set_break(filename, lineno[, temporary=0[, cond[, funcname]]]) + + Set a new breakpoint. If the *lineno* line doesn't exist for the *filename* + passed as argument, return an error message. The *filename* should be in + canonical form, as described in the :meth:`canonic` method. + +.. method:: Bdb.clear_break(filename, lineno) + + Delete the breakpoints in *filename* and *lineno*. If none were set, an + error message is returned. + +.. method:: Bdb.clear_bpbynumber(arg) + + Delete the breakpoint which has the index *arg* in the + :attr:`Breakpoint.bpbynumber`. If `arg` is not numeric or out of range, + return an error message. + +.. method:: Bdb.clear_all_file_breaks(filename) + + Delete all breakpoints in *filename*. If none were set, an error message is + returned. + +.. method:: Bdb.clear_all_breaks() + + Delete all existing breakpoints. + +.. method:: Bdb.get_break(filename, lineno) + + Check if there is a breakpoint for *lineno* of *filename*. + +.. method:: Bdb.get_breaks(filename, lineno) + + Return all breakpoints for *lineno* in *filename*, or an empty list if none + are set. + +.. method:: Bdb.get_file_breaks(filename) + + Return all breakpoints in *filename*, or an empty list if none are set. + +.. method:: Bdb.get_all_breaks() + + Return all breakpoints that are set. + + +Derived classes and clients can call the following methods to get a data +structure representing a stack trace. + +.. method:: Bdb.get_stack(f, t) + + Get a list of records for a frame and all higher (calling) and lower frames, + and the size of the higher part. + +.. method:: Bdb.format_stack_entry(frame_lineno, [lprefix=': ']) + + Return a string with information about a stack entry, identified by a + ``(frame, lineno)`` tuple: + + * The canonical form of the filename which contains the frame. + * The function name, or ``""``. + * The input arguments. + * The return value. + * The line of code (if it exists). + + +The following two methods can be called by clients to use a debugger to debug a +:term:`statement`, given as a string. + +.. method:: Bdb.run(cmd, [globals, [locals]]) + + Debug a statement executed via the :keyword:`exec` statement. *globals* + defaults to :attr:`__main__.__dict__`, *locals* defaults to *globals*. + +.. method:: Bdb.runeval(expr, [globals, [locals]]) + + Debug an expression executed via the :func:`eval` function. *globals* and + *locals* have the same meaning as in :meth:`run`. + +.. method:: Bdb.runctx(cmd, globals, locals) + + For backwards compatibility. Calls the :meth:`run` method. + +.. method:: Bdb.runcall(func, *args, **kwds) + + Debug a single function call, and return its result. + + +Finally, the module defines the following functions: + +.. function:: checkfuncname(b, frame) + + Check whether we should break here, depending on the way the breakpoint *b* + was set. + + If it was set via line number, it checks if ``b.line`` is the same as the one + in the frame also passed as argument. If the breakpoint was set via function + name, we have to check we are in the right frame (the right function) and if + we are in its first executable line. + +.. function:: effective(file, line, frame) + + Determine if there is an effective (active) breakpoint at this line of code. + Return breakpoint number or 0 if none. + + Called only if we know there is a breakpoint at this location. Returns the + breakpoint that was triggered and a flag that indicates if it is ok to delete + a temporary breakpoint. + +.. function:: set_trace() + + Starts debugging with a :class:`Bdb` instance from caller's frame. diff --git a/Doc/library/codeop.rst b/Doc/library/codeop.rst index 419e873..35430b4 100644 --- a/Doc/library/codeop.rst +++ b/Doc/library/codeop.rst @@ -43,8 +43,8 @@ To do just the former: :exc:`OverflowError` or :exc:`ValueError` if there is an invalid literal. The *symbol* argument determines whether *source* is compiled as a statement - (``'single'``, the default) or as an expression (``'eval'``). Any other value - will cause :exc:`ValueError` to be raised. + (``'single'``, the default) or as an :term:`expression` (``'eval'``). Any + other value will cause :exc:`ValueError` to be raised. .. warning:: diff --git a/Doc/library/contextlib.rst b/Doc/library/contextlib.rst index 6a4fd3d..cab2e8c 100644 --- a/Doc/library/contextlib.rst +++ b/Doc/library/contextlib.rst @@ -15,9 +15,9 @@ Functions provided: .. function:: contextmanager(func) - This function is a decorator that can be used to define a factory function for - :keyword:`with` statement context managers, without needing to create a class or - separate :meth:`__enter__` and :meth:`__exit__` methods. + This function is a :term:`decorator` that can be used to define a factory + function for :keyword:`with` statement context managers, without needing to + create a class or separate :meth:`__enter__` and :meth:`__exit__` methods. A simple example (this is not recommended as a real way of generating HTML!):: diff --git a/Doc/library/doctest.rst b/Doc/library/doctest.rst index 721d7c0..99a2921 100644 --- a/Doc/library/doctest.rst +++ b/Doc/library/doctest.rst @@ -1070,7 +1070,8 @@ capabilities, then you should use the advanced API. The advanced API revolves around two container classes, which are used to store the interactive examples extracted from doctest cases: -* :class:`Example`: A single python statement, paired with its expected output. +* :class:`Example`: A single python :term:`statement`, paired with its expected + output. * :class:`DocTest`: A collection of :class:`Example`\ s, typically extracted from a single docstring or text file. diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index 5d0d8a5..37c53a5 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -177,8 +177,8 @@ available. They are listed here in alphabetical order. @classmethod def f(cls, arg1, arg2, ...): ... - The ``@classmethod`` form is a function decorator -- see the description of - function definitions in :ref:`function` for details. + The ``@classmethod`` form is a function :term:`decorator` -- see the description + of function definitions in :ref:`function` for details. It can be called either on the class (such as ``C.f()``) or on an instance (such as ``C().f()``). The instance is ignored except for its class. If a class @@ -814,7 +814,7 @@ available. They are listed here in alphabetical order. If given, *doc* will be the docstring of the property attribute. Otherwise, the property will copy *fget*'s docstring (if it exists). This makes it possible to - create read-only properties easily using :func:`property` as a decorator:: + create read-only properties easily using :func:`property` as a :term:`decorator`:: class Parrot(object): def __init__(self): @@ -906,7 +906,7 @@ available. They are listed here in alphabetical order. .. index:: single: Numerical Python - Return a slice object representing the set of indices specified by + Return a :term:`slice` object representing the set of indices specified by ``range(start, stop, step)``. The *start* and *step* arguments default to ``None``. Slice objects have read-only data attributes :attr:`start`, :attr:`stop` and :attr:`step` which merely return the argument values (or their @@ -952,8 +952,8 @@ available. They are listed here in alphabetical order. @staticmethod def f(arg1, arg2, ...): ... - The ``@staticmethod`` form is a function decorator -- see the description of - function definitions in :ref:`function` for details. + The ``@staticmethod`` form is a function :term:`decorator` -- see the + description of function definitions in :ref:`function` for details. It can be called either on the class (such as ``C.f()``) or on an instance (such as ``C().f()``). The instance is ignored except for its class. diff --git a/Doc/library/functools.rst b/Doc/library/functools.rst index a3d3729..1c8fa5b 100644 --- a/Doc/library/functools.rst +++ b/Doc/library/functools.rst @@ -76,9 +76,9 @@ The :mod:`functools` module defines the following functions: *WRAPPER_UPDATES* (which updates the wrapper function's *__dict__*, i.e. the instance dictionary). - The main intended use for this function is in decorator functions which wrap the - decorated function and return the wrapper. If the wrapper function is not - updated, the metadata of the returned function will reflect the wrapper + The main intended use for this function is in :term:`decorator` functions which + wrap the decorated function and return the wrapper. If the wrapper function is + not updated, the metadata of the returned function will reflect the wrapper definition rather than the original function definition, which is typically less than helpful. diff --git a/Doc/library/inspect.rst b/Doc/library/inspect.rst index 988b737..5cdec20 100644 --- a/Doc/library/inspect.rst +++ b/Doc/library/inspect.rst @@ -220,7 +220,7 @@ attributes: .. function:: isfunction(object) - Return true if the object is a Python function or unnamed (lambda) function. + Return true if the object is a Python function or unnamed (:term:`lambda`) function. .. function:: istraceback(object) diff --git a/Doc/library/mmap.rst b/Doc/library/mmap.rst index 26748c4..715610e 100644 --- a/Doc/library/mmap.rst +++ b/Doc/library/mmap.rst @@ -84,6 +84,49 @@ To map anonymous memory, -1 should be passed as the fileno along with the length *offset* may be specified as a non-negative integer offset. mmap references will be relative to the offset from the beginning of the file. *offset* defaults to 0. *offset* must be a multiple of the PAGESIZE or ALLOCATIONGRANULARITY. + + This example shows a simple way of using :func:`mmap`:: + + import mmap + + # write a simple example file + with open("hello.txt", "w") as f: + f.write("Hello Python!\n") + + with open("hello.txt", "r+") as f: + # memory-map the file, size 0 means whole file + map = mmap.mmap(f.fileno(), 0) + # read content via standard file methods + print map.readline() # prints "Hello Python!" + # read content via slice notation + print map[:5] # prints "Hello" + # update content using slice notation; + # note that new content must have same size + map[6:] = " world!\n" + # ... and read again using standard file methods + map.seek(0) + print map.readline() # prints "Hello world!" + # close the map + map.close() + + + The next example demonstrates how to create an anonymous map and exchange + data between the parent and child processes:: + + import mmap + import os + + map = mmap.mmap(-1, 13) + map.write("Hello world!") + + pid = os.fork() + + if pid == 0: # In a child process + map.seek(0) + print map.readline() + + map.close() + Memory-mapped file objects support the following methods: diff --git a/Doc/library/operator.rst b/Doc/library/operator.rst index cb89a7f..15f46eb 100644 --- a/Doc/library/operator.rst +++ b/Doc/library/operator.rst @@ -262,10 +262,10 @@ Operations which work with sequences include: Many operations have an "in-place" version. The following functions provide a more primitive access to in-place operators than the usual syntax does; for -example, the statement ``x += y`` is equivalent to ``x = operator.iadd(x, y)``. -Another way to put it is to say that ``z = operator.iadd(x, y)`` is equivalent -to the compound statement ``z = x; z += y``. - +example, the :term:`statement` ``x += y`` is equivalent to +``x = operator.iadd(x, y)``. Another way to put it is to say that +``z = operator.iadd(x, y)`` is equivalent to the compound statement +``z = x; z += y``. .. function:: iadd(a, b) __iadd__(a, b) diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index e94560b..56d4851 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -2149,8 +2149,8 @@ decimal arithmetic context. The specific types are not treated specially beyond their implementation of the context management protocol. See the :mod:`contextlib` module for some examples. -Python's :term:`generator`\s and the ``contextlib.contextfactory`` decorator provide a -convenient way to implement these protocols. If a generator function is +Python's :term:`generator`\s and the ``contextlib.contextfactory`` :term:`decorator` +provide a convenient way to implement these protocols. If a generator function is decorated with the ``contextlib.contextfactory`` decorator, it will return a context manager implementing the necessary :meth:`__enter__` and :meth:`__exit__` methods, rather than the iterator produced by an undecorated diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst index 3b9112a..97f94aa 100644 --- a/Doc/library/sys.rst +++ b/Doc/library/sys.rst @@ -80,9 +80,9 @@ always available. If *value* is not ``None``, this function prints it to ``sys.stdout``, and saves it in ``builtins._``. - ``sys.displayhook`` is called on the result of evaluating an expression entered - in an interactive Python session. The display of these values can be customized - by assigning another one-argument function to ``sys.displayhook``. + ``sys.displayhook`` is called on the result of evaluating an :term:`expression` + entered in an interactive Python session. The display of these values can be + customized by assigning another one-argument function to ``sys.displayhook``. .. function:: excepthook(type, value, traceback) @@ -536,14 +536,16 @@ always available. stderr File objects corresponding to the interpreter's standard input, output and error - streams. ``stdin`` is used for all interpreter input except for scripts. - ``stdout`` is used for the output of :func:`print` and expression statements. - The interpreter's own prompts and (almost all of) its error messages go to - ``stderr``. ``stdout`` and ``stderr`` needn't be built-in file objects: any - object is acceptable as long as it has a :meth:`write` method that takes a - string argument. (Changing these objects doesn't affect the standard I/O - streams of processes executed by :func:`os.popen`, :func:`os.system` or the - :func:`exec\*` family of functions in the :mod:`os` module.) + streams. ``stdin`` is used for all interpreter input except for scripts but + including calls to :func:`input`. ``stdout`` is used for + the output of :func:`print` and :term:`expression` statements and for the + prompts of :func:`input`. The interpreter's own prompts + and (almost all of) its error messages go to ``stderr``. ``stdout`` and + ``stderr`` needn't be built-in file objects: any object is acceptable as long + as it has a :meth:`write` method that takes a string argument. (Changing these + objects doesn't affect the standard I/O streams of processes executed by + :func:`os.popen`, :func:`os.system` or the :func:`exec\*` family of functions in + the :mod:`os` module.) .. data:: __stdin__ diff --git a/Doc/library/timeit.rst b/Doc/library/timeit.rst index 3387c7f..6a8a94d 100644 --- a/Doc/library/timeit.rst +++ b/Doc/library/timeit.rst @@ -85,11 +85,12 @@ The module defines the following public class: .. note:: - By default, :meth:`timeit` temporarily turns off garbage collection during the - timing. The advantage of this approach is that it makes independent timings - more comparable. This disadvantage is that GC may be an important component of - the performance of the function being measured. If so, GC can be re-enabled as - the first statement in the *setup* string. For example:: + By default, :meth:`timeit` temporarily turns off :term:`garbage collection` + during the timing. The advantage of this approach is that it makes + independent timings more comparable. This disadvantage is that GC may be + an important component of the performance of the function being measured. + If so, GC can be re-enabled as the first statement in the *setup* string. + For example:: timeit.Timer('for i in range(10): oct(i)', 'gc.enable()').timeit() diff --git a/Doc/library/weakref.rst b/Doc/library/weakref.rst index 9a1e076..fdfbae0 100644 --- a/Doc/library/weakref.rst +++ b/Doc/library/weakref.rst @@ -20,22 +20,22 @@ In the following, the term :dfn:`referent` means the object which is referred to by a weak reference. A weak reference to an object is not enough to keep the object alive: when the -only remaining references to a referent are weak references, garbage collection -is free to destroy the referent and reuse its memory for something else. A -primary use for weak references is to implement caches or mappings holding large -objects, where it's desired that a large object not be kept alive solely because -it appears in a cache or mapping. For example, if you have a number of large -binary image objects, you may wish to associate a name with each. If you used a -Python dictionary to map names to images, or images to names, the image objects -would remain alive just because they appeared as values or keys in the -dictionaries. The :class:`WeakKeyDictionary`, :class:`WeakValueDictionary` -and :class:`WeakSet` classes supplied by the :mod:`weakref` module are an -alternative, using weak references to construct mappings that don't keep objects -alive solely because they appear in the container objects. -If, for example, an image object is a value in a :class:`WeakValueDictionary`, -then when the last remaining references to that image object are the weak -references held by weak mappings, garbage collection can reclaim the object, -and its corresponding entries in weak mappings are simply deleted. +only remaining references to a referent are weak references, +:term:`garbage collection` is free to destroy the referent and reuse its memory +for something else. A primary use for weak references is to implement caches or +mappings holding large objects, where it's desired that a large object not be +kept alive solely because it appears in a cache or mapping. For example, if you +have a number of large binary image objects, you may wish to associate a name +with each. If you used a Python dictionary to map names to images, or images to +names, the image objects would remain alive just because they appeared as values +or keys in the dictionaries. The :class:`WeakKeyDictionary` and +:class:`WeakValueDictionary` classes supplied by the :mod:`weakref` module are +an alternative, using weak references to construct mappings that don't keep +objects alive solely because they appear in the mapping objects. If, for +example, an image object is a value in a :class:`WeakValueDictionary`, then when +the last remaining references to that image object are the weak references held +by weak mappings, garbage collection can reclaim the object, and its +corresponding entries in weak mappings are simply deleted. :class:`WeakKeyDictionary` and :class:`WeakValueDictionary` use weak references in their implementation, setting up callback functions on the weak references diff --git a/Doc/library/windows.rst b/Doc/library/windows.rst index a231bc2..b09dd8b 100644 --- a/Doc/library/windows.rst +++ b/Doc/library/windows.rst @@ -1,3 +1,4 @@ +.. _mswin-specific-services: **************************** MS Windows Specific Services diff --git a/Doc/library/xml.etree.elementtree.rst b/Doc/library/xml.etree.elementtree.rst index 81a9316..172a2a0 100644 --- a/Doc/library/xml.etree.elementtree.rst +++ b/Doc/library/xml.etree.elementtree.rst @@ -31,6 +31,9 @@ convert it from and to XML. A C implementation of this API is available as :mod:`xml.etree.cElementTree`. +See http://effbot.org/zone/element-index.htm for tutorials and links to other +docs. Fredrik Lundh's page is also the location of the development version of the +xml.etree.ElementTree. .. _elementtree-functions: @@ -355,6 +358,33 @@ ElementTree Objects object opened for writing. *encoding* is the output encoding (default is US-ASCII). +This is the XML file that is going to be manipulated:: + + + + Example page + + +

Moved to example.org + or example.com.

+ + + +Example of changing the attribute "target" of every link in first paragraph:: + + >>> from xml.etree.ElementTree import ElementTree + >>> tree = ElementTree() + >>> tree.parse("index.xhtml") + + >>> p = tree.find("body/p") # Finds first occurrence of tag p in body + >>> p + + >>> links = p.getiterator("a") # Returns list of all links + >>> links + [, ] + >>> for i in links: # Iterates through all found links + ... i.attrib["target"] = "blank" + >>> tree.write("output.xhtml") .. _elementtree-qname-objects: @@ -440,3 +470,41 @@ XMLTreeBuilder Objects Feeds data to the parser. *data* is encoded data. +:meth:`XMLTreeBuilder.feed` calls *target*\'s :meth:`start` method +for each opening tag, its :meth:`end` method for each closing tag, +and data is processed by method :meth:`data`. :meth:`XMLTreeBuilder.close` +calls *target*\'s method :meth:`close`. +:class:`XMLTreeBuilder` can be used not only for building a tree structure. +This is an example of counting the maximum depth of an XML file:: + + >>> from xml.etree.ElementTree import XMLTreeBuilder + >>> class MaxDepth: # The target object of the parser + ... maxDepth = 0 + ... depth = 0 + ... def start(self, tag, attrib): # Called for each opening tag. + ... self.depth += 1 + ... if self.depth > self.maxDepth: + ... self.maxDepth = self.depth + ... def end(self, tag): # Called for each closing tag. + ... self.depth -= 1 + ... def data(self, data): + ... pass # We do not need to do anything with data. + ... def close(self): # Called when all data has been parsed. + ... return self.maxDepth + ... + >>> target = MaxDepth() + >>> parser = XMLTreeBuilder(target=target) + >>> exampleXml = """ + ... + ... + ... + ... + ... + ... + ... + ... + ... + ... """ + >>> parser.feed(exampleXml) + >>> parser.close() + 4 diff --git a/Doc/reference/compound_stmts.rst b/Doc/reference/compound_stmts.rst index 08d2f5d..432f3c8 100644 --- a/Doc/reference/compound_stmts.rst +++ b/Doc/reference/compound_stmts.rst @@ -421,7 +421,7 @@ when the function is called. The function definition does not execute the function body; this gets executed only when the function is called. -A function definition may be wrapped by one or more decorator expressions. +A function definition may be wrapped by one or more :term:`decorator` expressions. Decorator expressions are evaluated when the function is defined, in the scope that contains the function definition. The result must be a callable, which is invoked with the function object as the only argument. The returned value is diff --git a/Doc/tutorial/stdlib2.rst b/Doc/tutorial/stdlib2.rst index 3ef21d2..17fb867 100644 --- a/Doc/tutorial/stdlib2.rst +++ b/Doc/tutorial/stdlib2.rst @@ -244,8 +244,8 @@ Weak References =============== Python does automatic memory management (reference counting for most objects and -garbage collection to eliminate cycles). The memory is freed shortly after the -last reference to it has been eliminated. +:term:`garbage collection` to eliminate cycles). The memory is freed shortly +after the last reference to it has been eliminated. This approach works fine for most applications but occasionally there is a need to track objects only as long as they are being used by something else. diff --git a/Doc/using/cmdline.rst b/Doc/using/cmdline.rst index 18e6c68..38b9a0f 100644 --- a/Doc/using/cmdline.rst +++ b/Doc/using/cmdline.rst @@ -1,5 +1,7 @@ .. highlightlang:: none +.. _using-on-general: + Command line and environment ============================ @@ -12,6 +14,8 @@ settings. :ref:`implementations` for further resources. +.. _using-on-cmdline: + Command line ------------ @@ -289,35 +293,7 @@ Miscellaneous options .. warning:: The line numbers in error messages will be off by one! - -Related files -- UNIX ---------------------- - -These are subject to difference depending on local installation conventions; -:envvar:`prefix` (``${prefix}``) and :envvar:`exec_prefix` (``${exec_prefix}``) -are installation-dependent and should be interpreted as for GNU software; they -may be the same. - -For example, on most Linux systems, the default for both is :file:`/usr`. - -+-----------------------------------------------+------------------------------------------+ -| File/directory | Meaning | -+===============================================+==========================================+ -| :file:`{exec_prefix}/bin/python` | Recommended location of the interpreter. | -+-----------------------------------------------+------------------------------------------+ -| :file:`{prefix}/lib/python{version}`, | Recommended locations of the directories | -| :file:`{exec_prefix}/lib/python{version}` | containing the standard modules. | -+-----------------------------------------------+------------------------------------------+ -| :file:`{prefix}/include/python{version}`, | Recommended locations of the directories | -| :file:`{exec_prefix}/include/python{version}` | containing the include files needed for | -| | developing Python extensions and | -| | embedding the interpreter. | -+-----------------------------------------------+------------------------------------------+ -| :file:`~/.pythonrc.py` | User-specific initialization file loaded | -| | by the user module; not used by default | -| | or by most applications. | -+-----------------------------------------------+------------------------------------------+ - +.. _using-on-envvars: Environment variables --------------------- diff --git a/Doc/using/index.rst b/Doc/using/index.rst index f8d8ce4..e2fa4b4 100644 --- a/Doc/using/index.rst +++ b/Doc/using/index.rst @@ -13,5 +13,6 @@ interpreter and things that make working with Python easier. .. toctree:: cmdline.rst + windows.rst mac.rst diff --git a/Doc/using/windows.rst b/Doc/using/windows.rst new file mode 100644 index 0000000..db83605 --- /dev/null +++ b/Doc/using/windows.rst @@ -0,0 +1,316 @@ +.. highlightlang:: none + +.. _using-on-windows: + +************************* + Using Python on Windows +************************* + +.. sectionauthor:: Robert Lehmann + +This document aims to give an overview of Windows-specific behaviour you should +know about when using Python on Microsoft Windows. + + +Installing Python +================= + +Unlike most Unix systems and services, Windows does not require Python natively +and thus does not pre-install a version of Python. However, the CPython team +has compiled Windows installers (MSI packages) with every `release +`_ for many years. + +With ongoing development of Python, some platforms that used to be supported +earlier are not longer supported (due to the lack of users or developers). +Check :pep:`11` for details on all unsupported platforms. + +* DOS and Windows 3.x are deprecated since Python 2.0 and code specific to these + systems was removed in Python 2.1. +* Up to 2.5, Python was still compatible with Windows 95, 98 and ME (but already + raised a deprecation warning on installation). For Python 2.6 (and all + following releases), this support was dropped and new releases are just + expected to work on the Windows NT family. +* `Windows CE `_ is still supported. +* The `Cygwin `_ installer offers to install the `Python + interpreter `_ as well; it is located under + "Interpreters." (cf. `Cygwin package source + `_, `Maintainer releases + `_) + +See `Python for Windows (and DOS) `_ +for detailed information about platforms with precompiled installers. + +.. seealso:: + + `Python on XP `_ + "7 Minutes to "Hello World!"" + by Richard Dooling, 2006 + + `Installing on Windows `_ + in "`Dive into Python: Python from novice to pro + `_" + by Mark Pilgrim, 2004, + ISBN 1-59059-356-1 + + `For Windows users `_ + in "Installing Python" + in "`A Byte of Python `_" + by Swaroop C H, 2003 + + +Alternative bundles +=================== + +Besides the standard CPython distribution, there are modified packages including +additional functionality. The following is a list of popular versions and their +key features: + +`ActivePython `_ + Installer with multi-platform compatibility, documentation, PyWin32 + +`Python Enthought Edition `_ + Popular modules (such as PyWin32) with their respective documentation, tool + suite for building extensible python applications + + + +Configuring Python +================== + +In order to run Python flawlessly, you might have to change certain environment +settings in Windows. + + +Excursus: Setting environment variables +--------------------------------------- + +Windows has a built-in dialog for changing environment variables: Right-click +the icon for your machine (usually located on your Desktop and called "My +Computer") and choose :menuselection:`Properties` there. Then, open the +:guilabel:`Advanced` tab and click the :guilabel:`Environment Variables` button. + +In short, your path is: + + :menuselection:`My Computer + --> Properties + --> Advanced + --> Environment Variables` + +In this dialog, you can add or modify User and System variables. To change +System variables, you need non-restricted access to your machine +(i.e. Administrator rights). + +Another way of adding variables to your environment is using the :command:`set` +command:: + + set PYTHONPATH=%PYTHONPATH%;C:\My_python_lib + +To make this setting permanent, you could add the corresponding command line to +your :file:`autoexec.bat`. + +Viewing environment variables can also be done more straight-forward: The +command prompt will expand strings wrapped into percent signs automatically:: + + echo %PATH% + +Consult :command:`set /?` for details on this behaviour. + +.. seealso:: + + http://support.microsoft.com/kb/100843 + Environment variables in Windows NT + + http://support.microsoft.com/kb/310519 + How To Manage Environment Variables in Windows XP + + +Finding the Python executable +----------------------------- + +Besides using the automatically created start menu entry for the Python +interpreter, you might want to start Python in the DOS prompt. To make this +work, you need to set your :envvar:`%PATH%` environment variable to include the +directory of your Python distribution, delimited by a semicolon from other +entries. An example variable could look like this (assuming the first two +entries are Windows' default):: + + C:\WINNT\system32;C:\WINNT;C:\Python25 + +Typing :command:`python` on your command prompt will now fire up the Python +interpreter. Thus, you can also execute your scripts with command line options, +see :ref:`using-on-cmdline` documentation. + + +Finding modules +--------------- + +Python usually stores its library (and thereby your site-packages folder) in the +installation directory. So, if you had installed Python to +:file:`C:\\Python\\`, the default library would reside in +:file:`C:\\Python\\Lib\\` and third-party modules should be stored in +:file:`C:\\Python\\Lib\\site-packages\\`. + +.. % `` this fixes syntax highlighting errors in some editors + due to the \\ hackery + +You can add folders to your search path to make Python's import mechanism search +in these directories as well. Use :envvar:`PYTHONPATH`, as described in +:ref:`using-on-envvars`, to modify :data:`sys.path`. On Windows, paths are +separated by semicolons, though, to distinguish them from drive identifiers +(:file:`C:\\` etc.). + +.. % `` + +Modifying the module search path can also be done through the Windows registry: +Edit +:file:`HKEY_LOCAL_MACHINE\\SOFTWARE\\Python\\PythonCore\\{version}\\PythonPath\\`, +as described above for the environment variable :envvar:`%PYTHONPATH%`. A +convenient registry editor is :program:`regedit` (start it by typing "regedit" +into :menuselection:`Start --> Run`). + + +Executing scripts +----------------- + +Python scripts (files with the extension ``.py``) will be executed by +:program:`python.exe` by default. This executable opens a terminal, which stays +open even if the program uses a GUI. If you do not want this to happen, use the +extension ``.pyw`` which will cause the script to be executed by +:program:`pythonw.exe` by default (both executables are located in the top-level +of your Python installation directory). This suppresses the terminal window on +startup. + +You can also make all ``.py`` scripts execute with :program:`pythonw.exe`, +setting this through the usual facilites, for example (names might differ, +depending on your version of Windows): + +#. Open the context menu of a :file:`{*}.py` file. +#. Click :menuselection:`Open with...`. +#. Choose the interpreter of your choice (utilize :guilabel:`Other...` or + :guilabel:`Choose Program...` if it is not in the list of default programs). +#. Check :guilabel:`Always open files with this program`. +#. Click :guilabel:`OK`. + + + +Additional modules +================== + +Even though Python aims to be portable among all platforms, there are features +that are unique to Windows. A couple of modules, both in the standard library +and external, and snippets exist to use these features. + +The Windows-specific standard modules are documented in +:ref:`mswin-specific-services`. + + +PyWin32 +------- + +The `PyWin32 `_ module by Mark Hammond +is a collection of modules for advanced Windows-specific support. This includes +utilites for: + +* `Component Object Model `_ (COM) +* Win32 API calls +* Registry +* Event log +* `Microsoft Foundation Classes `_ (MFC) + user interfaces + +`PythonWin `_ is a sample MFC application +shipped with PyWin32. It is an embeddable IDE with a built-in debugger. + +.. seealso:: + + `Win32 How Do I...? `_ + by Tim Golden + + `Python and COM `_ + by David and Paul Boddie + + +Py2exe +------ + +`Py2exe `_ is a :mod:`distutils` extension (see +:ref:`extending-distutils`) which wraps Python scripts into executable Windows +programs (:file:`{*}.exe` files). When you have done this, you can distribute +your application without requiring your users to install Python. + + +WConio +------ + +Since Python's advanced terminal handling layer, :mod:`curses`, is restricted to +Unix-like systems, there is a library exclusive to Windows as well: Windows +Console I/O for Python. + +`WConio `_ is a wrapper for +Turbo-C's :file:`CONIO.H`, used to create text user interfaces. + + + +Compiling Python on Windows +=========================== + +If you want to compile CPython yourself, first thing you should do is get the +`source `_. You can download either the +latest release's source or just grab a fresh `checkout +`_. + +For Microsoft Visual C++, which is the compiler with which official Python +releases are built, the source tree contains solutions/project files. View the +:file:`readme.txt` in their respective directories: + ++--------------------+--------------+-----------------------+ +| Directory | MSVC version | Visual Studio version | ++====================+==============+=======================+ +| :file:`PC/VC6/` | 5.0 | 97 | +| +--------------+-----------------------+ +| | 6.0 | 6.0 | ++--------------------+--------------+-----------------------+ +| :file:`PCbuild/` | 7.1 | 2003 | ++--------------------+--------------+-----------------------+ +| :file:`PCbuild8/` | 8.0 | 2005 | ++--------------------+--------------+-----------------------+ +| :file:`PCbuild9/` | 9.0 | 2008 | ++--------------------+--------------+-----------------------+ + +Note that not all of these build directories are fully supported. Read the +release notes to see which compiler version the official releases for your +version are built with. + +Check :file:`PC/readme.txt` for general information on the build process. + + +For extension modules, consult :ref:`building-on-windows`. + +.. seealso:: + + `Python + Windows + distutils + SWIG + gcc MinGW `_ + or "Creating Python extensions in C/C++ with SWIG and compiling them with + MinGW gcc under Windows" or "Installing Python extension with distutils + and without Microsoft Visual C++" by Sébastien Sauvage, 2003 + + `MingW -- Python extensions `_ + by Trent Apted et al, 2007 + + +Other resources +=============== + +.. seealso:: + + `Python Programming On Win32 `_ + "Help for Windows Programmers" + by Mark Hammond and Andy Robinson, O'Reilly Media, 2000, + ISBN 1-56592-621-8 + + `A Python for Windows Tutorial `_ + by Amanda Birmingham, 2004 + diff --git a/Lib/tarfile.py b/Lib/tarfile.py index f8afae9..a21f1ab 100644 --- a/Lib/tarfile.py +++ b/Lib/tarfile.py @@ -1542,7 +1542,8 @@ class TarFile(object): self.closed = False self.members = [] # list of members as TarInfo objects self._loaded = False # flag if all members have been read - self.offset = 0 # current position in the archive file + self.offset = self.fileobj.tell() + # current position in the archive file self.inodes = {} # dictionary caching the inodes of # archive members already added diff --git a/Lib/test/test_cmd.py b/Lib/test/test_cmd.py new file mode 100644 index 0000000..5aa1c40 --- /dev/null +++ b/Lib/test/test_cmd.py @@ -0,0 +1,186 @@ +#!/usr/bin/env python +""" +Test script for the 'cmd' module +Original by Michael Schneider +""" + + +from test import test_support +import cmd +import sys + +class samplecmdclass(cmd.Cmd): + """ + Instance the sampleclass: + >>> mycmd = samplecmdclass() + + Test for the function parseline(): + >>> mycmd.parseline("") + (None, None, '') + >>> mycmd.parseline("?") + ('help', '', 'help ') + >>> mycmd.parseline("?help") + ('help', 'help', 'help help') + >>> mycmd.parseline("!") + ('shell', '', 'shell ') + >>> mycmd.parseline("!command") + ('shell', 'command', 'shell command') + >>> mycmd.parseline("func") + ('func', '', 'func') + >>> mycmd.parseline("func arg1") + ('func', 'arg1', 'func arg1') + + + Test for the function onecmd(): + >>> mycmd.onecmd("") + >>> mycmd.onecmd("add 4 5") + 9 + >>> mycmd.onecmd("") + 9 + >>> mycmd.onecmd("test") + *** Unknown syntax: test + + Test for the function emptyline(): + >>> mycmd.emptyline() + *** Unknown syntax: test + + Test for the function default(): + >>> mycmd.default("default") + *** Unknown syntax: default + + Test for the function completedefault(): + >>> mycmd.completedefault() + This is the completedefault methode + >>> mycmd.completenames("a") + ['add'] + + Test for the function completenames(): + >>> mycmd.completenames("12") + [] + >>> mycmd.completenames("help") + ['help', 'help'] + + Test for the function complete_help(): + >>> mycmd.complete_help("a") + ['add'] + >>> mycmd.complete_help("he") + ['help', 'help'] + >>> mycmd.complete_help("12") + [] + + Test for the function do_help(): + >>> mycmd.do_help("testet") + *** No help on testet + >>> mycmd.do_help("add") + help text for add + >>> mycmd.onecmd("help add") + help text for add + >>> mycmd.do_help("") + + Documented commands (type help ): + ======================================== + add + + Undocumented commands: + ====================== + exit help shell + + + Test for the function print_topics(): + >>> mycmd.print_topics("header", ["command1", "command2"], 2 ,10) + header + ====== + command1 + command2 + + + Test for the function columnize(): + >>> mycmd.columnize([str(i) for i in xrange(20)]) + 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 + >>> mycmd.columnize([str(i) for i in xrange(20)], 10) + 0 7 14 + 1 8 15 + 2 9 16 + 3 10 17 + 4 11 18 + 5 12 19 + 6 13 + + This is a interactive test, put some commands in the cmdqueue attribute + and let it execute + This test includes the preloop(), postloop(), default(), emptyline(), + parseline(), do_help() functions + >>> mycmd.use_rawinput=0 + >>> mycmd.cmdqueue=["", "add", "add 4 5", "help", "help add","exit"] + >>> mycmd.cmdloop() + Hello from preloop + help text for add + *** invalid number of arguments + 9 + + Documented commands (type help ): + ======================================== + add + + Undocumented commands: + ====================== + exit help shell + + help text for add + Hello from postloop + """ + + def preloop(self): + print "Hello from preloop" + + def postloop(self): + print "Hello from postloop" + + def completedefault(self, *ignored): + print "This is the completedefault methode" + return + + def complete_command(self): + print "complete command" + return + + def do_shell(self): + pass + + def do_add(self, s): + l = s.split() + if len(l) != 2: + print "*** invalid number of arguments" + return + try: + l = [int(i) for i in l] + except ValueError: + print "*** arguments should be numbers" + return + print l[0]+l[1] + + def help_add(self): + print "help text for add" + return + + def do_exit(self, arg): + return True + +def test_main(verbose=None): + from test import test_support, test_cmd + test_support.run_doctest(test_cmd, verbose) + +import trace, sys,re,StringIO +def test_coverage(coverdir): + tracer=trace.Trace(ignoredirs=[sys.prefix, sys.exec_prefix,], + trace=0, count=1) + tracer.run('reload(cmd);test_main()') + r=tracer.results() + print "Writing coverage results..." + r.write_results(show_missing=True, summary=True, coverdir=coverdir) + +if __name__ == "__main__": + if "-c" in sys.argv: + test_coverage('/tmp/cmd.cover') + else: + test_main() diff --git a/Lib/test/test_tarfile.py b/Lib/test/test_tarfile.py index 10498bf..a97df37 100644 --- a/Lib/test/test_tarfile.py +++ b/Lib/test/test_tarfile.py @@ -159,6 +159,38 @@ class MiscReadTest(ReadTest): tar = tarfile.open(fileobj=fobj, mode=self.mode) self.assertEqual(tar.name, None) + def test_fileobj_with_offset(self): + # Skip the first member and store values from the second member + # of the testtar. + tar = tarfile.open(self.tarname, mode=self.mode) + tar.next() + t = tar.next() + name = t.name + offset = t.offset + data = tar.extractfile(t).read() + tar.close() + + # Open the testtar and seek to the offset of the second member. + if self.mode.endswith(":gz"): + _open = gzip.GzipFile + elif self.mode.endswith(":bz2"): + _open = bz2.BZ2File + else: + _open = open + fobj = _open(self.tarname, "rb") + fobj.seek(offset) + + # Test if the tarfile starts with the second member. + tar = tar.open(self.tarname, mode="r:", fileobj=fobj) + t = tar.next() + self.assertEqual(t.name, name) + # Read to the end of fileobj and test if seeking back to the + # beginning works. + tar.getmembers() + self.assertEqual(tar.extractfile(t).read(), data, + "seek back did not work") + tar.close() + def test_fail_comp(self): # For Gzip and Bz2 Tests: fail with a ReadError on an uncompressed file. if self.mode == "r:": diff --git a/Misc/ACKS b/Misc/ACKS index 0870456..76f2463 100644 --- a/Misc/ACKS +++ b/Misc/ACKS @@ -579,6 +579,7 @@ Neil Schemenauer David Scherer Gregor Schmid Ralf Schmitt +Michael Schneider Peter Schneider-Kamp Arvin Schnell Chad J. Schroeder -- cgit v0.12