PEP 308: Conditional Expressions¶

For a long time, people have been requesting a way to write conditionalexpressions, which are expressions that return value A or value B depending onwhether a Boolean value is true or false. A conditional expression lets youwrite a single assignment statement that has the same effect as the following:

ifcondition:x=true_valueelse:x=false_value

There have been endless tedious discussions of syntax on both python-dev andcomp.lang.python. A vote was even held that found the majority of voters wantedconditional expressions in some form, but there was no syntax that was preferredby a clear majority. Candidates included C’scond?true_v:false_v,ifcondthentrue_velsefalse_v, and 16 other variations.

Guido van Rossum eventually chose a surprising syntax:

x=true_valueifconditionelsefalse_value

Evaluation is still lazy as in existing Boolean expressions, so the order ofevaluation jumps around a bit. Thecondition expression in the middle isevaluated first, and thetrue_value expression is evaluated only if thecondition was true. Similarly, thefalse_value expression is only evaluatedwhen the condition is false.

This syntax may seem strange and backwards; why does the condition go in themiddle of the expression, and not in the front as in C’sc?x:y? Thedecision was checked by applying the new syntax to the modules in the standardlibrary and seeing how the resulting code read. In many cases where aconditional expression is used, one value seems to be the ‘common case’ and onevalue is an ‘exceptional case’, used only on rarer occasions when the conditionisn’t met. The conditional syntax makes this pattern a bit more obvious:

contents=((doc+'\n')ifdocelse'')

I read the above statement as meaning “herecontents is usually assigned avalue ofdoc+'\n'; sometimesdoc is empty, in which special case an emptystring is returned.” I doubt I will use conditional expressions very oftenwhere there isn’t a clear common and uncommon case.

There was some discussion of whether the language should require surroundingconditional expressions with parentheses. The decision was made tonotrequire parentheses in the Python language’s grammar, but as a matter of style Ithink you should always use them. Consider these two statements:

# First version -- no parenslevel=1ifloggingelse0# Second version -- with parenslevel=(1ifloggingelse0)

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 decideswhether the assignment tolevel is performed. The second version readsbetter, in my opinion, because it makes it clear that the assignment is alwaysperformed and the choice is being made between two values.

Another reason for including the brackets: a few odd combinations of listcomprehensions and lambdas could look like incorrect conditional expressions.SeePEP 308 for some examples. If you put parentheses around yourconditional expressions, you won’t run into this case.

PEP 309: Partial Function Application¶

Thefunctools module is intended to contain tools for functional-styleprogramming.

One useful tool in this module is thepartial() function. For programswritten in a functional style, you’ll sometimes want to construct variants ofexisting functions that have some of the parameters filled in. Consider aPython functionf(a,b,c); you could create a new functiong(b,c) thatwas equivalent tof(1,b,c). This is called “partial functionapplication”.

partial() takes the arguments(function,arg1,arg2,...kwarg1=value1,kwarg2=value2). The resulting object is callable, so you can just call it toinvokefunction with the filled-in arguments.

Here’s a small but realistic example:

importfunctoolsdeflog(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')

Here’s another example, from a program that uses PyGTK. Here a context-sensitivepop-up menu is being constructed dynamically. The callback providedfor the menu option is a partially applied version of theopen_item()method, where the first argument has been provided.

...classApplication:defopen_item(self,path):...definit(self):open_func=functools.partial(self.open_item,item_path)popup_menu.append(("Open",open_func,1))

Another function in thefunctools module is theupdate_wrapper(wrapper,wrapped) function that helps you writewell-behaved decorators.update_wrapper() copies the name, module, anddocstring attribute to a wrapper function so that tracebacks inside the wrappedfunction are easier to understand. For example, you might write:

defmy_decorator(f):defwrapper(*args,**kwds):print'Calling decorated function'returnf(*args,**kwds)functools.update_wrapper(wrapper,f)returnwrapper

wraps() is a decorator that can be used inside your own decorators to copythe wrapped function’s information. An alternate version of the previousexample would be:

defmy_decorator(f):@functools.wraps(f)defwrapper(*args,**kwds):print'Calling decorated function'returnf(*args,**kwds)returnwrapper

PEP 314: Metadata for Python Software Packages v1.1¶

Some simple dependency support was added to Distutils. Thesetup()function now hasrequires,provides, andobsoletes keywordparameters. When you build a source distribution using thesdist command,the dependency information will be recorded in thePKG-INFO file.

Another new keyword parameter isdownload_url, which should be set to a URLfor the package’s source code. This means it’s now possible to look up an entryin the package index, determine the dependencies for a package, and download therequired packages.

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),)

Another new enhancement to the Python package index athttps://pypi.org is storing source and binary archives for apackage. The newupload Distutils command will upload a package tothe repository.

Before a package can be uploaded, you must be able to build a distribution usingthesdist Distutils command. Once that works, you can runpythonsetup.pyupload to add your package to the PyPI archive. Optionally you canGPG-sign the package by supplying the--sign and--identityoptions.

Package uploading was implemented by Martin von Löwis and Richard Jones.

PEP 328: Absolute and Relative Imports¶

The simpler part ofPEP 328 was implemented in Python 2.4: parentheses could nowbe used to enclose the names imported from a module using thefrom...import... statement, making it easier to import many different names.

The more complicated part has been implemented in Python 2.5: importing a modulecan be specified to use absolute or package-relative imports. The plan is tomove toward making absolute imports the default in future versions of Python.

Let’s say you have a package directory like this:

pkg/pkg/__init__.pypkg/main.pypkg/string.py

This defines a package namedpkg containing thepkg.main andpkg.string submodules.

Consider the code in themain.py module. What happens if it executesthe statementimportstring? In Python 2.4 and earlier, it will first lookin the package’s directory to perform a relative import, findspkg/string.py, imports the contents of that file as thepkg.string module, and that module is bound to the namestring in thepkg.main module’s namespace.

That’s fine ifpkg.string was what you wanted. But what if you wantedPython’s standardstring module? There’s no clean way to ignorepkg.string and look for the standard module; generally you had to look atthe contents ofsys.modules, which is slightly unclean. Holger Krekel’spy.std package provides a tidier way to perform imports from the standardlibrary,importpy;py.std.string.join(), but that package isn’t availableon all Python installations.

Reading code which relies on relative imports is also less clear, because areader may be confused about which module,string orpkg.string,is intended to be used. Python users soon learned not to duplicate the names ofstandard library modules in the names of their packages’ submodules, but youcan’t protect against having your submodule’s name being used for a new moduleadded in a future version of Python.

