Merge pull request #70 from dcrosta/idioms

some idioms I used this morning

docs/conf.py

@@ -25,7 +25,7 @@ sys.path.append(os.path.abspath('_themes'))
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.ifconfig', 'sphinx.ext.todo']
+extensions = ['sphinx.ext.ifconfig', 'sphinx.ext.todo', 'sphinx.ext.intersphinx']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -260,3 +260,7 @@ epub_copyright = u'2010, Kenneth Reitz'
 #epub_tocdup = True
 
 todo_include_todos = True
+
+intersphinx_mapping = {
+    'python': ('http://docs.python.org/', None),
+}

docs/writing/style.rst

@@ -3,9 +3,67 @@ Code Style
 
 
 Idioms
-::::::
+------
+
+Idiomatic Python code is often referred to as being *Pythonic*.
+
+.. _unpacking-ref:
+
+Unpacking
+~~~~~~~~~
+
+If you know the length of a list or tuple, you can assign names to its
+elements with unpacking:
+
+.. code-block:: python
+
+    for index, item in enumerate(some_list):
+        # do something with index and item
+
+You can use this to swap variables, as well:
+
+.. code-block:: python
+
+    a, b = b, a
+
+Create an ignored variable
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you need to assign something (for instance, in :ref:`unpacking-ref`) but
+will not need that variable, use ``_``:
+
+.. code-block:: python
+
+    filename = 'foobar.txt'
+    basename, _, ext = filename.rpartition()
+
+.. note::
+
+   "``_``" is commonly used as an alias for the :func:`~gettext.gettext`
+   function. If your application uses (or may someday use) :mod:`gettext`,
+   you may want to avoid using ``_`` for ignored variables, as you may
+   accidentally shadow :func:`~gettext.gettext`.
+
+Create a length-N list of the same thing
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Use the Python list ``*`` operator:
+
+.. code-block:: python
+
+    four_nones = [None] * 4
+
+Create a length-N list of lists
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Because lists are mutable, the ``*`` operator (as above) will create a list
+of N references to the `same` list, which is not likely what you want.
+Instead, use a list comprehension:
+
+.. code-block:: python
+
+    four_lists = [[] for _ in xrange(4)]
 
-Idiomatic Python code is often referred to as being *pythonic*.
 
 
 Zen of Python