Математический анализ. 3е издание
 Скачать 4.86 Mb.
|
|
Встроенные строки документирования Как оказывается, во встроенных модулях и объектах языка Python ис пользуется сходная методика присоединения документации – до и по Источники документации в языке Python 369 сле списка атрибутов, возвращаемых функцией dir. Например, чтобы увидеть удобочитаемое описание встроенного модуля, его надо импор тировать и вывести строку __doc__: >>> import sys >>> print sys.__doc__ This module provides access to some objects used or maintained by the interpreter and to ...остальной текст опущен... Dynamic objects: argv command line arguments; argv[0] is the script pathname if known path module search path; path[0] is the script directory, else '' modules dictionary of loaded modules ...остальной текст опущен... Описание функций, классов и методов внутри встроенных модулей присоединено к их атрибутам __doc__: >>> print sys.getrefcount.__doc__ getrefcount(object) > integer Return the current reference count for the object. ...остальной текст опущен... Кроме того, можно прочитать описание встроенных функций, находя щееся в их строках документирования: >>> print int.__doc__ int(x[, base]) > integer Convert a string or number to an integer, if possible. ...остальной текст опущен... >>> print open.__doc__ file(name[, mode[, buffering]]) > file object Open a file. The mode can be 'r', 'w' or 'a' for reading ...остальной текст опущен... Просматривая таким способом строки документирования встроенных инструментов, вы можете получить богатый объем информации, одна ко вам не требуется этого делать – эту информацию функция help, тема следующего раздела, предоставляет вам автоматически. PyDoc: функция help Методика использования строк документирования оказалась настоль ко удобной, что теперь в состав Python входит инструмент, который упрощает их отображение. Стандартный инструмент PyDoc написан на языке Python, он умеет извлекать строки документирования вместе с информацией о структуре программных компонентов и формировать из них удобно отформатированные отчеты различных типов. Существуют различные способы запуска PyDoc, включая сценарий ко мандной строки (за дополнительной информацией обращайтесь к ру 370 Глава 14. Документация ководству по библиотеке Python). Два, пожалуй, самых заметных ин терфейса к PyDoc – это встроенная функция help и графический интер фейс к PyDoc для воспроизводства отчетов в формате HTML. Функция help вызывает PyDoc для создания простых текстовых отчетов (кото рые выглядят как страницы руководства в UNIX подобных системах): >>> import sys >>> help(sys.getrefcount) Help on builtin function getrefcount: getrefcount(...) getrefcount(object) > integer Return the current reference count for the object. ...остальной текст опущен... Обратите внимание: чтобы вызывать функцию help, не обязательно импортировать модуль sys, но его необходимо импортировать, чтобы получить справку по модулю sys – функция ожидает получить ссылку на объект. Для крупных объектов, таких как модули и классы, функ ция help делит выводимую информацию на множество разделов, часть из которых показана здесь. Запустите следующую команду в интерак тивном сеансе, чтобы получить полный отчет: >>> help(sys) Help on builtin module sys: NAME sys FILE (builtin) DESCRIPTION This module provides access to some objects used or maintained by the interpreter and to functions ...остальной текст опущен... FUNCTIONS __displayhook__ = displayhook(...) displayhook(object) > None Print an object to sys.stdout and also save it ...остальной текст опущен... DATA __name__ = 'sys' __stderr__ = ...остальной текст опущен... Часть информации в этом отчете извлечена из строк документирова ния, а часть этих сведений (например, сигнатуры функций) – это ин формация о структуре программных компонентов, которую PyDoc из влекает автоматически, в результате анализа внутреннего устройства объектов. Кроме того, функция help может использоваться для полу Источники документации в языке Python 371 чения сведений о встроенных функциях, методах и типах. Чтобы по лучить справку о встроенном типе, нужно просто передать функции имя типа (например, dict – для словарей, str – для строк, list – для списков). Вам будет предоставлен большой объем информации с опи саниями всех методов, доступных для этого типа: >>> help(dict) Help on class dict in module __builtin__: class dict(object) | dict( ) > new empty dictionary. ...остальной текст опущен... >>> help(str.replace) Help on method_descriptor: replace(...) S.replace (old, new[, maxsplit]) > string Return a copy of string S with all occurrences ...остальной текст опущен... >>> help(ord) Help on builtin function ord: ord(...) ord(c) > integer Return the integer ordinal of a onecharacter string. Наконец, функция help может извлекать информацию не только из встроенных, но и из любых других модулей. Ниже приводится отчет, полученный для файла docstrings.py, представленного выше. Здесь снова часть информации представлена строками документирования, а часть была получена автоматически, в результате исследования структуры объектов: >>> help(docstrings.square) Help on function square in module docstrings: square(x) function documentation can we have your liver then? >>> help(docstrings.employee) ...остальной текст опущен... >>> help(docstrings) Help on module docstrings: NAME docstrings FILE c:\python22\docstrings.py DESCRIPTION 372 Глава 14. Документация Module documentation Words Go Here CLASSES employee ...остальной текст опущен... FUNCTIONS square(x) function documentation can we have your liver then? DATA __file__ = 'C:\\PYTHON22\\docstrings.pyc' __name__ = 'docstrings' spam = 40 PyDoc: отчеты в формате HTML Функция help прекрасно подходит для извлечения информации при ра боте в интерактивной оболочке. Однако для PyDoc существует и графи ческий интерфейс (простой и переносимый сценарий Python/Tkinter), с помощью которого можно создавать отчеты в формате HTML, доступ ные для просмотра в любом веб броузере. В этом случае PyDoc может выполняться как локально, так и удаленно, в режиме клиент/сервер. Внутри отчетов автоматически создаются гиперссылки, которые по зволят щелчком мыши перемещаться к описаниям взаимосвязанных компонентов в вашем приложении. Чтобы запустить PyDoc в этом режиме, сначала необходимо запустить поисковый механизм, графический интерфейс которого представлен на рис. 14.1. Сделать это можно, выбрав пункт меню Module Docs в меню Рис. 14.1. Главное окно графического интерфейса PyDoc: введите имя требуемого модуля, нажмите клавишу Enter, выберите модуль и затем щелкните на кнопке «go to selected» (или, не вводя имя модуля, щелкните на кнопке «open browser», чтобы увидеть список всех доступных модулей) Источники документации в языке Python 373 Python кнопки Пуск в Windows или запустив сценарий pydocgui.pyw в каталоге Tools, где был установлен Python (также можно запустить сценарий pydoc.py с ключом g). Введите имя интересующего вас моду ля и нажмите клавишу Enter – PyDoc обойдет каталоги в пути поиска модулей (sys.path) и отыщет ссылки на указанный модуль. Отыскав нужную запись, выберите ее и щелкните на кнопке «go to se lected» (перейти к выбранному элементу). PyDoc откроет веб броузер и отобразит отчет в формате HTML. На рис. 14.2 показано, как выгля дит информация, представленная PyDoc, для встроенного модуля glob. Обратите внимание на гиперссылки в разделе «Modules» (модули) на этой странице – вы можете щелкать на них мышью и перемещаться на страницы с описаниями этих (импортированных) модулей. Для боль ших страниц PyDoc также генерирует гиперссылки на различные раз делы на этой странице. Рис. 14.2. Отыскав требуемый модуль в окне, представленном на рис. 14.1, щелкните на кнопке «go to selected», и описание модуля в формате HTML будет отображено в веб+броузере, как в данном случае, где отображено описание модуля из стандартной библиотеки 374 Глава 14. Документация Подобно функции help графический интерфейс может извлекать ин формацию и из пользовательских модулей. На рис. 14.3 показана страница с информацией, извлеченной из нашего файла docstrings.py. PyDoc можно настраивать и запускать разными способами, но мы не будем рассматривать эти возможности здесь – за дополнительной ин формацией обращайтесь к руководству по стандартной библиотеке языка Python. Главное, что вы должны запомнить, – PyDoc по сути создает отчеты о реализации на основе той информации, что имеется, – если вы использовали строки документирования в своих файлах, Py Doc сделает все необходимое, чтобы собрать и отформатировать их со ответствующим образом. PyDoc – это всего лишь средство получения справки об объектах, таких как функции и модули, но он обеспечивает Рис. 14.3. PyDoc может служить источником документации как для встро+ енных, так и для пользовательских модулей. Здесь приводится страница с описанием пользовательского модуля, где можно видеть все строки доку+ ментирования (docstrings), извлеченные из файла с исходными текстами Источники документации в языке Python 375 простой доступ к документации с описанием этих компонентов. Его отчеты более полезны, чем просто списки атрибутов, хотя и менее ис черпывающи, чем стандартные руководства. Совет дня: если поле ввода имени модуля в окне на рис. 14.1 оста вить пустым и щелкнуть на кнопке «open browser» (открыть бро узер), PyDoc воспроизведет веб страницу с гиперссылками на все модули, доступные для импорта на данном компьютере. Сюда входят модули стандартной библиотеки, расширения сторонних производителей, пользовательские модули, расположенные в пу ти поиска импортируемых модулей, и даже модули, написанные на языке C, скомпонованные статически или динамически. Та кую информацию сложно получить иными путями, если не пи сать свой программный код, который будет заниматься исследо ванием исходных текстов набора модулей. Кроме того, PyDoc может сохранять документацию в формате HTML для последующего просмотра или вывода на печать; указа ния о том, как это сделать, вы найдете в документации. Следует отметить, что PyDoc может не совсем корректно работать со сцена риями, которые читают данные из потока стандартного ввода, – PyDoc импортирует целевой модуль для последующего исследо вания, но при работе в режиме с графическим интерфейсом может отсутствовать связь с потоком стандартного ввода. Однако моду ли, которые не требуют немедленного ввода информации в мо мент импортирования, будут обслуживаться корректно. Стандартный набор руководств Стандартные руководства играют роль наиболее полного и самого све жего описания языка Python и набора инструментальных средств. Ру ководства распространяются в формате HTML и в других форматах и в Windows устанавливаются вместе системой Python – они доступны в виде пунктов подменю Python, в меню кнопки Пуск (Start), а также в ме ню Help (Cправка) среды разработки IDLE. Набор руководств можно как получить отдельно, в различных форматах, по адресу http://www.py+ thon.org , так и читать непосредственно на сайте (следуйте по ссылке Documentation (Документация)). Руководства в системе Windows оформле ны в виде файлов справки, поддерживающих возможность поиска; электронная версия на сайте Python.org также имеет страницу поиска. После открытия руководства в операционной системе Windows оно отображает начальную страницу, как показано на рис. 14.4. Двумя са мыми важными, пожалуй, здесь являются ссылки «Library Referen ce» (справочное руководство по библиотеке, где описываются встроен ные типы, функции, исключения и модули стандартной библиотеки) и «Language Reference» (справочное руководство по языку, где приво дится формальное описание языковых конструкций). На этой странице имеется также ссылка «Tutorial» (самоучитель), которая ведет к крат кому введению для начинающих изучение языка. 376 Глава 14. Документация Вебресурсы На официальном веб сайте проекта Python (http://www.python.org) вы найдете ссылки на различные ресурсы, посвященные этому языку про граммирования, часть которых охватывает специализированные темы и области применения языка. Щелкнув по ссылке «Documentation», можно получить доступ к электронному учебнику и к «Beginners Guide to Python» (руководство по языку Python для начинающих). На сайте также имеются ссылки на другие ресурсы на других языках. Массу информации о языке Python можно отыскать в Интернет эн циклопедии, в блогах, на веб сайтах и других ресурсах в Сети. Чтобы получить перечень ссылок на такие ресурсы, попробуйте поискать по строке «Python programming» в поисковой системе Google. Печатные издания Последний источник информации – это огромная коллекция печат ных справочных пособий по языку Python. Однако учтите, что обычно Рис. 14.4. Стандартный набор руководств по языку Python, доступный на сайте www.python.org в меню Help (Справка) среды разработки IDLE и в меню кнопки Пуск (Start) в операционной системе Windows. В Windows набор руководств оформлен в виде файла справки, поддерживающего возможность поиска; электронная версия на веб+сайте также имеет страницу поиска. Из всех предлагаемых руководств самым востребованным является Library reference (справочное руководство по библиотеке) Типичные ошибки программирования 377 книги немного отстают от развития языка Python, частично из за то го, что для написания книги необходимо время, частично из за естест венных задержек, свойственных самому процессу издания. Обычно книга выходит в свет с отставанием на три или более месяцев от теку щего состояния дел. В отличие от стандартных руководств, книги ред ко распространяются бесплатно. Однако для многих удобство и качество профессионального издания с лихвой окупает потраченные деньги. Более того, язык Python изме няется настолько медленно, что книги сохраняют свою актуальность в течение еще нескольких лет после их издания, особенно если их ав торы публикуют дополнения в Сети. Ссылки на другие книги о Python вы найдете в предисловии. Типичные ошибки программирования Прежде чем перейти к упражнениям этой части книги, рассмотрим не которые наиболее распространенные ошибки, которые допускают на чинающие программисты в инструкциях и программах на языке Py thon. Многие из этих ошибок, уже упоминавшиеся ранее в этой части книги, я привел здесь для полноты картины. С ростом опыта использо вания языка Python вы научитесь избегать их, но несколько слов, ска занных сейчас, помогут вам избегать их с самого начала: • Не забывайте про двоеточия. Никогда не забывайте вводить сим вол двоеточия в конце заголовков составных инструкций (первая строка таких инструкций, как if, while, for и других). Сначала вы наверняка будете забывать об этом (как я и большинство из 3000 моих студентов), но вскоре это превратится для вас в привычку. • Начинайте с первой позиции в строке. Программный код верхнего уровня (не вложенный) должен начинаться с первой позиции в стро ке. Сюда относится как не вложенный программный код в моду лях, так и программный код, который вводится в интерактивной оболочке. • Пустые строки имеют особый смысл в интерактивной оболочке. Пустые строки в теле составных инструкций внутри файлов моду лей всегда игнорируются, но когда программный код вводится в ин терактивной оболочке, они завершают составные инструкции. Дру гими словами, ввод пустой строки сообщает интерактивной ко мандной оболочке, что вы закончили ввод составной инструкции – если вам необходимо продолжить ввод такой инструкции, не нажи майте клавишу Enter, когда отображается строка приглашения к вводу ..., пока вы действительно не закончите ее ввод. • Используйте отступы непротиворечивым способом. Старайтесь не смешивать символы табуляции и пробелы при оформлении отсту пов в блоке, если вы не знаете точно, как текстовый редактор интер претирует символы табуляции. В противном случае интерпретатор 378 Глава 14. Документация Python будет видеть совсем не то, что вы видите на экране, когда он будет выполнять преобразование символов табуляции в пробелы. Это справедливо не только для Python, но и для любого другого язы ка программирования с блочно структурированным оформлением программного кода – если у другого программиста в текстовом ре дакторе ширина символов табуляции настроена иначе, он не смо жет понять структуру вашего программного кода. Для оформления отступов лучше использовать что то одно – или символы табуля ции, или пробелы. • Не пишите на языке C. Напоминаю программистам, использую щим C/C++: нет никакой необходимости заключать условные вы ражения в круглые скобки в инструкциях if и while (например, if (X == 1): ). Это допустимо (любое выражение можно заключить в круглые скобки), но в данном контексте они совершенно излиш ни. Кроме того, не заканчивайте все инструкции точками с запятой – это также вполне допустимо в языке Python, но они совершенно бесполезны, если в каждой строке находится всего одна инструк ция (конец строки обычно обозначает конец инструкции). И помни те – не встраивайте инструкции присваивания в условные выраже ния циклов while и не заключайте блоки в фигурные скобки {} (вло женные блоки оформляются с помощью отступов). |