README

   1 pyimportcan -- Python imports canonical format filter.
   2 It is free software: see the file COPYING for copying conditions.
   3
   4 PROBLEM
   5
   6 Python allows various different formats of how to make importing of
   7 modules and functions:
   8
   9 * from foo import bar
  10 * from foo import bar, baz
  11 * from foo import (
  12     bar,
  13     baz
  14   )
  15 * from foo import (
  16     baz,
  17     bar,
  18   )
  19 * from foo import bar, \
  20       baz
  21
  22 Everything can be unsorted at any place, thus making the task of
  23 checking if import already exists rather hard. Moreover it complicates
  24 just adding another import, because you have to find it first and deal
  25 with the format it is already written.
  26
  27 Everything can use different indentation practices. Everything can be
  28 doubled and you won't notice it:
  29
  30     from foo import bar
  31     [many lines]
  32     from foo import (
  33         baz,
  34         bar
  35     )
  36
  37 Allowing multiple imports on one line leads to possibility of long lines
  38 appearing.
  39
  40 The whole import sections with various formats just can not be
  41 technically sorted with the editor (no way to do "vip:sort<CR>" in Vim).
  42
  43 Merge conflict in the imports section can be not so trivial to resolve,
  44 however in most cases just aggregating them will be enough.
  45
  46 If you want to find the code that imports bar from foo, then you can do
  47 it with "from foo import bar", but can not with "import (\n" is most
  48 cases. You are forced to use special Python-related software to deal
  49 with it, but no grep or sed.
  50
  51 SOLUTION
  52
  53 Use the very convenient simple single format. Single import per line,
  54 period. Sorted and only identical ones. With git merge conflict lines
  55 removed. This script reads stdin with import-lines and writes canonical
  56 representation of them to stdout. For example you can select lines in
  57 Vim and just enter ":!pyimportcan.pl".