Перенос строк кода Python
PEP-8 не рекомендует писать строки кода длиннее, чем 79 символов. С этим можно не согласиться, однако, встречаются строки, которые не влезают даже на наши широкоформатные мониторы.
👨🎓 Старайтесь не делать очень длинные строки, разбивая сложные условия или формулы на отдельные части, вынося их в переменные или функции с осмысленными названиями.
Если есть острая необходимость иметь длинное выражение, тогда приходится переносить код на следующие строки. Можно делать двумя способами: скобками и слэшем.
Если, перед выражением открыта скобка (круглая, квадратная или фигурная в зависимости от контекста), но она не закрыта в этой строке, то Python будет сканировать последующие строки, пока не найдет соответствующую закрывающую скобку (англ. implicit line joining). Примеры:
Обратите внимание, что в первом примере скобки очень важны. Без скобок код не скомпилируется из-за отступов, а если их убрать, то результат будет неверен: income станет gross_wages, а последующие строки не будут иметь эффекта!
Метод переноса обратным слэшем. Ставим обратный слэш конце строки и сразу энтер (перенос строки): тогда следующая строка будет включена в текущую (англ. explicit line joining), не взирая на отступы, как будто бы они написаны в одну строку:
Еще примеры со слэшем:
Почему скобки лучше для переноса:
🐉 Специально для канала @pyway. Подписывайтесь на мой канал в Телеграм @pyway 👈
Строки и функции для работы с ними (faq)
С троки в языке программирования Python – это объекты, которые состоят из последовательности символов. Наравне с bool, int и прочих, работа со строковым типом данных является неотъемлемой частью программирования, так как очень редко встречаются приложения, в которых не используется текст.
Вводная информация о строках
Как и во многих других языках программирования, в Python есть большая коллекция функций, операторов и методов, позволяющих работать со строковым типом.
Что представляют собой строки в Python
С точки зрения Питона, строка – это упорядоченная последовательность символов, которая предназначена для хранения информации в виде простого текста.
Поэтому тип данных string используется в случае, когда что-то нужно представить в текстовой форме.
Литералы строк
Литерал – способ создания объектов, в случае строк Питон предлагает несколько основных вариантов:
>>> ‘string’ # одинарные кавычки ‘string’ >>> «string» # двойные кавычки ‘string’ >>> «»»string»»» ‘string’ >>> »’string»’ ‘string’
Если внутри строки необходимо расположить двойные кавычки, и сама строка была создана с помощью двойных кавычек, можно сделать следующее:
>>> ‘book «war and peace»‘ # разный тип кавычек ‘book «war and peace»‘ >>> «book ‘war and peace'» # разный тип кавычек «book ‘war and peace'» >>> «book \»war and peace\»» # экранирование кавычек одного типа ‘book «war and peace»‘ >>> ‘book \’war and peace\» # экранирование кавычек одного типа «book ‘war and peace'»
💡 Разницы между строками с одинарными и двойными кавычками нет – это одно и то же
Какие кавычки использовать – решать вам, соглашение PEP 8 не дает рекомендаций по использованию кавычек. Просто выберите один тип кавычек и придерживайтесь его. Однако если в стоке используются те же кавычки, что и в литерале строки, используйте разные типы кавычек – обратная косая черта в строке ухудшает читаемость кода.
Кодировка строк
В третьей версии языка программирования Python все строки представляют собой последовательность Unicode-символов.
В Python 3 кодировка по умолчанию исходного кода – UTF-8. Во второй версии по умолчанию использовалась ASCII. Если необходимо использовать другую кодировку, можно разместить специальное объявление на первой строке файла, к примеру:
Максимальная длина строки в Python
Максимальная длина строки зависит от платформы. Обычно это:
>>> import sys >>> sys.maxsize 2147483647
Перенос строк
Перенос строки осуществляется с помощью символа \n :
>>> text = «one\ntwo\nthree» >>> print(text) one two three
Конкатенация строк
>>> s1 = «Hello» + » world» >>> s2 = » world» >>> s1+s2 ‘Hello world’
При необходимости объединения строки с числом его предварительно нужно привести тоже к строке, используя функцию str() :
>>> name = «John» >>> age = 30 >>> «Name: » + name + «, age: » + str(age) ‘Name: John, age: 30’
Сравнение строк
При сравнении нескольких строк рассматриваются отдельные символы и их регистр:
При этом сравниваются по очереди первые символы, затем – 2-е и так далее.
>>> s1 = «1a» >>> s2 = «aa» >>> s3 = «Aa» >>> s4 = «ba» >>> «1a» > «aa» # сравнение цифры с буквой False >>> «aa» > «Aa» # сравнение регистров True >>> «aa» > «ba» # сравнение букв по алфавитному порядку False >>> «aa»
Далеко не всегда желательной является зависимость от регистра, в таком случае можно привести обе строки к одному и тому же регистру. Для этого используются функции lower() – для приведения к нижнему и upper() – к верхнему:
>>> s1 = «Intel» >>> s2 = «intel» >>> s1 == s2 False >>> s1.lower() == s2.lower() True
Пустая строка Python
Объявить пустую строку можно следующими способами:
Как удалить строку в Python
Или перезаписать переменную пустой строкой:
Обращение по индексу
Для выбора определенного символа из строки можно воспользоваться обращением по индексу, записав его в квадратных скобках:
>>> s = «abcdef» >>> s[0] ‘a’ >>> s[2] ‘c’
Индекс начинается с 0
В Python предусмотрена возможность получить доступ и по отрицательному индексу. В таком случае отсчет будет вестись от конца строки:
Форматирование строк
Часто возникает ситуация, когда необходимо создать строку, подставив в нее определенные значения, полученные во время выполнения программы. Подстановка данных в таком случае выполняется при помощи форматирования строк, сделать это можно несколькими способами.
Оператор %
Строки в Python обладают встроенной операцией, к которой можно получить доступ оператором %, что дает возможность очень просто делать форматирование. Самый простой пример – когда для подстановки нужен только один аргумент, значением будет он сам:
>>> name = «Alex» >>> ‘Hello, %s’ % name ‘Hello, Alex’
Если же для подстановки используется несколько аргументов, то значением будет кортеж со строками:
>>> ‘%d %s, %d %s’ % (6, ‘bananas’, 10, ‘lemons’) ‘6 bananas, 10 lemons’
Как видно из предыдущего примера, зависимо от типа данных для подстановки и того, что требуется получить в итоге, пишется разный формат. Наиболее часто используются:
Такой способ форматирования строк называет «старым» стилем, который в Python 3 был заменен на более удобные способы.
str.format()
>>> print(‘<>‘.format(100)) 100 >>> ‘<0>, <1>, <2>‘.format(‘one’, ‘two’, ‘three’) ‘one, two, three’ >>> ‘<2>, <1>, <0>‘.format(‘one’, ‘two’, ‘three’) ‘three, two, one’
💭 В Python 3 форматирование строк с использованием «нового стиля» является более предпочтительным по сравнению с использованием %-стиля, так как предоставляет более широкие возможности, не усложняя простые варианты использования.
f-строки (Python 3.6+)
В Python версии 3.6 появился новый метод форматирования строк – «f-строки», с его помощью можно использовать встроенные выражения внутри строк:
>>> name = ‘Alex’ >>> f’Hello,
Такой способ форматирования очень мощный, так как дает возможность встраивать выражения:
>>> a = 5 >>> b = 10 >>> f’Five plus ten is and not <2 * (a + b)>.’ ‘Five plus ten is 15 and not 30.’
Таким образом, форматирование с помощью f-строк напоминает использование метода format(), но более гибкое, быстрое и читабельное.
Стандартная библиотека Template Strings
Функции для работы со строками
Для работы со строками в Питоне предусмотрены специальные функции. Рассмотрим их:
Преобразование числового или другого типа к строке:
Методы для работы со строками
Кроме функций, для работы со строками есть немало методов:
>>> text = «Wikipedia is a Python library that makes it easy to access and parse data from Wikipedia» >>> text.find(«Wikipedia») 0 >>> text.rfind(«Wikipedia») 79 >>> text.replace(«from Wikipedia», «from https://www.wikipedia.org/») ‘Wikipedia is a Python library that makes it easy to access and parse data from https://www.wikipedia.org/’ >>> text.split(» «) [‘Wikipedia’, ‘is’, ‘a’, ‘Python’, ‘library’, ‘that’, ‘makes’, ‘it’, ‘easy’, ‘to’, ‘access’, ‘and’, ‘parse’, ‘data’, ‘from’, ‘Wikipedia’] split_text = text.split(» «) >>> «_».join(split_text) ‘Wikipedia_is_a_Python_library_that_makes_it_easy_to_access_and_parse_data_from_Wikipedia’ >>> text = » test » >>> text.strip() ‘test’ >>> text.lstrip() ‘test ‘ >>> text.rstrip() ‘ test’ >>> text = «Python is a product of the Python Software Foundation» >>> text.lower() ‘python is a product of the python software foundation’ >>> text.upper() ‘PYTHON IS A PRODUCT OF THE PYTHON SOFTWARE FOUNDATION’ >>> text = «python is a product of the python software foundation» >>> text.capitalize() ‘Python is a product of the python software foundation’
Преобразование из строки в другой тип
В Питоне строки можно преобразовывать в другие типы данных:
string to int
Функция int() преобразовывает целое число в десятичной системе, заданное как строка, в тип int:
При необходимости можно указывать систему счисления:
>>> int(«0x12F», base=16) 303
string to list
Самый простой способ преобразования строки в список строк – метод split():
>>> ‘one two three four’.split() [‘one’, ‘two’, ‘three’, ‘four’]
При необходимости можно указывать разделитель:
>>> ‘one, two, three, four’.split(‘,’) [‘one’, ‘ two’, ‘ three’, ‘ four’]
string to bytes
Преобразование строкового типа в байтовый выполняется функцией encode() с указанием кодировки:
string to datetime
Строка в дату преобразовывается функцией strptime() из стандартного модуля datetime:
>>> from datetime import datetime >>> print(datetime.strptime(‘Jan 1 2020 1:33PM’, ‘%b %d %Y %I:%M%p’)) 2020-01-01 13:33:00
string to float
Для преобразования строки в число с плавающей точкой используется стандартная функция float:
string to dict
Создание словаря из строки возможно, если внутри нее данные в формате json. Для этого можно воспользоваться модулем json :
string to json
Конвертация объектов Python в объект json выполняется функцией dumps():
>>> import json >>> json.dumps(«hello») ‘»hello»‘
Best practices
Как разбить строку на символы
Разбиение строки на отдельные символы выполняется несколькими способами:
>>> text = «django» # вариант 1 >>> list(text) [‘d’, ‘j’, ‘a’, ‘n’, ‘g’, ‘o’] # вариант 2 >>> [c for c in «text»] [‘t’, ‘e’, ‘x’, ‘t’] # вариант 3 >>> for c in text: print(c) d j a n g o
Как из строки выделить числа
Для извлечения чисел из строки можно воспользоваться методами строк:
>>> str = «h3110 23 cat 444.4 rabbit 11 2 dog» >>> [int(s) for s in str.split() if s.isdigit()] [23, 11, 2]
Данный пример извлекает только целые положительные числа. Более универсальный вариант – регулярные выражения:
>>> str = «h3110 23 cat 444.4 rabbit 11 2 dog» >>> import re >>> re.findall(r’\d+’, str) [‘3110′, ’23’, ‘444’, ‘4’, ’11’, ‘2’]
Как перевернуть строку
Существует несколько способов перевернуть строку, начиная от классического – запустить цикл в обратной последовательности, выбирая каждый символ с конца и вставляя его в новую строку, и заканчивая срезами – вариант только для Питона.
С помощью среза – самый быстрый способ:
Использование reversed() и str.join() :
Как удалить последний символ в строке
Как и в предыдущем случае – чтобы убрать последний символ наиболее простым и быстрым вариантом будет использование среза:
>>> «Some text1″[:-1] ‘Some text’
Как убрать пробелы из строки
В случае удаления пробелов со строки может быть два варианта:
1. Обрезать строку так, чтобы удалить с нее первый и последний пробел, такой вариант может пригодиться, когда пользователь случайно поставит пробел в конце введенного текста:
>>> » Some text «.strip() ‘Some text’
2. Удалить со строки все пробелы:
>>> » So me t e x t «.replace(‘ ‘, ») ‘Sometext’
Работа со строками – неотъемлемая часть создания практически любого приложения, где используется текст, и язык программирования Python предоставляет широкие возможности работы с такими данными.
Перевод текста на новую строку в Python. Как перенести текст на новую строку – инструкция
Для того чтобы в Python обозначить конец одной строки и начать новую, нужно использовать специальный символ. При этом важно знать, как его правильно использовать в работе с различными файлами Python, в требуемые моменты отображать его в консоли. Подробно необходимо разобраться с тем, как пользоваться разделительным знаком для новых строк при работе с программным кодом, можно ли добавлять текст без его применения.
Общая информация о символе новой строки
\n – обозначение переноса информации на новую строку и закрытия старой строчки в Python. Данный символ состоит из двух элементов:
Для использования данного символа можно применить выражение “print(f”Hello\nWorld!”)”, за счет которого можно переносить информацию в f-строках.
Пример использования символа \n для распределения массива информации по новым строчкам
Что такое функция print
Без дополнительных настроек символ переноса данных на следующую строку добавляется в скрытом режиме. За счет этого его невозможно увидеть между строк без активации определенной функции. Пример отображение разделительного значка в программном коде:
Print (“Hello, World”!”) – “Hello, World!”\n
При этом такое нахождение данного символа прописано в базовых характеристиках Python. Функция “print” имеет стандартное значение для параметра “end” – \n. Именно благодаря данной функции этот символ выставляется в конце строк для переноса данных на следующие строчки. Расшифровка функции “print”:
print(*objects, sep=’ ‘, end=’\n’, file=sys.stdout, flush=False)
Значение параметра “end” из функции “print” равняется символу “\n”. По автоматическому алгоритму программного кода он дополняет строчки на конце, перед которыми прописывается функция “print”. При использовании одной функции “print” можно не заметить суть ее работы, так как на экран будет выводиться только одна строка. Однако, если добавить несколько подобных инструкций, результат работы функции станет более явным:
print(«Hello, World 1!») print(«Hello, World 2!») print(«Hello, World 3!») print(«Hello, World 4!»)
Пример результата, прописанного выше программного кода:
Hello, World 1! Hello, World 2! Hello, World 3! Hello, World 4!
Замена символа новой строки через print
Используя функцию “print”, можно не применять разделительный значок между строк. Для этого в самой функции необходимо изменить параметр “end”. При этом вместо значения “end” нужно добавить пробел. За счет этого именно пробелом будет заменен символ “end”. Результат при установленных настройках по умолчанию:
>>> print(«Hello») >>> print(«World») Hello World
Отображение результата после замены символа “\n” на пробел:
>>> print(«Hello», end=» «) >>> print(«World») Hello World
Пример использования данного способа замены символов для отображения последовательности значений через одну строчку:
for i in range(15): if i Назначение различных символов для работы в Python
Разделение строки на подстроки
Чтобы разделить одну длинную строчку на несколько подстрочек, можно воспользоваться методом split. Если не вносить дополнительных правок, стандартным разделителем является пробел. После выполнения данного метода выбранный текст разделяется на отдельные слова по подстрочкам, преобразуется в список strings. Как пример:
string = «some new text» strings = string.split() print(strings) [‘some’, ‘new’, ‘text’]
Для того чтобы провести обратное преобразование, с помощью которого список подстрочек превратится в одну длинную строку, необходимо воспользоваться методом join. Еще один полезный метод для работы со строками – strip. С его помощью можно удалять пробелы, которые расположены с двух сторон от строки.
Заключение
Чтобы при работе в Python выводить определенные данные с новой строки, необходимо заканчивать старую строчку символом “\n”. С его помощью информация, стоящая после знака, переносится на следующую строку, а старая закрывается. Однако для переноса данных не обязательно использовать данный символ. Для этого можно воспользоваться параметром end =””. Значение “character” и является разделительным символом.
Этот документ описывает соглашение о том, как писать код для языка python, включая стандартную библиотеку, входящую в состав python.
PEP 8 создан на основе рекомендаций Гуидо ван Россума с добавлениями от Барри. Если где-то возникал конфликт, мы выбирали стиль Гуидо. И, конечно, этот PEP может быть неполным (фактически, он, наверное, никогда не будет закончен).
Ключевая идея Гуидо такова: код читается намного больше раз, чем пишется. Собственно, рекомендации о стиле написания кода направлены на то, чтобы улучшить читаемость кода и сделать его согласованным между большим числом проектов. В идеале, весь код будет написан в едином стиле, и любой сможет легко его прочесть.
Это руководство о согласованности и единстве. Согласованность с этим руководством очень важна. Согласованность внутри одного проекта еще важнее. А согласованность внутри модуля или функции — самое важное. Но важно помнить, что иногда это руководство неприменимо, и понимать, когда можно отойти от рекомендаций. Когда вы сомневаетесь, просто посмотрите на другие примеры и решите, какой выглядит лучше.
Две причины для того, чтобы нарушить данные правила:
Содержание
Внешний вид кода
Отступы
Используйте 4 пробела на каждый уровень отступа.
Продолжительные строки должны выравнивать обернутые элементы либо вертикально, используя неявную линию в скобках (круглых, квадратных или фигурных), либо с использованием висячего отступа. При использовании висячего отступа следует применять следующие соображения: на первой линии не должно быть аргументов, а остальные строки должны четко восприниматься как продолжение линии.
Закрывающие круглые/квадратные/фигурные скобки в многострочных конструкциях могут находиться под первым непробельным символом последней строки списка, например:
либо быть под первым символом строки, начинающей многострочную конструкцию:
Табуляция или пробелы?
Табуляция должна использоваться только для поддержки кода, написанного с отступами с помощью табуляции.
Python 3 запрещает смешивание табуляции и пробелов в отступах.
Python 2 пытается преобразовать табуляцию в пробелы.
Максимальная длина строки
Ограничьте длину строки максимум 79 символами.
Для более длинных блоков текста с меньшими структурными ограничениями (строки документации или комментарии), длину строки следует ограничить 72 символами.
Ограничение необходимой ширины окна редактора позволяет иметь несколько открытых файлов бок о бок, и хорошо работает при использовании инструментов анализа кода, которые предоставляют две версии в соседних столбцах.
Некоторые команды предпочитают большую длину строки. Для кода, поддерживающегося исключительно или преимущественно этой группой, в которой могут прийти к согласию по этому вопросу, нормально увеличение длины строки с 80 до 100 символов (фактически увеличивая максимальную длину до 99 символов), при условии, что комментарии и строки документации все еще будут 72 символа.
Стандартная библиотека Python консервативна и требует ограничения длины строки в 79 символов (а строк документации/комментариев в 72).
Предпочтительный способ переноса длинных строк является использование подразумеваемых продолжений строк Python внутри круглых, квадратных и фигурных скобок. Длинные строки могут быть разбиты на несколько строк, обернутые в скобки. Это предпочтительнее использования обратной косой черты для продолжения строки.
Обратная косая черта все еще может быть использована время от времени. Например, длинная конструкция with не может использовать неявные продолжения, так что обратная косая черта является приемлемой:
Сделайте правильные отступы для перенесённой строки. Предпочтительнее вставить перенос строки после логического оператора, но не перед ним. Например:
Пустые строки
Отделяйте функции верхнего уровня и определения классов двумя пустыми строками.
Определения методов внутри класса разделяются одной пустой строкой.
Дополнительные пустые строки возможно использовать для разделения различных групп похожих функций. Пустые строки могут быть опущены между несколькими связанными однострочниками (например, набор фиктивных реализаций).
Используйте пустые строки в функциях, чтобы указать логические разделы.
Python расценивает символ control+L как незначащий (whitespace), и вы можете использовать его, потому что многие редакторы обрабатывают его как разрыв страницы — таким образом логические части в файле будут на разных страницах. Однако, не все редакторы распознают control+L и могут на его месте отображать другой символ.
Кодировка исходного файла
Кодировка Python должна быть UTF-8 (ASCII в Python 2).
Файлы в ASCII (Python 2) или UTF-8 (Python 3) не должны иметь объявления кодировки.
Начиная с версии python 3.0 в стандартной библиотеке действует следующее соглашение: все идентификаторы обязаны содержать только ASCII символы, и означать английские слова везде, где это возможно (во многих случаях используются сокращения или неанглийские технические термины). Кроме того, строки и комментарии тоже должны содержать лишь ASCII символы. Исключения составляют: (а) test case, тестирующий не-ASCII особенности программы, и (б) имена авторов. Авторы, чьи имена основаны не на латинском алфавите, должны транслитерировать свои имена в латиницу.
Проектам с открытым кодом для широкой аудитории также рекомендуется использовать это соглашение.
Импорты
Каждый импорт, как правило, должен быть на отдельной строке.
В то же время, можно писать так:
Импорты всегда помещаются в начале файла, сразу после комментариев к модулю и строк документации, и перед объявлением констант.
Импорты должны быть сгруппированы в следующем порядке:
Вставляйте пустую строку между каждой группой импортов.
Указывайте спецификации __all__ после импортов.
Рекомендуется абсолютное импортирование, так как оно обычно более читаемо и ведет себя лучше (или, по крайней мере, даёт понятные сообщения об ошибках) если импортируемая система настроена неправильно (например, когда каталог внутри пакета заканчивается на sys.path):
Тем не менее, явный относительный импорт является приемлемой альтернативой абсолютному импорту, особенно при работе со сложными пакетами, где использование абсолютного импорта было бы излишне подробным:
В стандартной библиотеке следует избегать сложной структуры пакетов и всегда использовать абсолютные импорты.
Неявные относительно импорты никогда не должны быть использованы, и были удалены в Python 3.
Когда вы импортируете класс из модуля, вполне можно писать вот так:
Если такое написание вызывает конфликт имен, тогда пишите:
И используйте «myclass.MyClass» и «foo.bar.yourclass.YourClass».
Шаблоны импортов (from import *) следует избегать, так как они делают неясным то, какие имена присутствуют в глобальном пространстве имён, что вводит в заблуждение как читателей, так и многие автоматизированные средства. Существует один оправданный пример использования шаблона импорта, который заключается в опубликовании внутреннего интерфейса как часть общественного API (например, переписав реализацию на чистом Python в модуле акселератора (и не будет заранее известно, какие именно функции будут перезаписаны).
Пробелы в выражениях и инструкциях
Избегайте использования пробелов в следующих ситуациях:
Непосредственно внутри круглых, квадратных или фигурных скобок.
Непосредственно перед запятой, точкой с запятой или двоеточием:
Сразу перед открывающей скобкой, после которой начинается список аргументов при вызове функции:
Сразу перед открывающей скобкой, после которой следует индекс или срез:
Использование более одного пробела вокруг оператора присваивания (или любого другого) для того, чтобы выровнять его с другим:
Другие рекомендации
Если используются операторы с разными приоритетами, попробуйте добавить пробелы вокруг операторов с самым низким приоритетом. Используйте свои собственные суждения, однако, никогда не используйте более одного пробела, и всегда используйте одинаковое количество пробелов по обе стороны бинарного оператора.
Не используйте пробелы вокруг знака =, если он используется для обозначения именованного аргумента или значения параметров по умолчанию.
Не используйте составные инструкции (несколько команд в одной строке).
Иногда можно писать тело циклов while, for или ветку if в той же строке, если команда короткая, но если команд несколько, никогда так не пишите. А также избегайте длинных строк!
Комментарии
Комментарии, противоречащие коду, хуже, чем отсутствие комментариев. Всегда исправляйте комментарии, если меняете код!
Комментарии должны являться законченными предложениями. Если комментарий — фраза или предложение, первое слово должно быть написано с большой буквы, если только это не имя переменной, которая начинается с маленькой буквы (никогда не изменяйте регистр переменной!).
Если комментарий короткий, можно опустить точку в конце предложения. Блок комментариев обычно состоит из одного или более абзацев, составленных из полноценных предложений, поэтому каждое предложение должно оканчиваться точкой.
Ставьте два пробела после точки в конце предложения.
Программисты, которые не говорят на английском языке, пожалуйста, пишите комментарии на английском, если только вы не уверены на 120%, что ваш код никогда не будут читать люди, не знающие вашего родного языка.
Блоки комментариев
Блок комментариев обычно объясняет код (весь, или только некоторую часть), идущий после блока, и должен иметь тот же отступ, что и сам код. Каждая строчка такого блока должна начинаться с символа # и одного пробела после него (если только сам текст комментария не имеет отступа).
Абзацы внутри блока комментариев разделяются строкой, состоящей из одного символа #.
«Встрочные» комментарии
Старайтесь реже использовать подобные комментарии.
Такой комментарий находится в той же строке, что и инструкция. «Встрочные» комментарии должны отделяться по крайней мере двумя пробелами от инструкции. Они должны начинаться с символа # и одного пробела.
Комментарии в строке с кодом не нужны и только отвлекают от чтения, если они объясняют очевидное. Не пишите вот так:
Впрочем, такие комментарии иногда полезны:
Строки документации
Пишите документацию для всех публичных модулей, функций, классов, методов. Строки документации необязательны для приватных методов, но лучше написать, что делает метод. Комментарий нужно писать после строки с def.
PEP 257 объясняет, как правильно и хорошо документировать. Заметьте, очень важно, чтобы закрывающие кавычки стояли на отдельной строке. А еще лучше, если перед ними будет ещё и пустая строка, например:
Для однострочной документации можно оставить закрывающие кавычки на той же строке.
Контроль версий
Если вам нужно использовать Subversion, CVS или RCS в ваших исходных кодах, делайте вот так:
Вставляйте эти строки после документации модуля перед любым другим кодом и отделяйте их пустыми строками по одной до и после.
Соглашения по именованию
Соглашения по именованию переменных в python немного туманны, поэтому их список никогда не будет полным — тем не менее, ниже мы приводим список рекомендаций, действующих на данный момент. Новые модули и пакеты должны быть написаны согласно этим стандартам, но если в какой-либо уже существующей библиотеке эти правила нарушаются, предпочтительнее писать в едином с ней стиле.
Главный принцип
Имена, которые видны пользователю как часть общественного API должны следовать конвенциям, которые отражают использование, а не реализацию.
Описание: Стили имен
Существует много разных стилей. Поможем вам распознать, какой стиль именования используется, независимо от того, для чего он используется.
Обычно различают следующие стили:
Ещё существует стиль, в котором имена, принадлежащие одной логической группе, имеют один короткий префикс. Этот стиль редко используется в python, но мы упоминаем его для полноты. Например, функция os.stat() возвращает кортеж, имена в котором традиционно имеют вид st_mode, st_size, st_mtime и так далее. (Так сделано, чтобы подчеркнуть соответствие этих полей структуре системных вызовов POSIX, что помогает знакомым с ней программистам).
В библиотеке X11 используется префикс Х для всех public-функций. В python этот стиль считается излишним, потому что перед полями и именами методов стоит имя объекта, а перед именами функций стоит имя модуля.
В дополнение к этому, используются следующие специальные формы записи имен с добавлением символа подчеркивания в начало или конец имени:
_single_leading_underscore: слабый индикатор того, что имя используется для внутренних нужд. Например, from M import * не будет импортировать объекты, чьи имена начинаются с символа подчеркивания.
single_trailing_underscore_: используется по соглашению для избежания конфликтов с ключевыми словами языка python, например:
__double_leading_underscore: изменяет имя атрибута класса, то есть в классе FooBar поле __boo становится _FooBar__boo.
__double_leading_and_trailing_underscore__ (двойное подчеркивание в начале и в конце имени): магические методы или атрибуты, которые находятся в пространствах имен, управляемых пользователем. Например, __init__, __import__ или __file__. Не изобретайте такие имена, используйте их только так, как написано в документации.
Предписания: соглашения по именованию
Имена, которых следует избегать
Никогда не используйте символы l (маленькая латинская буква «эль»), O (заглавная латинская буква «о») или I (заглавная латинская буква «ай») как однобуквенные идентификаторы.
В некоторых шрифтах эти символы неотличимы от цифры один и нуля. Если очень нужно l, пишите вместо неё заглавную L.
Имена модулей и пакетов
Модули должны иметь короткие имена, состоящие из маленьких букв. Можно использовать символы подчеркивания, если это улучшает читабельность. То же самое относится и к именам пакетов, однако в именах пакетов не рекомендуется использовать символ подчёркивания.
Так как имена модулей отображаются в имена файлов, а некоторые файловые системы являются нечувствительными к регистру символов и обрезают длинные имена, очень важно использовать достаточно короткие имена модулей — это не проблема в Unix, но, возможно, код окажется непереносимым в старые версии Windows, Mac, или DOS.
Когда модуль расширения, написанный на С или C++, имеет сопутствующий python-модуль (содержащий интерфейс высокого уровня), С/С++ модуль начинается с символа подчеркивания, например, _socket.
Имена классов
Имена классов должны обычно следовать соглашению CapWords.
Вместо этого могут использоваться соглашения для именования функций, если интерфейс документирован и используется в основном как функции.
Имена исключений
Так как исключения являются классами, к исключениям применяется стиль именования классов. Однако вы можете добавить Error в конце имени (если, конечно, исключение действительно является ошибкой).
Имена глобальных переменных
Будем надеяться, что глобальные переменные используются только внутри одного модуля. Руководствуйтесь теми же соглашениями, что и для имен функций.
Добавляйте в модули, которые написаны так, чтобы их использовали с помощью from M import *, механизм __all__, чтобы предотвратить экспортирование глобальных переменных. Или же, используйте старое соглашение, добавляя перед именами таких глобальных переменных один символ подчеркивания (которым вы можете обозначить те глобальные переменные, которые используются только внутри модуля).
Имена функций
Имена функций должны состоять из маленьких букв, а слова разделяться символами подчеркивания — это необходимо, чтобы увеличить читабельность.
Стиль mixedCase допускается в тех местах, где уже преобладает такой стиль, для сохранения обратной совместимости.
Аргументы функций и методов
Всегда используйте self в качестве первого аргумента метода экземпляра объекта.
Всегда используйте cls в качестве первого аргумента метода класса.
Если имя аргумента конфликтует с зарезервированным ключевым словом python, обычно лучше добавить в конец имени символ подчеркивания, чем исказить написание слова или использовать аббревиатуру. Таким образом, class_ лучше, чем clss. (Возможно, хорошим вариантом будет подобрать синоним).
Имена методов и переменных экземпляров классов
Используйте тот же стиль, что и для имен функций: имена должны состоять из маленьких букв, а слова разделяться символами подчеркивания.
Используйте один символ подчёркивания перед именем для непубличных методов и атрибутов.
Чтобы избежать конфликтов имен с подклассами, используйте два ведущих подчеркивания.
Python искажает эти имена: если класс Foo имеет атрибут с именем __a, он не может быть доступен как Foo.__a. (Настойчивый пользователь все еще может получить доступ, вызвав Foo._Foo__a.) Вообще, два ведущих подчеркивания должны использоваться только для того, чтобы избежать конфликтов имен с атрибутами классов, предназначенных для наследования.
Примечание: есть некоторые разногласия по поводу использования __ имена (см. ниже).
Константы
Константы обычно объявляются на уровне модуля и записываются только заглавными буквами, а слова разделяются символами подчеркивания. Например: MAX_OVERFLOW, TOTAL.
Проектирование наследования
Публичные атрибуты — это те, которые будут использовать другие программисты, и вы должны быть уверены в отсутствии обратной несовместимости. Непубличные атрибуты, в свою очередь, не предназначены для использования третьими лицами, поэтому вы можете не гарантировать, что не измените или не удалите их.
Мы не используем термин «приватный атрибут», потому что на самом деле в python таких не бывает.
Другой тип атрибутов классов принадлежит так называемому API подклассов (в других языках они часто называются protected). Некоторые классы проектируются так, чтобы от них наследовали другие классы, которые расширяют или модифицируют поведение базового класса. Когда вы проектируете такой класс, решите и явно укажите, какие атрибуты являются публичными, какие принадлежат API подклассов, а какие используются только базовым классом.
Теперь сформулируем рекомендации:
Открытые атрибуты не должны иметь в начале имени символа подчеркивания.
Если имя открытого атрибута конфликтует с ключевым словом языка, добавьте в конец имени один символ подчеркивания. Это более предпочтительно, чем аббревиатура или искажение написания (однако, у этого правила есть исключение — аргумента, который означает класс, и особенно первый аргумент метода класса (class method) должен иметь имя cls).
Назовите простые публичные атрибуты понятными именами и не пишите сложные методы доступа и изменения (accessor/mutator, get/set, — прим. перев.) Помните, что в python очень легко добавить их потом, если потребуется. В этом случае используйте свойства (properties), чтобы скрыть функциональную реализацию за синтаксисом доступа к атрибутам.
Примечание 1: Свойства (properties) работают только в классах нового стиля (в Python 3 все классы являются таковыми).
Примечание 2: Постарайтесь избавиться от побочных эффектов, связанным с функциональным поведением; впрочем, такие вещи, как кэширование, вполне допустимы.
Примечание 3: Избегайте использования вычислительно затратных операций, потому что из-за записи с помощью атрибутов создается впечатление, что доступ происходит (относительно) быстро.
Если вы планируете класс таким образом, чтобы от него наследовались другие классы, но не хотите, чтобы подклассы унаследовали некоторые атрибуты, добавьте в имена два символа подчеркивания в начало, и ни одного — в конец. Механизм изменения имен в python сработает так, что имя класса добавится к имени такого атрибута, что позволит избежать конфликта имен с атрибутами подклассов.
Примечание 1: Будьте внимательны: если подкласс будет иметь то же имя класса и имя атрибута, то вновь возникнет конфликт имен.
Примечание 2: Механизм изменения имен может затруднить отладку или работу с __getattr__(), однако он хорошо документирован и легко реализуется вручную.
Примечание 3: Не всем нравится этот механизм, поэтому старайтесь достичь компромисса между необходимостью избежать конфликта имен и возможностью доступа к этим атрибутам.
Общие рекомендации
Код должен быть написан так, чтобы не зависеть от разных реализаций языка (PyPy, Jython, IronPython, Pyrex, Psyco и пр.).
Например, не полагайтесь на эффективную реализацию в CPython конкатенации строк в выражениях типа a+=b или a=a+b. Такие инструкции выполняются значительно медленнее в Jython. В критичных к времени выполнения частях программы используйте ».join() — таким образом склеивание строк будет выполнено за линейное время независимо от реализации python.
Сравнения с None должны обязательно выполняться с использованием операторов is или is not, а не с помощью операторов сравнения. Кроме того, не пишите if x, если имеете в виду if x is not None — если, к примеру, при тестировании такая переменная может принять значение другого типа, отличного от None, но при приведении типов может получиться False!
При реализации методов сравнения, лучше всего реализовать все 6 операций сравнения (__eq__, __ne__, __lt__, __le__, __gt__, __ge__), чем полагаться на то, что другие программисты будут использовать только конкретный вид сравнения.
Для минимизации усилий можно воспользоваться декоратором functools.total_ordering() для реализации недостающих методов.
Всегда используйте выражение def, а не присваивание лямбда-выражения к имени.
Наследуйте свой класс исключения от Exception, а не от BaseException. Прямое наследование от BaseException зарезервировано для исключений, которые не следует перехватывать.
Используйте цепочки исключений соответствующим образом. В Python 3, «raise X from Y» следует использовать для указания явной замены без потери отладочной информации.
Когда намеренно заменяется исключение (использование «raise X» в Python 2 или «raise X from None» в Python 3.3+), проследите, чтобы соответствующая информация передалась в новое исключение (такие, как сохранение имени атрибута при преобразовании KeyError в AttributeError или вложение текста исходного исключения в новом).
Когда вы генерируете исключение, пишите raise ValueError(‘message’) вместо старого синтаксиса raise ValueError, message.
Старая форма записи запрещена в python 3.
Такое использование предпочтительнее, потому что из-за скобок не нужно использовать символы для продолжения перенесенных строк, если эти строки длинные или если используется форматирование.
Когда код перехватывает исключения, перехватывайте конкретные ошибки вместо простого выражения except:.
К примеру, пишите вот так:
Простое написание «except:» также перехватит и SystemExit, и KeyboardInterrupt, что породит проблемы, например, сложнее будет завершить программу нажатием control+C. Если вы действительно собираетесь перехватить все исключения, пишите «except Exception:».
Хорошим правилом является ограничение использования «except:», кроме двух случаев:
При связывании перехваченных исключений с именем, предпочитайте явный синтаксис привязки, добавленный в Python 2.6:
Это единственный синтаксис, поддерживающийся в Python 3, который позволяет избежать проблем неоднозначности, связанных с более старым синтаксисом на основе запятой.
При перехвате ошибок операционной системы, предпочитайте использовать явную иерархию исключений, введенную в Python 3.3, вместо анализа значений errno.
Постарайтесь заключать в каждую конструкцию try. except минимум кода, чтобы легче отлавливать ошибки. Опять же, это позволяет избежать замаскированных ошибок.
Когда ресурс является локальным на участке кода, используйте выражение with для того, чтобы после выполнения он был очищен оперативно и надёжно.
Менеджеры контекста следует вызывать с помощью отдельной функции или метода, всякий раз, когда они делают что-то другое, чем получение и освобождение ресурсов. Например:
Последний пример не дает никакой информации, указывающей на то, что __enter__ и __exit__ делают что-то кроме закрытия соединения после транзакции. Быть явным важно в данном случае.
Используйте строковые методы вместо модуля string — они всегда быстрее и имеют тот же API для unicode-строк. Можно отказаться от этого правила, если необходима совместимость с версиями python младше 2.0.
В Python 3 остались только строковые методы.
Пользуйтесь ».startswith() и ».endswith() вместо обработки срезов строк для проверки суффиксов или префиксов.
startswith() и endswith() выглядят чище и порождают меньше ошибок. Например:
Сравнение типов объектов нужно делать с помощью isinstance(), а не прямым сравнением типов:
Когда вы проверяете, является ли объект строкой, обратите внимание на то, что строка может быть unicode-строкой. В python 2 у str и unicode есть общий базовый класс, поэтому вы можете написать:
Отметим, что в Python 3, unicode и basestring больше не существуют (есть только str) и bytes больше не является своего рода строкой (это последовательность целых чисел).
Для последовательностей (строк, списков, кортежей) используйте тот факт, что пустая последовательность есть false:
Не пользуйтесь строковыми константами, которые имеют важные пробелы в конце — они невидимы, а многие редакторы (а теперь и reindent.py) обрезают их.
Не сравнивайте логические типы с True и False с помощью ==:
