Правила оформления Python-кода

1. Отступы

Рекомендуется использовать 4 пробела на каждый уровень отступа. Python 3 запрещает смешивание табуляции и пробелов в отступах. Код, в котором используются и те, и другие типы отступов, должен быть исправлен так, чтобы отступы в нем были расставлены только с помощью пробелов.

          
          def no_tab_using():
              no_tab = 'Using 4 spaces'
          
        

          
          	def use_tab():
          		one_tab_using = 'Ugly'
          
        

2. Точки с запятой

Не разделяйте ваши строки с помощью точек с запятой и не используйте точки с запятой для разделения команд, находящихся на одной строке.

          
            a = 'String'
            b = 15
            c = 7.2
          
        

          
            a = 'String';
            b = 15; c = 7.2;
          
        

3. Скобки

Используйте скобки экономно. Не используйте их с выражением return или с условной конструкцией, если не требуется организовать перенос строки. Однако скобки хорошо использовать для создания кортежей.

          
            if budget < 0:
                return False
            # -------------------
            while counter <= 10:
              counter += 1
            # -------------------
            if sea_country and cheap_country:
                add_country_for_visit()
            # -------------------
            if not line:
                continue
            # -------------------
            return result
            # -------------------
            for (key, value) in dict.items(): ...
          
        

          
            if (budget < 0):
                return (False)
            # -------------------
            if not(line):
                continue
            # -------------------
            return (result)
          
        

4. Пробелы в выражениях и инструкциях

            
              pineapple(pine[1], {apple: 2})
            
          

            
              pineapple( pine[ 1 ], { apple: 2 } )
            
          

            
              get_number_of_guests(1)
            
          

            
              get_number_of_guests (1)
            
          

            
              dish['ingredients'] = cook_book[:3]
            
          

            
              dish ['ingredients'] = cook_book [:3]
            
          

                
                  if number_of_goods == 4:
                      print(number_of_goods, total_price)
                
            

            
              if number_of_goods == 4 :
                  print(number_of_goods , total_price)
            
          

                  
                    counter == 1
                  
              

                  
                    counter<1
                  
              

                  
                    price = 1000
                    price_with_taxes = 1200
                    price_with_taxes_and_discounts = 1100
                  
              

                  
                    price                          = 1000
                    price_with_taxes               = 1200
                    price_with_taxes_and_discounts = 1100
                  
              

                  
                    def complex(real, imag=0.0): return magic(r=real, i=imag)
                  
              

                  
                    def complex(real, imag = 0.0): return magic(r = real, i = imag)
                  
              

5. Длина строк

Ограничивайте длину строк 79 символами (а длину строк документации и комментариев — 72 символами). В общем случае не используйте обратный слеш в качестве перехода на новую строку. Используйте доступное в Python явное объединение строк посредством круглых и фигурных скобок. Если необходимо, можно добавить дополнительную пару скобок вокруг выражения.

          
            style_object(self, width, height, color='black', design=None,
                    emphasis=None, highlight=0)

            if (width == 0 and height == 0 and
                color == 'red' and emphasis == 'strong'):
          
        

Если ваш текст не помещается в одну строку, используйте скобки для явного объединения строк.

          
            long_string = ('This will build a very long long '
                'long long long long long long string')
          
        

Что касается длинных URL в комментариях, то располагайте их, если это необходимо, на одной строке.

          
            # See details at
            # http://www.example.com/example/example/example/example/example/example/example_example.html
          
        

          
            # See details at
            # http://www.example.com/example/example/example/example/example/\
            # example/example_example.html
          
        

Обратный слеш иногда используется. Например, с длинной конструкцией with для переноса блока инструкций.

          
            with open('/path/to/some/file/you/want/to/read') as file_1, \
                 open('/path/to/some/file/being/written', 'w') as file_2:
                file_2.write(file_1.read())
          
        

Ещё один подобный случай — длинные assert.

6. Пустые строки

Отделяйте функции (верхнего уровня, не функции внутри функций) и определения классов двумя пустыми строками. Определения методов внутри класса отделяйте одной пустой строкой. Две пустые строки должны быть между объявлениями верхнего уровня, будь это класс или функция. Одна пустая строка должна быть между определениями методов и между объявлением класса и его первым методом.

        
          import os
          .
          .
          class MyClass:
          .
          def __init__(self):
            self.name = 'My name'
            .
            def f(self):
                return 'hello world'
            .
            .
          def MyFunc():
          i = 12345
          return i
          .
          myclass = MyClass()
        
      

Используйте (без энтузиазма) пустые строки в коде функций, чтобы отделить друг от друга логические части.

Python расценивает символ control+L как незначащий (whitespace), и вы можете использовать его, потому что многие редакторы обрабатывают его как разрыв страницы — таким образом, логические части в файле будут на разных страницах. Однако не все редакторы распознают control+L и могут на его месте отображать другой символ.

7. Имена

Имена, которых следует избегать:

