[Python-checkins] python/nondist/peps pep-0290.txt,1.3,1.4

2002年8月29日 20:11:42 -0700

Update of /cvsroot/python/python/nondist/peps
In directory usw-pr-cvs1:/tmp/cvs-serv31016
Modified Files:
	pep-0290.txt 
Log Message:
Converted to reStructuredText & edited for readability.
Index: pep-0290.txt
===================================================================
RCS file: /cvsroot/python/python/nondist/peps/pep-0290.txt,v
retrieving revision 1.3
retrieving revision 1.4
diff -C2 -d -r1.3 -r1.4
*** pep-0290.txt	12 Aug 2002 14:22:33 -0000	1.3
--- pep-0290.txt	30 Aug 2002 03:11:40 -0000	1.4
***************
*** 3,9 ****
 Version: $Revision$
 Last-Modified: $Date$
! Author: python@rcn.com (Raymond D. Hettinger)
 Status: Active
 Type: Informational
 Created: 6-Jun-2002
 Post-History:
--- 3,10 ----
 Version: $Revision$
 Last-Modified: $Date$
! Author: Raymond D. Hettinger <python@rcn.com>
 Status: Active
 Type: Informational
+ Content-Type: text/x-rst
 Created: 6-Jun-2002
 Post-History:
***************
*** 11,187 ****

 Abstract

! This PEP is a collection of procedures and ideas for updating
! Python applications when newer versions of Python are installed.

! The migration tips highlight possible areas of incompatibility and
! make suggestions on how to find and resolve those differences. The
! modernization procedures show how older code can be updated to
! take advantage of new language features.

 Rationale

! This repository of procedures serves as a catalog or checklist of
! known migration issues and procedures for addressing those issues.
! 
! Migration issues can arise for several reasons. Some obsolete
! features are slowly deprecated according to the guidelines in PEP 4.
! Also, some code relies on undocumented behaviors which are subject to
! change between versions. Some code may rely on behavior which was
! subsequently shown to be a bug and that behavior changes when the bug
! is fixed.

! Modernization options arise when new versions of Python add features
! that allow improved clarity or higher performance than previously
! available.

 Guidelines for New Entries

! Developers with commit access may update the PEP directly. Others
! can send their ideas to a developer for possible inclusion.

! While a consistent format makes the repository easier to use, feel
! free to add or subtract sections to improve clarity.

! Grep patterns may be supplied as tool to help maintainers locate
! code for possible updates. However, fully automated search/replace
! style regular expressions are not recommended. Instead, each code
! fragment should be evaluated individually.

! The contra-indications section is the most important part of a new
! entry. It lists known situations where the update SHOULD NOT be
! applied.

 Modernization Procedures

! Pattern: if d.has_key(k): --> if k in d:
! Idea: For testing dictionary membership, use the 'in' keyword
! instead of the 'has_key()' method.
! Version: 2.2 or greater
! Benefits: The result is shorter and more readable. The style becomes
! consistent with tests for membership in lists. The result is
! slightly faster because has_key requires an attribute search
! and uses a relatively expensive CALL FUNCTION op code.
! Locating: grep has_key
! Contra-indications:
! 1. if dictlike.has_key(k) ## objects like shelve do not define
! __contains__()

! Pattern: for k in d.keys() --> for k in d
! for k in d.items() --> for k in d.iteritems()
! for k in d.values() --> for k in d.itervalues()
! Idea: Use the new iter methods for looping over dictionaries
! Version: 2.2 or greater
! Benefits: The iter methods are faster because the do not have to create
! a new list object with a complete copy of all of the keys,
! values, or items. Selecting only keys, items, or values as
! needed saves the time for creating throwaway object references
! and, in the case of items, saves a second hash look-up of
! the key.
! Contra-indications:
! 1. def getids(): return d.keys() ## do not change the return type
! 2. for k in dictlike.keys() ## objects like shelve do not define
! itermethods
! 3. k = d.keys(); j = k[:] ## iterators do not support slicing,
! sorting or other operations
! 4. for k in d.keys(): del[k] ## dict iterators prohibit modifying the
! dictionary

! Pattern: if v == None --> if v is None:
! if v != None --> if v is not None:
! Idea: Since there is only one None object, equality can be tested
! with identity.
! Version: All
! Benefits: Identity tests are slightly faster than equality tests. Also,
! some object types may overload comparison to be much slower.
! Locating: grep '== None' or grep '!= None'

! Pattern: os.stat("foo")[stat.ST_MTIME] --> os.stat("foo").st_mtime
! os.stat("foo")[stat.ST_MTIME] --> os.path.getmtime("foo")
! Idea: Replace stat contants or indices with new stat methods
! Version: 2.2 or greater
! Benefits: The methods are not order dependent and do not require an
! import of the stat module
! Locating: grep os.stat

! Pattern: import whrandom --> import random
! Idea: Replace deprecated module
! Version: 2.1 or greater
! Benefits: All random methods collected in one place
! Locating: grep whrandom

