Лутц М. - Изучаем Python (1077325), страница 79
Текст из файла (страница 79)
1, существует множество мест, где можно отыскать информацию о Ру1Ьоп, и объем этой информации все увеличивается. Поскольку документация играет важную роль в практическом программировании, мы исследуем каждую из этих категорий в следующих разделах. 366 Глава 14, Документация Функция йг Функция с! г — это простой способ получить список всех атрибутов объекта (т. е. методов и элементов данных). Она может быть вызвана для любого объекта, который имеет атрибуты. Например, чтобы узнать, что имеется в стандартном библиотечном модуле вув, просто импортируйте его и передайте имя модуля функции с! г: »> !щрог! вув »> е!г(вув) Отар)аупоок '. ' Оос ', ' ехсертооох ', паве втеегг ', ' втюп ', ' вюоот ', ' деттгаще', 'агдч', 'ьо!11>п щооо1е свеев, 'ьутеогоег', 'соруыд)п', 'о!вр1ауьоок'. 'о11папс1е'. 'ехс !пго', 'ехс туре', 'ехсертьоох', остальные имена опущены...) Здесь показаны только некоторые из имен; чтобы получить полный список, выполните эти инструкции на своей машине.
Чтобы узнать, какие атрибуты содержат объекты встроенных типов, передайте функции С1г литерал требуемого типа. Например, чтобы увидеть атрибуты списков и строк, можно передать функции пустой объект: »> о!г([)) [' асс , ' с1авв ', ...остальные имена опущены... 'аррепс', 'сопит', 'ехтепо, 'тпеех', 'тпвегт', 'рор', 'гечегве', 'вот!'1 'гещоче »> с!г('') [' асс ', ' с1авв ', ...остальные имена опущены... 'сар!та1тге', 'септег', 'сопит', 'Оесосе', 'епсосе', 'епсви!то', 'ехрапотаьв', 'гтпо', '1поех', чва1пощ', чеа1рьа', '!во!д!!', 'тв1оыег, Чвврасе, 'твттт1е', 'твчррег', )о1п', '1)ом ', ...остальные ииена опущены. Результаты работы функции отг для любого встроенного типа включают набор атрибутов, которые имеют отношение к реализации этого типа (методы перегруженных операторов); все они начинаются и заканчиваются двумя символами подчеркивания, чтобы сделать их отличными от обычных имен, и вы можете пока просто игнорировать их.
Того же эффекта можно добиться, передав функции с! г имя типа вме- сто литерала: Такой прием работает по той простой причине, что имена функций преобразования, такие как втг и 1!в!, в языке Ру1)топ фактически являются именами типов — вызов любого из этих конструкторов приводит к созданию экземпляра этого типа. Подробнее о конструкторах »> о!г(в!г) == о!г('') Тгое »> о!г(1!вт) "— - О!г([1) Тгое Р Результат тот ие, нто и в предыдущем лРимере 361 Источники документации в языке Рут)топ и о перегрузке операторов мы будем говорить в шестой части книги, когда будем обсуждать классы. Функция Отг служит своего рода »кратким напоминанием» вЂ” она предоставляет список имен атрибутов, но ничего не сообщает о том, что эти имена означают, За этой информацией необходимо обращаться к следующему источнику документации.
Строки документирования: дос Помимо комментариев, начинающихся с символа «, язык Ру«йоп поддерживает возможность создания документации, которая автоматически присоединяется к объектам и доступна во время выполнения. Синтаксически такие строки располагаются в начале файлов модулей, функций и классов, перед исполняемым программным кодом (перед ними вполне могут располагаться комментарии «).
Интерпретатор автоматически помещает строки документирования в атрибут г)ос соответствующего объекта. Строки документирования, определяемые пользователем В качестве примера рассмотрим файл агосагппяа.ру. Строки документирования в нем располагаются в самом его начале, а также в начале функции и класса. Здесь для создания многострочных описаний файла и функции я использовал строки в тройных кавычках, но допускается использовать строки любого типа.
Мы еще не познакомились с инструкциями Оег и с!а55, поэтому вы можете просто игнорировать все, что находится после них, за исключением строк в самом начале: Маеп1е сосиеептат«оп Хогсе Йп неге ерае = 40 Оет ецреге(х); Гопст1пп Еосоеептат«оп сап ие Па»е уоиг 11»ег тяеп» гетпгп х ° *2 с1аав еер1руее: "с1а55 Сосраептаттоп" Рд55 рг!пт зцееге(4) ргтпт 5цедге. Оос Самое важное в протоколе документирования заключается в том, что ваши комментарии становятся доступны для просмотра в виде атрибутов Оос после того, как файл будет импортирован. Поэтому, чтобы отобразить строки документирования, связанные с модулем и его объ- 368 Глава 14.
Документация ектами, достаточно просто импортировать файл и вывести значения их атрибутов ооо, где интерпретатор сохраняет текст: »> 1врогт ооозтг1прз 16 топот>оп Оосовептат1оп сап не Паче уоог 11чег тоепч »> рг1пт Ооозтг1прз. Ооо Ноеч1е Оооовептаттап Ногае 6о Неге »> рг1пт ооозтг1пзз.зооаге. ооо топот>оп Оооовептаттоп сап че паче уоог 1>чег тпеп? »> рг1пт Ооозтг1паз.евр1оуее. Ооо о1азз оооовептат1оп Обратите внимание, что для вывода строк документирования необходимо явно использовать инструкцию р г!пт, в противном случае будет выводиться единственная строка со встроенными символами новой строки.
Кроме того, существует возможность присоединять строки документирования к методам классов (эта возможность описывается ниже), но так как они представлены инструкциями Оее, вложенными в классы, это не является особым случаем. Чтобы извлечь строку с описанием метода класса, определяемого внутри модуля, необходимо указать имя модуля, класса и метода: воэо1е. с1азз, ее?Нос. Нос (примеры строк документирования методов приводятся в главе 26). Стандарты оформления строк документирования Не существует какого-то общепринятого стандарта, который регламентировал бы, что должно входить в строки документирования (хотя в некоторых компаниях существуют свои внутренние стандарты). В свое время предлагались различные шаблоны и языки разметки (например, НТМЬ или ХМЬ), но они не завоевали популярность в мире РуФ)топ.
И, положа руку на сердце, едва ли мы дождемся появления программистов, которые захотят писать документацию на языке разметки НТМЬ! Вообще, среди программистов документация обычно отходит на задний план. Если вы увидите хоть какие-то комментарии в файле, считайте, что вам повезло. Однако я настоятельно рекомендую тщательно документировать свой программный код — это действительно очень важная часть хорошо написанного программного кода. Замечу, что нет никаких стандартов на структуру строк документирования, поэтому, если вы хотите использовать их, чувствуйте себя свободными.
Встроенные строки документирования Как оказывается, во встроенных модулях и объектах языка Ру(Ьоп используется сходная методика присоединения документации — до и по- 369 Источники документации е языке Ру!Ьоп еле списка атрибутов, возвращаемых функцией Ь1г. Например, чтобы увидеть удобочитаемое описание встроенного модуля, его надо импортировать и вывести строку Ьос »> 1арогв вув »> рг1пс вув, Оос То!в щоос!е ргоч1оев асеева то воще ос]еств ивео ог ща1п!а!пес Ьу !Пе 1и!егргегег апо !о ...остальной текст опущен... Оупащ!с ЬЬ]ес!в; агдч -- сощпапс 11пе агдсщеп!в; агдч[О] !в !Ье всг!р! ра!Плаще 11 японо ра!и -- щоьс1в веагсь ра!ь; ра1п[О] 1в тпе всгзр! ь!гессогу, е1ве '' щооо1ев -- Ь1с11опагу от 1оасес паос1вв остальной текст опущен..
Описание функций, классов и методов внутри встроенных модулей присоединено к их атрибутам Ьос »> рг1пс вув.девгегсосп1. Ьос де!ге!сосо!(Ьь]ес!) -> !и!едет яе!Ьгп гпе ссггеп! гегегвпсе сооп! Тот !Ье оь)ест. остальной текст опущен. Кроме того, можно прочитать описание встроенных функций, находя- щееся в их строках документирования: »> рг1п1 1п1. Ьос 1п!(к[, Ьаве]) -> зп!едет сопчег! а втг!пд ог повьет !о ап 1п!едет, зг рова!ь)е. ...остальной текст опущен...
»> рг1пс орел, Ьос 111е[паще[, посв[, Ьоттег1пд]]) -> 1>1е оо)ес! Орел а Т>1е. Тяе щоое сап Ье 'г', 'н' ог 'а' тот геасзпд .остальной текст опущен... Просматривая таким способом строки документирования встроенных инструментов, вы можете получить богатый объем информации, однако вам не требуется этого делать — эту информацию функция Ье1р, тема следующего раздела, предоставляет вам автоматически. РуОос функция Ье! р Методика использования строк документирования оказалась настолько удобной, что теперь в состав Ру1]гоп входит инструмент, который упрощает их отображение. Стандартный инструмент РуРос написан на языке Рудйоп, он умеет извлекать строки документирования вместе с информацией о структуре программных компонентов и формировать из них удобно отформатированные отчеты различных типов. Существуют различные способы запуска РуВос, включая сценарий командной строки (за дополнительной информацией обращайтесь к ру- Глава 14.
![](https://s.studizba.com/z.php?f=/templates/si/i/noavatar.png&w=100&h=100&t=1"){kind=avatar}