• Односимвольные имена, исключая счетчики либо итераторы. Никогда не используйте символы l (маленькая латинская буква «эль»), O (заглавная латинская буква «о») или I (заглавная латинская буква «ай») как однобуквенные идентификаторы. В некоторых шрифтах эти символы неотличимы от цифры один и нуля. Если очень нужно l, пишите вместо неё заглавную L.

            
              long_name = 'Хорошее имя переменной'
              L = 'Допустимо, но лучше избегать'
            
          

            
              l = 1
              I = 1
              O = 0
            
          

• Дефисы и подчеркивания в именах модулей и пакетов.

            
              import my_module
            
          

            
              import my-module
            
          

• Двойные подчеркивания (в начале и конце имен) зарезервированы для языка.

            
              my_variable = 'Variable'
            
          

            
              __myvariable__ = 'Variable'
            
          

            
              my_variable = 'Variable'
            
          

            
              My-Variable = 'Variable'
            
          

            
              import vkapi
            
          

            
              import My-First-VKontakte-API-Modul
            
          

          
            class MyFirstClass:
          
        

          
            MAX_OVERFLOW = 10
            TOTAL = 100
          
        

8. Комментарии

Комментарии, противоречащие коду, хуже, чем отсутствие комментариев. Всегда исправляйте комментарии, если меняете код!

Комментарии должны быть законченными предложениями. Если комментарий — фраза или предложение, первое слово должно быть написано с большой буквы, если только это не имя переменной, которая начинается с маленькой буквы (никогда не отступайте от этого правила для имен переменных).

Ставьте два пробела после точки в конце предложения.

Если вы — программист, не говорящий по-английски, то всё равно следует использовать английский язык для написания комментариев. Особенно, если нет уверенности на 120% в том, что этот код будут читать только люди, говорящие на вашем родном языке.

            
              counter = counter + 1                 # Increment counter
            
          

            
              """Return something useful

              Optional plotz says to frobnicate the bizbaz first.

              """
            
          

9. Циклы

            
              colors = ['red', 'green', 'blue', 'yellow']
              for color in colors:
                  print(color)
            
          

            
              colors = ['red', 'green', 'blue', 'yellow']
              for i in range(len(colors)):
                  print(colors[i])
            
          

            
              colors = ['red', 'green', 'blue', 'yellow']
              for color in reversed(colors):
                  print(color)
            
          

            
              colors = ['red', 'green', 'blue', 'yellow']
              for i in range(len(colors)-1, -1, -1):
                  print(colors[i])
            
          

            
              for i in range(6):
                  print(i**2)
            
          

            
              for i in [0, 1, 2, 3, 4, 5]:
                  print(i**2)
            
          

            
              colors = ['red', 'green', 'blue', 'yellow']
              for i, color in enumerate(colors):
                  print(i, '-->', color)
            
          

            
              colors = ['red', 'green', 'blue', 'yellow']
              for i in range(len(colors)):
                  print(i, '-->', colors[i])
            
          

            
              names = ['raymond', 'rachel', 'matthew']
              colors = ['red', 'green', 'blue', 'yellow']
              for name, color in zip(names, colors):
                  print(name, '-->', color)
            
          

            
              names = ['raymond', 'rachel', 'matthew']
              colors = ['red', 'green', 'blue', 'yellow']
              n = min(len(names), len(colors))
              for i in range(n):
                  print(names[i], '-->', colors[i])
            
          

10. Импорты

Каждый импорт, как правило, должен быть на отдельной строке.

          
            import os
            import sys
          
        

          
            import sys, os
          
        

В то же время, можно писать так:

          
            from subprocess import Popen, PIPE
          
        

Импорты всегда располагаются в начале файла, сразу после комментариев уровня модуля, строк документации, перед объявлением констант и объектов уровня модуля. Импорты должны быть сгруппированы в порядке от самых простых до самых сложных:

• импорты из стандартной библиотеки,
• сторонние импорты,
• импорты из библиотек вашего приложения.

Наряду с группированием, импорты должны быть отсортированы лексикографически, нерегистрозависимо, согласно полному пути до каждого модуля.

          
            import foo
            from foo import bar
            from foo.bar import baz
            from foo.bar import Quux
            from Foob import ar
          
        

Рекомендуется абсолютное импортирование, так как оно обычно более читаемо и ведет себя лучше (или, по крайней мере, даёт понятные сообщения об ошибках), если импортируемая система настроена неправильно (например, когда каталог внутри пакета заканчивается на sys.path).

          
            import mypkg.sibling
            from mypkg import sibling
            from mypkg.sibling import example
          
        

Тем не менее, явный относительный импорт является приемлемой альтернативой абсолютному импорту, особенно при работе со сложными пакетами, где использование абсолютного импорта было бы излишне подробным.

          
            from . import sibling
            from .sibling import example
          
        

Следует избегать шаблонов импортов (from import *), так как они делают неясным то, какие имена присутствуют в глобальном пространстве имён, что вводит в заблуждение как читателей, так и многие автоматизированные средства.