! Pattern: import types ; type(v, types.IntType) --> isinstance(v, int)
! type(s, types.StringTypes --> isinstance(s, basestring)
! Idea: The types module will likely to be deprecated in the future.
! Version: 2.3 or greater (basestring introduced in Py2.3)
! Benefits: May be slightly faster, avoid a deprecated feature.
! Locating: grep types *.py | grep import

! Pattern: import string ; string.method(s, ...) --> s.method(...)
! c in string.whitespace --> c.isspace()
! Idea: The string module will likely to be deprecated in the future.
! Version: 2.0 or greater
! Benefits: Slightly faster, avoid a deprecated feature.
! Locating: grep string *.py | grep import

! Pattern: NewError = 'NewError' --> class NewError(Exception): pass
! Idea: String exceptions are deprecated, derive from the Exception
! base class.
! Version: Any
! Benefits: Unlike the obsolete string exceptions, class exceptions all
! derive from another exception or the Exception base class.
! This allows meaningful groupings of exceptions. It also
! allows an "except Exception" clause to catch all exceptions.
! Locating: Use PyChecker

! Pattern: "foobar"[:3] == "foo" -> "foobar".startswith("foo")
! "foobar"[-3:] == "bar" -> "foobar".endswith("bar")
! Version: 2.0 or greater
! Benefits: Faster because no slice has to be created. Less risk of
! miscounting.

! Pattern: "s1".find("s2") >= 0 or "s1".find("s2") != -1 -> "s2" in "s1"
! Idea: In Python 2.3, for "s2" in "s1", the length
! restriction on s2 are lifted; they can now be strings
! of any length.
! Version: 2.3 or later
! Benefits: When searching for a substring, where you don't care
! about the position of the substring in the original
! string, using the `in' operator makes things more
! clear.

! References

! [1] PEP 4, Deprecation of Standard Modules
! http://www.python.org/peps/pep-0004.html

! Copyright

! This document has been placed in the public domain.

! Local Variables:
! mode: indented-text
! indent-tabs-mode: nil
! sentence-end-double-space: t
! fill-column: 70
! End:

--- 12,288 ----

 Abstract
+ ========

! This PEP is a collection of procedures and ideas for updating Python
! applications when newer versions of Python are installed.

! The migration tips highlight possible areas of incompatibility and
! make suggestions on how to find and resolve those differences. The
! modernization procedures show how older code can be updated to take
! advantage of new language features.

 Rationale
+ =========

! This repository of procedures serves as a catalog or checklist of
! known migration issues and procedures for addressing those issues.

! Migration issues can arise for several reasons. Some obsolete
! features are slowly deprecated according to the guidelines in PEP 4
! [1]_. Also, some code relies on undocumented behaviors which are
! subject to change between versions. Some code may rely on behavior
! which was subsequently shown to be a bug and that behavior changes
! when the bug is fixed.

+ Modernization options arise when new versions of Python add features
+ that allow improved clarity or higher performance than previously
+ available.

 Guidelines for New Entries
+ ==========================

! Developers with commit access may update this PEP directly. Others
! can send their ideas to a developer for possible inclusion.

! While a consistent format makes the repository easier to use, feel
! free to add or subtract sections to improve clarity.

! Grep patterns may be supplied as tool to help maintainers locate code
! for possible updates. However, fully automated search/replace style
! regular expressions are not recommended. Instead, each code fragment
! should be evaluated individually.

! The contra-indications section is the most important part of a new
! entry. It lists known situations where the update SHOULD NOT be
! applied.

 Modernization Procedures
+ ========================

! Procedures are grouped by the Python version required to be able to
! take advantage of the modernization.

! Python 2.3 or Later
! -------------------

+ Testing String Membership
+ '''''''''''''''''''''''''

! In Python 2.3, for ``string2 in string1``, the length restriction on
! ``string2`` is lifted; it can now be a string of any length. When
! searching for a substring, where you don't care about the position of
! the substring in the original string, using the ``in`` operator makes
! the meaning clear.

+ Pattern::

! string1.find(string2) >= 0 --> string2 in string1
! string1.find(string2) != -1 --> string2 in string1

! Python 2.2 or Later
! -------------------

+ Testing Dictionary Membership
+ '''''''''''''''''''''''''''''

! For testing dictionary membership, use the 'in' keyword instead of the
! 'has_key()' method. The result is shorter and more readable. The
! style becomes consistent with tests for membership in lists. The
! result is slightly faster because ``has_key`` requires an attribute
! search and uses a relatively expensive function call.

+ Pattern::

! if d.has_key(k): --> if k in d:

+ Contra-indications:

! 1. Some dictionary-like objects like ``shelve`` do not define a
! ``__contains__()`` method::

+ if dictlike.has_key(k)

! Locating: ``grep has_key``

! Looping Over Dictionaries
! '''''''''''''''''''''''''

+ Use the new ``iter`` methods for looping over dictionaries. The
+ ``iter`` methods are faster because they do not have to create a new
+ list object with a complete copy of all of the keys, values, or items.
+ Selecting only keys, values, or items (key/value pairs) as needed
+ saves the time for creating throwaway object references and, in the
+ case of items, saves a second hash look-up of the key.

! Pattern::

! for key in d.keys(): --> for key in d:
! for value in d.values(): --> for value in d.itervalues():
! for key, value in d.items():
! --> for key, value in d.iteritems():

+ Contra-indications:

+ 1. If you need a list, do not change the return type::

! def getids(): return d.keys()

! 2. Some dictionary-like objects like ``shelve`` do not define
! ``iter`` methods::

+ for k in dictlike.keys():

+ 3. Iterators do not support slicing, sorting or other operations::

! k = d.keys(); j = k[:]

+ 4. Dictionary iterators prohibit modifying the dictionary::
+ 
+ for k in d.keys(): del[k]
+ 
+ 
+ ``stat`` Methods
+ ''''''''''''''''
+ 
+ Replace ``stat`` constants or indices with new ``os.stat`` attributes
+ and methods. The ``os.stat`` attributes and methods are not
+ order-dependent and do not require an import of the ``stat`` module.

+ Pattern::
+ 
+ os.stat("foo")[stat.ST_MTIME] --> os.stat("foo").st_mtime
+ os.stat("foo")[stat.ST_MTIME] --> os.path.getmtime("foo")
+ 
+ Locating: ``grep os.stat`` or ``grep stat.S``
+ 
+ 
+ Reduce Dependency on ``types`` Module
+ '''''''''''''''''''''''''''''''''''''
+ 
+ The ``types`` module is likely to be deprecated in the future. Use
+ built-in constructor functions instead. They may be slightly faster.
+ 
+ Pattern::
+ 
+ isinstance(v, types.IntType) --> isinstance(v, int)
+ isinstance(s, types.StringTypes) --> isinstance(s, basestring)
+ 
+ Full use of this technique requires Python 2.3 or later
+ (``basestring`` was introduced in Python 2.3), but Python 2.2 is
+ sufficient for most uses.
+ 
+ Locating: ``grep types *.py | grep import``
+ 
+ 
+ Python 2.1 or Later
+ -------------------
+ 
+ ``whrandom`` Module Deprecated
+ ''''''''''''''''''''''''''''''
+ 
+ All random-related methods have been collected in one place, the
+ ``random`` module.
+ 
+ Pattern::
+ 
+ import whrandom --> import random
+ 
+ Locating: ``grep whrandom``
+ 
+ 
+ Python 2.0 or Later
+ -------------------
+ 
+ String Methods
+ ''''''''''''''
+ 
+ The string module is likely to be deprecated in the future. Use
+ string methods instead. They're faster too.
+ 
+ Pattern::
+ 
+ import string ; string.method(s, ...) --> s.method(...)
+ c in string.whitespace --> c.isspace()
+ 
+ Locating: ``grep string *.py | grep import``
+ 
+ 
+ ``startswith`` and ``endswith`` String Methods
+ ''''''''''''''''''''''''''''''''''''''''''''''
+ 
+ Use these string methods instead of slicing. They're faster because
+ no slice has to be created, and there's no risk of miscounting.
+ 
+ Pattern::
+ 
+ "foobar"[:3] == "foo" --> "foobar".startswith("foo")
+ "foobar"[-3:] == "bar" --> "foobar".endswith("bar")
+ 
+ 
+ Python 1.5 or Later
+ -------------------
+ 
+ Class-Based Exceptions
+ ''''''''''''''''''''''
+ 
+ String exceptions are deprecated, so derive from the ``Exception``
+ base class. Unlike the obsolete string exceptions, class exceptions
+ all derive from another exception or the ``Exception`` base class.
+ This allows meaningful groupings of exceptions. It also allows an
+ "``except Exception``" clause to catch all exceptions.
+ 
+ Pattern::
+ 
+ NewError = 'NewError' --> class NewError(Exception): pass
+ 
+ Locating: Use PyChecker_.
+ 
+ 
+ All Python Versions
+ -------------------
+ 
+ Testing for ``None``
+ ''''''''''''''''''''
+ 
+ Since there is only one ``None`` object, equality can be tested with
+ identity. Identity tests are slightly faster than equality tests.
+ Also, some object types may overload comparison, so equality testing
+ may be much slower.
+ 
+ Pattern::
+ 
+ if v == None --> if v is None:
+ if v != None --> if v is not None:
+ 
+ Locating: ``grep '== None'`` or ``grep '!= None'``
+ 
+ 
+ References
+ ==========
+ 
+ .. [1] PEP 4, Deprecation of Standard Modules, von Loewis
+ (http://www.python.org/peps/pep-0004.html)
+ 
+ .. _PyChecker: http://pychecker.sourceforge.net/
+ 
+ 
+ Copyright
+ =========
+ 
+ This document has been placed in the public domain.
+ 
+ 
+ 
+ ..
+ Local Variables:
+ mode: indented-text
+ indent-tabs-mode: nil
+ sentence-end-double-space: t
+ fill-column: 70
+ End: