/Doc/howto/doanddont.rst

http://unladen-swallow.googlecode.com/ · ReStructuredText · 308 lines · 218 code · 90 blank · 0 comment · 0 complexity · 650b92b85c3f07e6b70adaca3f710b7d MD5 · raw file

  1. ************************************
  2. Idioms and Anti-Idioms in Python
  3. ************************************
  4. :Author: Moshe Zadka
  5. This document is placed in the public domain.
  6. .. topic:: Abstract
  7. This document can be considered a companion to the tutorial. It shows how to use
  8. Python, and even more importantly, how *not* to use Python.
  9. Language Constructs You Should Not Use
  10. ======================================
  11. While Python has relatively few gotchas compared to other languages, it still
  12. has some constructs which are only useful in corner cases, or are plain
  13. dangerous.
  14. from module import \*
  15. ---------------------
  16. Inside Function Definitions
  17. ^^^^^^^^^^^^^^^^^^^^^^^^^^^
  18. ``from module import *`` is *invalid* inside function definitions. While many
  19. versions of Python do not check for the invalidity, it does not make it more
  20. valid, no more than having a smart lawyer makes a man innocent. Do not use it
  21. like that ever. Even in versions where it was accepted, it made the function
  22. execution slower, because the compiler could not be certain which names are
  23. local and which are global. In Python 2.1 this construct causes warnings, and
  24. sometimes even errors.
  25. At Module Level
  26. ^^^^^^^^^^^^^^^
  27. While it is valid to use ``from module import *`` at module level it is usually
  28. a bad idea. For one, this loses an important property Python otherwise has ---
  29. you can know where each toplevel name is defined by a simple "search" function
  30. in your favourite editor. You also open yourself to trouble in the future, if
  31. some module grows additional functions or classes.
  32. One of the most awful question asked on the newsgroup is why this code::
  33. f = open("www")
  34. f.read()
  35. does not work. Of course, it works just fine (assuming you have a file called
  36. "www".) But it does not work if somewhere in the module, the statement ``from os
  37. import *`` is present. The :mod:`os` module has a function called :func:`open`
  38. which returns an integer. While it is very useful, shadowing builtins is one of
  39. its least useful properties.
  40. Remember, you can never know for sure what names a module exports, so either
  41. take what you need --- ``from module import name1, name2``, or keep them in the
  42. module and access on a per-need basis --- ``import module;print module.name``.
  43. When It Is Just Fine
  44. ^^^^^^^^^^^^^^^^^^^^
  45. There are situations in which ``from module import *`` is just fine:
  46. * The interactive prompt. For example, ``from math import *`` makes Python an
  47. amazing scientific calculator.
  48. * When extending a module in C with a module in Python.
  49. * When the module advertises itself as ``from import *`` safe.
  50. Unadorned :keyword:`exec`, :func:`execfile` and friends
  51. -------------------------------------------------------
  52. The word "unadorned" refers to the use without an explicit dictionary, in which
  53. case those constructs evaluate code in the *current* environment. This is
  54. dangerous for the same reasons ``from import *`` is dangerous --- it might step
  55. over variables you are counting on and mess up things for the rest of your code.
  56. Simply do not do that.
  57. Bad examples::
  58. >>> for name in sys.argv[1:]:
  59. >>> exec "%s=1" % name
  60. >>> def func(s, **kw):
  61. >>> for var, val in kw.items():
  62. >>> exec "s.%s=val" % var # invalid!
  63. >>> execfile("handler.py")
  64. >>> handle()
  65. Good examples::
  66. >>> d = {}
  67. >>> for name in sys.argv[1:]:
  68. >>> d[name] = 1
  69. >>> def func(s, **kw):
  70. >>> for var, val in kw.items():
  71. >>> setattr(s, var, val)
  72. >>> d={}
  73. >>> execfile("handle.py", d, d)
  74. >>> handle = d['handle']
  75. >>> handle()
  76. from module import name1, name2
  77. -------------------------------
  78. This is a "don't" which is much weaker than the previous "don't"s but is still
  79. something you should not do if you don't have good reasons to do that. The
  80. reason it is usually bad idea is because you suddenly have an object which lives
  81. in two separate namespaces. When the binding in one namespace changes, the
  82. binding in the other will not, so there will be a discrepancy between them. This
  83. happens when, for example, one module is reloaded, or changes the definition of
  84. a function at runtime.
  85. Bad example::
  86. # foo.py
  87. a = 1
  88. # bar.py
  89. from foo import a
  90. if something():
  91. a = 2 # danger: foo.a != a
  92. Good example::
  93. # foo.py
  94. a = 1
  95. # bar.py
  96. import foo
  97. if something():
  98. foo.a = 2
  99. except:
  100. -------
  101. Python has the ``except:`` clause, which catches all exceptions. Since *every*
  102. error in Python raises an exception, this makes many programming errors look
  103. like runtime problems, and hinders the debugging process.
  104. The following code shows a great example::
  105. try:
  106. foo = opne("file") # misspelled "open"
  107. except:
  108. sys.exit("could not open file!")
  109. The second line triggers a :exc:`NameError` which is caught by the except
  110. clause. The program will exit, and you will have no idea that this has nothing
  111. to do with the readability of ``"file"``.
  112. The example above is better written ::
  113. try:
  114. foo = opne("file") # will be changed to "open" as soon as we run it
  115. except IOError:
  116. sys.exit("could not open file")
  117. There are some situations in which the ``except:`` clause is useful: for
  118. example, in a framework when running callbacks, it is good not to let any
  119. callback disturb the framework.
  120. Exceptions
  121. ==========
  122. Exceptions are a useful feature of Python. You should learn to raise them
  123. whenever something unexpected occurs, and catch them only where you can do
  124. something about them.
  125. The following is a very popular anti-idiom ::
  126. def get_status(file):
  127. if not os.path.exists(file):
  128. print "file not found"
  129. sys.exit(1)
  130. return open(file).readline()
  131. Consider the case the file gets deleted between the time the call to
  132. :func:`os.path.exists` is made and the time :func:`open` is called. That means
  133. the last line will throw an :exc:`IOError`. The same would happen if *file*
  134. exists but has no read permission. Since testing this on a normal machine on
  135. existing and non-existing files make it seem bugless, that means in testing the
  136. results will seem fine, and the code will get shipped. Then an unhandled
  137. :exc:`IOError` escapes to the user, who has to watch the ugly traceback.
  138. Here is a better way to do it. ::
  139. def get_status(file):
  140. try:
  141. return open(file).readline()
  142. except (IOError, OSError):
  143. print "file not found"
  144. sys.exit(1)
  145. In this version, \*either\* the file gets opened and the line is read (so it
  146. works even on flaky NFS or SMB connections), or the message is printed and the
  147. application aborted.
  148. Still, :func:`get_status` makes too many assumptions --- that it will only be
  149. used in a short running script, and not, say, in a long running server. Sure,
  150. the caller could do something like ::
  151. try:
  152. status = get_status(log)
  153. except SystemExit:
  154. status = None
  155. So, try to make as few ``except`` clauses in your code --- those will usually be
  156. a catch-all in the :func:`main`, or inside calls which should always succeed.
  157. So, the best version is probably ::
  158. def get_status(file):
  159. return open(file).readline()
  160. The caller can deal with the exception if it wants (for example, if it tries
  161. several files in a loop), or just let the exception filter upwards to *its*
  162. caller.
  163. The last version is not very good either --- due to implementation details, the
  164. file would not be closed when an exception is raised until the handler finishes,
  165. and perhaps not at all in non-C implementations (e.g., Jython). ::
  166. def get_status(file):
  167. fp = open(file)
  168. try:
  169. return fp.readline()
  170. finally:
  171. fp.close()
  172. Using the Batteries
  173. ===================
  174. Every so often, people seem to be writing stuff in the Python library again,
  175. usually poorly. While the occasional module has a poor interface, it is usually
  176. much better to use the rich standard library and data types that come with
  177. Python than inventing your own.
  178. A useful module very few people know about is :mod:`os.path`. It always has the
  179. correct path arithmetic for your operating system, and will usually be much
  180. better than whatever you come up with yourself.
  181. Compare::
  182. # ugh!
  183. return dir+"/"+file
  184. # better
  185. return os.path.join(dir, file)
  186. More useful functions in :mod:`os.path`: :func:`basename`, :func:`dirname` and
  187. :func:`splitext`.
  188. There are also many useful builtin functions people seem not to be aware of for
  189. some reason: :func:`min` and :func:`max` can find the minimum/maximum of any
  190. sequence with comparable semantics, for example, yet many people write their own
  191. :func:`max`/:func:`min`. Another highly useful function is :func:`reduce`. A
  192. classical use of :func:`reduce` is something like ::
  193. import sys, operator
  194. nums = map(float, sys.argv[1:])
  195. print reduce(operator.add, nums)/len(nums)
  196. This cute little script prints the average of all numbers given on the command
  197. line. The :func:`reduce` adds up all the numbers, and the rest is just some
  198. pre- and postprocessing.
  199. On the same note, note that :func:`float`, :func:`int` and :func:`long` all
  200. accept arguments of type string, and so are suited to parsing --- assuming you
  201. are ready to deal with the :exc:`ValueError` they raise.
  202. Using Backslash to Continue Statements
  203. ======================================
  204. Since Python treats a newline as a statement terminator, and since statements
  205. are often more than is comfortable to put in one line, many people do::
  206. if foo.bar()['first'][0] == baz.quux(1, 2)[5:9] and \
  207. calculate_number(10, 20) != forbulate(500, 360):
  208. pass
  209. You should realize that this is dangerous: a stray space after the ``\`` would
  210. make this line wrong, and stray spaces are notoriously hard to see in editors.
  211. In this case, at least it would be a syntax error, but if the code was::
  212. value = foo.bar()['first'][0]*baz.quux(1, 2)[5:9] \
  213. + calculate_number(10, 20)*forbulate(500, 360)
  214. then it would just be subtly wrong.
  215. It is usually much better to use the implicit continuation inside parenthesis:
  216. This version is bulletproof::
  217. value = (foo.bar()['first'][0]*baz.quux(1, 2)[5:9]
  218. + calculate_number(10, 20)*forbulate(500, 360))