add examples of python idioms.

Author: Kevin Burke

docs/writing/style.rst

@@ -75,3 +75,175 @@ Then run it on a file or series of files to get a report of any violations.
     optparse.py:472:29: E221 multiple spaces before operator
     optparse.py:544:21: W601 .has_key() is deprecated, use 'in'
 
+Conventions
+:::::::::::
+
+Here are some conventions you should follow to make your code easier to read.
+
+Check if variable equals a constant
+-----------------------------------
+
+You don't need to explicitly compare a value to True, or None, or 0 - you can
+just add it to the if statement.
+
+**Bad**:
+
+.. code-block:: python
+
+    if attr == True:
+        print 'True!'
+
+    if attr == None:
+        print 'attr is None!'
+
+**Good**:
+
+.. code-block:: python
+
+    # Just check the value
+    if attr:
+        print 'True!'
+
+    # or check for the opposite
+    if not attr:
+        print 'attr is None!'
+
+Access a Dictionary Element
+---------------------------
+
+Don't use the ``has_key`` function. Instead use ``x in d`` syntax, or pass
+a default argument to ``get``.
+
+**Bad**:
+
+.. code-block:: python
+
+    d = {'hello': 'world'}
+    if d.has_key('hello'):
+        print d['hello']    # prints 'world'
+    else:
+        print 'default_value'
+
+**Good**:
+
+.. code-block:: python
+
+    d = {'hello': 'world'}
+
+    print d.get('hello', 'default_value') # prints 'world'
+    print d.get('thingy', 'default_value') # prints 'default_value'
+
+    # Or:
+    if 'hello' in d:
+        print d['hello']
+
+Short Ways to Manipulate Lists
+------------------------------
+
+`List comprehensions
+<http://docs.python.org/tutorial/datastructures.html#list-comprehensions>`_
+provide a powerful, concise way to work with lists. Also, the `map
+<http://docs.python.org/library/functions.html#map>`_ and `filter
+<http://docs.python.org/library/functions.html#filter>`_ functions can perform
+operations on lists using a different concise syntax.
+
+**Bad**:
+
+.. code-block:: python
+
+    # Filter elements less than 5
+    a = [3, 4, 5]
+    b = []
+    for i in a:
+        if a > 4:
+            b.append(a)
+
+**Good**:
+
+.. code-block:: python
+
+    b = [i for i in a if i > 4]
+    b = filter(lambda x: x > 4, a)
+
+**Bad**:
+
+.. code-block:: python
+
+    # Add three to all list members.
+    a = [3, 4, 5]
+    count = 0
+    for i in a:
+        a[count] = i + 3
+        count = count + 1
+
+**Good**:
+
+.. code-block:: python
+
+    a = [3, 4, 5]
+    a = [i + 3 for i in a]
+    # Or:
+    a = map(lambda i: i + 3, a)
+
+Use `enumerate <http://docs.python.org/library/functions.html#enumerate>`_ to
+keep a count of your place in the list.
+
+.. code-block:: python
+
+    for i, item in a:
+        print i + ", " + item
+    # prints 
+    # 0, 3
+    # 1, 4
+    # 2, 5
+
+Read From a File
+----------------
+
+Use the ``with open`` syntax to read from files. This will automatically close
+files for you.
+
+**Bad**:
+
+.. code-block:: python
+
+    f = open('file.txt')
+    a = f.read()
+    print a
+    f.close()
+
+**Good**:
+
+.. code-block:: python
+
+    with open('file.txt') as f:
+        for line in f:
+            print line
+
+Returning Multiple Values from a Function
+-----------------------------------------
+
+Python supports returning multiple values from a function as a comma-separated
+list, so you don't have to create an object or dictionary and pack multiple
+values in before you return
+
+**Bad**:
+
+.. code-block:: python
+
+    def math_func(a):
+        return {'square': a ** 2, 'cube': a ** 3}
+
+    d = math_func(3)
+    s = d['square']
+    c = d['cube']
+
+**Good**:
+
+.. code-block:: python
+
+    def math_func(a):
+        return a ** 2, a ** 3
+
+    square, cube = math_func(3)
+