From 3268aff854518edc4097ca3d1db67e0d3a04fca5 Mon Sep 17 00:00:00 2001
From: Dan Crosta <dcrosta@late.am>
Date: Tue, 3 Jan 2012 10:03:59 -0500
Subject: [PATCH 1/2] some idioms I used this morning

---
 docs/writing/style.rst | 55 ++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 53 insertions(+), 2 deletions(-)

diff --git a/docs/writing/style.rst b/docs/writing/style.rst
index 803dca13d..ada5d3c2e 100644
--- a/docs/writing/style.rst
+++ b/docs/writing/style.rst
@@ -3,9 +3,60 @@ 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()
+
+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

From 8587cf6a951f9434dd8bddbe9f03cd701a527636 Mon Sep 17 00:00:00 2001
From: Dan Crosta <dcrosta@late.am>
Date: Thu, 5 Jan 2012 11:00:50 -0500
Subject: [PATCH 2/2] per feedback from @ejucovy, warn about shadowing gettext
 with "_"

---
 docs/conf.py           | 6 +++++-
 docs/writing/style.rst | 7 +++++++
 2 files changed, 12 insertions(+), 1 deletion(-)

diff --git a/docs/conf.py b/docs/conf.py
index 7aa022318..ad90eb21f 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -25,7 +25,7 @@
 
 # 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_tocdup = True
 
 todo_include_todos = True
+
+intersphinx_mapping = {
+    'python': ('http://docs.python.org/', None),
+}
diff --git a/docs/writing/style.rst b/docs/writing/style.rst
index ada5d3c2e..666ac6c03 100644
--- a/docs/writing/style.rst
+++ b/docs/writing/style.rst
@@ -37,6 +37,13 @@ will not need that variable, use ``_``:
     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
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~