Чтение онлайн

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

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

Для строк документации рекомендуется везде использовать утроенные кавычки (""").

Однострочная документация пишется в императиве, как команда: «делай это», «возвращай то».

Многострочная документация содержит расширенное описание модуля, функции, класса. Она будет смотреться лучше, если текст будет написан с тем же отступом, что и начало строки документации.

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

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

Документация для класса должна перечислять общедоступные методы и атрибуты, содержать рекомендации по применению класса в качестве базового для других классов. Если класс является подклассом, необходимо указать, какие методы полностью заменяют, перегружают, а какие используют, но расширяют соответствующие методы надкласса. Необходимо указать и другие изменения по сравнению с надклассом.

Контроль версий повышает качество процесса создания программного обеспечения. Для этих целей часто используются RCS или CVS. «Python Style Guide» рекомендует записывать $Revision: 1.31 $ в переменную с именем __version__, а другие данные заключать в комментарии "#".

Сегодня сосуществуют несколько более или менее широко распространенных правил именования объектов. Программисты вольны выбрать тот, который принят в их организации или конкретном проекте. Автор Python рекомендует придерживаться нижеследующих правил для именования различных объектов, с тем чтобы это было понятно любому программисту, использующему Python.

Имена модулей лучше давать строчными буквами, например, shelve, string, либо делать первые буквы слов прописными, StringIO, UserDict. Имена написанных на C модулей расширения обычно начинаются с подчеркивания "_", а соответствующие им высокоуровневые обертки — с прописных букв: _tkinter и Tkinter.

Ключевые слова нельзя использовать в качестве имен, однако, если все–таки необходимо воспользоваться этим именем, стоит добавить одиночное подчеркивание в конце имени. Например: class_.

Классы обычно называют, выделяя первые буквы слов прописными, как в Tag или HTTPServer.

Имена исключений обычно содержат в своем составе слово «error» (или «warning»). Встроенные модули пишут это слово со строчной буквы (как os.error) (но могут писать и с прописной): distutils.DistutilsModuleError.

Функции, экспортируемые модулем, могут именоваться по–разному. Можно давать с прописных букв имена наиболее важных функций, а вспомогательные писать строчными.

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

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

Имена констант (имен, которые не должны переопределяться) лучше записывать прописными буквами, например: RED, GREEN, BLUE.

При работе с языком Python необходимо учитывать, что интерпретатор считает некоторые классы имен специальными (обычно такие имена начинаются с подчеркивания).

Заключение

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

Лекция знакомит с наиболее важными модулями и пакетами стандартных библиотек Python в мере, достаточной для свободного ориентирования в них.

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

Понятие модуля

Перед тем как приступить к изучению модулей стандартной библиотеки, необходимо определить то, что в Python называется модулем.

В соответствии с модульным подходом к программированию большая задача разбивается на несколько более мелких, каждую из которых (в идеале) решает отдельный модуль. В разных методологиях даются различные ограничения на размер модулей, однако при построении модульной структуры программы важнее составить такую композицию модулей, которая позволила бы свести к минимуму связи между ними. Набор классов и функций, имеющий множество связей между своими элементами, было бы логично расположить в одном модуле. Есть и еще одно полезное замечание: модули должно быть легче использовать, чем написать заново. Это значит, что модуль должен иметь удобный интерфейс: набор функций, классов и констант, который он предлагает своим пользователям.

В языке Python набор модулей, посвященных одной проблеме, можно поместить в пакет. Хорошим примером такого пакета является пакет xml, в котором собраны модули для различных аспектов обработки XML.

В программе на Python модуль представлен объектом–модулем, атрибутами которого являются имена, определенные в модуле:

Листинг

>>> import datetime

>>> d1 = datetime.date(2004, 11, 20)

В данном примере импортируется модуль datetime. В результате работы оператора import в текущем пространстве имен появляется объект с именем datetime.