In Python 2.5, you can switchimport’s behaviour to absolute importsusing afrom__future__importabsolute_import directive. This absolute-importbehaviour will become the default in a future version (probably Python2.7). Once absolute imports are the default,importstring will alwaysfind the standard library’s version. It’s suggested that users should beginusing absolute imports as much as possible, so it’s preferable to begin writingfrompkgimportstring in your code.

Relative imports are still possible by adding a leading period to the modulename when using thefrom...import form:

# Import names from pkg.stringfrom.stringimportname1,name2# Import pkg.stringfrom.importstring

This imports thestring module relative to the current package, so inpkg.main this will importname1 andname2 frompkg.string.Additional leading periods perform the relative import starting from the parentof the current package. For example, code in theA.B.C module can do:

from.importD# Imports A.B.Dfrom..importE# Imports A.Efrom..FimportG# Imports A.F.G

Leading periods cannot be used with theimportmodname form of the importstatement, only thefrom...import form.

PEP 338: Executing Modules as Scripts¶

The-m switch added in Python 2.4 to execute a module as a scriptgained a few more abilities. Instead of being implemented in C code inside thePython interpreter, the switch now uses an implementation in a new module,runpy.

Therunpy module implements a more sophisticated import mechanism so thatit’s now possible to run modules in a package such aspychecker.checker.The module also supports alternative import mechanisms such as thezipimport module. This means you can add a .zip archive’s path tosys.path and then use the-m switch to execute code from thearchive.

PEP 341: Unified try/except/finally¶

Until Python 2.5, thetry statement came in two flavours. You coulduse afinally block to ensure that code is always executed, or one ormoreexcept blocks to catch specific exceptions. You couldn’tcombine bothexcept blocks and afinally block, becausegenerating the right bytecode for the combined version was complicated and itwasn’t clear what the semantics of the combined statement should be.

Guido van Rossum spent some time working with Java, which does support theequivalent of combiningexcept blocks and afinally block,and this clarified what the statement should mean. In Python 2.5, you can nowwrite:

try:block-1...exceptException1:handler-1...exceptException2:handler-2...else:else-blockfinally:final-block

The code inblock-1 is executed. If the code raises an exception, the variousexcept blocks are tested: if the exception is of classException1,handler-1 is executed; otherwise if it’s of classException2,handler-2 is executed, and so forth. If no exception israised, theelse-block is executed.

No matter what happened previously, thefinal-block is executed once the codeblock is complete and any raised exceptions handled. Even if there’s an error inan exception handler or theelse-block and a new exception is raised, the codein thefinal-block is still run.

PEP 342: New Generator Features¶

Python 2.5 adds a simple way to pass valuesinto a generator. As introduced inPython 2.3, generators only produce output; once a generator’s code was invokedto create an iterator, there was no way to pass any new information into thefunction when its execution is resumed. Sometimes the ability to pass in someinformation would be useful. Hackish solutions to this include making thegenerator’s code look at a global variable and then changing the globalvariable’s value, or passing in some mutable object that callers then modify.

To refresh your memory of basic generators, here’s a simple example:

defcounter(maximum):i=0whilei<maximum:yieldii+=1

When you callcounter(10), the result is an iterator that returns the valuesfrom 0 up to 9. On encountering theyield statement, the iteratorreturns the provided value and suspends the function’s execution, preserving thelocal variables. Execution resumes on the following call to the iterator’snext() method, picking up after theyield statement.

In Python 2.3,yield was a statement; it didn’t return any value. In2.5,yield is now an expression, returning a value that can beassigned to a variable or otherwise operated on:

val=(yieldi)

I recommend that you always put parentheses around ayield expressionwhen 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 theminstead of having to remember when they’re needed.

(PEP 342 explains the exact rules, which are that ayield-expression must always be parenthesized except when itoccurs at the top-levelexpression on the right-hand side of an assignment. This means you can writeval=yieldi but have to use parentheses when there’s an operation, as inval=(yieldi)+12.)

Values are sent into a generator by calling itssend(value) method. Thegenerator’s code is then resumed and theyield expression returns thespecifiedvalue. If the regularnext() method is called, theyield returnsNone.

Here’s the previous example, modified to allow changing the value of theinternal counter.

defcounter(maximum):i=0whilei<maximum:val=(yieldi)# If value provided, change counterifvalisnotNone:i=valelse:i+=1

And here’s an example of changing the counter:

>>>it=counter(10)>>>printit.next()0>>>printit.next()1>>>printit.send(8)8>>>printit.next()9>>>printit.next()Traceback (most recent call last):  File"t.py", line15, in?printit.next()StopIteration

yield will usually returnNone, so you should always checkfor this case. Don’t just use its value in expressions unless you’re sure thatthesend() method will be the only method used to resume your generatorfunction.

In addition tosend(), there are two other new methods on generators:

• throw(type,value=None,traceback=None) is used to raise an exceptioninside the generator; the exception is raised by theyield expressionwhere the generator’s execution is paused.

• close() raises a newGeneratorExit exception inside the generatorto terminate the iteration. On receiving this exception, the generator’s codemust either raiseGeneratorExit orStopIteration. Catching theGeneratorExit exception and returning a value is illegal and will triggeraRuntimeError; if the function raises some other exception, thatexception is propagated to the caller.close() will also be called byPython’s garbage collector when the generator is garbage-collected.

  If you need to run cleanup code when aGeneratorExit occurs, I suggestusing atry:...finally: suite instead of catchingGeneratorExit.

The cumulative effect of these changes is to turn generators from one-wayproducers of information into both producers and consumers.

Generators also becomecoroutines, a more generalized form of subroutines.Subroutines are entered at one point and exited at another point (the top of thefunction, and areturn statement), but coroutines can be entered,exited, and resumed at many different points (theyield statements).We’ll have to figure out patterns for using coroutines effectively in Python.

The addition of theclose() method has one side effect that isn’t obvious.close() is called when a generator is garbage-collected, so this means thegenerator’s code gets one last chance to run before the generator is destroyed.This last chance means thattry...finally statements in generators can nowbe guaranteed to work; thefinally clause will now always get achance to run. The syntactic restriction that you couldn’t mixyieldstatements with atry...finally suite has therefore been removed. Thisseems like a minor bit of language trivia, but using generators andtry...finally is actually necessary in order to implement thewith statement described byPEP 343. I’ll look at this new statementin the following section.

Another even more esoteric effect of this change: previously, thegi_frame attribute of a generator was always a frame object. It’s nowpossible forgi_frame to beNone once the generator has beenexhausted.

PEP 343: The ‘with’ statement¶

The ‘with’ statement clarifies code that previously would usetry...finally blocks to ensure that clean-up code is executed. In thissection, I’ll discuss the statement as it will commonly be used. In the nextsection, I’ll examine the implementation details and show how to write objectsfor use with this statement.

The ‘with’ statement is a new control-flow structure whose basicstructure is:

withexpression[asvariable]:with-block

The expression is evaluated, and it should result in an object that supports thecontext management protocol (that is, has__enter__() and__exit__()methods.

The object’s__enter__() is called beforewith-block is executed andtherefore can run set-up code. It also may return a value that is bound to thenamevariable, if given. (Note carefully thatvariable isnot assignedthe result ofexpression.)

After execution of thewith-block is finished, the object’s__exit__()method is called, even if the block raised an exception, and can therefore runclean-up code.

To enable the statement in Python 2.5, you need to add the following directiveto your module:

from__future__importwith_statement

The statement will always be enabled in Python 2.6.

Some standard Python objects now support the context management protocol and canbe used with the ‘with’ statement. File objects are one example:

withopen('/etc/passwd','r')asf:forlineinf:printline...moreprocessingcode...

After this statement has executed, the file object inf will have beenautomatically closed, even if thefor loop raised an exceptionpart-way through the block.

Thethreading module’s locks and condition variables also support the‘with’ statement:

lock=threading.Lock()withlock:# Critical section of code...

The lock is acquired before the block is executed and always released once theblock is complete.

The newlocalcontext() function in thedecimal module makes it easyto save and restore the current decimal context, which encapsulates the desiredprecision and rounding characteristics for computations:

fromdecimalimportDecimal,Context,localcontext# Displays with default precision of 28 digitsv=Decimal('578')printv.sqrt()withlocalcontext(Context(prec=16)):# All code in this block uses a precision of 16 digits.# The original context is restored on exiting the block.printv.sqrt()

db_connection=DatabaseConnection()withdb_connectionascursor:cursor.execute('insert into ...')cursor.execute('delete from ...')# ... more operations ...

classDatabaseConnection:# Database interfacedefcursor(self):"Returns a cursor object and starts a new transaction"defcommit(self):"Commits current transaction"defrollback(self):"Rolls back current transaction"

classDatabaseConnection:...def__enter__(self):# Code to start a new transactioncursor=self.cursor()returncursor

classDatabaseConnection:...def__exit__(self,type,value,tb):iftbisNone:# No exception, so commitself.commit()else:# Exception occurred, so rollback.self.rollback()# return False

fromcontextlibimportcontextmanager@contextmanagerdefdb_transaction(connection):cursor=connection.cursor()try:yieldcursorexcept:connection.rollback()raiseelse:connection.commit()db=DatabaseConnection()withdb_transaction(db)ascursor:...

lock=threading.Lock()withnested(db_transaction(db),lock)as(cursor,locked):...

importurllib,sysfromcontextlibimportclosingwithclosing(urllib.urlopen('http://www.yahoo.com'))asf:forlineinf:sys.stdout.write(line)

PEP 352: Exceptions as New-Style Classes¶

Exception classes can now be new-style classes, not just classic classes, andthe built-inException class and all the standard built-in exceptions(NameError,ValueError, etc.) are now new-style classes.

The inheritance hierarchy for exceptions has been rearranged a bit. In 2.5, theinheritance relationships are:

BaseException# New in Python 2.5|-KeyboardInterrupt|-SystemExit|-Exception|-(allothercurrentbuilt-inexceptions)

This rearrangement was done because people often want to catch all exceptionsthat indicate program errors.KeyboardInterrupt andSystemExitaren’t errors, though, and usually represent an explicit action such as the userhittingControl-C or code callingsys.exit(). A bareexcept: willcatch all exceptions, so you commonly need to listKeyboardInterrupt andSystemExit in order to re-raise them. The usual pattern is:

try:...except(KeyboardInterrupt,SystemExit):raiseexcept:# Log error...# Continue running program...

In Python 2.5, you can now writeexceptException to achieve the sameresult, catching all the exceptions that usually indicate errors but leavingKeyboardInterrupt andSystemExit alone. As in previous versions,a bareexcept: still catches all exceptions.

The goal for Python 3.0 is to require any class raised as an exception to derivefromBaseException or some descendant ofBaseException, and futurereleases in the Python 2.x series may begin to enforce this constraint.Therefore, I suggest you begin making all your exception classes derive fromException now. It’s been suggested that the bareexcept: form shouldbe removed in Python 3.0, but Guido van Rossum hasn’t decided whether to do thisor not.

Raising of strings as exceptions, as in the statementraise"Erroroccurred", is deprecated in Python 2.5 and will trigger a warning. The aim isto be able to remove the string-exception feature in a few releases.

PEP 353: Using ssize_t as the index type¶

A wide-ranging change to Python’s C API, using a newPy_ssize_t typedefinition instead ofint, will permit the interpreter to handle moredata on 64-bit platforms. This change doesn’t affect Python’s capacity on 32-bitplatforms.

Various pieces of the Python interpreter used C’sint type to storesizes or counts; for example, the number of items in a list or tuple were storedin anint. The C compilers for most 64-bit platforms still defineint as a 32-bit type, so that meant that lists could only hold up to2**31-1 = 2147483647 items. (There are actually a few differentprogramming models that 64-bit C compilers can use – seehttps://unix.org/version2/whatsnew/lp64_wp.html for a discussion – but themost commonly available model leavesint as 32 bits.)

A limit of 2147483647 items doesn’t really matter on a 32-bit platform becauseyou’ll run out of memory before hitting the length limit. Each list itemrequires space for a pointer, which is 4 bytes, plus space for aPyObject representing the item. 2147483647*4 is already more bytesthan a 32-bit address space can contain.

It’s possible to address that much memory on a 64-bit platform, however. Thepointers for a list that size would only require 16 GiB of space, so it’s notunreasonable that Python programmers might construct lists that large.Therefore, the Python interpreter had to be changed to use some type other thanint, and this will be a 64-bit type on 64-bit platforms. The changewill cause incompatibilities on 64-bit machines, so it was deemed worth makingthe transition now, while the number of 64-bit users is still relatively small.(In 5 or 10 years, we mayall be on 64-bit machines, and the transition wouldbe more painful then.)

This change most strongly affects authors of C extension modules. Pythonstrings and container types such as lists and tuples now usePy_ssize_t to store their size. Functions such asPyList_Size() now returnPy_ssize_t. Code in extension modulesmay therefore need to have some variables changed toPy_ssize_t.

ThePyArg_ParseTuple() andPy_BuildValue() functions have a newconversion code,n, forPy_ssize_t.PyArg_ParseTuple()’ss# andt# still outputint by default, but you can define themacroPY_SSIZE_T_CLEAN before includingPython.h to makethem returnPy_ssize_t.

PEP 353 has a section on conversion guidelines that extension authors shouldread to learn about supporting 64-bit platforms.

PEP 357: The ‘__index__’ method¶

The NumPy developers had a problem that could only be solved by adding a newspecial method,__index__(). When using slice notation, as in[start:stop:step], the values of thestart,stop, andstep indexesmust all be either integers or long integers. NumPy defines a variety ofspecialized 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 beused as slice indexes.

Slicing can’t just use the existing__int__() method because that methodis also used to implement coercion to integers. If slicing used__int__(), floating-point numbers would also become legal slice indexesand that’s clearly an undesirable behaviour.

Instead, a new special method called__index__() was added. It takes noarguments and returns an integer giving the slice index to use. For example:

classC:def__index__(self):returnself.value

The return value must be either a Python integer or long integer. Theinterpreter will check that the type returned is correct, and raises aTypeError if this requirement isn’t met.

A correspondingnb_index slot was added to the C-levelPyNumberMethods structure to let C extensions implement this protocol.PyNumber_Index(obj) can be used in extension code to call the__index__() function and retrieve its result.

Other Language Changes¶

Here are all of the changes that Python 2.5 makes to the core Python language.

• Thedict type has a new hook for letting subclasses provide a defaultvalue when a key isn’t contained in the dictionary. When a key isn’t found, thedictionary’s__missing__(key) method will be called. This hook is usedto implement the newdefaultdict class in thecollectionsmodule. The following example defines a dictionary that returns zero for anymissing key:

  classzerodict(dict):def__missing__(self,key):return0d=zerodict({1:1,2:2})printd[1],d[2]# Prints 1, 2printd[3],d[4]# Prints 0, 0

• Both 8-bit and Unicode strings have newpartition(sep) andrpartition(sep) methods that simplify a common use case.

  Thefind(S) method is often used to get an index which is then used toslice the string and obtain the pieces that are before and after the separator.partition(sep) condenses this pattern into a single method call thatreturns a 3-tuple containing the substring before the separator, the separatoritself, 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 elementsare empty.rpartition(sep) also returns a 3-tuple but starts searchingfrom the end of the string; ther stands for ‘reverse’.

  Some examples:

  >>>('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')

  (Implemented by Fredrik Lundh following a suggestion by Raymond Hettinger.)

• Thestartswith() andendswith() methods of string types now accepttuples of strings to check for.

  defis_image_file(filename):returnfilename.endswith(('.gif','.jpg','.tiff'))

  (Implemented by Georg Brandl following a suggestion by Tom Lynn.)

• Themin() andmax() built-in functions gained akey keywordparameter analogous to thekey argument forsort(). This parametersupplies a function that takes a single argument and is called for every valuein the list;min()/max() will return the element with thesmallest/largest return value from this function. For example, to find thelongest string in a list, you can do:

  L=['medium','longest','short']# Prints 'longest'printmax(L,key=len)# Prints 'short', because lexicographically 'short' has the largest valueprintmax(L)

  (Contributed by Steven Bethard and Raymond Hettinger.)

• Two new built-in functions,any() andall(), evaluate whether aniterator contains any true or false values.any() returnsTrueif any value returned by the iterator is true; otherwise it will returnFalse.all() returnsTrue only if all of the valuesreturned by the iterator evaluate as true. (Suggested by Guido van Rossum, andimplemented by Raymond Hettinger.)

• The result of a class’s__hash__() method can now be either a longinteger or a regular integer. If a long integer is returned, the hash of thatvalue is taken. In earlier versions the hash value was required to be aregular integer, but in 2.5 theid() built-in was changed to alwaysreturn non-negative numbers, and users often seem to useid(self) in__hash__() methods (though this is discouraged).

• ASCII is now the default encoding for modules. It’s now a syntax error if amodule contains string literals with 8-bit characters but doesn’t have anencoding declaration. In Python 2.4 this triggered a warning, not a syntaxerror. SeePEP 263 for how to declare a module’s encoding; for example, youmight add a line like this near the top of the source file:

  # -*- coding: latin1 -*-

• A new warning,UnicodeWarning, is triggered when you attempt tocompare a Unicode string and an 8-bit string that can’t be converted to Unicodeusing the default ASCII encoding. The result of the comparison is false:

  >>>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 unequalFalse>>>chr(127)==unichr(127)# chr(127) can be convertedTrue

  Previously this would raise aUnicodeDecodeError exception, but in 2.5this could result in puzzling problems when accessing a dictionary. If youlooked upunichr(128) andchr(128) was being used as a key, you’d get aUnicodeDecodeError exception. Other changes in 2.5 resulted in thisexception being raised instead of suppressed by the code indictobject.cthat implements dictionaries.

  Raising an exception for such a comparison is strictly correct, but the changemight have broken code, so insteadUnicodeWarning was introduced.

  (Implemented by Marc-André Lemburg.)

• One error that Python programmers sometimes make is forgetting to include an__init__.py module in a package directory. Debugging this mistake can beconfusing, and usually requires running Python with the-v switch tolog all the paths searched. In Python 2.5, a newImportWarning warning istriggered when an import would have picked up a directory as a package but no__init__.py was found. This warning is silently ignored by default;provide the-Wd option when running the Python executable to displaythe warning message. (Implemented by Thomas Wouters.)

• The list of base classes in a class definition can now be empty. As anexample, this is now legal:

  classC():pass

  (Implemented by Brett Cannon.)

>>>quit'Use Ctrl-D (i.e. EOF) to exit.'

New, Improved, and Removed 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 bymodule name. Consult theMisc/NEWS file in the source tree for a morecomplete list of changes, or look through the SVN logs for all the details.

• Theaudioop module now supports the a-LAW encoding, and the code foru-LAW encoding has been improved. (Contributed by Lars Immisch.)

• Thecodecs module gained support for incremental codecs. Thecodec.lookup() function now returns aCodecInfo instance insteadof a tuple.CodecInfo instances behave like a 4-tuple to preservebackward compatibility but also have the attributesencode,decode,incrementalencoder,incrementaldecoder,streamwriter, andstreamreader. Incremental codecs can receiveinput and produce output in multiple chunks; the output is the same as if theentire input was fed to the non-incremental codec. See thecodecs moduledocumentation for details. (Designed and implemented by Walter Dörwald.)

• Thecollections module gained a new type,defaultdict, thatsubclasses the standarddict type. The new type mostly behaves like adictionary 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 todefaultdict’s constructor is a factory functionthat gets called whenever a key is requested but not found. This factoryfunction receives no arguments, so you can use built-in type constructors suchaslist() orint(). For example, you can make an index of wordsbased on their initial letter like this:

  words="""Nel mezzo del cammin di nostra vitami ritrovai per una selva oscurache la diritta via era smarrita""".lower().split()index=defaultdict(list)forwinwords:init_letter=w[0]index[init_letter].append(w)

  Printingindex results in the following output:

  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']}

  (Contributed by Guido van Rossum.)

• Thedeque double-ended queue type supplied by thecollectionsmodule now has aremove(value) method that removes the first occurrenceofvalue in the queue, raisingValueError if the value isn’t found.(Contributed by Raymond Hettinger.)

• New module: Thecontextlib module contains helper functions for usewith the new ‘with’ statement. See sectionThe contextlib modulefor more about this module.

• New module: ThecProfile module is a C implementation of the existingprofile module that has much lower overhead. The module’s interface isthe same asprofile: you runcProfile.run('main()') to profile afunction, can save profile data to a file, etc. It’s not yet known if theHotshot profiler, which is also written in C but doesn’t match theprofile module’s interface, will continue to be maintained in futureversions of Python. (Contributed by Armin Rigo.)

  Also, thepstats module for analyzing the data measured by the profilernow supports directing the output to any file object by supplying astreamargument to theStats constructor. (Contributed by Skip Montanaro.)

• Thecsv module, which parses files in comma-separated value format,received several enhancements and a number of bugfixes. You can now set themaximum size in bytes of a field by calling thecsv.field_size_limit(new_limit) function; omitting thenew_limitargument will return the currently set limit. Thereader class now hasaline_num attribute that counts the number of physical lines read fromthe source; records can span multiple physical lines, soline_num is notthe same as the number of records read.

  The CSV parser is now stricter about multi-line quoted fields. Previously, if aline ended within a quoted field without a terminating newline character, anewline would be inserted into the returned field. This behavior caused problemswhen reading files that contained carriage return characters within fields, sothe code was changed to return the field without inserting newlines. As aconsequence, if newlines embedded within fields are important, the input shouldbe split into lines in a manner that preserves the newline characters.

  (Contributed by Skip Montanaro and Andrew McNamara.)

• Thedatetime class in thedatetime module now has astrptime(string,format) method for parsing date strings, contributedby Josh Spoerri. It uses the same format characters astime.strptime() andtime.strftime():

  fromdatetimeimportdatetimets=datetime.strptime('10:13:15 2006-03-07','%H:%M:%S %Y-%m-%d')

• TheSequenceMatcher.get_matching_blocks() method in thedifflibmodule now guarantees to return a minimal list of blocks describing matchingsubsequences. Previously, the algorithm would occasionally break a block ofmatching elements into two list entries. (Enhancement by Tim Peters.)

• Thedoctest module gained aSKIP option that keeps an example frombeing executed at all. This is intended for code snippets that are usageexamples intended for the reader and aren’t actually test cases.

  Anencoding parameter was added to thetestfile() function and theDocFileSuite class to specify the file’s encoding. This makes iteasier to use non-ASCII characters in tests contained within a docstring.(Contributed by Bjorn Tillenius.)

• Theemail package has been updated to version 4.0. (Contributed byBarry Warsaw.)

• Thefileinput module was made more flexible. Unicode filenames are nowsupported, and amode parameter that defaults to"r" was added to theinput() function to allow opening files in binary oruniversalnewlines mode. Another new parameter,openhook, lets you use a functionother thanopen() to open the input files. Once you’re iterating overthe set of files, theFileInput object’s newfileno() returnsthe file descriptor for the currently opened file. (Contributed by GeorgBrandl.)

• In thegc module, the newget_count() function returns a 3-tuplecontaining the current collection counts for the three GC generations. This isaccounting information for the garbage collector; when these counts reach aspecified threshold, a garbage collection sweep will be made. The existinggc.collect() function now takes an optionalgeneration argument of 0, 1,or 2 to specify which generation to collect. (Contributed by Barry Warsaw.)

• Thensmallest() andnlargest() functions in theheapqmodule now support akey keyword parameter similar to the one provided bythemin()/max() functions and thesort() methods. Forexample:

  >>>importheapq>>>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']

  (Contributed by Raymond Hettinger.)

• Theitertools.islice() function now acceptsNone for the start andstep arguments. This makes it more compatible with the attributes of sliceobjects, so that you can now write the following:

  s=slice(5)# Create slice objectitertools.islice(iterable,s.start,s.stop,s.step)

  (Contributed by Raymond Hettinger.)

• Theformat() function in thelocale module has been modified andtwo new functions were added,format_string() andcurrency().

  Theformat() function’sval parameter could previously be a string aslong as no more than one %char specifier appeared; now the parameter must beexactly one %char specifier with no surrounding text. An optionalmonetaryparameter was also added which, ifTrue, will use the locale’s rules forformatting currency in placing a separator between groups of three digits.

  To format strings with multiple %char specifiers, use the newformat_string() function that works likeformat() but also supportsmixing %char specifiers with arbitrary text.

  A newcurrency() function was also added that formats a number accordingto the current locale’s settings.

  (Contributed by Georg Brandl.)

• Themailbox module underwent a massive rewrite to add the capability tomodify mailboxes in addition to reading them. A new set of classes that includembox,MH, andMaildir are used to read mailboxes, andhave anadd(message) method to add messages,remove(key) toremove messages, andlock()/unlock() to lock/unlock the mailbox.The following example converts a maildir-format mailbox into an mbox-formatone:

  importmailbox# 'factory=None' uses email.Message.Message as the class representing# individual messages.src=mailbox.Maildir('maildir',factory=None)dest=mailbox.mbox('/tmp/mbox')formsginsrc:dest.add(msg)

  (Contributed by Gregory K. Johnson. Funding was provided by Google’s 2005Summer of Code.)

• New module: themsilib module allows creating Microsoft Installer.msi files and CAB files. Some support for reading the.msidatabase is also included. (Contributed by Martin von Löwis.)

• Thenis module now supports accessing domains other than the systemdefault domain by supplying adomain argument to thenis.match() andnis.maps() functions. (Contributed by Ben Bell.)

• Theoperator module’sitemgetter() andattrgetter()functions now support multiple fields. A call such asoperator.attrgetter('a','b') will return a function that retrieves thea andb attributes. Combining this new feature with thesort() method’skey parameter lets you easily sort lists usingmultiple fields. (Contributed by Raymond Hettinger.)

• Theoptparse module was updated to version 1.5.1 of the Optik library.TheOptionParser class gained anepilog attribute, a stringthat will be printed after the help message, and adestroy() method tobreak reference cycles created by the object. (Contributed by Greg Ward.)

• Theos module underwent several changes. Thestat_float_timesvariable now defaults to true, meaning thatos.stat() will now return timevalues as floats. (This doesn’t necessarily mean thatos.stat() willreturn times that are precise to fractions of a second; not all systems supportsuch precision.)

  Constants namedos.SEEK_SET,os.SEEK_CUR, andos.SEEK_END have been added; these are the parameters to theos.lseek() function. Two new constants for locking areos.O_SHLOCK andos.O_EXLOCK.

  Two new functions,wait3() andwait4(), were added. They’re similarthewaitpid() function which waits for a child process to exit and returnsa tuple of the process ID and its exit status, butwait3() andwait4() return additional information.wait3() doesn’t take aprocess ID as input, so it waits for any child process to exit and returns a3-tuple ofprocess-id,exit-status,resource-usage as returned from theresource.getrusage() function.wait4(pid) does take a process ID.(Contributed by Chad J. Schroeder.)

  On FreeBSD, theos.stat() function now returns times with nanosecondresolution, and the returned object now hasst_gen andst_birthtime. Thest_flags attribute is also available, if theplatform supports it. (Contributed by Antti Louko and Diego Pettenò.)

• The Python debugger provided by thepdb module can now store lists ofcommands to execute when a breakpoint is reached and execution stops. Oncebreakpoint #1 has been created, entercommands1 and enter a series ofcommands to be executed, finishing the list withend. The command list caninclude commands that resume execution, such ascontinue ornext.(Contributed by Grégoire Dooms.)

• Thepickle andcPickle modules no longer accept a return valueofNone from the__reduce__() method; the method must return a tupleof arguments instead. The ability to returnNone was deprecated in Python2.4, so this completes the removal of the feature.

• Thepkgutil module, containing various utility functions for findingpackages, was enhanced to supportPEP 302’s import hooks and now also works forpackages stored in ZIP-format archives. (Contributed by Phillip J. Eby.)

• The pybench benchmark suite by Marc-André Lemburg is now included in theTools/pybench directory. The pybench suite is an improvement on thecommonly usedpystone.py program because pybench provides a moredetailed measurement of the interpreter’s speed. It times particular operationssuch as function calls, tuple slicing, method lookups, and numeric operations,instead of performing many different operations and reducing the result to asingle number aspystone.py does.

• Thepyexpat module now uses version 2.0 of the Expat parser.(Contributed by Trent Mick.)

• TheQueue class provided by theQueue module gained two newmethods.join() blocks until all items in the queue have been retrievedand all processing work on the items have been completed. Worker threads callthe other new method,task_done(), to signal that processing for an itemhas been completed. (Contributed by Raymond Hettinger.)

• The oldregex andregsub modules, which have been deprecatedever since Python 2.0, have finally been deleted. Other deleted modules:statcache,tzparse,whrandom.

• Also deleted: thelib-old directory, which includes ancient modulessuch asdircmp andni, was removed.lib-old wasn’t on thedefaultsys.path, so unless your programs explicitly added the directory tosys.path, this removal shouldn’t affect your code.

• Therlcompleter module is no longer dependent on importing thereadline module and therefore now works on non-Unix platforms. (Patchfrom Robert Kiendl.)

• TheSimpleXMLRPCServer andDocXMLRPCServer classes now have arpc_paths attribute that constrains XML-RPC operations to a limited setof URL paths; the default is to allow only'/' and'/RPC2'. Settingrpc_paths toNone or an empty tuple disables this path checking.

• Thesocket module now supportsAF_NETLINK sockets on Linux,thanks to a patch from Philippe Biondi. Netlink sockets are a Linux-specificmechanism for communications between a user-space process and kernel code; anintroductory article about them is athttps://www.linuxjournal.com/article/7356.In Python code, netlink addresses are represented as a tuple of 2 integers,(pid,group_mask).

  Two new methods on socket objects,recv_into(buffer) andrecvfrom_into(buffer), store the received data in an object thatsupports the buffer protocol instead of returning the data as a string. Thismeans you can put the data directly into an array or a memory-mapped file.

  Socket objects also gainedgetfamily(),gettype(), andgetproto() accessor methods to retrieve the family, type, and protocolvalues for the socket.

• New module: thespwd module provides functions for accessing the shadowpassword database on systems that support shadow passwords.

• Thestruct is now faster because it compiles format strings intoStruct objects withpack() andunpack() methods. This issimilar to how there module lets you create compiled regular expressionobjects. You can still use the module-levelpack() andunpack()functions; they’ll createStruct objects and cache them. Or you canuseStruct instances directly:

  s=struct.Struct('ih3s')data=s.pack(1972,187,'abc')year,number,name=s.unpack(data)

  You can also pack and unpack data to and from buffer objects directly using thepack_into(buffer,offset,v1,v2,...) andunpack_from(buffer,offset) methods. This lets you store data directly into an array or amemory-mapped file.

  (Struct objects were implemented by Bob Ippolito at the NeedForSpeedsprint. Support for buffer objects was added by Martin Blais, also at theNeedForSpeed sprint.)

• The Python developers switched from CVS to Subversion during the 2.5development process. Information about the exact build version is available asthesys.subversion variable, a 3-tuple of(interpreter-name,branch-name,revision-range). For example, at the time of writing my copy of 2.5 wasreporting('CPython','trunk','45313:45315').

  This information is also available to C extensions via thePy_GetBuildInfo() function that returns a string of build informationlike this:"trunk:45355:45356M,Apr132006,07:42:19". (Contributed byBarry Warsaw.)

• Another new function,sys._current_frames(), returns the current stackframes for all running threads as a dictionary mapping thread identifiers to thetopmost stack frame currently active in that thread at the time the function iscalled. (Contributed by Tim Peters.)

• TheTarFile class in thetarfile module now has anextractall() method that extracts all members from the archive into thecurrent working directory. It’s also possible to set a different directory asthe 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 autodetectedusing the mode'r|*'. (Contributed by Lars Gustäbel.)

• Thethreading module now lets you set the stack size used when newthreads are created. Thestack_size([*size*]) function returns thecurrently configured stack size, and supplying the optionalsize parametersets a new value. Not all platforms support changing the stack size, butWindows, POSIX threading, and OS/2 all do. (Contributed by Andrew MacIntyre.)

• Theunicodedata module has been updated to use version 4.1.0 of theUnicode character database. Version 3.2.0 is required by some specifications,so it’s still available asunicodedata.ucd_3_2_0.

• New module: theuuid module generates universally unique identifiers(UUIDs) according toRFC 4122. The RFC defines several different UUIDversions that are generated from a starting string, from system properties, orpurely randomly. This module contains aUUID class and functionsnameduuid1(),uuid3(),uuid4(), anduuid5() togenerate different versions of UUID. (Version 2 UUIDs are not specified inRFC 4122 and are not supported by this module.)

  >>>importuuid>>># 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')

  (Contributed by Ka-Ping Yee.)

• Theweakref module’sWeakKeyDictionary andWeakValueDictionary types gained new methods for iterating over theweak references contained in the dictionary.iterkeyrefs() andkeyrefs() methods were added toWeakKeyDictionary, anditervaluerefs() andvaluerefs() were added toWeakValueDictionary. (Contributed by Fred L. Drake, Jr.)

• Thewebbrowser module received a number of enhancements. It’s nowusable as a script withpython-mwebbrowser, taking a URL as the argument;there are a number of switches to control the behaviour (-n for a newbrowser window,-t for a new tab). New module-level functions,open_new() andopen_new_tab(), were added to support this. Themodule’sopen() function supports an additional feature, anautoraiseparameter that signals whether to raise the open window when possible. A numberof additional browsers were added to the supported list such as Firefox, Opera,Konqueror, and elinks. (Contributed by Oleg Broytmann and Georg Brandl.)

• Thexmlrpclib module now supports returningdatetime objectsfor the XML-RPC date type. Supplyuse_datetime=True to theloads()function or theUnmarshaller class to enable this feature. (Contributedby Skip Montanaro.)

• Thezipfile module now supports the ZIP64 version of the format,meaning that a .zip archive can now be larger than 4 GiB and can containindividual files larger than 4 GiB. (Contributed by Ronald Oussoren.)

• Thezlib module’sCompress andDecompress objects nowsupport acopy() method that makes a copy of the object’s internal stateand returns a newCompress orDecompress object.(Contributed by Chris AtLee.)

importctypeslibc=ctypes.CDLL('libc.so.6')result=libc.printf("Line of output\n")

s="this is a string"buf=ctypes.create_string_buffer(s)libc.strfry(buf)

>>>libc.atof('2.71828')-1783957616>>>libc.atof.restype=ctypes.c_double>>>libc.atof('2.71828')2.71828

importctypesd={}ctypes.pythonapi.PyObject_SetItem(ctypes.py_object(d),ctypes.py_object("abc"),ctypes.py_object(1))# d is now {'abc', 1}.

fromxml.etreeimportElementTreeasETtree=ET.parse('ex-1.xml')feed=urllib.urlopen('http://planet.python.org/rss10.xml')tree=ET.parse(feed)

svg=ET.XML("""<svg width="10px" version="1.0">             </svg>""")svg.set('height','320px')svg.append(elem1)

ifelem.tagisET.Comment:...elifelem.tagisET.ProcessingInstruction:...

# Encoding is US-ASCIItree.write('output.xml')# Encoding is UTF-8f=open('output.xml','w')tree.write(f,encoding='utf-8')

# Old versionsh=md5.md5()h=md5.new()# New versionh=hashlib.md5()# Old versionsh=sha.sha()h=sha.new()# New versionh=hashlib.sha1()# Hash that weren't previously availableh=hashlib.sha224()h=hashlib.sha256()h=hashlib.sha384()h=hashlib.sha512()# Alternative formh=hashlib.new('md5')# Provide algorithm as a string

conn=sqlite3.connect('/tmp/example')

c=conn.cursor()# Create tablec.execute('''create table stocks(date text, trans text, symbol text, qty real, price real)''')# Insert a row of datac.execute("""insert into stocks          values ('2006-01-05','BUY','RHAT',100,35.14)""")

# Never do this -- insecure!symbol='IBM'c.execute("... where symbol = '%s'"%symbol)# Do this insteadt=(symbol,)c.execute('select * from stocks where symbol=?',t)# Larger examplefortin(('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)

>>>c=conn.cursor()>>>c.execute('select * from stocks order by price')>>>forrowinc:...printrow...(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)>>>

fromwsgirefimportsimple_serverwsgi_app=...host=''port=8000httpd=simple_server.make_server(host,port,wsgi_app)httpd.serve_forever()

Build and C API Changes¶

Changes to Python’s build process and to the C API include:

• The Python source tree was converted from CVS to Subversion, in a complexmigration procedure that was supervised and flawlessly carried out by Martin vonLöwis. The procedure was developed asPEP 347.

• Coverity, a company that markets a source code analysis tool called Prevent,provided the results of their examination of the Python source code. Theanalysis found about 60 bugs that were quickly fixed. Many of the bugs wererefcounting problems, often occurring in error-handling code. Seehttps://scan.coverity.com for the statistics.

• The largest change to the C API came fromPEP 353, which modifies theinterpreter to use aPy_ssize_t type definition instead ofint. See the earlier sectionPEP 353: Using ssize_t as the index type for a discussion of thischange.

• The design of the bytecode compiler has changed a great deal, no longergenerating bytecode by traversing the parse tree. Instead the parse tree isconverted to an abstract syntax tree (or AST), and it is the abstract syntaxtree that’s traversed to produce the bytecode.

  It’s possible for Python code to obtain AST objects by using thecompile() built-in and specifying_ast.PyCF_ONLY_AST as the value oftheflags parameter:

  from_astimportPyCF_ONLY_ASTast=compile("""a=0for i in range(10):    a += i""","<string>",'exec',PyCF_ONLY_AST)assignment=ast.body[0]for_loop=ast.body[1]

  No official documentation has been written for the AST code yet, butPEP 339discusses the design. To start learning about the code, read the definition ofthe various AST nodes inParser/Python.asdl. A Python script reads thisfile and generates a set of C structure definitions inInclude/Python-ast.h. ThePyParser_ASTFromString() andPyParser_ASTFromFile(), defined inInclude/pythonrun.h, takePython source as input and return the root of an AST representing the contents.This AST can then be turned into a code object byPyAST_Compile(). Formore information, read the source code, and then ask questions on python-dev.

  The AST code was developed under Jeremy Hylton’s management, and implemented by(in alphabetical order) Brett Cannon, Nick Coghlan, Grant Edwards, JohnEhresman, Kurt Kaiser, Neal Norwitz, Tim Peters, Armin Rigo, and NeilSchemenauer, plus the participants in a number of AST sprints at conferencessuch as PyCon.

• 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 neverfreed arenas. With this patch, Python will free arenas when they’re empty. Thenet effect is that on some platforms, when you allocate many objects, Python’smemory usage may actually drop when you delete them and the memory may bereturned to the operating system. (Implemented by Evan Jones, and reworked byTim Peters.)

  Note that this change means extension modules must be more careful whenallocating memory. Python’s API has many different functions for allocatingmemory that are grouped into families. For example,PyMem_Malloc(),PyMem_Realloc(), andPyMem_Free() are one family that allocatesraw memory, whilePyObject_Malloc(),PyObject_Realloc(), andPyObject_Free() are another family that’s supposed to be used forcreating Python objects.

  Previously these different families all reduced to the platform’smalloc() andfree() functions. This meant it didn’t matter ifyou got things wrong and allocated memory with thePyMem function butfreed it with thePyObject function. With 2.5’s changes to obmalloc,these families now do different things and mismatches will probably result in asegfault. You should carefully test your C extension modules with Python 2.5.

• The built-in set types now have an official C API. CallPySet_New()andPyFrozenSet_New() to create a new set,PySet_Add() andPySet_Discard() to add and remove elements, andPySet_Contains()andPySet_Size() to examine the set’s state. (Contributed by RaymondHettinger.)

• C code can now obtain information about the exact revision of the Pythoninterpreter by calling thePy_GetBuildInfo() function that returns astring of build information like this:"trunk:45355:45356M,Apr132006,07:42:19". (Contributed by Barry Warsaw.)

• Two new macros can be used to indicate C functions that are local to thecurrent file so that a faster calling convention can be used.Py_LOCAL declares the function as returning a value of thespecifiedtype and uses a fast-calling qualifier.Py_LOCAL_INLINE does the same thing and also requests thefunction be inlined. If macroPY_LOCAL_AGGRESSIVE is defined beforepython.h is included, a set of more aggressive optimizations are enabledfor the module; you should benchmark the results to find out if theseoptimizations actually make the code faster. (Contributed by Fredrik Lundh atthe NeedForSpeed sprint.)

• PyErr_NewException(name,base,dict) can now accept a tuple of baseclasses as itsbase argument. (Contributed by Georg Brandl.)

• ThePyErr_Warn() function for issuing warnings is now deprecated infavour ofPyErr_WarnEx(category,message,stacklevel) which lets youspecify the number of stack frames separating this function and the caller. Astacklevel of 1 is the function callingPyErr_WarnEx(), 2 is thefunction above that, and so forth. (Added by Neal Norwitz.)

• The CPython interpreter is still written in C, but the code can now becompiled with a C++ compiler without errors. (Implemented by Anthony Baxter,Martin von Löwis, Skip Montanaro.)

• ThePyRange_New() function was removed. It was never documented, neverused in the core code, and had dangerously lax error checking. In the unlikelycase that your extensions were using it, you can replace it by something likethe following:

  range=PyObject_CallFunction((PyObject*)&PyRange_Type,"lll",start,stop,step);

Porting to Python 2.5¶

This section lists previously described changes that may require changes to yourcode:

• ASCII is now the default encoding for modules. It’s now a syntax error if amodule contains string literals with 8-bit characters but doesn’t have anencoding declaration. In Python 2.4 this triggered a warning, not a syntaxerror.

• Previously, thegi_frame attribute of a generator was always a frameobject. Because of thePEP 342 changes described in sectionPEP 342: New Generator Features,it’s now possible forgi_frame to beNone.

• A new warning,UnicodeWarning, is triggered when you attempt tocompare a Unicode string and an 8-bit string that can’t be converted to Unicodeusing the default ASCII encoding. Previously such comparisons would raise aUnicodeDecodeError exception.

• Library: thecsv module is now stricter about multi-line quoted fields.If your files contain newlines embedded within fields, the input should be splitinto lines in a manner which preserves the newline characters.

• Library: thelocale module’sformat() function’s wouldpreviously accept any string as long as no more than one %char specifierappeared. In Python 2.5, the argument must be exactly one %char specifier withno surrounding text.

• Library: Thepickle andcPickle modules no longer accept areturn value ofNone from the__reduce__() method; the method mustreturn a tuple of arguments instead. The modules also no longer accept thedeprecatedbin keyword parameter.

• Library: TheSimpleXMLRPCServer andDocXMLRPCServer classes nowhave arpc_paths attribute that constrains XML-RPC operations to alimited set of URL paths; the default is to allow only'/' and'/RPC2'.Settingrpc_paths toNone or an empty tuple disables this pathchecking.

• C API: Many functions now usePy_ssize_t instead ofint toallow processing more data on 64-bit machines. Extension code may need to makethe same change to avoid warnings and to support 64-bit machines. See theearlier sectionPEP 353: Using ssize_t as the index type for a discussion of this change.

• C API: The obmalloc changes mean that you must be careful to not mix usageof thePyMem_* andPyObject_* families of functions. Memoryallocated with one family’s*_Malloc must be freed with thecorresponding family’s*_Free function.

Acknowledgements¶

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äbel, Raymond Hettinger, Ralf W.Grosse-Kunstleve, Kent Johnson, Iain Lowe, Martin von Löwis, Fredrik Lundh, AndrewMcNamara, Skip Montanaro, Gustavo Niemeyer, Paul Prescod, James Pryor, MikeRovner, Scott Weikart, Barry Warsaw, Thomas Wouters.