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

Thu, 29 Aug 2002 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: