mention a coding convention

1 files changed, 21 insertions, 0 deletions

diff --git a/docs/conventions.rst b/docs/conventions.rst
index 4cffd1084..21b506623 100644
--- a/docs/conventions.rst
+++ b/docs/conventions.rst
@@ -91,3 +91,24 @@ discussed on a page, is rendered like so:
 
    Sidebar information.
 
+When multiple objects are imported from the same package,
+the following convention is used:
+
+    .. code-block:: python
+
+       from foo import (
+           bar,
+           baz,
+           )
+
+It may look unusual, but it has advantages:
+
+* It allows one to swap out the higher-level package ``foo`` for something
+  else that provides the similar API. An example would be swapping out
+  one Database for another (e.g. graduating from SQLite to PostgreSQL).
+
+* Looks more neat in cases where a large number of objects get imported from
+  that package.
+
+* Adding/removing imported objects from the package is quicker and results
+  in simpler diffs.