From d886c933784e499a6243b0ebbfc04fb0bb2be4fa Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Mon, 25 Mar 2013 12:16:39 +0200 Subject: mention a coding convention --- docs/conventions.rst | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) (limited to 'docs') 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. -- cgit v1.2.3