| \documentclass{howto} |
| \usepackage{distutils} |
| % $Id$ |
| |
| % Fix XXX comments |
| |
| \title{What's New in Python 2.5} |
| \release{1.0} |
| \author{A.M. Kuchling} |
| \authoraddress{\email{amk@amk.ca}} |
| |
| \begin{document} |
| \maketitle |
| \tableofcontents |
| |
| This article explains the new features in Python 2.5. The final |
| release of Python 2.5 is scheduled for August 2006; |
| \pep{356} describes the planned release schedule. |
| |
| The changes in Python 2.5 are an interesting mix of language and |
| library improvements. The library enhancements will be more important |
| to Python's user community, I think, because several widely-useful |
| packages were added. New modules include ElementTree for XML |
| processing (section~\ref{module-etree}), the SQLite database module |
| (section~\ref{module-sqlite}), and the \module{ctypes} module for |
| calling C functions (section~\ref{module-ctypes}). |
| |
| The language changes are of middling significance. Some pleasant new |
| features were added, but most of them aren't features that you'll use |
| every day. Conditional expressions were finally added to the language |
| using a novel syntax; see section~\ref{pep-308}. The new |
| '\keyword{with}' statement will make writing cleanup code easier |
| (section~\ref{pep-343}). Values can now be passed into generators |
| (section~\ref{pep-342}). Imports are now visible as either absolute |
| or relative (section~\ref{pep-328}). Some corner cases of exception |
| handling are handled better (section~\ref{pep-341}). All these |
| improvements are worthwhile, but they're improvements to one specific |
| language feature or another; none of them are broad modifications to |
| Python's semantics. |
| |
| As well as the language and library additions, other improvements and |
| bugfixes were made throughout the source tree. A search through the |
| SVN change logs finds there were 353 patches applied and 458 bugs |
| fixed between Python 2.4 and 2.5. (Both figures are likely to be |
| underestimates.) |
| |
| This article doesn't try to be a complete specification of the new |
| features; instead changes are briefly introduced using helpful |
| examples. For full details, you should always refer to the |
| documentation for Python 2.5 at \url{http://docs.python.org}. |
| If you want to understand the complete implementation and design |
| rationale, refer to the PEP for a particular new feature. |
| |
| Comments, suggestions, and error reports for this document are |
| welcome; please e-mail them to the author or open a bug in the Python |
| bug tracker. |
| |
| %====================================================================== |
| \section{PEP 308: Conditional Expressions\label{pep-308}} |
| |
| For a long time, people have been requesting a way to write |
| conditional expressions, which are expressions that return value A or |
| value B depending on whether a Boolean value is true or false. A |
| conditional expression lets you write a single assignment statement |
| that has the same effect as the following: |
| |
| \begin{verbatim} |
| if condition: |
| x = true_value |
| else: |
| x = false_value |
| \end{verbatim} |
| |
| There have been endless tedious discussions of syntax on both |
| python-dev and comp.lang.python. A vote was even held that found the |
| majority of voters wanted conditional expressions in some form, |
| but there was no syntax that was preferred by a clear majority. |
| Candidates included C's \code{cond ? true_v : false_v}, |
| \code{if cond then true_v else false_v}, and 16 other variations. |
| |
| Guido van~Rossum eventually chose a surprising syntax: |
| |
| \begin{verbatim} |
| x = true_value if condition else false_value |
| \end{verbatim} |
| |
| Evaluation is still lazy as in existing Boolean expressions, so the |
| order of evaluation jumps around a bit. The \var{condition} |
| expression in the middle is evaluated first, and the \var{true_value} |
| expression is evaluated only if the condition was true. Similarly, |
| the \var{false_value} expression is only evaluated when the condition |
| is false. |
| |
| This syntax may seem strange and backwards; why does the condition go |
| in the \emph{middle} of the expression, and not in the front as in C's |
| \code{c ? x : y}? The decision was checked by applying the new syntax |
| to the modules in the standard library and seeing how the resulting |
| code read. In many cases where a conditional expression is used, one |
| value seems to be the 'common case' and one value is an 'exceptional |
| case', used only on rarer occasions when the condition isn't met. The |
| conditional syntax makes this pattern a bit more obvious: |
| |
| \begin{verbatim} |
| contents = ((doc + '\n') if doc else '') |
| \end{verbatim} |
| |
| I read the above statement as meaning ``here \var{contents} is |
| usually assigned a value of \code{doc+'\e n'}; sometimes |
| \var{doc} is empty, in which special case an empty string is returned.'' |
| I doubt I will use conditional expressions very often where there |
| isn't a clear common and uncommon case. |
| |
| There was some discussion of whether the language should require |
| surrounding conditional expressions with parentheses. The decision |
| was made to \emph{not} require parentheses in the Python language's |
| grammar, but as a matter of style I think you should always use them. |
| Consider these two statements: |
| |
| \begin{verbatim} |
| # First version -- no parens |
| level = 1 if logging else 0 |
| |
| # Second version -- with parens |
| level = (1 if logging else 0) |
| \end{verbatim} |
| |
| In the first version, I think a reader's eye might group the statement |
| into 'level = 1', 'if logging', 'else 0', and think that the condition |
| decides whether the assignment to \var{level} is performed. The |
| second version reads better, in my opinion, because it makes it clear |
| that the assignment is always performed and the choice is being made |
| between two values. |
| |
| Another reason for including the brackets: a few odd combinations of |
| list comprehensions and lambdas could look like incorrect conditional |
| expressions. See \pep{308} for some examples. If you put parentheses |
| around your conditional expressions, you won't run into this case. |
| |
| |
| \begin{seealso} |
| |
| \seepep{308}{Conditional Expressions}{PEP written by |
| Guido van~Rossum and Raymond D. Hettinger; implemented by Thomas |
| Wouters.} |
| |
| \end{seealso} |
| |
| |
| %====================================================================== |
| \section{PEP 309: Partial Function Application\label{pep-309}} |
| |
| The \module{functools} module is intended to contain tools for |
| functional-style programming. |
| |
| One useful tool in this module is the \function{partial()} function. |
| For programs written in a functional style, you'll sometimes want to |
| construct variants of existing functions that have some of the |
| parameters filled in. Consider a Python function \code{f(a, b, c)}; |
| you could create a new function \code{g(b, c)} that was equivalent to |
| \code{f(1, b, c)}. This is called ``partial function application''. |
| |
| \function{partial} takes the arguments |
| \code{(\var{function}, \var{arg1}, \var{arg2}, ... |
| \var{kwarg1}=\var{value1}, \var{kwarg2}=\var{value2})}. The resulting |
| object is callable, so you can just call it to invoke \var{function} |
| with the filled-in arguments. |
| |
| Here's a small but realistic example: |
| |
| \begin{verbatim} |
| import functools |
| |
| def log (message, subsystem): |
| "Write the contents of 'message' to the specified subsystem." |
| print '%s: %s' % (subsystem, message) |
| ... |
| |
| server_log = functools.partial(log, subsystem='server') |
| server_log('Unable to open socket') |
| \end{verbatim} |
| |
| Here's another example, from a program that uses PyGTK. Here a |
| context-sensitive pop-up menu is being constructed dynamically. The |
| callback provided for the menu option is a partially applied version |
| of the \method{open_item()} method, where the first argument has been |
| provided. |
| |
| \begin{verbatim} |
| ... |
| class Application: |
| def open_item(self, path): |
| ... |
| def init (self): |
| open_func = functools.partial(self.open_item, item_path) |
| popup_menu.append( ("Open", open_func, 1) ) |
| \end{verbatim} |
| |
| |
| Another function in the \module{functools} module is the |
| \function{update_wrapper(\var{wrapper}, \var{wrapped})} function that |
| helps you write well-behaved decorators. \function{update_wrapper()} |
| copies the name, module, and docstring attribute to a wrapper function |
| so that tracebacks inside the wrapped function are easier to |
| understand. For example, you might write: |
| |
| \begin{verbatim} |
| def my_decorator(f): |
| def wrapper(*args, **kwds): |
| print 'Calling decorated function' |
| return f(*args, **kwds) |
| functools.update_wrapper(wrapper, f) |
| return wrapper |
| \end{verbatim} |
| |
| \function{wraps()} is a decorator that can be used inside your own |
| decorators to copy the wrapped function's information. An alternate |
| version of the previous example would be: |
| |
| \begin{verbatim} |
| def my_decorator(f): |
| @functools.wraps(f) |
| def wrapper(*args, **kwds): |
| print 'Calling decorated function' |
| return f(*args, **kwds) |
| return wrapper |
| \end{verbatim} |
| |
| \begin{seealso} |
| |
| \seepep{309}{Partial Function Application}{PEP proposed and written by |
| Peter Harris; implemented by Hye-Shik Chang and Nick Coghlan, with |
| adaptations by Raymond Hettinger.} |
| |
| \end{seealso} |
| |
| |
| %====================================================================== |
| \section{PEP 314: Metadata for Python Software Packages v1.1\label{pep-314}} |
| |
| Some simple dependency support was added to Distutils. The |
| \function{setup()} function now has \code{requires}, \code{provides}, |
| and \code{obsoletes} keyword parameters. When you build a source |
| distribution using the \code{sdist} command, the dependency |
| information will be recorded in the \file{PKG-INFO} file. |
| |
| Another new keyword parameter is \code{download_url}, which should be |
| set to a URL for the package's source code. This means it's now |
| possible to look up an entry in the package index, determine the |
| dependencies for a package, and download the required packages. |
| |
| \begin{verbatim} |
| VERSION = '1.0' |
| setup(name='PyPackage', |
| version=VERSION, |
| requires=['numarray', 'zlib (>=1.1.4)'], |
| obsoletes=['OldPackage'] |
| download_url=('http://www.example.com/pypackage/dist/pkg-%s.tar.gz' |
| % VERSION), |
| ) |
| \end{verbatim} |
| |
| Another new enhancement to the Python package index at |
| \url{http://cheeseshop.python.org} is storing source and binary |
| archives for a package. The new \command{upload} Distutils command |
| will upload a package to the repository. |
| |
| Before a package can be uploaded, you must be able to build a |
| distribution using the \command{sdist} Distutils command. Once that |
| works, you can run \code{python setup.py upload} to add your package |
| to the PyPI archive. Optionally you can GPG-sign the package by |
| supplying the \longprogramopt{sign} and |
| \longprogramopt{identity} options. |
| |
| Package uploading was implemented by Martin von~L\"owis and Richard Jones. |
| |
| \begin{seealso} |
| |
| \seepep{314}{Metadata for Python Software Packages v1.1}{PEP proposed |
| and written by A.M. Kuchling, Richard Jones, and Fred Drake; |
| implemented by Richard Jones and Fred Drake.} |
| |
| \end{seealso} |
| |
| |
| %====================================================================== |
| \section{PEP 328: Absolute and Relative Imports\label{pep-328}} |
| |
| The simpler part of PEP 328 was implemented in Python 2.4: parentheses |
| could now be used to enclose the names imported from a module using |
| the \code{from ... import ...} statement, making it easier to import |
| many different names. |
| |
| The more complicated part has been implemented in Python 2.5: |
| importing a module can be specified to use absolute or |
| package-relative imports. The plan is to move toward making absolute |
| imports the default in future versions of Python. |
| |
| Let's say you have a package directory like this: |
| \begin{verbatim} |
| pkg/ |
| pkg/__init__.py |
| pkg/main.py |
| pkg/string.py |
| \end{verbatim} |
| |
| This defines a package named \module{pkg} containing the |
| \module{pkg.main} and \module{pkg.string} submodules. |
| |
| Consider the code in the \file{main.py} module. What happens if it |
| executes the statement \code{import string}? In Python 2.4 and |
| earlier, it will first look in the package's directory to perform a |
| relative import, finds \file{pkg/string.py}, imports the contents of |
| that file as the \module{pkg.string} module, and that module is bound |
| to the name \samp{string} in the \module{pkg.main} module's namespace. |
| |
| That's fine if \module{pkg.string} was what you wanted. But what if |
| you wanted Python's standard \module{string} module? There's no clean |
| way to ignore \module{pkg.string} and look for the standard module; |
| generally you had to look at the contents of \code{sys.modules}, which |
| is slightly unclean. |
| Holger Krekel's \module{py.std} package provides a tidier way to perform |
| imports from the standard library, \code{import py ; py.std.string.join()}, |
| but that package isn't available on all Python installations. |
| |
| Reading code which relies on relative imports is also less clear, |
| because a reader may be confused about which module, \module{string} |
| or \module{pkg.string}, is intended to be used. Python users soon |
| learned not to duplicate the names of standard library modules in the |
| names of their packages' submodules, but you can't protect against |
| having your submodule's name being used for a new module added in a |
| future version of Python. |
| |
| In Python 2.5, you can switch \keyword{import}'s behaviour to |
| absolute imports using a \code{from __future__ import absolute_import} |
| directive. This absolute-import behaviour will become the default in |
| a future version (probably Python 2.7). Once absolute imports |
| are the default, \code{import string} will |
| always find the standard library's version. |
| It's suggested that users should begin using absolute imports as much |
| as possible, so it's preferable to begin writing \code{from pkg import |
| string} in your code. |
| |
| Relative imports are still possible by adding a leading period |
| to the module name when using the \code{from ... import} form: |
| |
| \begin{verbatim} |
| # Import names from pkg.string |
| from .string import name1, name2 |
| # Import pkg.string |
| from . import string |
| \end{verbatim} |
| |
| This imports the \module{string} module relative to the current |
| package, so in \module{pkg.main} this will import \var{name1} and |
| \var{name2} from \module{pkg.string}. Additional leading periods |
| perform the relative import starting from the parent of the current |
| package. For example, code in the \module{A.B.C} module can do: |
| |
| \begin{verbatim} |
| from . import D # Imports A.B.D |
| from .. import E # Imports A.E |
| from ..F import G # Imports A.F.G |
| \end{verbatim} |
| |
| Leading periods cannot be used with the \code{import \var{modname}} |
| form of the import statement, only the \code{from ... import} form. |
| |
| \begin{seealso} |
| |
| \seepep{328}{Imports: Multi-Line and Absolute/Relative} |
| {PEP written by Aahz; implemented by Thomas Wouters.} |
| |
| \seeurl{http://codespeak.net/py/current/doc/index.html} |
| {The py library by Holger Krekel, which contains the \module{py.std} package.} |
| |
| \end{seealso} |
| |
| |
| %====================================================================== |
| \section{PEP 338: Executing Modules as Scripts\label{pep-338}} |
| |
| The \programopt{-m} switch added in Python 2.4 to execute a module as |
| a script gained a few more abilities. Instead of being implemented in |
| C code inside the Python interpreter, the switch now uses an |
| implementation in a new module, \module{runpy}. |
| |
| The \module{runpy} module implements a more sophisticated import |
| mechanism so that it's now possible to run modules in a package such |
| as \module{pychecker.checker}. The module also supports alternative |
| import mechanisms such as the \module{zipimport} module. This means |
| you can add a .zip archive's path to \code{sys.path} and then use the |
| \programopt{-m} switch to execute code from the archive. |
| |
| |
| \begin{seealso} |
| |
| \seepep{338}{Executing modules as scripts}{PEP written and |
| implemented by Nick Coghlan.} |
| |
| \end{seealso} |
| |
| |
| %====================================================================== |
| \section{PEP 341: Unified try/except/finally\label{pep-341}} |
| |
| Until Python 2.5, the \keyword{try} statement came in two |
| flavours. You could use a \keyword{finally} block to ensure that code |
| is always executed, or one or more \keyword{except} blocks to catch |
| specific exceptions. You couldn't combine both \keyword{except} blocks and a |
| \keyword{finally} block, because generating the right bytecode for the |
| combined version was complicated and it wasn't clear what the |
| semantics of the combined statement should be. |
| |
| Guido van~Rossum spent some time working with Java, which does support the |
| equivalent of combining \keyword{except} blocks and a |
| \keyword{finally} block, and this clarified what the statement should |
| mean. In Python 2.5, you can now write: |
| |
| \begin{verbatim} |
| try: |
| block-1 ... |
| except Exception1: |
| handler-1 ... |
| except Exception2: |
| handler-2 ... |
| else: |
| else-block |
| finally: |
| final-block |
| \end{verbatim} |
| |
| The code in \var{block-1} is executed. If the code raises an |
| exception, the various \keyword{except} blocks are tested: if the |
| exception is of class \class{Exception1}, \var{handler-1} is executed; |
| otherwise if it's of class \class{Exception2}, \var{handler-2} is |
| executed, and so forth. If no exception is raised, the |
| \var{else-block} is executed. |
| |
| No matter what happened previously, the \var{final-block} is executed |
| once the code block is complete and any raised exceptions handled. |
| Even if there's an error in an exception handler or the |
| \var{else-block} and a new exception is raised, the |
| code in the \var{final-block} is still run. |
| |
| \begin{seealso} |
| |
| \seepep{341}{Unifying try-except and try-finally}{PEP written by Georg Brandl; |
| implementation by Thomas Lee.} |
| |
| \end{seealso} |
| |
| |
| %====================================================================== |
| \section{PEP 342: New Generator Features\label{pep-342}} |
| |
| Python 2.5 adds a simple way to pass values \emph{into} a generator. |
| As introduced in Python 2.3, generators only produce output; once a |
| generator's code was invoked to create an iterator, there was no way to |
| pass any new information into the function when its execution is |
| resumed. Sometimes the ability to pass in some information would be |
| useful. Hackish solutions to this include making the generator's code |
| look at a global variable and then changing the global variable's |
| value, or passing in some mutable object that callers then modify. |
| |
| To refresh your memory of basic generators, here's a simple example: |
| |
| \begin{verbatim} |
| def counter (maximum): |
| i = 0 |
| while i < maximum: |
| yield i |
| i += 1 |
| \end{verbatim} |
| |
| When you call \code{counter(10)}, the result is an iterator that |
| returns the values from 0 up to 9. On encountering the |
| \keyword{yield} statement, the iterator returns the provided value and |
| suspends the function's execution, preserving the local variables. |
| Execution resumes on the following call to the iterator's |
| \method{next()} method, picking up after the \keyword{yield} statement. |
| |
| In Python 2.3, \keyword{yield} was a statement; it didn't return any |
| value. In 2.5, \keyword{yield} is now an expression, returning a |
| value that can be assigned to a variable or otherwise operated on: |
| |
| \begin{verbatim} |
| val = (yield i) |
| \end{verbatim} |
| |
| I recommend that you always put parentheses around a \keyword{yield} |
| expression when you're doing something with the returned value, as in |
| the above example. The parentheses aren't always necessary, but it's |
| easier to always add them instead of having to remember when they're |
| needed. |
| |
| (\pep{342} explains the exact rules, which are that a |
| \keyword{yield}-expression must always be parenthesized except when it |
| occurs at the top-level expression on the right-hand side of an |
| assignment. This means you can write \code{val = yield i} but have to |
| use parentheses when there's an operation, as in \code{val = (yield i) |
| + 12}.) |
| |
| Values are sent into a generator by calling its |
| \method{send(\var{value})} method. The generator's code is then |
| resumed and the \keyword{yield} expression returns the specified |
| \var{value}. If the regular \method{next()} method is called, the |
| \keyword{yield} returns \constant{None}. |
| |
| Here's the previous example, modified to allow changing the value of |
| the internal counter. |
| |
| \begin{verbatim} |
| def counter (maximum): |
| i = 0 |
| while i < maximum: |
| val = (yield i) |
| # If value provided, change counter |
| if val is not None: |
| i = val |
| else: |
| i += 1 |
| \end{verbatim} |
| |
| And here's an example of changing the counter: |
| |
| \begin{verbatim} |
| >>> it = counter(10) |
| >>> print it.next() |
| 0 |
| >>> print it.next() |
| 1 |
| >>> print it.send(8) |
| 8 |
| >>> print it.next() |
| 9 |
| >>> print it.next() |
| Traceback (most recent call last): |
| File ``t.py'', line 15, in ? |
| print it.next() |
| StopIteration |
| \end{verbatim} |
| |
| \keyword{yield} will usually return \constant{None}, so you |
| should always check for this case. Don't just use its value in |
| expressions unless you're sure that the \method{send()} method |
| will be the only method used to resume your generator function. |
| |
| In addition to \method{send()}, there are two other new methods on |
| generators: |
| |
| \begin{itemize} |
| |
| \item \method{throw(\var{type}, \var{value}=None, |
| \var{traceback}=None)} is used to raise an exception inside the |
| generator; the exception is raised by the \keyword{yield} expression |
| where the generator's execution is paused. |
| |
| \item \method{close()} raises a new \exception{GeneratorExit} |
| exception inside the generator to terminate the iteration. |
| On receiving this |
| exception, the generator's code must either raise |
| \exception{GeneratorExit} or \exception{StopIteration}; catching the |
| exception and doing anything else is illegal and will trigger |
| a \exception{RuntimeError}. \method{close()} will also be called by |
| Python's garbage collector when the generator is garbage-collected. |
| |
| If you need to run cleanup code when a \exception{GeneratorExit} occurs, |
| I suggest using a \code{try: ... finally:} suite instead of |
| catching \exception{GeneratorExit}. |
| |
| \end{itemize} |
| |
| The cumulative effect of these changes is to turn generators from |
| one-way producers of information into both producers and consumers. |
| |
| Generators also become \emph{coroutines}, a more generalized form of |
| subroutines. Subroutines are entered at one point and exited at |
| another point (the top of the function, and a \keyword{return} |
| statement), but coroutines can be entered, exited, and resumed at |
| many different points (the \keyword{yield} statements). We'll have to |
| figure out patterns for using coroutines effectively in Python. |
| |
| The addition of the \method{close()} method has one side effect that |
| isn't obvious. \method{close()} is called when a generator is |
| garbage-collected, so this means the generator's code gets one last |
| chance to run before the generator is destroyed. This last chance |
| means that \code{try...finally} statements in generators can now be |
| guaranteed to work; the \keyword{finally} clause will now always get a |
| chance to run. The syntactic restriction that you couldn't mix |
| \keyword{yield} statements with a \code{try...finally} suite has |
| therefore been removed. This seems like a minor bit of language |
| trivia, but using generators and \code{try...finally} is actually |
| necessary in order to implement the \keyword{with} statement |
| described by PEP 343. I'll look at this new statement in the following |
| section. |
| |
| Another even more esoteric effect of this change: previously, the |
| \member{gi_frame} attribute of a generator was always a frame object. |
| It's now possible for \member{gi_frame} to be \code{None} |
| once the generator has been exhausted. |
| |
| \begin{seealso} |
| |
| \seepep{342}{Coroutines via Enhanced Generators}{PEP written by |
| Guido van~Rossum and Phillip J. Eby; |
| implemented by Phillip J. Eby. Includes examples of |
| some fancier uses of generators as coroutines. |
| |
| Earlier versions of these features were proposed in |
| \pep{288} by Raymond Hettinger and \pep{325} by Samuele Pedroni. |
| } |
| |
| \seeurl{http://en.wikipedia.org/wiki/Coroutine}{The Wikipedia entry for |
| coroutines.} |
| |
| \seeurl{http://www.sidhe.org/\~{}dan/blog/archives/000178.html}{An |
| explanation of coroutines from a Perl point of view, written by Dan |
| Sugalski.} |
| |
| \end{seealso} |
| |
| |
| %====================================================================== |
| \section{PEP 343: The 'with' statement\label{pep-343}} |
| |
| The '\keyword{with}' statement clarifies code that previously would |
| use \code{try...finally} blocks to ensure that clean-up code is |
| executed. In this section, I'll discuss the statement as it will |
| commonly be used. In the next section, I'll examine the |
| implementation details and show how to write objects for use with this |
| statement. |
| |
| The '\keyword{with}' statement is a new control-flow structure whose |
| basic structure is: |
| |
| \begin{verbatim} |
| with expression [as variable]: |
| with-block |
| \end{verbatim} |
| |
| The expression is evaluated, and it should result in an object that |
| supports the context management protocol. This object may return a |
| value that can optionally be bound to the name \var{variable}. (Note |
| carefully that \var{variable} is \emph{not} assigned the result of |
| \var{expression}.) The object can then run set-up code |
| before \var{with-block} is executed and some clean-up code |
| is executed after the block is done, even if the block raised an exception. |
| |
| To enable the statement in Python 2.5, you need |
| to add the following directive to your module: |
| |
| \begin{verbatim} |
| from __future__ import with_statement |
| \end{verbatim} |
| |
| The statement will always be enabled in Python 2.6. |
| |
| Some standard Python objects now support the context management |
| protocol and can be used with the '\keyword{with}' statement. File |
| objects are one example: |
| |
| \begin{verbatim} |
| with open('/etc/passwd', 'r') as f: |
| for line in f: |
| print line |
| ... more processing code ... |
| \end{verbatim} |
| |
| After this statement has executed, the file object in \var{f} will |
| have been automatically closed, even if the 'for' loop |
| raised an exception part-way through the block. |
| |
| The \module{threading} module's locks and condition variables |
| also support the '\keyword{with}' statement: |
| |
| \begin{verbatim} |
| lock = threading.Lock() |
| with lock: |
| # Critical section of code |
| ... |
| \end{verbatim} |
| |
| The lock is acquired before the block is executed and always released once |
| the block is complete. |
| |
| The new \function{localcontext()} function in the \module{decimal} module |
| makes it easy to save and restore the current decimal context, which |
| encapsulates the desired precision and rounding characteristics for |
| computations: |
| |
| \begin{verbatim} |
| from decimal import Decimal, Context, localcontext |
| |
| # Displays with default precision of 28 digits |
| v = Decimal('578') |
| print v.sqrt() |
| |
| with localcontext(Context(prec=16)): |
| # All code in this block uses a precision of 16 digits. |
| # The original context is restored on exiting the block. |
| print v.sqrt() |
| \end{verbatim} |
| |
| \subsection{Writing Context Managers\label{context-managers}} |
| |
| Under the hood, the '\keyword{with}' statement is fairly complicated. |
| Most people will only use '\keyword{with}' in company with existing |
| objects and don't need to know these details, so you can skip the rest |
| of this section if you like. Authors of new objects will need to |
| understand the details of the underlying implementation and should |
| keep reading. |
| |
| A high-level explanation of the context management protocol is: |
| |
| \begin{itemize} |
| |
| \item The expression is evaluated and should result in an object |
| called a ``context manager''. The context manager must have |
| \method{__enter__()} and \method{__exit__()} methods. |
| |
| \item The context manager's \method{__enter__()} method is called. The value |
| returned is assigned to \var{VAR}. If no \code{'as \var{VAR}'} clause |
| is present, the value is simply discarded. |
| |
| \item The code in \var{BLOCK} is executed. |
| |
| \item If \var{BLOCK} raises an exception, the |
| \method{__exit__(\var{type}, \var{value}, \var{traceback})} is called |
| with the exception details, the same values returned by |
| \function{sys.exc_info()}. The method's return value controls whether |
| the exception is re-raised: any false value re-raises the exception, |
| and \code{True} will result in suppressing it. You'll only rarely |
| want to suppress the exception, because if you do |
| the author of the code containing the |
| '\keyword{with}' statement will never realize anything went wrong. |
| |
| \item If \var{BLOCK} didn't raise an exception, |
| the \method{__exit__()} method is still called, |
| but \var{type}, \var{value}, and \var{traceback} are all \code{None}. |
| |
| \end{itemize} |
| |
| Let's think through an example. I won't present detailed code but |
| will only sketch the methods necessary for a database that supports |
| transactions. |
| |
| (For people unfamiliar with database terminology: a set of changes to |
| the database are grouped into a transaction. Transactions can be |
| either committed, meaning that all the changes are written into the |
| database, or rolled back, meaning that the changes are all discarded |
| and the database is unchanged. See any database textbook for more |
| information.) |
| |
| Let's assume there's an object representing a database connection. |
| Our goal will be to let the user write code like this: |
| |
| \begin{verbatim} |
| db_connection = DatabaseConnection() |
| with db_connection as cursor: |
| cursor.execute('insert into ...') |
| cursor.execute('delete from ...') |
| # ... more operations ... |
| \end{verbatim} |
| |
| The transaction should be committed if the code in the block |
| runs flawlessly or rolled back if there's an exception. |
| Here's the basic interface |
| for \class{DatabaseConnection} that I'll assume: |
| |
| \begin{verbatim} |
| class DatabaseConnection: |
| # Database interface |
| def cursor (self): |
| "Returns a cursor object and starts a new transaction" |
| def commit (self): |
| "Commits current transaction" |
| def rollback (self): |
| "Rolls back current transaction" |
| \end{verbatim} |
| |
| The \method {__enter__()} method is pretty easy, having only to start |
| a new transaction. For this application the resulting cursor object |
| would be a useful result, so the method will return it. The user can |
| then add \code{as cursor} to their '\keyword{with}' statement to bind |
| the cursor to a variable name. |
| |
| \begin{verbatim} |
| class DatabaseConnection: |
| ... |
| def __enter__ (self): |
| # Code to start a new transaction |
| cursor = self.cursor() |
| return cursor |
| \end{verbatim} |
| |
| The \method{__exit__()} method is the most complicated because it's |
| where most of the work has to be done. The method has to check if an |
| exception occurred. If there was no exception, the transaction is |
| committed. The transaction is rolled back if there was an exception. |
| |
| In the code below, execution will just fall off the end of the |
| function, returning the default value of \code{None}. \code{None} is |
| false, so the exception will be re-raised automatically. If you |
| wished, you could be more explicit and add a \keyword{return} |
| statement at the marked location. |
| |
| \begin{verbatim} |
| class DatabaseConnection: |
| ... |
| def __exit__ (self, type, value, tb): |
| if tb is None: |
| # No exception, so commit |
| self.commit() |
| else: |
| # Exception occurred, so rollback. |
| self.rollback() |
| # return False |
| \end{verbatim} |
| |
| |
| \subsection{The contextlib module\label{module-contextlib}} |
| |
| The new \module{contextlib} module provides some functions and a |
| decorator that are useful for writing objects for use with the |
| '\keyword{with}' statement. |
| |
| The decorator is called \function{contextmanager}, and lets you write |
| a single generator function instead of defining a new class. The generator |
| should yield exactly one value. The code up to the \keyword{yield} |
| will be executed as the \method{__enter__()} method, and the value |
| yielded will be the method's return value that will get bound to the |
| variable in the '\keyword{with}' statement's \keyword{as} clause, if |
| any. The code after the \keyword{yield} will be executed in the |
| \method{__exit__()} method. Any exception raised in the block will be |
| raised by the \keyword{yield} statement. |
| |
| Our database example from the previous section could be written |
| using this decorator as: |
| |
| \begin{verbatim} |
| from contextlib import contextmanager |
| |
| @contextmanager |
| def db_transaction (connection): |
| cursor = connection.cursor() |
| try: |
| yield cursor |
| except: |
| connection.rollback() |
| raise |
| else: |
| connection.commit() |
| |
| db = DatabaseConnection() |
| with db_transaction(db) as cursor: |
| ... |
| \end{verbatim} |
| |
| The \module{contextlib} module also has a \function{nested(\var{mgr1}, |
| \var{mgr2}, ...)} function that combines a number of context managers so you |
| don't need to write nested '\keyword{with}' statements. In this |
| example, the single '\keyword{with}' statement both starts a database |
| transaction and acquires a thread lock: |
| |
| \begin{verbatim} |
| lock = threading.Lock() |
| with nested (db_transaction(db), lock) as (cursor, locked): |
| ... |
| \end{verbatim} |
| |
| Finally, the \function{closing(\var{object})} function |
| returns \var{object} so that it can be bound to a variable, |
| and calls \code{\var{object}.close()} at the end of the block. |
| |
| \begin{verbatim} |
| import urllib, sys |
| from contextlib import closing |
| |
| with closing(urllib.urlopen('http://www.yahoo.com')) as f: |
| for line in f: |
| sys.stdout.write(line) |
| \end{verbatim} |
| |
| \begin{seealso} |
| |
| \seepep{343}{The ``with'' statement}{PEP written by Guido van~Rossum |
| and Nick Coghlan; implemented by Mike Bland, Guido van~Rossum, and |
| Neal Norwitz. The PEP shows the code generated for a '\keyword{with}' |
| statement, which can be helpful in learning how the statement works.} |
| |
| \seeurl{../lib/module-contextlib.html}{The documentation |
| for the \module{contextlib} module.} |
| |
| \end{seealso} |
| |
| |
| %====================================================================== |
| \section{PEP 352: Exceptions as New-Style Classes\label{pep-352}} |
| |
| Exception classes can now be new-style classes, not just classic |
| classes, and the built-in \exception{Exception} class and all the |
| standard built-in exceptions (\exception{NameError}, |
| \exception{ValueError}, etc.) are now new-style classes. |
| |
| The inheritance hierarchy for exceptions has been rearranged a bit. |
| In 2.5, the inheritance relationships are: |
| |
| \begin{verbatim} |
| BaseException # New in Python 2.5 |
| |- KeyboardInterrupt |
| |- SystemExit |
| |- Exception |
| |- (all other current built-in exceptions) |
| \end{verbatim} |
| |
| This rearrangement was done because people often want to catch all |
| exceptions that indicate program errors. \exception{KeyboardInterrupt} and |
| \exception{SystemExit} aren't errors, though, and usually represent an explicit |
| action such as the user hitting Control-C or code calling |
| \function{sys.exit()}. A bare \code{except:} will catch all exceptions, |
| so you commonly need to list \exception{KeyboardInterrupt} and |
| \exception{SystemExit} in order to re-raise them. The usual pattern is: |
| |
| \begin{verbatim} |
| try: |
| ... |
| except (KeyboardInterrupt, SystemExit): |
| raise |
| except: |
| # Log error... |
| # Continue running program... |
| \end{verbatim} |
| |
| In Python 2.5, you can now write \code{except Exception} to achieve |
| the same result, catching all the exceptions that usually indicate errors |
| but leaving \exception{KeyboardInterrupt} and |
| \exception{SystemExit} alone. As in previous versions, |
| a bare \code{except:} still catches all exceptions. |
| |
| The goal for Python 3.0 is to require any class raised as an exception |
| to derive from \exception{BaseException} or some descendant of |
| \exception{BaseException}, and future releases in the |
| Python 2.x series may begin to enforce this constraint. Therefore, I |
| suggest you begin making all your exception classes derive from |
| \exception{Exception} now. It's been suggested that the bare |
| \code{except:} form should be removed in Python 3.0, but Guido van~Rossum |
| hasn't decided whether to do this or not. |
| |
| Raising of strings as exceptions, as in the statement \code{raise |
| "Error occurred"}, is deprecated in Python 2.5 and will trigger a |
| warning. The aim is to be able to remove the string-exception feature |
| in a few releases. |
| |
| |
| \begin{seealso} |
| |
| \seepep{352}{Required Superclass for Exceptions}{PEP written by |
| Brett Cannon and Guido van~Rossum; implemented by Brett Cannon.} |
| |
| \end{seealso} |
| |
| |
| %====================================================================== |
| \section{PEP 353: Using ssize_t as the index type\label{pep-353}} |
| |
| A wide-ranging change to Python's C API, using a new |
| \ctype{Py_ssize_t} type definition instead of \ctype{int}, |
| will permit the interpreter to handle more data on 64-bit platforms. |
| This change doesn't affect Python's capacity on 32-bit platforms. |
| |
| Various pieces of the Python interpreter used C's \ctype{int} type to |
| store sizes or counts; for example, the number of items in a list or |
| tuple were stored in an \ctype{int}. The C compilers for most 64-bit |
| platforms still define \ctype{int} as a 32-bit type, so that meant |
| that lists could only hold up to \code{2**31 - 1} = 2147483647 items. |
| (There are actually a few different programming models that 64-bit C |
| compilers can use -- see |
| \url{http://www.unix.org/version2/whatsnew/lp64_wp.html} for a |
| discussion -- but the most commonly available model leaves \ctype{int} |
| as 32 bits.) |
| |
| A limit of 2147483647 items doesn't really matter on a 32-bit platform |
| because you'll run out of memory before hitting the length limit. |
| Each list item requires space for a pointer, which is 4 bytes, plus |
| space for a \ctype{PyObject} representing the item. 2147483647*4 is |
| already more bytes than a 32-bit address space can contain. |
| |
| It's possible to address that much memory on a 64-bit platform, |
| however. The pointers for a list that size would only require 16~GiB |
| of space, so it's not unreasonable that Python programmers might |
| construct lists that large. Therefore, the Python interpreter had to |
| be changed to use some type other than \ctype{int}, and this will be a |
| 64-bit type on 64-bit platforms. The change will cause |
| incompatibilities on 64-bit machines, so it was deemed worth making |
| the transition now, while the number of 64-bit users is still |
| relatively small. (In 5 or 10 years, we may \emph{all} be on 64-bit |
| machines, and the transition would be more painful then.) |
| |
| This change most strongly affects authors of C extension modules. |
| Python strings and container types such as lists and tuples |
| now use \ctype{Py_ssize_t} to store their size. |
| Functions such as \cfunction{PyList_Size()} |
| now return \ctype{Py_ssize_t}. Code in extension modules |
| may therefore need to have some variables changed to |
| \ctype{Py_ssize_t}. |
| |
| The \cfunction{PyArg_ParseTuple()} and \cfunction{Py_BuildValue()} functions |
| have a new conversion code, \samp{n}, for \ctype{Py_ssize_t}. |
| \cfunction{PyArg_ParseTuple()}'s \samp{s\#} and \samp{t\#} still output |
| \ctype{int} by default, but you can define the macro |
| \csimplemacro{PY_SSIZE_T_CLEAN} before including \file{Python.h} |
| to make them return \ctype{Py_ssize_t}. |
| |
| \pep{353} has a section on conversion guidelines that |
| extension authors should read to learn about supporting 64-bit |
| platforms. |
| |
| \begin{seealso} |
| |
| \seepep{353}{Using ssize_t as the index type}{PEP written and implemented by Martin von~L\"owis.} |
| |
| \end{seealso} |
| |
| |
| %====================================================================== |
| \section{PEP 357: The '__index__' method\label{pep-357}} |
| |
| The NumPy developers had a problem that could only be solved by adding |
| a new special method, \method{__index__}. When using slice notation, |
| as in \code{[\var{start}:\var{stop}:\var{step}]}, the values of the |
| \var{start}, \var{stop}, and \var{step} indexes must all be either |
| integers or long integers. NumPy defines a variety of specialized |
| integer types corresponding to unsigned and signed integers of 8, 16, |
| 32, and 64 bits, but there was no way to signal that these types could |
| be used as slice indexes. |
| |
| Slicing can't just use the existing \method{__int__} method because |
| that method is also used to implement coercion to integers. If |
| slicing used \method{__int__}, floating-point numbers would also |
| become legal slice indexes and that's clearly an undesirable |
| behaviour. |
| |
| Instead, a new special method called \method{__index__} was added. It |
| takes no arguments and returns an integer giving the slice index to |
| use. For example: |
| |
| \begin{verbatim} |
| class C: |
| def __index__ (self): |
| return self.value |
| \end{verbatim} |
| |
| The return value must be either a Python integer or long integer. |
| The interpreter will check that the type returned is correct, and |
| raises a \exception{TypeError} if this requirement isn't met. |
| |
| A corresponding \member{nb_index} slot was added to the C-level |
| \ctype{PyNumberMethods} structure to let C extensions implement this |
| protocol. \cfunction{PyNumber_Index(\var{obj})} can be used in |
| extension code to call the \method{__index__} function and retrieve |
| its result. |
| |
| \begin{seealso} |
| |
| \seepep{357}{Allowing Any Object to be Used for Slicing}{PEP written |
| and implemented by Travis Oliphant.} |
| |
| \end{seealso} |
| |
| |
| %====================================================================== |
| \section{Other Language Changes\label{other-lang}} |
| |
| Here are all of the changes that Python 2.5 makes to the core Python |
| language. |
| |
| \begin{itemize} |
| |
| \item The \class{dict} type has a new hook for letting subclasses |
| provide a default value when a key isn't contained in the dictionary. |
| When a key isn't found, the dictionary's |
| \method{__missing__(\var{key})} |
| method will be called. This hook is used to implement |
| the new \class{defaultdict} class in the \module{collections} |
| module. The following example defines a dictionary |
| that returns zero for any missing key: |
| |
| \begin{verbatim} |
| class zerodict (dict): |
| def __missing__ (self, key): |
| return 0 |
| |
| d = zerodict({1:1, 2:2}) |
| print d[1], d[2] # Prints 1, 2 |
| print d[3], d[4] # Prints 0, 0 |
| \end{verbatim} |
| |
| \item Both 8-bit and Unicode strings have new \method{partition(sep)} |
| and \method{rpartition(sep)} methods that simplify a common use case. |
| |
| The \method{find(S)} method is often used to get an index which is |
| then used to slice the string and obtain the pieces that are before |
| and after the separator. |
| \method{partition(sep)} condenses this |
| pattern into a single method call that returns a 3-tuple containing |
| the substring before the separator, the separator itself, and the |
| substring after the separator. If the separator isn't found, the |
| first element of the tuple is the entire string and the other two |
| elements are empty. \method{rpartition(sep)} also returns a 3-tuple |
| but starts searching from the end of the string; the \samp{r} stands |
| for 'reverse'. |
| |
| Some examples: |
| |
| \begin{verbatim} |
| >>> ('http://www.python.org').partition('://') |
| ('http', '://', 'www.python.org') |
| >>> ('file:/usr/share/doc/index.html').partition('://') |
| ('file:/usr/share/doc/index.html', '', '') |
| >>> (u'Subject: a quick question').partition(':') |
| (u'Subject', u':', u' a quick question') |
| >>> 'www.python.org'.rpartition('.') |
| ('www.python', '.', 'org') |
| >>> 'www.python.org'.rpartition(':') |
| ('', '', 'www.python.org') |
| \end{verbatim} |
| |
| (Implemented by Fredrik Lundh following a suggestion by Raymond Hettinger.) |
| |
| \item The \method{startswith()} and \method{endswith()} methods |
| of string types now accept tuples of strings to check for. |
| |
| \begin{verbatim} |
| def is_image_file (filename): |
| return filename.endswith(('.gif', '.jpg', '.tiff')) |
| \end{verbatim} |
| |
| (Implemented by Georg Brandl following a suggestion by Tom Lynn.) |
| % RFE #1491485 |
| |
| \item The \function{min()} and \function{max()} built-in functions |
| gained a \code{key} keyword parameter analogous to the \code{key} |
| argument for \method{sort()}. This parameter supplies a function that |
| takes a single argument and is called for every value in the list; |
| \function{min()}/\function{max()} will return the element with the |
| smallest/largest return value from this function. |
| For example, to find the longest string in a list, you can do: |
| |
| \begin{verbatim} |
| L = ['medium', 'longest', 'short'] |
| # Prints 'longest' |
| print max(L, key=len) |
| # Prints 'short', because lexicographically 'short' has the largest value |
| print max(L) |
| \end{verbatim} |
| |
| (Contributed by Steven Bethard and Raymond Hettinger.) |
| |
| \item Two new built-in functions, \function{any()} and |
| \function{all()}, evaluate whether an iterator contains any true or |
| false values. \function{any()} returns \constant{True} if any value |
| returned by the iterator is true; otherwise it will return |
| \constant{False}. \function{all()} returns \constant{True} only if |
| all of the values returned by the iterator evaluate as true. |
| (Suggested by Guido van~Rossum, and implemented by Raymond Hettinger.) |
| |
| \item The result of a class's \method{__hash__()} method can now |
| be either a long integer or a regular integer. If a long integer is |
| returned, the hash of that value is taken. In earlier versions the |
| hash value was required to be a regular integer, but in 2.5 the |
| \function{id()} built-in was changed to always return non-negative |
| numbers, and users often seem to use \code{id(self)} in |
| \method{__hash__()} methods (though this is discouraged). |
| % Bug #1536021 |
| |
| \item ASCII is now the default encoding for modules. It's now |
| a syntax error if a module contains string literals with 8-bit |
| characters but doesn't have an encoding declaration. In Python 2.4 |
| this triggered a warning, not a syntax error. See \pep{263} |
| for how to declare a module's encoding; for example, you might add |
| a line like this near the top of the source file: |
| |
| \begin{verbatim} |
| # -*- coding: latin1 -*- |
| \end{verbatim} |
| |
| \item A new warning, \class{UnicodeWarning}, is triggered when |
| you attempt to compare a Unicode string and an 8-bit string |
| that can't be converted to Unicode using the default ASCII encoding. |
| The result of the comparison is false: |
| |
| \begin{verbatim} |
| >>> chr(128) == unichr(128) # Can't convert chr(128) to Unicode |
| __main__:1: UnicodeWarning: Unicode equal comparison failed |
| to convert both arguments to Unicode - interpreting them |
| as being unequal |
| False |
| >>> chr(127) == unichr(127) # chr(127) can be converted |
| True |
| \end{verbatim} |
| |
| Previously this would raise a \class{UnicodeDecodeError} exception, |
| but in 2.5 this could result in puzzling problems when accessing a |
| dictionary. If you looked up \code{unichr(128)} and \code{chr(128)} |
| was being used as a key, you'd get a \class{UnicodeDecodeError} |
| exception. Other changes in 2.5 resulted in this exception being |
| raised instead of suppressed by the code in \file{dictobject.c} that |
| implements dictionaries. |
| |
| Raising an exception for such a comparison is strictly correct, but |
| the change might have broken code, so instead |
| \class{UnicodeWarning} was introduced. |
| |
| (Implemented by Marc-Andr\'e Lemburg.) |
| |
| \item One error that Python programmers sometimes make is forgetting |
| to include an \file{__init__.py} module in a package directory. |
| Debugging this mistake can be confusing, and usually requires running |
| Python with the \programopt{-v} switch to log all the paths searched. |
| In Python 2.5, a new \exception{ImportWarning} warning is triggered when |
| an import would have picked up a directory as a package but no |
| \file{__init__.py} was found. This warning is silently ignored by default; |
| provide the \programopt{-Wd} option when running the Python executable |
| to display the warning message. |
| (Implemented by Thomas Wouters.) |
| |
| \item The list of base classes in a class definition can now be empty. |
| As an example, this is now legal: |
| |
| \begin{verbatim} |
| class C(): |
| pass |
| \end{verbatim} |
| (Implemented by Brett Cannon.) |
| |
| \end{itemize} |
| |
| |
| %====================================================================== |
| \subsection{Interactive Interpreter Changes\label{interactive}} |
| |
| In the interactive interpreter, \code{quit} and \code{exit} |
| have long been strings so that new users get a somewhat helpful message |
| when they try to quit: |
| |
| \begin{verbatim} |
| >>> quit |
| 'Use Ctrl-D (i.e. EOF) to exit.' |
| \end{verbatim} |
| |
| In Python 2.5, \code{quit} and \code{exit} are now objects that still |
| produce string representations of themselves, but are also callable. |
| Newbies who try \code{quit()} or \code{exit()} will now exit the |
| interpreter as they expect. (Implemented by Georg Brandl.) |
| |
| The Python executable now accepts the standard long options |
| \longprogramopt{help} and \longprogramopt{version}; on Windows, |
| it also accepts the \programopt{/?} option for displaying a help message. |
| (Implemented by Georg Brandl.) |
| |
| |
| %====================================================================== |
| \subsection{Optimizations\label{opts}} |
| |
| Several of the optimizations were developed at the NeedForSpeed |
| sprint, an event held in Reykjavik, Iceland, from May 21--28 2006. |
| The sprint focused on speed enhancements to the CPython implementation |
| and was funded by EWT LLC with local support from CCP Games. Those |
| optimizations added at this sprint are specially marked in the |
| following list. |
| |
| \begin{itemize} |
| |
| \item When they were introduced |
| in Python 2.4, the built-in \class{set} and \class{frozenset} types |
| were built on top of Python's dictionary type. |
| In 2.5 the internal data structure has been customized for implementing sets, |
| and as a result sets will use a third less memory and are somewhat faster. |
| (Implemented by Raymond Hettinger.) |
| |
| \item The speed of some Unicode operations, such as finding |
| substrings, string splitting, and character map encoding and decoding, |
| has been improved. (Substring search and splitting improvements were |
| added by Fredrik Lundh and Andrew Dalke at the NeedForSpeed |
| sprint. Character maps were improved by Walter D\"orwald and |
| Martin von~L\"owis.) |
| % Patch 1313939, 1359618 |
| |
| \item The \function{long(\var{str}, \var{base})} function is now |
| faster on long digit strings because fewer intermediate results are |
| calculated. The peak is for strings of around 800--1000 digits where |
| the function is 6 times faster. |
| (Contributed by Alan McIntyre and committed at the NeedForSpeed sprint.) |
| % Patch 1442927 |
| |
| \item The \module{struct} module now compiles structure format |
| strings into an internal representation and caches this |
| representation, yielding a 20\% speedup. (Contributed by Bob Ippolito |
| at the NeedForSpeed sprint.) |
| |
| \item The \module{re} module got a 1 or 2\% speedup by switching to |
| Python's allocator functions instead of the system's |
| \cfunction{malloc()} and \cfunction{free()}. |
| (Contributed by Jack Diederich at the NeedForSpeed sprint.) |
| |
| \item The code generator's peephole optimizer now performs |
| simple constant folding in expressions. If you write something like |
| \code{a = 2+3}, the code generator will do the arithmetic and produce |
| code corresponding to \code{a = 5}. (Proposed and implemented |
| by Raymond Hettinger.) |
| |
| \item Function calls are now faster because code objects now keep |
| the most recently finished frame (a ``zombie frame'') in an internal |
| field of the code object, reusing it the next time the code object is |
| invoked. (Original patch by Michael Hudson, modified by Armin Rigo |
| and Richard Jones; committed at the NeedForSpeed sprint.) |
| % Patch 876206 |
| |
| Frame objects are also slightly smaller, which may improve cache locality |
| and reduce memory usage a bit. (Contributed by Neal Norwitz.) |
| % Patch 1337051 |
| |
| \item Python's built-in exceptions are now new-style classes, a change |
| that speeds up instantiation considerably. Exception handling in |
| Python 2.5 is therefore about 30\% faster than in 2.4. |
| (Contributed by Richard Jones, Georg Brandl and Sean Reifschneider at |
| the NeedForSpeed sprint.) |
| |
| \item Importing now caches the paths tried, recording whether |
| they exist or not so that the interpreter makes fewer |
| \cfunction{open()} and \cfunction{stat()} calls on startup. |
| (Contributed by Martin von~L\"owis and Georg Brandl.) |
| % Patch 921466 |
| |
| \end{itemize} |
| |
| |
| %====================================================================== |
| \section{New, Improved, and Removed Modules\label{modules}} |
| |
| The standard library received many enhancements and bug fixes in |
| Python 2.5. Here's a partial list of the most notable changes, sorted |
| alphabetically by module name. Consult the \file{Misc/NEWS} file in |
| the source tree for a more complete list of changes, or look through |
| the SVN logs for all the details. |
| |
| \begin{itemize} |
| |
| \item The \module{audioop} module now supports the a-LAW encoding, |
| and the code for u-LAW encoding has been improved. (Contributed by |
| Lars Immisch.) |
| |
| \item The \module{codecs} module gained support for incremental |
| codecs. The \function{codec.lookup()} function now |
| returns a \class{CodecInfo} instance instead of a tuple. |
| \class{CodecInfo} instances behave like a 4-tuple to preserve backward |
| compatibility but also have the attributes \member{encode}, |
| \member{decode}, \member{incrementalencoder}, \member{incrementaldecoder}, |
| \member{streamwriter}, and \member{streamreader}. Incremental codecs |
| can receive input and produce output in multiple chunks; the output is |
| the same as if the entire input was fed to the non-incremental codec. |
| See the \module{codecs} module documentation for details. |
| (Designed and implemented by Walter D\"orwald.) |
| % Patch 1436130 |
| |
| \item The \module{collections} module gained a new type, |
| \class{defaultdict}, that subclasses the standard \class{dict} |
| type. The new type mostly behaves like a dictionary but constructs a |
| default value when a key isn't present, automatically adding it to the |
| dictionary for the requested key value. |
| |
| The first argument to \class{defaultdict}'s constructor is a factory |
| function that gets called whenever a key is requested but not found. |
| This factory function receives no arguments, so you can use built-in |
| type constructors such as \function{list()} or \function{int()}. For |
| example, |
| you can make an index of words based on their initial letter like this: |
| |
| \begin{verbatim} |
| words = """Nel mezzo del cammin di nostra vita |
| mi ritrovai per una selva oscura |
| che la diritta via era smarrita""".lower().split() |
| |
| index = defaultdict(list) |
| |
| for w in words: |
| init_letter = w[0] |
| index[init_letter].append(w) |
| \end{verbatim} |
| |
| Printing \code{index} results in the following output: |
| |
| \begin{verbatim} |
| defaultdict(<type 'list'>, {'c': ['cammin', 'che'], 'e': ['era'], |
| 'd': ['del', 'di', 'diritta'], 'm': ['mezzo', 'mi'], |
| 'l': ['la'], 'o': ['oscura'], 'n': ['nel', 'nostra'], |
| 'p': ['per'], 's': ['selva', 'smarrita'], |
| 'r': ['ritrovai'], 'u': ['una'], 'v': ['vita', 'via']} |
| \end{verbatim} |
| |
| (Contributed by Guido van~Rossum.) |
| |
| \item The \class{deque} double-ended queue type supplied by the |
| \module{collections} module now has a \method{remove(\var{value})} |
| method that removes the first occurrence of \var{value} in the queue, |
| raising \exception{ValueError} if the value isn't found. |
| (Contributed by Raymond Hettinger.) |
| |
| \item New module: The \module{contextlib} module contains helper functions for use |
| with the new '\keyword{with}' statement. See |
| section~\ref{module-contextlib} for more about this module. |
| |
| \item New module: The \module{cProfile} module is a C implementation of |
| the existing \module{profile} module that has much lower overhead. |
| The module's interface is the same as \module{profile}: you run |
| \code{cProfile.run('main()')} to profile a function, can save profile |
| data to a file, etc. It's not yet known if the Hotshot profiler, |
| which is also written in C but doesn't match the \module{profile} |
| module's interface, will continue to be maintained in future versions |
| of Python. (Contributed by Armin Rigo.) |
| |
| Also, the \module{pstats} module for analyzing the data measured by |
| the profiler now supports directing the output to any file object |
| by supplying a \var{stream} argument to the \class{Stats} constructor. |
| (Contributed by Skip Montanaro.) |
| |
| \item The \module{csv} module, which parses files in |
| comma-separated value format, received several enhancements and a |
| number of bugfixes. You can now set the maximum size in bytes of a |
| field by calling the \method{csv.field_size_limit(\var{new_limit})} |
| function; omitting the \var{new_limit} argument will return the |
| currently-set limit. The \class{reader} class now has a |
| \member{line_num} attribute that counts the number of physical lines |
| read from the source; records can span multiple physical lines, so |
| \member{line_num} is not the same as the number of records read. |
| |
| The CSV parser is now stricter about multi-line quoted |
| fields. Previously, if a line ended within a quoted field without a |
| terminating newline character, a newline would be inserted into the |
| returned field. This behavior caused problems when reading files that |
| contained carriage return characters within fields, so the code was |
| changed to return the field without inserting newlines. As a |
| consequence, if newlines embedded within fields are important, the |
| input should be split into lines in a manner that preserves the |
| newline characters. |
| |
| (Contributed by Skip Montanaro and Andrew McNamara.) |
| |
| \item The \class{datetime} class in the \module{datetime} |
| module now has a \method{strptime(\var{string}, \var{format})} |
| method for parsing date strings, contributed by Josh Spoerri. |
| It uses the same format characters as \function{time.strptime()} and |
| \function{time.strftime()}: |
| |
| \begin{verbatim} |
| from datetime import datetime |
| |
| ts = datetime.strptime('10:13:15 2006-03-07', |
| '%H:%M:%S %Y-%m-%d') |
| \end{verbatim} |
| |
| \item The \method{SequenceMatcher.get_matching_blocks()} method |
| in the \module{difflib} module now guarantees to return a minimal list |
| of blocks describing matching subsequences. Previously, the algorithm would |
| occasionally break a block of matching elements into two list entries. |
| (Enhancement by Tim Peters.) |
| |
| \item The \module{doctest} module gained a \code{SKIP} option that |
| keeps an example from being executed at all. This is intended for |
| code snippets that are usage examples intended for the reader and |
| aren't actually test cases. |
| |
| An \var{encoding} parameter was added to the \function{testfile()} |
| function and the \class{DocFileSuite} class to specify the file's |
| encoding. This makes it easier to use non-ASCII characters in |
| tests contained within a docstring. (Contributed by Bjorn Tillenius.) |
| % Patch 1080727 |
| |
| \item The \module{email} package has been updated to version 4.0. |
| % XXX need to provide some more detail here |
| (Contributed by Barry Warsaw.) |
| |
| \item The \module{fileinput} module was made more flexible. |
| Unicode filenames are now supported, and a \var{mode} parameter that |
| defaults to \code{"r"} was added to the |
| \function{input()} function to allow opening files in binary or |
| universal-newline mode. Another new parameter, \var{openhook}, |
| lets you use a function other than \function{open()} |
| to open the input files. Once you're iterating over |
| the set of files, the \class{FileInput} object's new |
| \method{fileno()} returns the file descriptor for the currently opened file. |
| (Contributed by Georg Brandl.) |
| |
| \item In the \module{gc} module, the new \function{get_count()} function |
| returns a 3-tuple containing the current collection counts for the |
| three GC generations. This is accounting information for the garbage |
| collector; when these counts reach a specified threshold, a garbage |
| collection sweep will be made. The existing \function{gc.collect()} |
| function now takes an optional \var{generation} argument of 0, 1, or 2 |
| to specify which generation to collect. |
| (Contributed by Barry Warsaw.) |
| |
| \item The \function{nsmallest()} and |
| \function{nlargest()} functions in the \module{heapq} module |
| now support a \code{key} keyword parameter similar to the one |
| provided by the \function{min()}/\function{max()} functions |
| and the \method{sort()} methods. For example: |
| |
| \begin{verbatim} |
| >>> import heapq |
| >>> L = ["short", 'medium', 'longest', 'longer still'] |
| >>> heapq.nsmallest(2, L) # Return two lowest elements, lexicographically |
| ['longer still', 'longest'] |
| >>> heapq.nsmallest(2, L, key=len) # Return two shortest elements |
| ['short', 'medium'] |
| \end{verbatim} |
| |
| (Contributed by Raymond Hettinger.) |
| |
| \item The \function{itertools.islice()} function now accepts |
| \code{None} for the start and step arguments. This makes it more |
| compatible with the attributes of slice objects, so that you can now write |
| the following: |
| |
| \begin{verbatim} |
| s = slice(5) # Create slice object |
| itertools.islice(iterable, s.start, s.stop, s.step) |
| \end{verbatim} |
| |
| (Contributed by Raymond Hettinger.) |
| |
| \item The \function{format()} function in the \module{locale} module |
| has been modified and two new functions were added, |
| \function{format_string()} and \function{currency()}. |
| |
| The \function{format()} function's \var{val} parameter could |
| previously be a string as long as no more than one \%char specifier |
| appeared; now the parameter must be exactly one \%char specifier with |
| no surrounding text. An optional \var{monetary} parameter was also |
| added which, if \code{True}, will use the locale's rules for |
| formatting currency in placing a separator between groups of three |
| digits. |
| |
| To format strings with multiple \%char specifiers, use the new |
| \function{format_string()} function that works like \function{format()} |
| but also supports mixing \%char specifiers with |
| arbitrary text. |
| |
| A new \function{currency()} function was also added that formats a |
| number according to the current locale's settings. |
| |
| (Contributed by Georg Brandl.) |
| % Patch 1180296 |
| |
| \item The \module{mailbox} module underwent a massive rewrite to add |
| the capability to modify mailboxes in addition to reading them. A new |
| set of classes that include \class{mbox}, \class{MH}, and |
| \class{Maildir} are used to read mailboxes, and have an |
| \method{add(\var{message})} method to add messages, |
| \method{remove(\var{key})} to remove messages, and |
| \method{lock()}/\method{unlock()} to lock/unlock the mailbox. The |
| following example converts a maildir-format mailbox into an mbox-format one: |
| |
| \begin{verbatim} |
| import mailbox |
| |
| # 'factory=None' uses email.Message.Message as the class representing |
| # individual messages. |
| src = mailbox.Maildir('maildir', factory=None) |
| dest = mailbox.mbox('/tmp/mbox') |
| |
| for msg in src: |
| dest.add(msg) |
| \end{verbatim} |
| |
| (Contributed by Gregory K. Johnson. Funding was provided by Google's |
| 2005 Summer of Code.) |
| |
| \item New module: the \module{msilib} module allows creating |
| Microsoft Installer \file{.msi} files and CAB files. Some support |
| for reading the \file{.msi} database is also included. |
| (Contributed by Martin von~L\"owis.) |
| |
| \item The \module{nis} module now supports accessing domains other |
| than the system default domain by supplying a \var{domain} argument to |
| the \function{nis.match()} and \function{nis.maps()} functions. |
| (Contributed by Ben Bell.) |
| |
| \item The \module{operator} module's \function{itemgetter()} |
| and \function{attrgetter()} functions now support multiple fields. |
| A call such as \code{operator.attrgetter('a', 'b')} |
| will return a function |
| that retrieves the \member{a} and \member{b} attributes. Combining |
| this new feature with the \method{sort()} method's \code{key} parameter |
| lets you easily sort lists using multiple fields. |
| (Contributed by Raymond Hettinger.) |
| |
| \item The \module{optparse} module was updated to version 1.5.1 of the |
| Optik library. The \class{OptionParser} class gained an |
| \member{epilog} attribute, a string that will be printed after the |
| help message, and a \method{destroy()} method to break reference |
| cycles created by the object. (Contributed by Greg Ward.) |
| |
| \item The \module{os} module underwent several changes. The |
| \member{stat_float_times} variable now defaults to true, meaning that |
| \function{os.stat()} will now return time values as floats. (This |
| doesn't necessarily mean that \function{os.stat()} will return times |
| that are precise to fractions of a second; not all systems support |
| such precision.) |
| |
| Constants named \member{os.SEEK_SET}, \member{os.SEEK_CUR}, and |
| \member{os.SEEK_END} have been added; these are the parameters to the |
| \function{os.lseek()} function. Two new constants for locking are |
| \member{os.O_SHLOCK} and \member{os.O_EXLOCK}. |
| |
| Two new functions, \function{wait3()} and \function{wait4()}, were |
| added. They're similar the \function{waitpid()} function which waits |
| for a child process to exit and returns a tuple of the process ID and |
| its exit status, but \function{wait3()} and \function{wait4()} return |
| additional information. \function{wait3()} doesn't take a process ID |
| as input, so it waits for any child process to exit and returns a |
| 3-tuple of \var{process-id}, \var{exit-status}, \var{resource-usage} |
| as returned from the \function{resource.getrusage()} function. |
| \function{wait4(\var{pid})} does take a process ID. |
| (Contributed by Chad J. Schroeder.) |
| |
| On FreeBSD, the \function{os.stat()} function now returns |
| times with nanosecond resolution, and the returned object |
| now has \member{st_gen} and \member{st_birthtime}. |
| The \member{st_flags} member is also available, if the platform supports it. |
| (Contributed by Antti Louko and Diego Petten\`o.) |
| % (Patch 1180695, 1212117) |
| |
| \item The Python debugger provided by the \module{pdb} module |
| can now store lists of commands to execute when a breakpoint is |
| reached and execution stops. Once breakpoint \#1 has been created, |
| enter \samp{commands 1} and enter a series of commands to be executed, |
| finishing the list with \samp{end}. The command list can include |
| commands that resume execution, such as \samp{continue} or |
| \samp{next}. (Contributed by Gr\'egoire Dooms.) |
| % Patch 790710 |
| |
| \item The \module{pickle} and \module{cPickle} modules no |
| longer accept a return value of \code{None} from the |
| \method{__reduce__()} method; the method must return a tuple of |
| arguments instead. The ability to return \code{None} was deprecated |
| in Python 2.4, so this completes the removal of the feature. |
| |
| \item The \module{pkgutil} module, containing various utility |
| functions for finding packages, was enhanced to support PEP 302's |
| import hooks and now also works for packages stored in ZIP-format archives. |
| (Contributed by Phillip J. Eby.) |
| |
| \item The pybench benchmark suite by Marc-Andr\'e~Lemburg is now |
| included in the \file{Tools/pybench} directory. The pybench suite is |
| an improvement on the commonly used \file{pystone.py} program because |
| pybench provides a more detailed measurement of the interpreter's |
| speed. It times particular operations such as function calls, |
| tuple slicing, method lookups, and numeric operations, instead of |
| performing many different operations and reducing the result to a |
| single number as \file{pystone.py} does. |
| |
| \item The \module{pyexpat} module now uses version 2.0 of the Expat parser. |
| (Contributed by Trent Mick.) |
| |
| \item The old \module{regex} and \module{regsub} modules, which have been |
| deprecated ever since Python 2.0, have finally been deleted. |
| Other deleted modules: \module{statcache}, \module{tzparse}, |
| \module{whrandom}. |
| |
| \item Also deleted: the \file{lib-old} directory, |
| which includes ancient modules such as \module{dircmp} and |
| \module{ni}, was removed. \file{lib-old} wasn't on the default |
| \code{sys.path}, so unless your programs explicitly added the directory to |
| \code{sys.path}, this removal shouldn't affect your code. |
| |
| \item The \module{rlcompleter} module is no longer |
| dependent on importing the \module{readline} module and |
| therefore now works on non-{\UNIX} platforms. |
| (Patch from Robert Kiendl.) |
| % Patch #1472854 |
| |
| \item The \module{SimpleXMLRPCServer} and \module{DocXMLRPCServer} |
| classes now have a \member{rpc_paths} attribute that constrains |
| XML-RPC operations to a limited set of URL paths; the default is |
| to allow only \code{'/'} and \code{'/RPC2'}. Setting |
| \member{rpc_paths} to \code{None} or an empty tuple disables |
| this path checking. |
| % Bug #1473048 |
| |
| \item The \module{socket} module now supports \constant{AF_NETLINK} |
| sockets on Linux, thanks to a patch from Philippe Biondi. |
| Netlink sockets are a Linux-specific mechanism for communications |
| between a user-space process and kernel code; an introductory |
| article about them is at \url{http://www.linuxjournal.com/article/7356}. |
| In Python code, netlink addresses are represented as a tuple of 2 integers, |
| \code{(\var{pid}, \var{group_mask})}. |
| |
| Two new methods on socket objects, \method{recv_buf(\var{buffer})} and |
| \method{recvfrom_buf(\var{buffer})}, store the received data in an object |
| that supports the buffer protocol instead of returning the data as a |
| string. This means you can put the data directly into an array or a |
| memory-mapped file. |
| |
| Socket objects also gained \method{getfamily()}, \method{gettype()}, |
| and \method{getproto()} accessor methods to retrieve the family, type, |
| and protocol values for the socket. |
| |
| \item New module: the \module{spwd} module provides functions for |
| accessing the shadow password database on systems that support |
| shadow passwords. |
| |
| \item The \module{struct} is now faster because it |
| compiles format strings into \class{Struct} objects |
| with \method{pack()} and \method{unpack()} methods. This is similar |
| to how the \module{re} module lets you create compiled regular |
| expression objects. You can still use the module-level |
| \function{pack()} and \function{unpack()} functions; they'll create |
| \class{Struct} objects and cache them. Or you can use |
| \class{Struct} instances directly: |
| |
| \begin{verbatim} |
| s = struct.Struct('ih3s') |
| |
| data = s.pack(1972, 187, 'abc') |
| year, number, name = s.unpack(data) |
| \end{verbatim} |
| |
| You can also pack and unpack data to and from buffer objects directly |
| using the \method{pack_into(\var{buffer}, \var{offset}, \var{v1}, |
| \var{v2}, ...)} and \method{unpack_from(\var{buffer}, \var{offset})} |
| methods. This lets you store data directly into an array or a |
| memory-mapped file. |
| |
| (\class{Struct} objects were implemented by Bob Ippolito at the |
| NeedForSpeed sprint. Support for buffer objects was added by Martin |
| Blais, also at the NeedForSpeed sprint.) |
| |
| \item The Python developers switched from CVS to Subversion during the 2.5 |
| development process. Information about the exact build version is |
| available as the \code{sys.subversion} variable, a 3-tuple of |
| \code{(\var{interpreter-name}, \var{branch-name}, |
| \var{revision-range})}. For example, at the time of writing my copy |
| of 2.5 was reporting \code{('CPython', 'trunk', '45313:45315')}. |
| |
| This information is also available to C extensions via the |
| \cfunction{Py_GetBuildInfo()} function that returns a |
| string of build information like this: |
| \code{"trunk:45355:45356M, Apr 13 2006, 07:42:19"}. |
| (Contributed by Barry Warsaw.) |
| |
| \item Another new function, \function{sys._current_frames()}, returns |
| the current stack frames for all running threads as a dictionary |
| mapping thread identifiers to the topmost stack frame currently active |
| in that thread at the time the function is called. (Contributed by |
| Tim Peters.) |
| |
| \item The \class{TarFile} class in the \module{tarfile} module now has |
| an \method{extractall()} method that extracts all members from the |
| archive into the current working directory. It's also possible to set |
| a different directory as the extraction target, and to unpack only a |
| subset of the archive's members. |
| |
| The compression used for a tarfile opened in stream mode can now be |
| autodetected using the mode \code{'r|*'}. |
| % patch 918101 |
| (Contributed by Lars Gust\"abel.) |
| |
| \item The \module{threading} module now lets you set the stack size |
| used when new threads are created. The |
| \function{stack_size(\optional{\var{size}})} function returns the |
| currently configured stack size, and supplying the optional \var{size} |
| parameter sets a new value. Not all platforms support changing the |
| stack size, but Windows, POSIX threading, and OS/2 all do. |
| (Contributed by Andrew MacIntyre.) |
| % Patch 1454481 |
| |
| \item The \module{unicodedata} module has been updated to use version 4.1.0 |
| of the Unicode character database. Version 3.2.0 is required |
| by some specifications, so it's still available as |
| \member{unicodedata.ucd_3_2_0}. |
| |
| \item New module: the \module{uuid} module generates |
| universally unique identifiers (UUIDs) according to \rfc{4122}. The |
| RFC defines several different UUID versions that are generated from a |
| starting string, from system properties, or purely randomly. This |
| module contains a \class{UUID} class and |
| functions named \function{uuid1()}, |
| \function{uuid3()}, \function{uuid4()}, and |
| \function{uuid5()} to generate different versions of UUID. (Version 2 UUIDs |
| are not specified in \rfc{4122} and are not supported by this module.) |
| |
| \begin{verbatim} |
| >>> import uuid |
| >>> # make a UUID based on the host ID and current time |
| >>> uuid.uuid1() |
| UUID('a8098c1a-f86e-11da-bd1a-00112444be1e') |
| |
| >>> # make a UUID using an MD5 hash of a namespace UUID and a name |
| >>> uuid.uuid3(uuid.NAMESPACE_DNS, 'python.org') |
| UUID('6fa459ea-ee8a-3ca4-894e-db77e160355e') |
| |
| >>> # make a random UUID |
| >>> uuid.uuid4() |
| UUID('16fd2706-8baf-433b-82eb-8c7fada847da') |
| |
| >>> # make a UUID using a SHA-1 hash of a namespace UUID and a name |
| >>> uuid.uuid5(uuid.NAMESPACE_DNS, 'python.org') |
| UUID('886313e1-3b8a-5372-9b90-0c9aee199e5d') |
| \end{verbatim} |
| |
| (Contributed by Ka-Ping Yee.) |
| |
| \item The \module{weakref} module's \class{WeakKeyDictionary} and |
| \class{WeakValueDictionary} types gained new methods for iterating |
| over the weak references contained in the dictionary. |
| \method{iterkeyrefs()} and \method{keyrefs()} methods were |
| added to \class{WeakKeyDictionary}, and |
| \method{itervaluerefs()} and \method{valuerefs()} were added to |
| \class{WeakValueDictionary}. (Contributed by Fred L.~Drake, Jr.) |
| |
| \item The \module{webbrowser} module received a number of |
| enhancements. |
| It's now usable as a script with \code{python -m webbrowser}, taking a |
| URL as the argument; there are a number of switches |
| to control the behaviour (\programopt{-n} for a new browser window, |
| \programopt{-t} for a new tab). New module-level functions, |
| \function{open_new()} and \function{open_new_tab()}, were added |
| to support this. The module's \function{open()} function supports an |
| additional feature, an \var{autoraise} parameter that signals whether |
| to raise the open window when possible. A number of additional |
| browsers were added to the supported list such as Firefox, Opera, |
| Konqueror, and elinks. (Contributed by Oleg Broytmann and Georg |
| Brandl.) |
| % Patch #754022 |
| |
| \item The \module{xmlrpclib} module now supports returning |
| \class{datetime} objects for the XML-RPC date type. Supply |
| \code{use_datetime=True} to the \function{loads()} function |
| or the \class{Unmarshaller} class to enable this feature. |
| (Contributed by Skip Montanaro.) |
| % Patch 1120353 |
| |
| \item The \module{zipfile} module now supports the ZIP64 version of the |
| format, meaning that a .zip archive can now be larger than 4~GiB and |
| can contain individual files larger than 4~GiB. (Contributed by |
| Ronald Oussoren.) |
| % Patch 1446489 |
| |
| \item The \module{zlib} module's \class{Compress} and \class{Decompress} |
| objects now support a \method{copy()} method that makes a copy of the |
| object's internal state and returns a new |
| \class{Compress} or \class{Decompress} object. |
| (Contributed by Chris AtLee.) |
| % Patch 1435422 |
| |
| \end{itemize} |
| |
| |
| |
| %====================================================================== |
| \subsection{The ctypes package\label{module-ctypes}} |
| |
| The \module{ctypes} package, written by Thomas Heller, has been added |
| to the standard library. \module{ctypes} lets you call arbitrary functions |
| in shared libraries or DLLs. Long-time users may remember the \module{dl} module, which |
| provides functions for loading shared libraries and calling functions in them. The \module{ctypes} package is much fancier. |
| |
| To load a shared library or DLL, you must create an instance of the |
| \class{CDLL} class and provide the name or path of the shared library |
| or DLL. Once that's done, you can call arbitrary functions |
| by accessing them as attributes of the \class{CDLL} object. |
| |
| \begin{verbatim} |
| import ctypes |
| |
| libc = ctypes.CDLL('libc.so.6') |
| result = libc.printf("Line of output\n") |
| \end{verbatim} |
| |
| Type constructors for the various C types are provided: \function{c_int}, |
| \function{c_float}, \function{c_double}, \function{c_char_p} (equivalent to \ctype{char *}), and so forth. Unlike Python's types, the C versions are all mutable; you can assign to their \member{value} attribute |
| to change the wrapped value. Python integers and strings will be automatically |
| converted to the corresponding C types, but for other types you |
| must call the correct type constructor. (And I mean \emph{must}; |
| getting it wrong will often result in the interpreter crashing |
| with a segmentation fault.) |
| |
| You shouldn't use \function{c_char_p} with a Python string when the C function will be modifying the memory area, because Python strings are |
| supposed to be immutable; breaking this rule will cause puzzling bugs. When you need a modifiable memory area, |
| use \function{create_string_buffer()}: |
| |
| \begin{verbatim} |
| s = "this is a string" |
| buf = ctypes.create_string_buffer(s) |
| libc.strfry(buf) |
| \end{verbatim} |
| |
| C functions are assumed to return integers, but you can set |
| the \member{restype} attribute of the function object to |
| change this: |
| |
| \begin{verbatim} |
| >>> libc.atof('2.71828') |
| -1783957616 |
| >>> libc.atof.restype = ctypes.c_double |
| >>> libc.atof('2.71828') |
| 2.71828 |
| \end{verbatim} |
| |
| \module{ctypes} also provides a wrapper for Python's C API |
| as the \code{ctypes.pythonapi} object. This object does \emph{not} |
| release the global interpreter lock before calling a function, because the lock must be held when calling into the interpreter's code. |
| There's a \class{py_object()} type constructor that will create a |
| \ctype{PyObject *} pointer. A simple usage: |
| |
| \begin{verbatim} |
| import ctypes |
| |
| d = {} |
| ctypes.pythonapi.PyObject_SetItem(ctypes.py_object(d), |
| ctypes.py_object("abc"), ctypes.py_object(1)) |
| # d is now {'abc', 1}. |
| \end{verbatim} |
| |
| Don't forget to use \class{py_object()}; if it's omitted you end |
| up with a segmentation fault. |
| |
| \module{ctypes} has been around for a while, but people still write |
| and distribution hand-coded extension modules because you can't rely on \module{ctypes} being present. |
| Perhaps developers will begin to write |
| Python wrappers atop a library accessed through \module{ctypes} instead |
| of extension modules, now that \module{ctypes} is included with core Python. |
| |
| \begin{seealso} |
| |
| \seeurl{http://starship.python.net/crew/theller/ctypes/} |
| {The ctypes web page, with a tutorial, reference, and FAQ.} |
| |
| \seeurl{../lib/module-ctypes.html}{The documentation |
| for the \module{ctypes} module.} |
| |
| \end{seealso} |
| |
| |
| %====================================================================== |
| \subsection{The ElementTree package\label{module-etree}} |
| |
| A subset of Fredrik Lundh's ElementTree library for processing XML has |
| been added to the standard library as \module{xml.etree}. The |
| available modules are |
| \module{ElementTree}, \module{ElementPath}, and |
| \module{ElementInclude} from ElementTree 1.2.6. |
| The \module{cElementTree} accelerator module is also included. |
| |
| The rest of this section will provide a brief overview of using |
| ElementTree. Full documentation for ElementTree is available at |
| \url{http://effbot.org/zone/element-index.htm}. |
| |
| ElementTree represents an XML document as a tree of element nodes. |
| The text content of the document is stored as the \member{.text} |
| and \member{.tail} attributes of |
| (This is one of the major differences between ElementTree and |
| the Document Object Model; in the DOM there are many different |
| types of node, including \class{TextNode}.) |
| |
| The most commonly used parsing function is \function{parse()}, that |
| takes either a string (assumed to contain a filename) or a file-like |
| object and returns an \class{ElementTree} instance: |
| |
| \begin{verbatim} |
| from xml.etree import ElementTree as ET |
| |
| tree = ET.parse('ex-1.xml') |
| |
| feed = urllib.urlopen( |
| 'http://planet.python.org/rss10.xml') |
| tree = ET.parse(feed) |
| \end{verbatim} |
| |
| Once you have an \class{ElementTree} instance, you |
| can call its \method{getroot()} method to get the root \class{Element} node. |
| |
| There's also an \function{XML()} function that takes a string literal |
| and returns an \class{Element} node (not an \class{ElementTree}). |
| This function provides a tidy way to incorporate XML fragments, |
| approaching the convenience of an XML literal: |
| |
| \begin{verbatim} |
| svg = ET.XML("""<svg width="10px" version="1.0"> |
| </svg>""") |
| svg.set('height', '320px') |
| svg.append(elem1) |
| \end{verbatim} |
| |
| Each XML element supports some dictionary-like and some list-like |
| access methods. Dictionary-like operations are used to access attribute |
| values, and list-like operations are used to access child nodes. |
| |
| \begin{tableii}{c|l}{code}{Operation}{Result} |
| \lineii{elem[n]}{Returns n'th child element.} |
| \lineii{elem[m:n]}{Returns list of m'th through n'th child elements.} |
| \lineii{len(elem)}{Returns number of child elements.} |
| \lineii{list(elem)}{Returns list of child elements.} |
| \lineii{elem.append(elem2)}{Adds \var{elem2} as a child.} |
| \lineii{elem.insert(index, elem2)}{Inserts \var{elem2} at the specified location.} |
| \lineii{del elem[n]}{Deletes n'th child element.} |
| \lineii{elem.keys()}{Returns list of attribute names.} |
| \lineii{elem.get(name)}{Returns value of attribute \var{name}.} |
| \lineii{elem.set(name, value)}{Sets new value for attribute \var{name}.} |
| \lineii{elem.attrib}{Retrieves the dictionary containing attributes.} |
| \lineii{del elem.attrib[name]}{Deletes attribute \var{name}.} |
| \end{tableii} |
| |
| Comments and processing instructions are also represented as |
| \class{Element} nodes. To check if a node is a comment or processing |
| instructions: |
| |
| \begin{verbatim} |
| if elem.tag is ET.Comment: |
| ... |
| elif elem.tag is ET.ProcessingInstruction: |
| ... |
| \end{verbatim} |
| |
| To generate XML output, you should call the |
| \method{ElementTree.write()} method. Like \function{parse()}, |
| it can take either a string or a file-like object: |
| |
| \begin{verbatim} |
| # Encoding is US-ASCII |
| tree.write('output.xml') |
| |
| # Encoding is UTF-8 |
| f = open('output.xml', 'w') |
| tree.write(f, encoding='utf-8') |
| \end{verbatim} |
| |
| (Caution: the default encoding used for output is ASCII. For general |
| XML work, where an element's name may contain arbitrary Unicode |
| characters, ASCII isn't a very useful encoding because it will raise |
| an exception if an element's name contains any characters with values |
| greater than 127. Therefore, it's best to specify a different |
| encoding such as UTF-8 that can handle any Unicode character.) |
| |
| This section is only a partial description of the ElementTree interfaces. |
| Please read the package's official documentation for more details. |
| |
| \begin{seealso} |
| |
| \seeurl{http://effbot.org/zone/element-index.htm} |
| {Official documentation for ElementTree.} |
| |
| \end{seealso} |
| |
| |
| %====================================================================== |
| \subsection{The hashlib package\label{module-hashlib}} |
| |
| A new \module{hashlib} module, written by Gregory P. Smith, |
| has been added to replace the |
| \module{md5} and \module{sha} modules. \module{hashlib} adds support |
| for additional secure hashes (SHA-224, SHA-256, SHA-384, and SHA-512). |
| When available, the module uses OpenSSL for fast platform optimized |
| implementations of algorithms. |
| |
| The old \module{md5} and \module{sha} modules still exist as wrappers |
| around hashlib to preserve backwards compatibility. The new module's |
| interface is very close to that of the old modules, but not identical. |
| The most significant difference is that the constructor functions |
| for creating new hashing objects are named differently. |
| |
| \begin{verbatim} |
| # Old versions |
| h = md5.md5() |
| h = md5.new() |
| |
| # New version |
| h = hashlib.md5() |
| |
| # Old versions |
| h = sha.sha() |
| h = sha.new() |
| |
| # New version |
| h = hashlib.sha1() |
| |
| # Hash that weren't previously available |
| h = hashlib.sha224() |
| h = hashlib.sha256() |
| h = hashlib.sha384() |
| h = hashlib.sha512() |
| |
| # Alternative form |
| h = hashlib.new('md5') # Provide algorithm as a string |
| \end{verbatim} |
| |
| Once a hash object has been created, its methods are the same as before: |
| \method{update(\var{string})} hashes the specified string into the |
| current digest state, \method{digest()} and \method{hexdigest()} |
| return the digest value as a binary string or a string of hex digits, |
| and \method{copy()} returns a new hashing object with the same digest state. |
| |
| \begin{seealso} |
| |
| \seeurl{../lib/module-hashlib.html}{The documentation |
| for the \module{hashlib} module.} |
| |
| \end{seealso} |
| |
| |
| %====================================================================== |
| \subsection{The sqlite3 package\label{module-sqlite}} |
| |
| The pysqlite module (\url{http://www.pysqlite.org}), a wrapper for the |
| SQLite embedded database, has been added to the standard library under |
| the package name \module{sqlite3}. |
| |
| SQLite is a C library that provides a lightweight disk-based database |
| that doesn't require a separate server process and allows accessing |
| the database using a nonstandard variant of the SQL query language. |
| Some applications can use SQLite for internal data storage. It's also |
| possible to prototype an application using SQLite and then port the |
| code to a larger database such as PostgreSQL or Oracle. |
| |
| pysqlite was written by Gerhard H\"aring and provides a SQL interface |
| compliant with the DB-API 2.0 specification described by |
| \pep{249}. |
| |
| If you're compiling the Python source yourself, note that the source |
| tree doesn't include the SQLite code, only the wrapper module. |
| You'll need to have the SQLite libraries and headers installed before |
| compiling Python, and the build process will compile the module when |
| the necessary headers are available. |
| |
| To use the module, you must first create a \class{Connection} object |
| that represents the database. Here the data will be stored in the |
| \file{/tmp/example} file: |
| |
| \begin{verbatim} |
| conn = sqlite3.connect('/tmp/example') |
| \end{verbatim} |
| |
| You can also supply the special name \samp{:memory:} to create |
| a database in RAM. |
| |
| Once you have a \class{Connection}, you can create a \class{Cursor} |
| object and call its \method{execute()} method to perform SQL commands: |
| |
| \begin{verbatim} |
| c = conn.cursor() |
| |
| # Create table |
| c.execute('''create table stocks |
| (date text, trans text, symbol text, |
| qty real, price real)''') |
| |
| # Insert a row of data |
| c.execute("""insert into stocks |
| values ('2006-01-05','BUY','RHAT',100,35.14)""") |
| \end{verbatim} |
| |
| Usually your SQL operations will need to use values from Python |
| variables. You shouldn't assemble your query using Python's string |
| operations because doing so is insecure; it makes your program |
| vulnerable to an SQL injection attack. |
| |
| Instead, use the DB-API's parameter substitution. Put \samp{?} as a |
| placeholder wherever you want to use a value, and then provide a tuple |
| of values as the second argument to the cursor's \method{execute()} |
| method. (Other database modules may use a different placeholder, |
| such as \samp{\%s} or \samp{:1}.) For example: |
| |
| \begin{verbatim} |
| # Never do this -- insecure! |
| symbol = 'IBM' |
| c.execute("... where symbol = '%s'" % symbol) |
| |
| # Do this instead |
| t = (symbol,) |
| c.execute('select * from stocks where symbol=?', t) |
| |
| # Larger example |
| for t in (('2006-03-28', 'BUY', 'IBM', 1000, 45.00), |
| ('2006-04-05', 'BUY', 'MSOFT', 1000, 72.00), |
| ('2006-04-06', 'SELL', 'IBM', 500, 53.00), |
| ): |
| c.execute('insert into stocks values (?,?,?,?,?)', t) |
| \end{verbatim} |
| |
| To retrieve data after executing a SELECT statement, you can either |
| treat the cursor as an iterator, call the cursor's \method{fetchone()} |
| method to retrieve a single matching row, |
| or call \method{fetchall()} to get a list of the matching rows. |
| |
| This example uses the iterator form: |
| |
| \begin{verbatim} |
| >>> c = conn.cursor() |
| >>> c.execute('select * from stocks order by price') |
| >>> for row in c: |
| ... print row |
| ... |
| (u'2006-01-05', u'BUY', u'RHAT', 100, 35.140000000000001) |
| (u'2006-03-28', u'BUY', u'IBM', 1000, 45.0) |
| (u'2006-04-06', u'SELL', u'IBM', 500, 53.0) |
| (u'2006-04-05', u'BUY', u'MSOFT', 1000, 72.0) |
| >>> |
| \end{verbatim} |
| |
| For more information about the SQL dialect supported by SQLite, see |
| \url{http://www.sqlite.org}. |
| |
| \begin{seealso} |
| |
| \seeurl{http://www.pysqlite.org} |
| {The pysqlite web page.} |
| |
| \seeurl{http://www.sqlite.org} |
| {The SQLite web page; the documentation describes the syntax and the |
| available data types for the supported SQL dialect.} |
| |
| \seeurl{../lib/module-sqlite3.html}{The documentation |
| for the \module{sqlite3} module.} |
| |
| \seepep{249}{Database API Specification 2.0}{PEP written by |
| Marc-Andr\'e Lemburg.} |
| |
| \end{seealso} |
| |
| |
| %====================================================================== |
| \subsection{The wsgiref package\label{module-wsgiref}} |
| |
| % XXX should this be in a PEP 333 section instead? |
| |
| The Web Server Gateway Interface (WSGI) v1.0 defines a standard |
| interface between web servers and Python web applications and is |
| described in \pep{333}. The \module{wsgiref} package is a reference |
| implementation of the WSGI specification. |
| |
| The package includes a basic HTTP server that will run a WSGI |
| application; this server is useful for debugging but isn't intended for |
| production use. Setting up a server takes only a few lines of code: |
| |
| \begin{verbatim} |
| from wsgiref import simple_server |
| |
| wsgi_app = ... |
| |
| host = '' |
| port = 8000 |
| httpd = simple_server.make_server(host, port, wsgi_app) |
| httpd.serve_forever() |
| \end{verbatim} |
| |
| % XXX discuss structure of WSGI applications? |
| % XXX provide an example using Django or some other framework? |
| |
| \begin{seealso} |
| |
| \seeurl{http://www.wsgi.org}{A central web site for WSGI-related resources.} |
| |
| \seepep{333}{Python Web Server Gateway Interface v1.0}{PEP written by |
| Phillip J. Eby.} |
| |
| \end{seealso} |
| |
| |
| % ====================================================================== |
| \section{Build and C API Changes\label{build-api}} |
| |
| Changes to Python's build process and to the C API include: |
| |
| \begin{itemize} |
| |
| \item The Python source tree was converted from CVS to Subversion, |
| in a complex migration procedure that was supervised and flawlessly |
| carried out by Martin von~L\"owis. The procedure was developed as |
| \pep{347}. |
| |
| \item Coverity, a company that markets a source code analysis tool |
| called Prevent, provided the results of their examination of the Python |
| source code. The analysis found about 60 bugs that |
| were quickly fixed. Many of the bugs were refcounting problems, often |
| occurring in error-handling code. See |
| \url{http://scan.coverity.com} for the statistics. |
| |
| \item The largest change to the C API came from \pep{353}, |
| which modifies the interpreter to use a \ctype{Py_ssize_t} type |
| definition instead of \ctype{int}. See the earlier |
| section~\ref{pep-353} for a discussion of this change. |
| |
| \item The design of the bytecode compiler has changed a great deal, |
| no longer generating bytecode by traversing the parse tree. Instead |
| the parse tree is converted to an abstract syntax tree (or AST), and it is |
| the abstract syntax tree that's traversed to produce the bytecode. |
| |
| It's possible for Python code to obtain AST objects by using the |
| \function{compile()} built-in and specifying \code{_ast.PyCF_ONLY_AST} |
| as the value of the |
| \var{flags} parameter: |
| |
| \begin{verbatim} |
| from _ast import PyCF_ONLY_AST |
| ast = compile("""a=0 |
| for i in range(10): |
| a += i |
| """, "<string>", 'exec', PyCF_ONLY_AST) |
| |
| assignment = ast.body[0] |
| for_loop = ast.body[1] |
| \end{verbatim} |
| |
| No official documentation has been written for the AST code yet, but |
| \pep{339} discusses the design. To start learning about the code, read the |
| definition of the various AST nodes in \file{Parser/Python.asdl}. A |
| Python script reads this file and generates a set of C structure |
| definitions in \file{Include/Python-ast.h}. The |
| \cfunction{PyParser_ASTFromString()} and |
| \cfunction{PyParser_ASTFromFile()}, defined in |
| \file{Include/pythonrun.h}, take Python source as input and return the |
| root of an AST representing the contents. This AST can then be turned |
| into a code object by \cfunction{PyAST_Compile()}. For more |
| information, read the source code, and then ask questions on |
| python-dev. |
| |
| % List of names taken from Jeremy's python-dev post at |
| % http://mail.python.org/pipermail/python-dev/2005-October/057500.html |
| The AST code was developed under Jeremy Hylton's management, and |
| implemented by (in alphabetical order) Brett Cannon, Nick Coghlan, |
| Grant Edwards, John Ehresman, Kurt Kaiser, Neal Norwitz, Tim Peters, |
| Armin Rigo, and Neil Schemenauer, plus the participants in a number of |
| AST sprints at conferences such as PyCon. |
| |
| \item Evan Jones's patch to obmalloc, first described in a talk |
| at PyCon DC 2005, was applied. Python 2.4 allocated small objects in |
| 256K-sized arenas, but never freed arenas. With this patch, Python |
| will free arenas when they're empty. The net effect is that on some |
| platforms, when you allocate many objects, Python's memory usage may |
| actually drop when you delete them and the memory may be returned to |
| the operating system. (Implemented by Evan Jones, and reworked by Tim |
| Peters.) |
| |
| Note that this change means extension modules must be more careful |
| when allocating memory. Python's API has many different |
| functions for allocating memory that are grouped into families. For |
| example, \cfunction{PyMem_Malloc()}, \cfunction{PyMem_Realloc()}, and |
| \cfunction{PyMem_Free()} are one family that allocates raw memory, |
| while \cfunction{PyObject_Malloc()}, \cfunction{PyObject_Realloc()}, |
| and \cfunction{PyObject_Free()} are another family that's supposed to |
| be used for creating Python objects. |
| |
| Previously these different families all reduced to the platform's |
| \cfunction{malloc()} and \cfunction{free()} functions. This meant |
| it didn't matter if you got things wrong and allocated memory with the |
| \cfunction{PyMem} function but freed it with the \cfunction{PyObject} |
| function. With 2.5's changes to obmalloc, these families now do different |
| things and mismatches will probably result in a segfault. You should |
| carefully test your C extension modules with Python 2.5. |
| |
| \item The built-in set types now have an official C API. Call |
| \cfunction{PySet_New()} and \cfunction{PyFrozenSet_New()} to create a |
| new set, \cfunction{PySet_Add()} and \cfunction{PySet_Discard()} to |
| add and remove elements, and \cfunction{PySet_Contains} and |
| \cfunction{PySet_Size} to examine the set's state. |
| (Contributed by Raymond Hettinger.) |
| |
| \item C code can now obtain information about the exact revision |
| of the Python interpreter by calling the |
| \cfunction{Py_GetBuildInfo()} function that returns a |
| string of build information like this: |
| \code{"trunk:45355:45356M, Apr 13 2006, 07:42:19"}. |
| (Contributed by Barry Warsaw.) |
| |
| \item Two new macros can be used to indicate C functions that are |
| local to the current file so that a faster calling convention can be |
| used. \cfunction{Py_LOCAL(\var{type})} declares the function as |
| returning a value of the specified \var{type} and uses a fast-calling |
| qualifier. \cfunction{Py_LOCAL_INLINE(\var{type})} does the same thing |
| and also requests the function be inlined. If |
| \cfunction{PY_LOCAL_AGGRESSIVE} is defined before \file{python.h} is |
| included, a set of more aggressive optimizations are enabled for the |
| module; you should benchmark the results to find out if these |
| optimizations actually make the code faster. (Contributed by Fredrik |
| Lundh at the NeedForSpeed sprint.) |
| |
| \item \cfunction{PyErr_NewException(\var{name}, \var{base}, |
| \var{dict})} can now accept a tuple of base classes as its \var{base} |
| argument. (Contributed by Georg Brandl.) |
| |
| \item The \cfunction{PyErr_Warn()} function for issuing warnings |
| is now deprecated in favour of \cfunction{PyErr_WarnEx(category, |
| message, stacklevel)} which lets you specify the number of stack |
| frames separating this function and the caller. A \var{stacklevel} of |
| 1 is the function calling \cfunction{PyErr_WarnEx()}, 2 is the |
| function above that, and so forth. (Added by Neal Norwitz.) |
| |
| \item The CPython interpreter is still written in C, but |
| the code can now be compiled with a {\Cpp} compiler without errors. |
| (Implemented by Anthony Baxter, Martin von~L\"owis, Skip Montanaro.) |
| |
| \item The \cfunction{PyRange_New()} function was removed. It was |
| never documented, never used in the core code, and had dangerously lax |
| error checking. In the unlikely case that your extensions were using |
| it, you can replace it by something like the following: |
| \begin{verbatim} |
| range = PyObject_CallFunction((PyObject*) &PyRange_Type, "lll", |
| start, stop, step); |
| \end{verbatim} |
| |
| \end{itemize} |
| |
| |
| %====================================================================== |
| \subsection{Port-Specific Changes\label{ports}} |
| |
| \begin{itemize} |
| |
| \item MacOS X (10.3 and higher): dynamic loading of modules |
| now uses the \cfunction{dlopen()} function instead of MacOS-specific |
| functions. |
| |
| \item MacOS X: a \longprogramopt{enable-universalsdk} switch was added |
| to the \program{configure} script that compiles the interpreter as a |
| universal binary able to run on both PowerPC and Intel processors. |
| (Contributed by Ronald Oussoren.) |
| |
| \item Windows: \file{.dll} is no longer supported as a filename extension for |
| extension modules. \file{.pyd} is now the only filename extension that will |
| be searched for. |
| |
| \end{itemize} |
| |
| |
| %====================================================================== |
| \section{Porting to Python 2.5\label{porting}} |
| |
| This section lists previously described changes that may require |
| changes to your code: |
| |
| \begin{itemize} |
| |
| \item ASCII is now the default encoding for modules. It's now |
| a syntax error if a module contains string literals with 8-bit |
| characters but doesn't have an encoding declaration. In Python 2.4 |
| this triggered a warning, not a syntax error. |
| |
| \item Previously, the \member{gi_frame} attribute of a generator |
| was always a frame object. Because of the \pep{342} changes |
| described in section~\ref{pep-342}, it's now possible |
| for \member{gi_frame} to be \code{None}. |
| |
| \item A new warning, \class{UnicodeWarning}, is triggered when |
| you attempt to compare a Unicode string and an 8-bit string that can't |
| be converted to Unicode using the default ASCII encoding. Previously |
| such comparisons would raise a \class{UnicodeDecodeError} exception. |
| |
| \item Library: the \module{csv} module is now stricter about multi-line quoted |
| fields. If your files contain newlines embedded within fields, the |
| input should be split into lines in a manner which preserves the |
| newline characters. |
| |
| \item Library: the \module{locale} module's |
| \function{format()} function's would previously |
| accept any string as long as no more than one \%char specifier |
| appeared. In Python 2.5, the argument must be exactly one \%char |
| specifier with no surrounding text. |
| |
| \item Library: The \module{pickle} and \module{cPickle} modules no |
| longer accept a return value of \code{None} from the |
| \method{__reduce__()} method; the method must return a tuple of |
| arguments instead. The modules also no longer accept the deprecated |
| \var{bin} keyword parameter. |
| |
| \item Library: The \module{SimpleXMLRPCServer} and \module{DocXMLRPCServer} |
| classes now have a \member{rpc_paths} attribute that constrains |
| XML-RPC operations to a limited set of URL paths; the default is |
| to allow only \code{'/'} and \code{'/RPC2'}. Setting |
| \member{rpc_paths} to \code{None} or an empty tuple disables |
| this path checking. |
| |
| \item C API: Many functions now use \ctype{Py_ssize_t} |
| instead of \ctype{int} to allow processing more data on 64-bit |
| machines. Extension code may need to make the same change to avoid |
| warnings and to support 64-bit machines. See the earlier |
| section~\ref{pep-353} for a discussion of this change. |
| |
| \item C API: |
| The obmalloc changes mean that |
| you must be careful to not mix usage |
| of the \cfunction{PyMem_*()} and \cfunction{PyObject_*()} |
| families of functions. Memory allocated with |
| one family's \cfunction{*_Malloc()} must be |
| freed with the corresponding family's \cfunction{*_Free()} function. |
| |
| \end{itemize} |
| |
| |
| %====================================================================== |
| \section{Acknowledgements \label{acks}} |
| |
| The author would like to thank the following people for offering |
| suggestions, corrections and assistance with various drafts of this |
| article: Georg Brandl, Nick Coghlan, Phillip J. Eby, Lars Gust\"abel, |
| Raymond Hettinger, Ralf W. Grosse-Kunstleve, Kent Johnson, Iain Lowe, |
| Martin von~L\"owis, Fredrik Lundh, Andrew McNamara, Skip Montanaro, |
| Gustavo Niemeyer, Paul Prescod, James Pryor, Mike Rovner, Scott |
| Weikart, Barry Warsaw, Thomas Wouters. |
| |
| \end{document} |