Перейти на главную страничку сайта (список статей, файлы для скачивания)

ФОРУМ (здесь можно обсудить эту статью, а также любые проблемы программирования на различных макроязыках и в скриптовых средах)

Г. Россум, Ф.Л.Дж. Дрейк, Д.С. Откидач, Язык программирования Python

Часть III: Библиотека стандартных модулей

Описание языка Python было бы неполным без описания библиотеки — огромной коллекции модулей. Некоторые модули написаны на C и встраиваются в интерпретатор, другие написаны на языке Python и доступны в исходном виде. Некоторые модули предоставляют услуги, характерные для языка Python (например, вывод сообщений об ошибках) или определенной операционной системы (например, доступ к определенным аппаратным средствам), другие определяют интерфейсы, характерные для некоторой области применения (например, WWW).

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

14. Конфигурационные модули

14.1. site — общая конфигурация

Этот модуль автоматически импортируется при каждом запуске интерпретатора (за исключением случаев, когда используется опция командной строки -S) и предназначен, в первую очередь, для добавления путей поиска модулей, характерных для данной машины. По умолчанию в пути поиска добавляются каталоги с именами ‘sys.prefix + '/lib/site-packages'’ и ‘sys.prefix + '/site-python'’ (UNIX) или sys.prefix (другие платформы). Кроме того, модуль обрабатывает конфигурационные файлы путей вида ‘package.pth’ во всех указанных каталогах. Эти конфигурационные файлы должны содержать дополнительные пути (по одному каталогу в строке), которые будут включены в sys.path. Пустые строки и строки, начинающиеся с ‘#’, игнорируются.

Например, пусть стандартные библиотеки установлены в каталоге ‘/usr/lib/python1.5’, в котором присутствует подкаталог ‘site-packages’. Пусть каталог ‘/usr/lib/python1.5/site-packages’ в свою очередь содержит вложенные каталоги ‘foo’, ‘bar’ и ‘spam’ и конфигурационные файлы ‘foo.pth’ и ‘bar.pth’. Предположим, файл ‘foo.pth’ содержит следующие строки:

# foo package configuration

foo
bar
bletch

и ‘bar.pth’ содержит:

# bar package configuration

bar

Тогда в sys.path будут добавлены каталоги ‘/usr/lib/python1.5/site-packages/bar’ и ‘/usr/lib/python1.5/site-packages/foo’.

Обратите внимание, что каталоги ‘bletch’ и ‘spam’ не добавляются, так как не существует файла или каталога с именем ‘bletch’ и каталог ‘spam’ не упомянут ни в одном из конфигурационных файлов.

После выполнения перечисленных манипуляций с путями, производится попытка импортировать модуль sitecustomize, в который может выполнять дополнительные настройки. Если при импортировании генерируется исключение ImportError, оно молча игнорируется.

14.2. user — конфигурация пользователя

В целях безопасности интерпретатор не выполняет автоматически конфигурационный файл пользователя. Только в интерактивном режиме интерпретатор выполняет файл, указанный в переменной окружения PYTHONSTARTUP. Однако некоторые программы могут позволить загрузить стандартный конфигурационный файл пользователя. Программа, желающая использовать такой механизм, должна выполнить инструкцию ‘import user’.

Модуль user ищет файл с именем ‘.pythonrc.py’ в домашнем каталоге пользователя и выполняет его с помощью встроенной функции execfile() в своем собственном (модуля user) глобальном пространстве имен. Ошибки, возникающие при выполнении ‘.pythonrc.py’ модулем user не обрабатываются. Если домашний каталог не может быть определен, выполняется файл ‘.pythonrc.py’ в текущем каталоге.

Будьте сдержаны в том, что Вы помещаете в свой файл ‘.pythonrc.py’. Так как Вы не знаете, какие программы будут его использовать, изменение поведения стандартных модулей и функций вряд ли будет хорошей идеей.

Рекомендация для программистов, желающих использовать описанный здесь механизм: простейший способ устанавливать параметры — определить переменные в файле ‘.pythonrc.py’. Например, модуль spam может определить, насколько подробными пользователь хочет видеть его сообщения, с помощью следующих инструкций:

import user
try:
    # значение, установленное пользователем
    verbose = user.spam_verbose
except AttributeError:
    # значение по умолчанию
    verbose = 0

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

15. Служебные модули

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

15.1. sys — характерные для системы параметры и функции

Этот модуль предоставляет доступ к переменным, используемым или поддерживаемым интерпретатором, и функциям, которые интенсивно взаимодействуют с интерпретатором. Модуль sys всегда доступен.

argv

Список аргументов, переданных в командной строке программе на языке Python. argv[0] является именем программы (является имя полным или нет, зависит от используемой операционной системы). Если интерпретатор запущен с опцией - c, argv[0] является строкой ’-c’. При чтении команд со стандартного потока ввода (в том числе в интерактивном режиме) argv[0] является строкой ’-’ или ’’ в зависимости от того, использовалась опция ‘-’ или нет.

byteorder

Строка, указывающая характерный для платформы порядок следования байтов: ’big’ (big-endian) или ’little’ (little-endian). Переменная доступна, начиная с версии 2.0.

builtin_module_names

Кортеж строк — имен всех модулей, встроенных в интерпретатор. Эта информация не может быть получена никаким другим путем (modules.keys() дает список имен импортированных модулей).

copyright

Строка, содержащая авторские права на интерпретатор языка Python.

dllhandle (Windows)

Целое число, дескриптор DLL интерпретатора Python.

exc_info()

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

Если в настоящий момент обработка исключения не выполняется, возвращаемый кортеж содержит три объекта None. В противном случае, возвращается ‘(type, value, traceback)’, где type — тип исключения (класс или строка), value — значение исключения (экземпляр класса) или ассоциированное значение (строка) и traceback — объект traceback (см. раздел 11.9.3), представляющий пройденный путь от места возникновения исключительной ситуации.

Важное замечание: присваивание traceback локальной переменной в функции, обрабатывающей исключение, приведет к образованию циклических ссылок между объектами. Таким образом, удаление объекта будет возможным, только если интерпретатор собран со сборщиком мусора (см. описание модуля gc). Так как в большинстве случаев объект traceback не нужен, наилучшим решением будет использование функции в виде ‘type, value = sys.exc_info()[:2]’ для получения только типа и значения исключения. Если Вам необходим объект traceback, удостоверьтесь в том, что Вы удаляете его после использования (лучше всего это делать в ветви finally инструкции try) или используйте exc_info() в отдельной функции, вызванной из ветви except.

exc_type

exc_value

exc_traceback

Присутствуют только для совместимости со старыми версиями — используйте функцию exc_info(). Так как они являются глобальными переменными, содержат значения для исключения, обработка которого была начата последней. Таким образом, их использование не безопасно в многопоточных программах. Если в данный момент исключение не обрабатывается, значение exc_type равно None и переменные exc_value и exc_traceback не определены.

exec_prefix

Строка, содержащая начало пути к зависимым от платформы файлам интерпретатора Python (зависит от параметров сборки и/или установки). Например, конфигурационные файлы на платформах UNIX располагаются в каталоге ‘sys.exec_prefix + ’/lib/python’ + sys.version[:3] + ’/config’’.

executable

Строка с (полным) именем исполняемого файла интерпретатора Python, если оно имеет смысл для данной системы.

exit([exit_code])

Прерывает выполнение программы. Реализуется путем генерации исключения SystemExit, то есть страховочный код (ветвь finally инструкции try) принимается во внимание и попытка выхода может быть прервана на внешнем уровне путем обработки исключения. Необязательный аргумент может быть целым числом (по умолчанию 0, что соответствует успешному завершению; многие системы требуют, чтобы это число было от 0 до 127), которое будет использовано в качестве кода завершения, или объект любого другого типа. В последнем случае использование None эквивалентно 0, для других объектов на стандартный поток ошибок выводится строковое представление (полученное аналогично тому, как это делает встроенная функция str()) и в качестве кода завершения используется 1. В частности инструкция ‘sys.exit('Сообщение об ошибке')’ является быстрым способом прервать выполнение программы с выводом сообщения об ошибке.

exitfunc

Эта переменная на самом деле не определена самим модулем, но Вы можете присвоить ей объект-функцию, которая будет вызвана (без аргументов) при завершении работы интерпретатора. Функция exitfunc() не вызывается, если процесс прерван с помощью некоторых сигналов, при возникновении фатальной ошибки и при вызове функции os._exit(). Мы настоятельно не рекомендуем устанавливать переменную exitfunc напрямую (это может привести к некорректной работе других компонент программы) — воспользуйтесь модулем atexit, который предоставляет возможность регистрировать несколько функций.

getdefaultencoding()

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

getrefcount(object)

Возвращает число ссылок на объект object. Число будет на единицу больше, чем Вы, возможно, ожидали, так как оно включает временно созданную ссылку на объект как аргумент функции getrefcount().

getrecursionlimit()

Возвращает текущее ограничение рекурсии — максимальную глубину стека интерпретатора Python. Это ограничение предотвращает переполнение стека при бесконечных рекурсиях. Ограничение рекурсии может быть установлено с помощью функции setrecursionlimit(). Эта функция доступна, начиная с версии 2.0.

hexversion

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

if sys.hexversion >= 0x010502F0:
    # Используем новые возможности.
    ...
else:
    # Используем альтернативную реализацию или
    # выводим предупреждение.
    ...

Функция названа ‘hexversion’ потому, что возвращаемое ей значение выглядит действительно осмысленным, только если смотреть на его шестнадцатеричное представление (например, полученное с помощью встроенной функции hex()). Информация о версии в более дружественном виде хранится в переменной version_info.

last_type

last_value

last_traceback

Эти три переменные не всегда определены. Им присваиваются значения в случае, если исключение не обрабатывается и интерпретатор выводит информацию об ошибке. Наличие этих переменных позволяет пользователю в интерактивном режиме импортировать модуль отладчика и сделать “вскрытие трупа” программы, исключив необходимость повторного запуска команд, приведших к возникновению ошибки. Для этого достаточно выполнить ‘import pdb; pdb.pm()’ (см. главу 25.1).

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

maxint

Наибольшее целое число, которое может быть представлено в рамках типа int. Это число не меньше, чем 231 .. 1. Наименьшее представимое в рамках int целое число на большинстве платформ равно -maxint-1.

modules

Словарь, отображающий имена импортированных модулей в объекты-модули. Вы можете манипулировать им, например, для принудительной перезагрузки модулей или для того, чтобы сделать доступными для импортирования динамически созданные модули (см. описание модуля new). Заметим, что последовательное удаление модуля из modules и повторное его импортирование — это не совсем то, что делает встроенная функция reload().

path

Список строк — путей поиска модулей. Изначально эта переменная содержит каталог, в котором находится исполняемая в данный момент программа (или пустую строку, если команды считываются со стандартного потока ввода; пустая строка используется для обозначения текущего каталога), пути, указанные в переменной окружения PYTHONPATH и зависящие от платформы пути по умолчанию. Обратите внимание, что каталог, в котором находится программа, идет первым (path[0]).

platform

Строка, содержащая идентификатор платформы, например, ’sunos5’, ’linux1’ или ’win32’. Может использоваться, например, для добавления характерных для платформы путей в path.

prefix

Строка, содержащая начало пути к независимым от платформы файлам интерпретатора Python (зависит от параметров сборки и/или установки). Например, основная коллекция модулей на платформах UNIX устанавливается в каталог ‘sys.prefix + '/lib/python' + sys.version[:3]’, в то время как независимые от платформы заголовочные файлы (все, кроме ‘config.h’) располагаются в ‘sys.prefix + '/include/python' + sys.version[:3]’.

ps1

ps2

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

setcheckinterval(interval)

Устанавливает интервал, через который интерпретатор будет проверять (контролировать) такие вещи, например, как переключение между потоками и обработчики сигналов. interval — целое число (по умолчанию 10), количество выполненных байт-инструкций языка между проверками. Увеличивая интервал, Вы можете повысить производительность многопоточных программ, уменьшая — ускорить реакцию. При значениях интервала меньше или равных нулю, проверка производится после выполнения каждой байт-инструкции, обеспечивая максимальную оперативность в ущерб производительности.

setdefaultencoding(encoding)

Устанавливает кодировку, которая будет использоваться по умолчанию при преобразовании обычных строк в строки Unicode и наоборот. Если строка encoding не соответствует доступной кодировке, генерирует исключение LookupError. Эта функция предназначена для использования в модуле site (или sitecustomize), после этого она обычно удаляется из пространства имен модуля sys. Функция доступна, начиная с версии 2.0.

setprofile(profilefunc)

Устанавливает системную функцию, реализующую замер производительности (profiling) различных компонент программы (см. главу 25.2). Функция profilefunc будет вызываться аналогично трассировочной функции (см. описание функции settrace()), но не для каждой выполненной строки кода, а только при вызове и возврате из функций и при генерации исключений.

setrecursionlimit(limit)

Устанавливает максимальную глубину стека интерпретатора Python. Это ограничение предотвращает переполнение стека при бесконечных рекурсиях. Максимальная возможная глубина стека зависит от платформы. Вам может понадобиться установить более высокое значение, если Ваша программа использует глубокие рекурсивные вызовы. Однако делать это следует с осторожностью, так как слишком большое значение может привести к аварийному завершению работы интерпретатора. Эта функция доступна, начиная с версии 2.0.

settrace(tracefunc)

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

stdin

stdout

stderr

Файловые объекты, соответствующие стандартным потокам ввода, вывода и ошибок интерпретатора. stdin используется интерпретатором для операций ввода, таким как input() и raw_input(). stdout используется интерпретатором для операций вывода с помощью инструкции print, инструкций-выражений и для вывода приглашений функциями input() и raw_input(). Для вывода собственных приглашений интерпретатора в интерактивном режиме и вывода сообщений об ошибках (не перехваченных исключениях) используется stderr. Для корректной работы встроенных возможностей языка Python stdout и stderr должны быть объектами (произвольного типа), имеющими метод write(). Для корректной работы функций input() и raw_input() объект, на который ссылается stderr должен иметь метод readline(). Заметим, что изменение этих переменных не оказывает влияния на стандартные потоки ввода/вывода порождаемых (например, функциями os.popen() или os.system()) процессов.

__stdin__

__stdout__

__stderr__

Эти переменные хранят исходные значения для stdin, stderr и stdout при запуске программы и могут быть использованы для их восстановления.

tracebacklimit

Если этой переменной присвоено целое значение, она определяет максимальное число уровней информации, представляемой объектом traceback, которое будет выводиться при возникновении (необрабатываемой) исключительной ситуации. По умолчанию выводится не более 1000 уровней. Значение меньше или равное нулю запрещает вывод такой информации — выводится только тип исключения и его строковое представление.

version

Строка, содержащая информацию о версии, номере и времени сборки интерпретатора Python и компиляторе, который был использован, в виде ’version (#build_number, build_date, build_time) [compiler]’. Первые три символа используются для идентификации версии в именах каталогов, в которые производится установка. version используется в первой выводимой при запуске интерпретатора в интерактивном режиме строке: 'Python '+sys.version+' on '+platform.

version_info

Кортеж из пяти объектов, описывающих номер версии: ‘(major, minor, micro, releaselevel, serial)’. Все элементы, кроме releaselevel являются целыми числами. releaselevel может иметь одно из четырех значений: ’alpha’, ’beta’, ’candidate’ или ’final’. Значение version_info, соответствующее финальному выпуску Python 2.0, будет ‘(2, 0, 0, 'final', 0)’. Переменная определена, начиная с версии 1.6.

winver (Windows)

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

15.2. gc — управление "сборщиком мусора"

Этот модуль предоставляет интерфейс к необязательному “сборщику мусора” (garbage collector, GC): возможность отключить его, настроить частоту работы, установить отладочные параметры, а также предоставляет доступ к “потерянным” [1“Потерянными” (или недоступными) мы будем называть объекты, на которые не ссылается ни одна переменная. Единственный способ удалить их или получить к ним доступ — воспользоваться “сборщиком мусора”.] объектам, найденным “сборщиком мусора”, которые, однако, не могут быть удалены. Так как “сборщик мусора” дополняет механизм подсчета ссылок, уже используемый интерпретатором Python, Вы можете отключить его, если уверены, что программа не создает циклических ссылок. Автоматический сбор может быть отключен вызовом gc.disable(). Для поиска утечек памяти при отладке, следует вызвать gc.set_debug(gc.DEBUG_LEAK).

Модуль gc предоставляет следующие функции:

enable()

Включает автоматический “сбор мусора”.

disable()

Выключает автоматический “сбор мусора”.

isenabled()

Возвращает 1, если автоматический “сбор мусора” включен, иначе возвращает 0.

collect()

Запускает полный “сбор мусора” и возвращает общее количество найденных недоступных объектов. Список объектов, которые не могут быть удалены “сборщиком мусора”, становится доступными через переменную garbage.

set_debug(flags)

Устанавливает параметры отладки. Вся отладочная информация будет выводиться на стандартный поток ошибок. Отладочные флаги (см. ниже) можно комбинировать с помощью оператора битового ИЛИ. Полностью отключить отладку можно с помощью инструкции set_debug(0).

get_debug()

Возвращает параметры отладки, которые в настоящий момент установлены.

set_threshold(threshold0 [, threshold1 [, threshold2]])

Устанавливает пороги запуска (частоту) автоматического “сбора мусора”. Значение threshold0 равное нулю отключает автоматический “сбор мусора”.

Различаются три поколения объектов в зависимости от того, сколько запусков сборщика они пережили. Новые объекты — самые молодые, относятся к поколению 0. После каждого запуска сборщика объект “взрослеет”, перемещается в поколение 1, затем в поколение 2. Так как поколение 2 самое старшее, объекты остаются в нем после последующих запусков сборщика. Для того, чтобы решить, когда производить запуск, сборщик подсчитывает количество созданных и удаленных объектов после последнего запуска. Когда разница между ними достигает threshold0, запускается “сборщик мусора”. Изначально анализируется только самое молодое поколение. Если поколение 0 анализировалось более threshold1 раз после последнего анализа поколения 1, также анализируется и поколение 1. Аналогично threshold2 контролирует количество запусков сборщика для поколения 1, перед тем как обрабатывать поколение 2.

get_threshold()

Возвращает кортеж текущих порогов запуска “сборщика мусора” в виде ‘(threshold0, threshold1, threshold2)’.

Следующая переменная доступна только для чтения:

garbage

Список недоступных объектов, найденных “сборщиком мусора”, которые не могут быть удалены. Экземпляры классов, имеющие специальный метод __del__() и входящие в цикл ссылающихся друг на друга объектов, делают весь цикл неудаляемым. Если установлена опция отладки DEBUG_SAVEALL, в этой переменной сохраняются все найденные недоступные объекты (“сборщик мусора” их при этом не удаляет).

Для установки параметров отладки модуль предоставляет следующие константы-флаги:

DEBUG_STATS

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

DEBUG_COLLECTABLE

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

DEBUG_UNCOLLECTABLE

Выводить информацию о найденных недоступных объектах, которые не могут быть удалены. Эти объекты будут добавлены в список garbage.

DEBUG_INSTANCES

Если установлен флаг DEBUG_COLLECTABLE или DEBUG_UNCOLLECTABLE, выводить информацию о найденных экземплярах классов.

DEBUG_OBJECTS

Если установлен флаг DEBUG_COLLECTABLE или DEBUG_UNCOLLECTABLE, выводить информацию о найденных объектах, не являющихся экземплярами классов.

DEBUG_SAVEALL

При использовании этого флага все найденные недоступные объекты будут добавляться в garbage, в том числе и те, которые могут быть удалены.

DEBUG_LEAK

Флаги, необходимые для вывода информации, полезной при поиске утечек памяти (DEBUG_COLLECTABLE | DEBUG_UNCOLLECTABLE | DEBUG_INSTANCES | DEBUG_OBJECTS | DEBUG_SAVEALL).

15.3. atexit—выполнение действий при окончании работы программы

Доступен, начиная с версии 2.0.

Модуль atexit определяет единственную функцию, предназначенную для регистрации. Зарегистрированные с помощью нее функции будут автоматически вызваны при нормальном окончании работы программы. Функции не будут вызваны, если процесс программы был прерван с помощью некоторых сигналов, возникла фатальная внутренняя ошибка интерпретатора, а также при вызове функции os._exit().

Модуль предоставляет альтернативный интерфейс к функциональности, предоставляемой переменной sys.exitfunc. Таким образом, модуль может работать некорректно при использовании кода, который устанавливает sys.exitfunc напрямую. В частности, стандартные модули языка Python могут использовать atexit не предупреждая об этом. Во избежание конфликтов, авторам, использующим sys.exitfunc следует внести соответствующие изменения в программы.

register(func ...)

Регистрирует func как функцию, которая должна быть выполнена при завершении работы программы. Все остальные аргументы (позиционные и именованные) будут сохранены и использованы для вызова func.

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

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

try:
    _count = int(open("/tmp/counter").read())
except IOError:
    _count = 0

def incrcounter(n):
    global _count
    _count = _count + n

def savecounter():
    open("/tmp/counter", "w").write("%d" % _count)

import atexit
atexit.register(savecounter)

См. также реализацию модуля readline, демонстрирующую использование возможностей модуля atexit для чтения и записи файлов истории команд.

15.4. types — имена для всех встроенных типов

Этот модуль определяет имена для всех встроенных типов объектов, используемых интерпретатором (сами типы описаны в главе 11). Вполне безопасно использовать инструкцию ‘from types import *’ — модуль не определяет никаких имен, кроме тех, которые здесь перечислены. Все имена, которые будут добавлены в будущих версиях этого модуля, будут иметь окончание ‘Type’.

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

from types import *
def delete(list, item):
    if type(item) is IntType:
        del list[item]
    else:
        list.remove(item)

Модуль определяет следующие имена:

NoneType

Объект, имеющий тип None. Существует только один объект этого типа — None (пустой объект).

TypeType

Объект, имеющий тип type (тип) — тип объектов, возвращаемых встроенной функцией type(). Все объекты, определенные в этом модуле, являются объектами именно этого типа.

IntType

Объект, имеющий тип int (целое число, например, 1).

LongType

Объект, имеющий тип long int (длинное целое число, например, 1L).

FloatType

Объект, имеющий тип float (вещественное число, например, 1.0).

ComplexType

Объект, имеющий тип complex (комплексное число, например, 1.0j).

StringType

Объект, имеющий тип string (строка, например, ’Python’).

UnicodeType

Объект, имеющий тип unicode (строка Unicode, например, u’Python’).

TupleType

Объект, имеющий тип tuple (кортеж, например, ‘(1, 2, 3)’).

XRangeType

Объект, имеющий тип xrange. Объекты этого типа возвращаются встроенной функцией xrange().

BufferType

Объект, имеющий тип buffer (буфер, создается встроенной функцией buffer).

ListType

Объект, имеющий тип list (список, например, ‘[1, 2, 3]’).

DictType

DictionaryType

Два альтернативных имени для объекта, представляющего тип dictionary (словарь, например, ‘{'язык': 'Python', 'версия': '2.0'}’).

FunctionType

LambdaType

Два альтернативных имени для объекта, представляющего тип function (функция, определенная пользователем). Такой тип имеют объекты, определенные с помощью инструкции def или оператора lambda.

CodeType

Объект, имеющий тип code (объект кода, например, возвращаемый встроенной функцией compile()).

ClassType

Объект, имеющий тип class (класс). Объект-класс создается инструкцией class.

InstanceType

Объект, имеющий тип instance (экземпляр класса). Экземпляры создаются при применении операции вызова к объекту-классу.

MethodType

UnboundMethodType

Два альтернативных имени для объекта, представляющего тип method (метод, определенный пользователем).

BuiltinFunctionType

BuiltinMethodType

Два альтернативных имени для объекта, представляющего тип builtin_function_or_method (встроенная функция или метод, например, abs()).

ModuleType

Объект, имеющий тип module (модуль).

FileType

Объект, имеющий тип file (файловый объект, например, создаваемый встроенной функцией open()).

SliceType

Объект, имеющий тип slice (срез). Объекты этого типа создаются при использовании расширенной записи среза и встроенной функцией slice().

EllipsisType

Объект, имеющий тип ellipsis. Существует только один объект этого типа — Ellipsis (эллипсис), он указывает на использование троеточия в расширенной записи среза.

TracebackType

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

FrameType

Объект, имеющий тип frame (кадр стека). Объекты этого типа представляют окружение, в котором выполняется блок кода.

15.5. operator — операторы в виде функций

Модуль operator определяет набор функций, реализованных на языке C, соответствующих операторам языка Python. Обычно функции имеют такие же имена, как и специальные методы классов, предназначенных для выполнения соответствующих операций. Например, выражения ‘operator.add(x, y)’ и ‘x + y’ эквивалентны. Для удобства также определены имена без ‘__’ в начале и конце имени.

Модуль определяет следующие функции:

add(x, y)

__add__(x, y)

Возвращает x + y.

sub(x, y)

__sub__(x, y)

Возвращает x - y.

mul(x, y)

__mul__(x, y)

Возвращает x * y.

div(x, y)

__div__(x, y)

Возвращает x / y.

mod(x, y)

__mod__(x, y)

Возвращает x % y.

neg(x)

__neg__(x)

Возвращает -x.

pos(x, y)

__pos__(x, y)

Возвращает +x.

abs(x)

__abs__(x)

Возвращает абсолютное значение x (см. описание встроенной функции abs()).

inv(x)

__inv__(x)

invert(x)

__invert__(x)

Возвращает ~x. Имена invert() и __invert__() добавлены в версии 2.0.

lshift(x, y)

__lshift__(x, y)

Возвращает x << y.

and_(x, y)

__and__(x, y)

Возвращает x & y.

or_(x, y)

__or__(x, y)

Возвращает x | y.

xor(x, y)

__xor__(x, y)

Возвращает x ^ y.

not_(x)

__not__(x)

Возвращает not x.

truth(x)

Возвращает 1, если x является истиной, иначе возвращает 0.

concat(seq1, seq2)

__concat__(seq1, seq2)

Возвращает seq1 + seq2, где seq1 и seq2 должны быть последовательностями встроенного типа.

repeat(seq, n)

__repeat__(seq, n)

Возвращает seq * n, где seq должен быть последовательностью встроенного типа, а n — целым числом.

contains(x, y)

__contains__(x, y)

sequenceIncludes(x, y)

Возвращает результат проверки вхождения y in x. Обратите внимание на порядок следования операндов. Имя __contains__() определено, начиная с версии 2.0, имя sequenceIncludes() присутствует лишь для совместимости с предыдущими версиями.

countOf(x, y)

Возвращает число вхождений y в x. Эта функция никогда не использует метод count() экземпляров-последовательностей, а просто последовательно перебирает и сравнивает с y все элементы последовательности x.

indexOf(x, y)

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

getitem(x, y)

__getitem__(x, y)

Возвращает x[y].

setitem(x, y, z)

__setitem__(x, y, z)

Выполняет присваивание ‘x[y] = z’.

delitem(x, y)

__delitem__(x, y)

Эквивалентно инструкции ‘del x[y]’.

getslice(x, y, z)

__getslice__(x, y, z)

Возвращает x[y:z].

setslice(x, y, z, v)

__setslice__(x, y, z, v)

Выполняет присваивание ‘x[y:z] = v’.

delslice(x, y, z)

__delslice__(x, y, z)

Эквивалентно инструкции ‘del x[y:z]’.

isCallable(obj)

Возвращает 1, если объект obj поддерживает вызов, иначе возвращает 0. Эта функция существует для совместимости с предыдущими версиями — используйте вместо нее встроенную функцию callable().

isMappingType(obj)

Возвращает 1, если объект obj может быть отображением, то есть является словарем или экземпляром (произвольного) класса, иначе возвращает 0. Не существует надежного способа определить, поддерживает ли экземпляр класса все операции, характерные для отображения.

isNumberType(obj)

Возвращает 1, если obj может быть объектом числового типа, то есть является объектом встроенного числового типа или экземпляром (произвольного) класса, иначе возвращает 0. Не существует надежного способа определить, поддерживает ли экземпляр класса все операции, характерные для чисел.

isSequenceType(obj)

Возвращает 1, если obj может быть объектом числового типа, то есть является последовательностью одного из встроенных типов или экземпляром (произвольного) класса, иначе возвращает 0. Не существует надежного способа определить, поддерживает ли экземпляр класса все операции, характерные для последовательностей.

Чаще всего определенные здесь функции используются в качестве первого аргумента встроенных функций map() и reduce(). Например, самый быстрый способ подсчитать сумму элементов последовательности seq — вычислить выражение ‘reduce(operator.add, seq)’.

Для удобства ниже приведена таблица соответствия операторов функциям, определенным в модуле operator.

15.6. traceback — модуль для работы с объектами traceback

Этот модуль предоставляет средства для извлечения, форматирования и вывода информации, которую несут объекты traceback (см. раздел 11.9.3). Он позволяет полностью имитировать поведение интерпретатора и может быть полезен для вывода сообщений об ошибках без потери контроля над выполнением.

Модуль traceback определяет следующие функции:

print_tb(traceback [, limit [, file]])

Выводит до limit уровней информации из объекта traceback, начиная с места перехвата исключения, в сторону места, где оно было сгенерировано (именно так описывают путь вложенные друг в друга объекты traceback). Если аргумент limit опущен или равен None, выводится информация для sys.tracebacklimit (10000, если переменная sys.tracebacklimit не определена) вложенных объектов traceback. Вся информация выводится в file (должен быть объектом с методом write()) или стандартный поток вывода, если аргумент file не задан.

print_exception(type, value, traceback [, limit [, file]])

Работает аналогично функции print_tb(), но помимо вывода информации из объекта traceback выполняет следующие действия:

• Если аргумент traceback не равен None, выводит заголовок ‘Traceback (most recent call last):’.
• Выводит информацию о возникшем исключении (type и value; должны быть объектами, описывающими тип и значение исключения).
• Если type is SyntaxError и value имеет соответствующий формат, выводит строку, в которой возникла синтаксическая ошибка с символом ‘^’, указывающим на место обнаружения ошибки интерпретатором.

Именно таким образом выводятся сообщения об ошибке самим интерпретатором.

print_exc([limit [, file]])

Вызов этой функции эквивалентен вызову ‘print_exception(*(sys.exc_info() + (limit, file)))’.

print_last([limit [, file]])

Вызов этой функции эквивалентен вызову ‘print_exception(sys.last_type, sys.last_value, sys.last_traceback, limit, file)’.

print_stack([frame [, limit [, file]]])

Отслеживает и выводит путь по стеку от кадра стека frame до корня программы (модуля __main__). Если аргумент frame опущен или равен None, считается равным кадру стека блока, из которого функция print_stack() была вызвана. Необязательные аргументы limit и file имеют такое же значение, как и в функции print_exception().

extract_tb(traceback [, limit])

Возвращает информацию о пути, содержащуюся в объекте traceback, в виде списка (каждый элемент представляет кадр стека, соответствующий очередному вложенному объекту traceback) кортежей ‘(filename, line_number, function_name, text)’, где filename — имя файла, line_number — номер строки в файле, function_name — имя функции и text — строка исходного текста с обрезанными символами пропуска (whitespace) в начале и конце или None. Необязательный аргумент limit имеет такое же значение, как и в функции print_exception().

extract_stack([frame [, limit]])

Возвращает информацию, описывающую путь от указанного или текущего кадра стека до корня программы. Возвращаемое значение имеет такой же формат, как и значение, возвращаемое функцией extract_tb(). Необязательные аргументы frame и limit имеют такое же значение, как и в функции print_stack().

format_list(list)

Возвращает список готовых к выводу (например, методом writelines файлового объекта) строк, полученных форматированием списка кортежей list — результата функции extract_tb() или extract_stack(). Каждая строка возвращаемого списка соответствует элементу с таким же индексом аргумента. Каждая строка заканчивается символом перехода на новую строку и может содержать несколько символов перехода на новую строку, если последний элемент соответствующего кортежа (строка исходного текста) не равен None.

format_exception_only(type, value)

Возвращает список строк, подготовленный для вывода (например, методом writelines файлового объекта) информации об исключении. Каждая строка в возвращаемом списке заканчивается символом перехода на новую строку. type и value должны быть объектами, представляющими тип и значение исключения. Обычно список содержит только одну строку. Однако для исключений SyntaxError список будет состоять из нескольких строк, содержащих, в том числе, фрагмент исходного текста программы и информацию о месте обнаружения синтаксической ошибки. Строка, описывающая исключение, всегда идет в списке последней.

format_exception(type, value, traceback [, limit])

Возвращает список строк, подготовленный для вывода (например, методом writelines файлового объекта) информации об исключении и информации, представляемой объектом traceback. Аргументы имеют такое же значение, как и соответствующие аргументы функции print_exception(). Каждая строка в возвращаемом списке заканчивается символом перехода на новую строку и может содержать несколько символов перехода на новую строку. Вывод этих строк (например, с помощью метода writelines файлового объекта) дает такой же результат, как и вызов функции print_exception().

format_tb(traceback [, limit])

Вызов этой функции эквивалентен вызову ‘format_list(extract_tb(traceback, limit))’.

format_stack(frame [, limit])

Вызов этой функции эквивалентен вызову ‘format_list(extract_stack(frame, limit))’.

tb_lineno(traceback)

Возвращает номер текущей строки, представленной объектом traceback. Обычно возвращаемое значение равно traceback.tb_lineno. Однако при включенной оптимизации атрибут tb_lineno не обновляется корректно, в то время как функция tb_lineno() всегда возвращает правильное значение.

Следующий пример реализует простейший интерактивный интерпретатор, аналогичный стандартному:

import sys, traceback

def run_user_code(envdir):
    source = raw_input(">>> ")
    try:
        exec source in envdir
    except:
        print "Исключение в пользовательском коде:"
        print '-'*60
        traceback.print_exc(file=sys.stdout)
        print '-'*60
        envdir = {}

while 1:
    run_user_code(envdir)

Для создания более сложных интерактивных интерпретаторов лучше воспользоваться классами, определенными в модуле code.

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

15.7. imp — доступ к операциям, производимым инструкцией import

Этот модуль предоставляет интерфейс к операциям, используемым для реализации инструкции import. Он определяет следующие функции:

get_magic()

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

get_suffixes()

Возвращает список кортежей, каждый из которых имеет вид ‘(suffix, mode, type)’ и описывает определенный тип модулей: suffix — строка, добавляемая к имени модуля для образования имени файла; mode — строка режима, которую необходимо передать встроенной функции open() для того, чтобы открыть файл на чтение (’r’ для текстовых файлов и ’rb’ для двоичных); type — тип файла, может иметь значение PY_SOURCE, PY_COMPILED или C_EXTENSION (см. ниже).

find_module(name [, path])

Пытается найти модуль с именем name в путях path. Производится поиск файла с любым из суффиксов, возвращаемых функцией get_suffixes(), по очереди в каждом из каталогов в списке path. Неверные имена каталогов молча игнорируются, но все элементы списка должны быть строками. Если аргумент path опущен или равен None, поиск производится сначала среди встроенных (C_BUILTIN) и вложенных (PY_FROZEN) модулей, среди ресурсов (PY_RESOURCE) в операционных системах Macintosh или файлов, указанных в системном реестре Windows, затем в каталогах, перечисленных в sys.path.

В случае успеха функция возвращает кортеж вида ‘(file, pathname, description)’, где file — файл, открытый для чтения, с указателем, установленным на начало, pathname — полное имя файла модуля и description — один из кортежей в списке get_suffixes(), описывающий тип модуля. Если модуль не находится в файле, то file равен None, pathname — имени модуля, а description содержит пустые строки (суффикс и режим). Если модуль не найден, генерируется исключение ImportError. Другие исключения указывают на проблемы с аргументами или окружением.

Эта функция не обрабатывает иерархические имена модулей. Для того, чтобы найти P.M, то есть модуль M пакета P, найдите и загрузите модуль P, затем используйте функцию find_module() с аргументом path, равным P.__path__.

load_module(name, file, filename, description)

Загружает модуль. Если модуль до этого уже был импортирован, вызов функции load_module() эквивалентен вызову встроенной функции reload(). Аргумент name является полным именем модуля (то есть включает имя пакета). Аргументы file и filename — файловый объект, открытый для чтения, и имя соответствующего файла (None и имя модуля, если модуль загружается не из файла). Аргумент description должен быть кортежем, описывающим тип модуля. Все необходимые аргументы, кроме имени модуля, возвращаются функцией find_module(). Если модуль успешно загружен, функция возвращает объект-модуль. В противном случае генерируется исключение (обычно ImportError). Заметим, что после загрузки модуля файл file (если он не равен None) необходимо закрыть, даже если было сгенерировано исключение. Лучше всего это делать в ветви finally инструкции try.

new_module(name)

Возвращает новый пустой объект-модуль с именем name. Этот объект не добавляется в список sys.modules.

Модуль определяет следующие целочисленные константы, описывающие тип модуля:

PY_SOURCE

Файл с исходным текстом на языке Python.

PY_COMPILED

Байт-компилированный файл.

C_EXTENSION

Динамически загружаемая библиотека.

PY_RESOURCE

Ресурс в операционной системе Macintosh.

PKG_DIRECTORY

Каталог пакета.

C_BUILTIN

Встроенный модуль.

PY_FROZEN

Вложенный модуль (модуль на языке Python, зашитый в интерпретатор).

Для совместимости с ранними версиями интерпретатора модуль также определяет несколько устаревших констант и функций. Хорошие примеры использования описанных здесь возможностей Вы найдете в стандартных модулях knee (этот модуль присутствует только в качестве примера — не следует считать его стандартным интерфейсом) и rexec.

15.8. pprint — представление и вывод данных в более привлекательном виде

Этот модуль предоставляет возможность получить форматированное представление произвольных объектов языка Python. Аналогично встроенной функции repr(), возвращаемый результат обычно можно использовать в качестве аргумента встроенной функции eval(). Если длина представления вложенных объектов больше разрешенного значения, представление каждого объекта будет расположено на отдельной строке.

Модуль определяет один класс:

PrettyPrinter([keyword_list])

Этот конструктор воспринимает несколько именованных аргументов (keyword_list). Поток вывода может быть установлен с помощью аргумента с именем stream (должен быть объектом с методом write()). Если поток вывода не задан, используется sys.stdout. Аргументы с именами indent, depth и width определяют формат представления. indent определяет отступ (количество пробелов) каждого последующего уровня вложенных объектов, по умолчанию равен 1. depth определяет максимальный уровень вложенных объектов, которые будут представлены — представление объектов на следующем уровне заменяется на ‘...’. Если аргумент с таким именем не задан или его значение ложно, ограничений на количество уровней нет. Длина отдельных строк в представлении будет ограничена значением аргумента с именем width (по умолчанию 80 символов).

>>> import pprint, sys
>>> stuff = sys.path[:]
>>> stuff.insert(0, stuff[:])
>>> pp = pprint.PrettyPrinter(indent=4)
>>> pp.pprint(stuff)
[   [   '',
        '/usr/local/lib/python1.5',
        '/usr/local/lib/python1.5/test',
        '/usr/local/lib/python1.5/sunos5',
        '/usr/local/lib/python1.5/sharedmodules',
        '/usr/local/lib/python1.5/tkinter'],
    '',
    '/usr/local/lib/python1.5',
    '/usr/local/lib/python1.5/test',
    '/usr/local/lib/python1.5/sunos5',
    '/usr/local/lib/python1.5/sharedmodules',
    '/usr/local/lib/python1.5/tkinter']
>>>
>>> import parser
>>> suite = parser.suite(open('pprint.py').read())
>>> tup = parser.ast2tuple(suite)[1][1][1]
>>> pp = pprint.PrettyPrinter(depth=6)
>>> pp.pprint(tup)
(266, (267, (307, (287, (288, (...))))))

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

pformat(object)

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

pprint(object [, stream])

Выводит форматированное представление объекта object (с символом новой строки на конце) в файл stream. Если аргумент stream не задан, используется sys.stdout. Эта функция может быть использована в интерактивном режиме для контроля значений.

>>> stuff = sys.path[:]
>>> stuff.insert(0, stuff)
>>> pprint.pprint(stuff)
[<Recursion on list with id=869440>,
 '',
 '/usr/local/lib/python1.5',
 '/usr/local/lib/python1.5/test',
 '/usr/local/lib/python1.5/sunos5',
 '/usr/local/lib/python1.5/sharedmodules',
 '/usr/local/lib/python1.5/tkinter']

isreadable(object)

Возвращает 1, если представление объекта object может быть использовано для его восстановления с помощью функции eval(), иначе возвращает 0. Всегда возвращает 0 для рекурсивных объектов.

>>> pprint.isreadable(stuff)
0

isrecursive(object)

Возвращает 1, если объект содержит рекурсивные ссылки, иначе возвращает 0.

saferepr(object)

Выводит неформатированное представление объекта object с рекурсивными ссылками, представленными в виде ‘<Recursion on type with id=id>’, где type и id — тип и идентификатор объекта.

Экземпляры класса PrettyPrinter имеют следующие методы, принимающие во внимание значения именованных аргументов, переданных конструктору:

pformat(object)

Возвращает стоку с форматированным представлением объекта object.

pprint(object)

Выводит форматированное представление объекта object (с символом новой строки на конце) в файл, указанный при конструировании экземпляра.

isreadable(object)

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

isrecursive(object)

Возвращает 1, если объект содержит рекурсивные ссылки, иначе возвращает 0.

15.9. repr — альтернативная реализация функции repr()

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

Модуль определяет следующие имена:

Repr()

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

aRepr

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

repr(object)

Ссылается на метод repr() экземпляра aRepr. Возвращает строковое представление, аналогичное возвращаемому встроенной функцией repr(), но с ограничениями по размеру.

Экземпляры класса Repr предоставляют несколько атрибутов данных, которые могут быть использованы для установки ограничений размеров представлений объектов различных типов, и методы, возвращающие представления объектов этих типов:

maxlevel

Максимальный уровень вложенности объектов, включаемых в представление. По умолчанию равен 6.

maxdict

maxlist

maxtuple

Максимальное число элементов, включаемых в представление для словарей, списков и кортежей соответственно. По умолчанию включается представление четырех элементов словарей и шести элементов списков и кортежей.

maxlong

Максимальное число символов в представлении длинных целых чисел. Цифры опускаются в середине. По умолчанию равно 40.

maxstring

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

maxother

Максимальное число символов в представлении других типов, по умолчанию равно 20.

repr(object)

Возвращает строковое представление, аналогичное возвращаемому встроенной функцией repr(), но с указанными ограничениями по размеру.

repr1(object, level)

Этот метод вызывается рекурсивно методом repr(). Использует тип объекта object для того, чтобы определить, какой метод вызвать для получения представления.

repr_typename(object, level)

Методы, предназначенные для получения представления объектов определенного типа. Имя метода конструируется из имени типа, в котором пробелы заменены символами подчеркивания, путем добавления приставки ’repr_’. Методы, предназначенные для получения представления объектов определенного типа, вызываются методом repr1() и сами должны вызывать repr1() для вложенных объектов с аргументом level, меньше на единицу.

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

import repr
import sys

class MyRepr(repr.Repr):
    def repr_file(self, obj, level):
        if obj.name in ['<stdin>',
                        '<stdout>',
                        '<stderr>']:
            return obj.name
        else:
            return ‘obj‘

aRepr = MyRepr()
print aRepr.repr(sys.stdin) # выводит '<stdin>'

16. Работа со строками

Модули, описанные в этой главе, предоставляют широкий диапазон операций над строками.

16.1. string — наиболее распространенные операции над строками

Модуль string определяет несколько строковых констант, содержащих символы, которые относятся к определенному классу. Их значения зависят от текущих национальных установок (см. описание модуля locale).

digits

Десятичные цифры (’0123456789’).

hexdigits

Символы, используемые для записи шестнадцатеричного представления (’0123456789abcdefABCDEF’).

letters

Объединение строк lowercase и uppercase, описанных ниже.

lowercase

Строка, содержащая все строчные буквы (буквы в нижнем регистре).

octdigits

Символы, используемые для записи восьмеричного представления (’01234567’).

punctuation

Строка символов, которые считаются знаками препинания.

printable

Строка символов, которые считаются печатными. Является комбинацией констант digits, letters, punctuation и whitespace.

uppercase

Строка, содержащая все прописные буквы (буквы в верхнем регистре).

whitespace

Строка, содержащая все символы пропуска (whitespace). Обычно это ’\t\n\v\f\r ’

Модуль также определяет следующие функции:

maketrans(from, to)

Возвращает строку, которая может быть использована в методе translate() строк для того, чтобы произвести замену символов в строке from на символы, находящиеся в той же позиции в строке to. Строки from и to должны иметь одинаковую длину. Не используйте в качестве аргументов строки, производные от констант lowercase и uppercase — они могут иметь разную длину.

zfill(s, width)

Дополняет слева нулями строку s, представляющую число, до тех пор, пока длина строки не будет равной width. Строки, начинающиеся знаком, обрабатываются корректно.

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

atof(s)

Возвращает float(s).

atoi(s [, base])

Возвращает int(s, base).

atol(s [, base])

Возвращает long(s, base).

capitalize(word)

Возвращает word.capitalize().

capwords(s [, sep])

Разбивает строку на слова, используя в качестве разделителя sep, делает первую букву каждого слова прописной и возвращает объединение (через разделитель sep) полученных слов. Обратите внимание, что серии из символов пропуска при этом в начале и конце строки удаляются, а в середине строки заменяются одним пробелом. Метод строк title() работает аналогично, но сохраняет исходные символы пропуска.

expandtabs(s [, tabsize])

Возвращает s.expandtabs(tabsize).

find(s, sub [, start [, end]])

Возвращает s.find(sub, start, end).

rfind(s, sub [, start [, end]])

Возвращает s.rfind(sub, start, end).

index(s, sub [, start [, end]])

Возвращает s.index(sub, start, end).

rindex(s, sub [, start [, end]])

Возвращает s.rindex(sub, start, end).

count(s, sub [, start [, end]])

Возвращает s.count(sub, start, end).

lower(s)

Возвращает s.lower().

split(s [, sep [, maxsplit]])

splitfields(s [, sep [, maxsplit]])

Возвращает s.split(sep, maxsplit).

join(words [, sep])

joinfields(words [, sep])

Возвращает sep.join(words).

lstrip(s)

Возвращает s.lstrip().

rstrip(s)

Возвращает s.rstrip().

strip(s)

Возвращает s.strip().

swapcase(s)

Возвращает s.swapcase().

translate(s, table [, deletechars])

Возвращает s.translate(table, deletechars), но работает только с обычными строками.

upper(s)

Возвращает s.upper().

ljust(s, width)

Возвращает s.ljust(width).

rjust(s, width)

Возвращает s.rjust(width).

center(s, width)

Возвращает s.center(width).

replace(s, old, new [, maxsplit])

Возвращает s.replace(old, new, maxsplit).

16.2. re — операции с регулярными выражениями

Этот модуль предоставляет операции с регулярными выражениями, аналогичные тем, которые используются в языке Perl. Обрабатываемые строки (обычные и строки Unicode) могут содержать любые символы, в том числе NUL.

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

16.2.1. Синтаксис регулярных выражений

Регулярное выражение (regular expression) — это шаблон, который определяет множество строк, ему удовлетворяющих. Функции, определенные в модуле re позволяют определить, удовлетворяет ли определенная строка данному регулярному выражению (или, что то же самое, регулярное выражение строке).

Объединение регулярных выражений также является регулярным выражением. Если строка a удовлетворяет регулярному выражению A и строка b удовлетворяет регулярному выражению B, то a + b удовлетворяет A + B. Таким образом, сложные регулярные выражения могут быть сконструированы из примитивных выражений, описанных ниже.

Регулярные выражения могут содержать как обычные символы, так и специальные управляющие последовательности. Большинство обычных символов, таких как ‘A’, ‘a’ или ‘0’, являются простейшими регулярными выражениями, удовлетворяющими самим себе. Вы можете объединять обычные символы, так выражению ’list’ удовлетворяет строка ’list’.

Ниже приведены символы и последовательности, которые имеют специальное значение (atom — “неделимое” выражение, то есть обычный символ или последовательность, обозначающая класс или группу; expr — произвольное выражение):

16.2.2. Сопоставление в сравнении с поиском

Модуль re предоставляет две примитивные операции с регулярными выражениями: сопоставление (match) и поиск (search). Если для Вас привычна семантика использования регулярных выражений в языке Perl, поиск — это то, что Вам нужно (см. описания функции search() и одноименного метода объектов, представляющих компилированные регулярные выражения).

Сопоставление дает положительный результат, только если шаблон удовлетворяет строке с самого ее начала или заданной позиции:

>>> import re
>>> from operator import truth
>>> truth(re.match('a', 'ba'))
0
>>> truth(re.search('a', 'ba'))
1

При поиске специальный символ ’^’ в многострочном режиме (флаг MULTILINE) помимо начала строки удовлетворяет позиции сразу после символа перехода на новую строку (’\n’), в то время как при сопоставлении ’^’ независимо от режима удовлетворяет только началу строки:

>>> import re
>>> from operator import truth
>>> re_obj = re.compile('.*^a', re.M)
>>> truth(re_obj.match('\na'))
0
>>> truth(re_obj.search('\na'))
1

16.2.3. Функции и константы, определенные в модуле

compile(pattern [, flags])

Компилирует регулярное выражение в строке pattern и возвращает представляющий его объект. Поведением регулярного выражения можно управлять с помощью аргумента flags. Значение аргумента flags может быть составлено из описанных ниже констант с помощью оператора |.

Последовательность инструкций

prog = re.compile(pat)
result = prog.match(str)

эквивалентна инструкции

result = re.match(pat, str)

Однако использование compile() более эффективно, если регулярное выражение предполагается использовать неоднократно.

IGNORECASE

I

Используется, если необходимо выполнить сопоставление или поиск без учета регистра букв. Использование этого флага совместно с флагом LOCALE в версиях интерпретатора 1.5.2 и более ранних бессмысленно, а иногда (если используемая кодировка не является надмножеством ASCII) и опасно.

LOCALE

L

Делает классы r'\w', r'\W', r'\b' и r'\B' зависящими от текущих национальных установок (используются национальные установки на момент выполнения операции сопоставления или поиска, а не компиляции регулярного выражения).

MULTILINE

M

Устанавливает многострочный режим, в котором специальные символы ’^’ (только при выполнении поиска) и ’$’ (при выполнении как сопоставления, так и поиска) удовлетворяют не только началу и концу строки, но и сразу после и перед символом ’\n’ соответственно.

DOTALL

S

Делает специальный символ ’.’ удовлетворяющим любому символу. Без этого флага ’.’ удовлетворяет любому символу, кроме ’\n’.

VERBOSE

X

Использование этого флага позволяет писать регулярные выражения в более элегантном виде:

• Символы пропуска (whitespace) в строке-шаблоне игнорируются, за исключением определений множеств и записанных с использованием обратной косой черты.
• Все символы до конца строки после ‘#’, за исключением случаев, когда ‘#’ содержится в определении множества или записан с использованием обратной косой черты (r’\#’), считаются комментарием и игнорируются.

TEMPLATE

T

Устанавливает “режим шаблона”: поиск производится без отката назад в случае неудачи во время перебора. Эта опция является экспериментальной (ее поддержка может быть удалена в будущих версиях); доступна, начиная с версии 1.6.

UNICODE

U

Делает классы r'\w', r'\W', r'\b' и r'\B' интернациональными (в соответствии с классами символов в Unicode). Опция доступна, начиная с версии 1.6.

Приведенные ниже функции воспринимают в качестве аргумента pattern как строку, так и объект, представляющие компилированное регулярное выражение. Если необходимо установить флаги, используйте компилированное регулярное выражение или специальную последовательность вида ’(?flags)’ в строке.

search(pattern, string [, flags])

Ищет в строке string позицию, в которой она удовлетворяет регулярному выражению pattern и возвращает объект, представляющий результат сопоставления. Если такая позиция не найдена, возвращает None.

match(pattern, string [, flags])

Если 0 или более символов в начале строки string удовлетворяют регулярному выражению pattern, возвращает объект, представляющий результат сопоставления, в противном случае возвращает None.

split(pattern, string [, maxsplit])

Разбивает строку string в местах, удовлетворяющих регулярному выражению pattern и возвращает результат в виде списка. Если pattern содержит группирующие скобки, то текст групп также включается в возвращаемый список. Если задан и не равен 0 аргумент maxsplit, выполняется не более maxsplit расщеплений и остаток строки помещается в конец списка. Например:

>>> re.split('\W+', 'Words, words, words.')
['Words', 'words', 'words', '']
>>> re.split('(\W+)', 'Words, words, words.')
['Words', ', ', 'words', ', ', 'words', '.', '']
>>> re.split('\W+', 'Words, words, words.', 1)
['Words', 'words, words.']

findall(pattern, string)

Возвращает список непересекающихся фрагментов строки string, удовлетворяющих регулярному выражению pattern. Если pattern содержит группы, элементами списка будут строки, удовлетворяющие группе, или кортеж строк, если групп в шаблоне несколько. Результаты сопоставления с нулевой длиной также включаются в результат.

sub(pattern, repl, string [, count])

Возвращает строку, полученную заменой непересекающихся фрагментов строки string, удовлетворяющих регулярному выражению pattern, на repl. Если не найдено ни одного такого фрагмента, строка возвращается неизменной. repl может быть строкой или функцией. Функция должна воспринимать один аргумент — объект, представляющий результат сопоставления, и возвращать строку для замены. Например:

>>> def dashrepl(matchobj):
....    if matchobj.group(0) == '-': return ' '
....    else: return '-'
>>> re.sub('-{1,2}', dashrepl, 'pro----gram-files')
'pro--gram files'

Если задан и не равен 0 аргумент count, он определяет максимальное число производимых замен. По умолчанию число замен не ограничено.

Замена удовлетворяющего регулярному выражению фрагмента нулевой длины производится только в том случае, если он не является смежным с предыдущим таким фрагментом. Таким образом, 'sub('x*', '-', 'abc')' возвращает '-a-b-c-'.

Если repl является строкой, то обрабатываются содержащиеся в ней специальные последовательности, представляющие символы или ссылки на группы. Например, r'\n' заменяется символом новой строки, r'\6' (или r'\g<6>')—фрагментом, удовлетворяющим шестой группе, и r'\g<id>' — фрагментом, удовлетворяющим группе с именем id.

subn(pattern, repl, string [, count])

Выполняет те же самые операции, что и функция sub(), но возвращает кортеж, состоящий из новой строки и числа произведенных замен.

escape(string)

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

error

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

16.2.4. Объекты, представляющие регулярные выражения

Компилированные объекты регулярных выражений имеют следующие методы и атрибуты данных:

search(string [, pos [, endpos]])

Ищет в строке string позицию, в которой она удовлетворяет регулярному выражению и возвращает объект, представляющий результат сопоставления. Если такая позиция не найдена, возвращает None. Необязательные аргументы pos и endpos имеют такое же значение, как и для метода match(), описанного ниже.

match(string [, pos [, endpos]])

Если 0 или более символов в начале строки string удовлетворяют регулярному выражению, возвращает объект, представляющий результат сопоставления, в противном случае возвращает None.

Необязательный аргумент pos (по умолчанию равен 0) указывает позицию в строке, начиная с которой необходимо выполнять сопоставление. Использование этого аргумента не эквивалентно вызову метода для string[pos:], так как в первом случае специальные последовательности ’^’ и r'\A' удовлетворяют началу реальной строки. Аналогично аргумент endpos указывает позицию в строке, до которой будет выполняться сопоставление.

split(string [, maxsplit])

Вызов этого метода эквивалентен вызову функции split() с объектом, представляющим регулярное выражение, в качестве первого аргумента.

findall(string)

Вызов этого метода эквивалентен вызову функции findall() с объектом, представляющим регулярное выражение, в качестве первого аргумента.

sub(repl, string [, count])

Вызов этого метода эквивалентен вызову функции sub() с объектом, представляющим регулярное выражение, в качестве первого аргумента.

subn(repl, string [, count])

Вызов этого метода эквивалентен вызову функции subn() с объектом, представляющим регулярное выражение, в качестве первого аргумента.

flags

Значение аргумента flags, переданного функции compile() при компиляции объекта. Этот атрибут не отражает флаги, установленные с помощью специальных последовательностей в самом регулярном выражении.

groupindex

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

pattern

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

16.2.5. Объекты, представляющие результат сопоставления

Объекты, возвращаемые методами search() и match() компилированных регулярных выражений, а также одноименными функциями, имеют следующие методы и атрибуты данных:

group([group1 [, group2 ...]])

Возвращает один или более фрагментов, которые при выполнении операции сопоставления удовлетворили определениям одной или нескольких групп. Числа groupN указывают на группы с номерами от 1 до 99 или на фрагмент, удовлетворяющий всему регулярному выражению (группа с номером 0). groupN может быть также именем группы, заданной в регулярном выражении с помощью синтаксиса ’?P<name>expr’. Если шаблон не содержит группы с указанным номером (именем), генерируется исключение IndexError.

С одним аргументом метод group() возвращает одну строку, с несколькими аргументами — кортеж из строк (по строке для каждого указанного номера группы), без аргументов — строку, удовлетворяющую всему регулярному выражению (как если бы метод был вызван с одним аргументом, равным 0). Если регулярное выражение какой-либо группы не было удовлетворено фрагментом строки, возвращаемое значение для этой группы будет None вместо строки. Если же оно было удовлетворено несколько раз, в возвращаемое значение включается только последний результат.

Приведем небольшой пример. После выполнения инструкции

m = re.match(r"(?P<int>\d+)\.(\d*)", '3.14')

m.group(1) и m.group('int') возвращают ’3’, а m.group(2) возвращает ’14’.

groups([default])

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

groupdict([default])

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

start([group])

end([group])

Возвращает позиции начала и конца фрагмента в исходной строке, который удовлетворяет группе с номером (или именем) group (по умолчанию используется 0, что соответствует всему регулярному выражению). Если группа не удовлетворяют никакому фрагменту, возвращают -1. Фрагмент, удовлетворяющий группе g, то есть m.group(g), может быть также получен как m.string[m.start(g):m.end(g)].

span([group])

Возвращает кортеж ‘(m.start(group), m.end(group))’, где m — объект, к которому применяется метод. Обратите внимание, что, если группа не удовлетворяют никакому фрагменту, метод возвращает ‘(-1, -1)’.

expand(template)

В шаблоне template заменяет специальные последовательности, ссылающиеся на символы (например, ‘\n’) и удовлетворяющие фрагменты объекта (‘\1’, ‘\g<1>’, ‘\g<name>’) аналогично методу sub() и возвращает результат. Этот метод доступен, начиная с версии 2.0.

pos

Значение аргумента pos, переданного функции (методу) search() или match().

endpos

Значение аргумента endpos, переданного функции (методу) search() или match().

lastgroup

Имя последней удовлетворенной группы (наиболее охватывающей) или None, если эта группа не имеет имени или не была удовлетворена ни одна группа. Например:

>>> import re
>>> re.match('(?P<g1>a)(?P<g2>b(?P<g3>c))',
...          'abc').lastgroup
'g2'

lastindex

Номер последней удовлетворенной группы (наиболее охватывающей) или None, если не была удовлетворена ни одна группа. Например:

>>> import re
>>> re.match('(?P<g1>a)(?P<g2>b(?P<g3>c))',
...          'abc').lastindex
2

re

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

string

Значение аргумента string, переданного функции (методу) search() или match().

16.3. StringIO и cStringIO — работа со строками как с файловыми объектами

Модуль StringIO реализует класс StringIO, экземпляры которого ведут себя аналогично файловым объектам, но работает не с реальным файлом, а со строковым буфером. Модуль cStringIO, реализованный на C (и поэтому более быстрый), предоставляет аналогичный интерфейс, за исключением того, что вместо класса он определяет функцию-конструктор StringIO(). Объекты, возвращаемые этой функцией, ведут себя аналогично экземплярам класса StringIO.

Экземпляры класса StringIO поддерживают как обычные строки, так и строки Unicode. Однако следует быть осторожным при использовании одновременно обоих типов — если обычная строка содержит символы с установленным восьмым битом, методы write() и close() могут сгенерировать исключение UnicodeError. Объекты, созданные конструктором cStringIO.StringIO() поддерживают только обычные строки: строки Unicode, передаваемые методу write(), автоматически преобразуются и, если это невозможно, генерируется исключение UnicodeError.

StringIO([string])

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

Конструктор StringIO(), определенный в модуле cStringIO возвращает объекты разного типа в зависимости от наличия аргумента. В случае, если конструктор вызван с аргументом (должен быть обычной строкой, иначе будет сгенерировано исключение ValueError), Вы можете только читать информацию из созданного строкового буфера. При вызове без аргументов возвращаемый объект допускает как чтение, так и запись.

InputType (a iiaoea cStringIO)

Тип объекта, созданного вызовом функции cStringIO.StringIO() со строкой в качестве аргумента.

OutputType (в модуле cStringIO)

Тип объекта, созданного вызовом функции cStringIO.StringIO() без аргументов.

Объекты, возвращаемые конструктором StringIO() поддерживают операции, характерные для файловых объектов, а также имеют дополнительный метод:

getvalue()

Возвращает содержимое буфера в виде строки. Этот метод может быть вызван в любое время, до того как буфер был закрыт с помощью метода close().

16.4. codecs — регистрация кодеров и работа с ними

Доступен, начиная с версии 1.6.

Этот модуль определяет базовые классы для кодеров и предоставляет доступ к внутреннему реестру кодеров.

register(search_function)

Регистрирует search_function как функцию для поиска кодеров. Функция search_function вызывается с одним аргументом — именем кодировки, записанной строчными буквами, и должна возвращать кортеж объектов, поддерживающих вызов, ‘(encoder, decoder, stream_reader, stream_writer)’. encoder и decoder должны иметь интерфейс, аналогичный методам encode() и decode() экземпляров класса Codec, описанного ниже. stream_reader и stream_writer должны быть конструкторами, возвращающими объекты аналогичные экземплярам классов StreamReader и StreamWriter соответственно. Если search_function не может найти объекты для данной кодировки, она должна вернуть None.

lookup(encoding)

Ищет в реестре кодеров средства работы с кодировкой encoding и возвращает кортеж объектов ‘(encoder, decoder, stream_reader, stream_writer)’, описанный выше. Если объекты для данной кодировки не найдены, генерируется исключение LookupError.

Для упрощения работы с файлами и другими потоками, содержащими данные в определенной кодировке, модуль определяет следующие функции:

open(filename [, mode [, encoding [, errors [, buffering]]]])

Открывает файл с именем filename в кодировке encoding и возвращает файловый объект (экземпляр класса StreamReaderWriter, описанного ниже), обеспечивающий прозрачное кодирование/декодирование данных при записи/чтении. Аргумент mode указывает режим, в котором открывается файл (по умолчанию используется ’rb’). Во избежание потери данных файл всегда открывается в двоичном режиме. Аргумент errors определяет поведение при ошибках и может иметь значения ’strict’ (в случае возникновения ошибки генерируется исключение ValueError или производного от него класса; используется по умолчанию), ’ignore’ (ошибки игнорируются) или ’replace’ (используется подходящий символ замены, обычно ’\uFFFD’). Аргумент buffering имеет такое же значение, как и для встроенной функции open().

EncodedFile(file, input [, output, [errors]])

Возвращает файловый объект (экземпляр класса StreamRecoder, описанного ниже), обеспечивающий прозрачное перекодирование при работе с потоком file (файловый объект). Данные в файле хранятся в кодировке output, в то время как строки передаваемые методам write() и writelines() и возвращаемые методами read(), readline() и readlines() содержат данные в кодировке input. В качестве промежуточной кодировки обычно используется Unicode. Если кодировка output не задана, она считается равной input. Аргумент errors имеет такое же значение, как и для функции open().

Модуль определяет следующие классы, которые могут быть использованы в качестве базовых:

Codec()

Базовый класс для кодеров/декодеров. Производные от него классы должны реализовать следующие методы:

encode(input [, errors])

Должен возвращать кортеж из строки, полученной при кодировании input, и количества обработанных символов.

decode(input [, errors])

Должен возвращать кортеж из строки, полученной при раскодировании input, и количества обработанных символов.

StreamWriter(stream [, errors])

Базовый класс для файловых объектов, обеспечивающих прозрачное кодирование данных при записи его в поток stream. Этот класс является производным от класса Codec и использует для кодирования свой метод encode(), который должен быть переопределен в производном классе.

StreamReader(stream [, errors])

Базовый класс для файловых объектов, обеспечивающих прозрачное декодирование данных при чтении их из потока stream. Этот класс является производным от класса Codec и использует для декодирования свой метод decode(), который должен быть переопределен в производном классе.

Для упрощения реализации методов encode() и decode() классов, производных от Codec, могут быть полезны следующие функции:

charmap_encode(input, errors, encoding_map)

Кодирует строку input, используя отображение кодов символов encoding_map. Возвращает результат в том виде, в котором должен возвращать метод encode().

charmap_decode(input, errors, encoding_map)

Декодирует строку input, используя отображение кодов символов encoding_map. Возвращает результат в том виде, в котором должен возвращать метод decode().

Хорошими примерами использования описанных выше классов могут служить исходные тексты модулей пакета encodings.

Экземпляры приведенных ниже классов возвращаются функциями open() и EncodedFile():

StreamReaderWriter(stream, Reader, Writer [, errors])

Создает файловый объект, обеспечивающий доступ на чтение с кодированием (через объект Reader(stream, errors)) и запись с декодированием (через объект Writer(stream, errors)) к потоку stream.

StreamRecoder(stream, encode, decode, Reader, Writer [, errors])

Экземпляры этого класса обеспечивают прозрачное перекодирование при работе с потоком file (файловый объект). Данные в файле хранятся в кодировке output, в то время как строки передаваемые методам write() и writelines() и возвращаемые методами read(), readline() и readlines() содержат данные в кодировке input.

Следующие константы могут быть полезны при чтении и записи файлов, формат которых зависит от платформы:

BOM

BOM_BE

BOM_LE

BOM32_BE

BOM32_LE

BOM64_BE

BOM64_LE

Эти константы определяют метки, которые используются для обозначения порядка следования байтов (byte order mark, BOM). Константа BOM равна BOM_BE или BOM_LE и определяет “родной” порядок следования для данной платформы. Суффиксы ‘_BE’ и ‘_LE’ обозначают соответственно big-endian и little-endian.

17. Средства интернационализации

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

17.1. locale — использование национальных особенностей

Модуль locale позволяет работать с различными языками, не зная национальных и культурных особенностей каждой страны. Изначально система использует стандартные национальные установки (с именем ’C’).

Error

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

setlocale(category [, locale])

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

Если аргумент locale опущен или равен None, возвращает текущие установки для категории category.

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

import locale
locale.setlocale(locale.LC_ALL,'')

Это позволяет использовать пользовательские установки по умолчанию для всех категорий [В ОС Windows используются разные кодировки для консольных и графических приложений, для русского языка это cp866 и Unicode. Однако установки по умолчанию подразумевают кодировку, которая использовалась в старых версиях Windows в графическом режиме — cp1251. Поэтому использование национальных установок по умолчанию в Windows, к сожалению, не имеет смысла.]. Если национальные установки после этого не меняются, у Вас не должно возникнуть проблем с использованием нескольких потоков.

localeconv()

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

’decimal_point’ (категория LC_NUMERIC)

Символ, используемый в качестве десятичной точки.

’grouping’ (категория LC_NUMERIC)

Список чисел, указывающих, в каких относительных позициях ожидается использование группирующего разделителя localeconv()['thousands_sep']. Если последовательность заканчивается символом CHAR_MAX, разделитель далее не используется. Если последовательность заканчивается нулем, далее повторно используется последний размер группы .

’thousands_sep’ (категория LC_NUMERIC)

Символ, используемый в качестве разделителя между группами.

’int_curr_symbol’ (категория LC_MONETARY)

Международное обозначение национальной валюты (в соответствии со стандартом ISO 4217).

’currency_symbol’ (категория LC_MONETARY)

Местное обозначение национальной валюты.

’mon_decimal_point’ (категория LC_MONETARY)

Символ, используемый в качестве десятичной точки в денежных суммах.

’mon_grouping’ (категория LC_MONETARY)

Имеет такой же формат, как и localeconv()['grouping']. Используется для денежных сумм.

’mon_thousands_sep’ (категория LC_MONETARY)

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

’positive_sign’ (категория LC_MONETARY)

’negative_sign’ (категория LC_MONETARY)

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

’int_frac_digits’ (категория LC_MONETARY)

’rac_digits’ (категория LC_MONETARY)

Число цифр после десятичной точки для международных и местных сумм.

’p_cs_precedes’ (категория LC_MONETARY)

’n_cs_precedes’ (категория LC_MONETARY)

0, если символ валюты указывается после суммы, и 1, если символ валюты указывается перед суммой, для положительных и отрицательных денежных сумм соответственно.

’p_sep_by_space’ (категория LC_MONETARY)

’n_sep_by_space’ (категория LC_MONETARY)

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

’p_sign_posn’ (категория LC_MONETARY)

’n_sign_posn’ (категория LC_MONETARY)

Указывает, в каком формате должна быть выведена денежная сумма со знаком (соответственно положительным и отрицательным): 0 — сумма и символ валюты заключаются в скобки, 1 — знак указывается перед суммой и символом валюты, 2—после суммы и символа валюты, 3—непосредственно перед символом валюты, 4 — непосредственно после символа валюты и CHAR_MAX — формат не установлен.

CHAR_MAX

Символическая константа, обычно используется в словаре, возвращаемом функцией localeconv(), если формат не установлен.

getdefaultlocale([envvars])

Пытается определить пользовательские национальные установки по умолчанию для данной категории и возвращает их в виде кортежа из строк с кодом языка и кодировкой (вместо строки может быть None, если значение не может быть определено) [В Windows NT getdefaultlocale() возвращает верное значение, которое, однако, не может быть использовано в качестве аргумента функции setlocale(), так как последняя требует имя национальных установок в своем (не стандартном) виде. Ситуация возможно изменится в будущих версиях языка.]. Если установки по умолчанию не могут быть определены с помощью системного вызова, используются переменные окружения с именами, приведенными в списке envvars (по умолчанию используется ‘['LANGUAGE', 'LC_ALL', code'LC_CTYPE', 'LANG']’). Функция доступна, начиная с версии 2.0.

getlocale([category])

Возвращает текущие установки для категории category в виде кортежа из строк с кодом языка и кодировкой (вместо строки может быть None, если значение не может быть определено). Аргумент category может быть любой константой вида LC_*, кроме LC_ALL; по умолчанию используется LC_CTYPE. Функция доступна, начиная с версии 2.0.

normalize(locale)

Возвращает нормализованное имя национальных установок. Если имя locale не может быть нормализовано, оно возвращается без изменений. Если в исходном имени не указана кодировка, используется кодировка по умолчанию для данного языка (ISO8859-5 для русского). Функция доступна, начиная с версии 2.0.

resetlocale([category])

Изменяет текущие национальные установки для категории category (по умолчанию LC_ALL) на пользовательские установки по умолчанию [Не работает в Windows NT из-за несовместимости функций getdefaultlocale() и setlocale() (см. также сноску 2).]. Функция доступна, начиная с версии 2.0.

strcoll(string1, string2) (категория LC_COLLATE)

Производит лексикографическое сравнение строк string1 и string2 в соответствии с текущими национальными установками. Как и другие функции сравнения возвращает положительное, отрицательное число или 0 в зависимости от того, располагается строка string1 до или после string2 или строки равны. Строки не должны содержать символов ’\000’.

strxfrm(string) (категория LC_COLLATE)

Преобразует строку таким образом, чтобы можно было проводить более быстрое сравнение с помощью встроенной функции cmp() (или операторов сравнения) и результат был таким же, какой возвращает функция strcoll(). Строка не должна содержать символов ’\000’.

format(format, val [, grouping]) (категория LC_NUMERIC)

Возвращает строковое представление числа с учетом текущих национальных установок. Строка формата следует соглашениям, принятым для оператора %. Функция принимает во внимание местный символ десятичной точки и, если задан и является истиной аргумент grouping, группирует соответствующим образом цифры.

str(float) (категория LC_NUMERIC)

Возвращает строковое представление числа аналогично встроенной функции str(), но использует символ десятичной точки в соответствии с текущими национальными установками.

atof(string) (категория LC_NUMERIC)

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

atoi(string) (категория LC_NUMERIC)

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

Ниже перечислены константы, которые могут использоваться в качестве первого аргумента функции setlocale() (категории национальных установок):

LC_CTYPE

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

LC_COLLATE

От установок этой категории зависит поведение функций strcoll() и strxfrm().

LC_TIME

От установок этой категории зависит поведение функции time.strftime().

LC_MONETARY

Категория для формата денежных сумм (см. описание функции localeconv() выше).

LC_MESSAGES

Эта категория обычно определяет язык выводимых сообщений. Однако в настоящих реализациях интерпретатора установки этой категории не используются (см. описание модуля gettext).

LC_NUMERIC

Категория, определяющая формат чисел. Влияет на поведение функций format(), atoi(), atof() и str(), определенных в этом модуле.

LC_ALL

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

17.2. gettext — выдача сообщений на родном языке

Модуль gettext предоставляет возможность модулям и приложениям выдавать сообщения на родном языке пользователя. Этот модуль поддерживает как интерфейс к каталогу сообщений GNU gettext, так и основанный на классах интерфейс более высокого уровня, который больше подходит для кода на языке Python. В обоих случаях Вы пишите модуль или приложение с сообщениями на одном естественном языке и предоставляете каталог переведенных сообщений на другие языки.

Замечание: в текущих реализациях язык, на который осуществляется перевод, не зависит от национальных установок, выбранных с помощью функции locale.setlocale(), а выбирается в зависимости от значений переменных окружения LANGUAGE, LC_ALL, LC_MESSAGES и LANG (первая из них, имеющая непустое значение) или указывается явно. Далее мы будем обозначать строку с кодом выбранного языка как language.

17.2.1. Интерфейс GNU gettext

Используя интерфейс GNU gettext, Вы затрагиваете все приложение. Обычно это то, что нужно для одноязычных приложений. Если же Вы пишите модуль или Вашему приложению необходимо менять язык “на лету”, Вам следует использовать интерфейс основанный на классах.

bindtextdomain(domain [, localedir])

Привязывает домен с именем domain к каталогу localedir. В дальнейшем модуль gettext будет искать двоичный файл с переведенными сообщениями с путем os.path.join(localedir, language, 'LC_MESSAGES', domain +'.mo'). Если аргумент localedir опущен или равен None, возвращает каталог, к которому на данный момент привязан домен domain (по умолчанию используется каталог ‘os.path.join(sys.prefix, 'share', 'locale')').

textdomain([domain])

Если задан и не равен None аргумент domain, возвращает текущий домен, иначе устанавливает глобальный (для всего приложения) домен равным domain и возвращает его.

gettext(message)

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

dgettext(domain, message)

Работает аналогично функции gettext(), но ищет перевод в базе данных для домена domain.

GNU gettext также определяет функцию dcgettext(), однако она считается бесполезной и поэтому на данный момент не реализована.

Приведем пример типичного использования описанного интерфейса:

import gettext
gettext.textdomain('myapplication')
_ = gettext.gettext
...
# вывод строки, подлежащей переводу:
print _('This is a translatable string.')
...

17.2.2. Интерфейс, основанный на классах

Этот интерфейс предоставляет большие гибкость и удобства, чем интерфейс GNU gettext. Поэтому мы рекомендуем его для использования в модулях и приложениях, написанных на языке Python. Модуль gettext определяет “класс-переводчик”, который реализует чтение ‘.mo’-файлов и предоставляет методы, возвращающие обычные строки или строки Unicode с переводом. Экземпляры этого класса могут установить функцию _() во встроенном пространстве имен.

find(domain [, localedir [, languages]])

Эта функция реализует стандартный алгоритм поиска ‘.mo’-файлов для домена domain в каталоге localedir для языков, перечисленных в строке languages (по умолчанию используется значение одной из переменных окружения: LANGUAGE, LC_ALL, LC_MESSAGES или LANG). Строка languages (или одна из перечисленных переменных окружения) должна содержать список через двоеточие кодов языков в порядке убывания их приоритета. Функция find() возвращает путь к ‘.mo’-файлу, из которого следует брать перевод сообщения. Если ни один из файлов не найден, возвращает None.

translation(domain [, localedir [, languages [, class_]]])

Catalog(domain [, localedir [, languages [, class_]]])

Возвращает объект, реализующий перевод сообщений. Аргументы domain, localedir и languages передаются функции find() для поиска нужного ‘.mo’-файла. Возвращаемый объект является экземпляром класса class_ (по умолчанию используется GNUTranslations). Конструктор класса вызывается с одним аргументом — файловым объектом, реализующим доступ к ‘.mo’-файлу. Если ‘.mo’-файл не найден, генерируется исключение IOError. Функция translation() кэширует созданные объекты и использует их при повторных запросах объекта для того же ‘.mo’-файла.

Имя Catalog() определено для совместимости с версией модуля gettext, которую использует GNOME.

install(domain [, localedir [, unicode]])

Эквивалентно вызову ‘translation(domain, localedir).install(unicode)’. Эта функция предоставляет самый простой способ установить функцию _(), реализующую перевод сообщений. Для удобства _() устанавливается в пространство встроенных имен и, таким образом, доступна во всех модулях, используемых приложением.

Ниже описаны классы, непосредственно реализующие перевод строк сообщений.

NullTranslations([fp])

Этот класс реализует основной интерфейс, и используется в качестве базового класса для остальных классов-переводчиков. При инициализации устанавливает “защищенные” атрибуты _info и _charset созданного экземпляра равными None и, если задан и не равен None аргумент fp, вызывает метод _parse(fp), который должен быть переопределен в производных классах.

Экземпляры NullTranslations имеют следующие методы:

_parse(fp)

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

gettext(message)

В базовом классе возвращает сообщение message без изменений. В производных классах должен возвращать перевод сообщения.

ugettext(message)

В базовом классе возвращает сообщение message в виде строки Unicode. В производных классах должен возвращать перевод сообщения в виде строки Unicode.

info()

Возвращает значение “защищенного” атрибута _info (метаданные каталога в виде словаря).

charset()

Возвращает значение “защищенного” атрибута _charset (кодировка перевода сообщений в каталоге).

install([unicode])

Если аргумент unicode опущен или является ложью, устанавливает собственный метод gettext() в пространство встроенных имен под именем _(), в противном случае устанавливает собственный метод ugettext().

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

def gettext(message): return message

import __builtin__
if hasattr(__builtin__, 'ps1'):
    # Используется интерактивный режим
    _ = gettext
elif not hasattr(__builtin__, '_'):
    __builtin__._ = gettext

Это также позволит обеспечить корректную работу (без перевода сообщений) при импортировании модуля в интерактивном режиме.

Модуль gettext также определяет класс GNUTranslations, производный от NullTranslations. Этот класс переопределяет метод _parse(), обеспечивая чтение ‘.mo’-файлов в формате GNU gettext (как big-endian, так и little-endian). Он также анализирует метаданные каталога и сохраняет их в “защищенном” атрибуте экземпляра _info. Если каталог содержит запись с ключом ’Content-Type’, то указанная в ней кодировка сохраняется в “защищенном” атрибуте _charset.

Если ‘.mo’ оказывается поврежденным, при инициализации экземпляра GNUTranslations будет сгенерировано исключение IOError.

Класс GNUTranslations также переопределяет методы gettext() и ugettext(). Последний передает атрибут _charset встроенной функции unicode() для получения строки Unicode.

ОС Solaris определяет собственный формат ‘.mo’-файлов, который в настоящее время не поддерживается.

17.2.3. Изготовление каталога переведенных сообщений

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

filename = 'mylog.txt'
message = _('writing a log message')
fp = open(filename, 'w')
fp.write(message)
fp.close()

Здесь строка ’writing a log message’ помечена как подлежащая переводу, в то время как ’mylog.txt’ и ’w’ — нет.

В стандартную поставку Python включена утилита pygettext, которая извлекает строки, подлежащие переводу, из файла с исходным кодом и помещает их в ‘.pot’-файл [Аналогичную работу выполняет программа xpot, доступная в пакете po-utils по адресу http://www.iro.umontreal.ca/contrib/po-utils/HTML.]. Именно с этим файлом работает человек, выполняющий перевод. С помощью утилит пакета GNU gettext Вы можете изготовить ‘.mo’-файл, который читается экземплярами класса GNUTranslations.

18. Математический аппарат

Модули, описанные в этой главе, позволяют выполнять основные математические операции. Если Вас интересуют многомерные массивы и функции линейной алгебры, взгляните на пакет модулей “Numerical Python” (NumPy), доступный по адресу http://numpy.sourceforge.net/.

18.1. math — математические функции для работы с вещественными числами

Модуль math всегда доступен и предоставляет доступ к стандартным математическим функциям. Эти функции не работают с комплексными числами — для этого следует использовать одноименные функции из модуля cmath.

acos(x)

Возвращает арккосинус x.

asin(x)

Возвращает арксинус x.

atan(x)

Возвращает арктангенс x.

atan2(x, y)

Эквивалентно atan(x/y). Аргумент y может быть равен 0 — в этом случае возвращает pi/2.

ceil(x)

Возвращает наименьшее вещественное число с нулевой дробной частью большее, чем x.

cos(x)

Возвращает косинус x.

cosh(x)

Возвращает гиперболический косинус x.

exp(x)

Возвращает e**x.

fabs(x)

Возвращает абсолютное значение x.

floor(x)

Возвращает наибольшее вещественное число с нулевой дробной частью меньшее, чем x.

fmod(x, y)

Результат этой функции зависит от реализации одноименной функции библиотеки языка C. Обычно дает такой же результат, как x % y.

frexp(x)

Возвращает пару ‘(m, e)’, где m — мантисса (вещественное число) и e — экспоненциальная часть (целое число). Для чисел m и e всегда выполняется условие ‘x == m * 2**e’. Если аргумент x равен нулю, возвращает ‘(0.0, 0)’. В противном случае всегда выполняется ‘0.5 <= abs(m) < 1’.

hypot(x, y)

Возвращает евклидово кодовое расстояние, ‘sqrt(x*x + y*y)’.

ldexp(m, e)

Функция, обратная frexp(). Возвращает ‘m * (2**e)’.

log(x)

Возвращает натуральный логарифм x.

log10(x)

Возвращает десятичный логарифм x.

modf(x)

Возвращает кортеж из пары вещественных чисел — дробной и целой части x. Оба возвращаемых числа имеют такой же знак, как у числа x.

pow(x, y)

Возвращает x**y.

sin(x)

Возвращает синус x.

sinh(x)

Возвращает гиперболический синус x.

sqrt(x)

Возвращает квадратный корень из x.

tan(x)

Возвращает тангенс x.

tanh(x)

Возвращает гиперболический тангенс x.

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

Модуль также определяет две константы:

pi

Число пи.

e

Число e.

18.2. cmath — математические функции для работы с комплексными числами

Модуль cmath всегда доступен и предоставляет доступ к математическим функциям, работающими с комплексными числами.

acos(x)

Возвращает арккосинус x.

acosh(x)

Возвращает гиперболический арккосинус x.

asin(x)

Возвращает арксинус x.

asinh(x)

Возвращает гиперболический арксинус x.

atan(x)

Возвращает арктангенс x.

atanh(x)

Возвращает гиперболический арктангенс x.

cos(x)

Возвращает косинус x.

cosh(x)

Возвращает гиперболический косинус x.

exp(x)

Возвращает e**x.

log(x)

Возвращает натуральный логарифм x.

log10(x)

Возвращает десятичный логарифм x.

sin(x)

Возвращает синус x.

sinh(x)

Возвращает гиперболический синус x.

sqrt(x)

Возвращает квадратный корень из x.

tan(x)

Возвращает тангенс x.

tanh(x)

Возвращает гиперболический тангенс x.

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

Модуль также определяет две константы:

pi

Число пи (вещественное).

e

Число e (вещественное).

Заметим, что эти функции похожи, но не идентичны одноименным функциям в модуле math. Различия проявляются даже при использовании вещественных аргументов. Например, math.sqrt(-1) генерирует исключение, в то время как cmath.sqrt(-1) возвращает 1j. Кроме того, функции модуля cmath всегда возвращают комплексное число, даже если оно может быть выражено в рамках вещественного (в этом случае число имеет нулевую мнимую часть).

18.3. random — псевдослучайные числа с различными распределениями

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

betavariate(alpha, beta)

Бета-распределение. Оба аргумента должны быть больше -1, возвращает значение между 0 и 1.

cunifvariate(mean, arc)

Циклическое равномерное распределение. mean — средний угол, arc — ширина диапазона. Оба аргумента должны быть в диапазоне от 0 до пи. Возвращаемое значение находятся в диапазоне от mean - arc/2 до mean + arc/2 (также приводится к диапазону от 0 до пи).

expovariate(lambda)

Экспоненциальное распределение. Аргумент lambda равен единице, деленной на желаемое математическое ожидание распределения. Возвращает значения от 0 до +бесконечности.

gamma(alpha, beta)

Гамма-распределение. Аргументы должны удовлетворять условиям alpha > -1 и beta > 0.

gauss(mu, sigma)

normalvariate(mu, sigma)

Нормальное распределение (Гаусса). mu — математическое ожидание и sigma — стандартное отклонение. Функция gauss() имеет немного более быструю реализацию.

lognormvariate(mu, sigma)

Логарифмически нормальное распределение. Натуральный логарифм от значений, возвращаемых этой функцией, дает нормальное распределение с математическим ожидание mu и стандартным отклонением sigma. mu может иметь любое значения, sigma должен быть больше нуля.

vonmisesvariate(mu, kappa)

Распределение фон Мизеса. mu — математическое ожидание, выраженное в радианах от 0 до 2*пи, kappa — коэффициент кучности, который должен быть больше или равен нулю. Если аргумент kappa равен нулю, это распределение вырождается в равномерное распределение в диапазоне от 0 до 2*пи.

paretovariate(alpha)

Распределение Парето. alpha — параметр формы распределения.

weibullvariate(alpha, beta)

Распределение Вейбулла. alpha — масштабный коэффициент, beta — параметр формы распределения.

Для удобства модуль random также экспортирует имена random(), uniform(), randrange(), randint() и choice() из модуля whrandom и переопределяет seed():

seed([obj])

Инициализирует генератор случайных чисел хэш-значением объекта obj. Если аргумент obj опущен или равен None, использует для инициализации текущее время (аналогично whrandom.seed()).

18.4. whrandom — генератор псевдослучайных чисел

Этот модуль определяет класс whrandom, реализующий генератор псевдослучайных чисел Вичмана-Хилла [Wichmann, B. A. and Hill, I. D., “Algorithm AS 183: An efficient and portable pseudo-random number generator”, URL 31 (1982) 188–190.]:

whrandom([x, y, z])

Создает, инициализирует, вызывая метод seed(), и возвращает объект-генератор.

Экземпляры класса whrandom имеют следующие методы:

seed([x, y, z])

Инициализирует генератор целыми числами x, y и z. Числа должны быть в диапазоне от 0 до 255 (включительно). Если аргументы опущены или равны нулю, используются значения, производные от текущего времени. Если один или два аргумента равны нулю, нулевые значения заменяются единицей.

random()

Возвращает случайное вещественное число r такое, что 0.0 <= r < 1.0.

uniform(a, b)

Возвращает случайное вещественное число r такое, что a <= r < b.

randrange([start,] stop [, step])

Возвращает случайное целое число из ‘range(start, stop, step)’.

randint(a, b)

Возвращает случайное целое число из ‘range(a, b +1)’. Этот метод оставлен лишь для совместимости со старыми версиями модуля — используйте randrange().

choice(seq)

Выбирает случайный элемент из непустой последовательности seq и возвращает его.

При импортировании модуль whrandom создает экземпляр класса whrandom и делает его методы seed(), random(), uniform(), randrange(), randint() и choice() доступными в глобальном пространстве имен модуля. Заметим, что использование отдельных экземпляров класса whrandom приведет к использованию независимых последовательностей псевдослучайных чисел.

Методы экземпляров whrandom дают случайные числа с равномерным распределением. Если Вам необходимо получить случайные числа с другими распределениями, воспользуйтесь функциями, определенными в модуле random.

18.5. bisect — поддержание последовательностей в сортированном состоянии

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

Модуль bisect предоставляет следующие функции:

bisect(list, item [, lo [, hi]])

Находит место в списке (индекс), в которое необходимо вставить item, для того, чтобы сохранить список в сортированном состоянии. Аргументы lo и hi могут быть использованы для указания подмножества списка, которое следует принимать в рассмотрение. Возвращаемое значения подходит для использования в качестве первого аргумента метода list.insert().

insort(list, item [, lo [, hi]])

Вставляет item в список list, сохраняя сортированное состояние списка. Эквивалентно ‘list.insert(bisect.bisect(list, item, lo, hi), item)’.

Функция bisect() может быть полезна для распределения данных по категориям. В следующем примере эта функция используется для определения оценки (обозначаемой буквой, как это принято во многих западных странах) за экзамен по общему количеству набранных баллов. Пусть 85 и более баллов соответствует оценке ‘A’, 75–84 — ‘B’ и т. д.:

>>> grades = "FEDCBA"
>>> breakpoints = [30, 44, 66, 75, 85]
>>> from bisect import bisect
>>> def grade(total):
...           return grades[bisect(breakpoints, total)]
...
>>> grade(66)
'C'
>>> map(grade, [33, 99, 77, 44, 12, 88])
['E', 'A', 'B', 'D', 'F', 'A']

18.6. array — эффективные массивы чисел

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

Реальное представление значений зависит от архитектуры машины. Используемый размер доступен через атрибут itemsize массивов. При извлечении элементов из массивов, при конструировании которых использовался символ ’L’ или ’I’, значение представляется типом long int языка Python, так как в рамках типа int не может быть представлен весь диапазон чисел типов unsigned int и unsigned long.

array(typecode [, initializer])

Создает новый объект-массив, тип элементов которого определяется символом typecode, инициализирует элементами последовательности initializer (должен быть списком или обычной строкой; initializer передается методу fromlist() или fromstring()) и возвращает его.

ArrayType

Объект типа, соответствующий объектам, которые возвращает функция array().

Массивы имеют следующие атрибуты данных и методы:

typecode

Символ, определяющий тип элементов массива.

itemsize

Размер в байтах внутреннего представления одного элемента массива.

append(x)

Добавляет x в конец массива.

buffer_info()

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

byteswap()

Изменяет порядок следования байтов для всех элементов массива. Эта операция может быть выполнена только для значений, внутреннее представление которых имеет размер 1, 2, 4 или 8 байт. Метод может быть полезен при чтении данных из файла, который был записан на машине с другим порядком следования байтов.

count(x)

Возвращает число элементов массива равных x.

extend(a)

Добавляет элементы массива a в конец массива.

fromfile(f, n)

read(f, n)

Считывает и добавляет в конец массива n элементов (машинное представление) из файла, представленного файловым объектом (встроенного типа file) f. Если файл содержит меньше элементов, чем n, генерируется исключение EOFError, но все прочитанные к этому времени элементы добавляются в массив.

Имя read() присутствует для совместимости со старыми версиями.

fromlist(list)

Добавляет в конец массива элементы из списка list. Это эквивалентно инструкции ‘for x in list: a.append(x)’ с одним исключением: если список содержит элементы неверного типа, массив остается без изменений.

fromstring(s)

Добавляет в конец массива элементы из строки s, интерпретируя строку как машинное представление значений (то есть аналогично тому, как это делает метод fromfile()). Число символов в строке должно быть кратным размеру элементов массива.

index(x)

Возвращает индекс первого элемента массива равного x. Если массив не содержит таких значений, генерируется исключение ValueError.

insert(i, x)

Вставляет значение x в массив перед элементом с индексом i.

pop([i])

Удаляет из массива элемент с индексом i и возвращает его. Использование отрицательных индексов позволяет вести отсчет с конца. По умолчанию аргумент i равен -1, то есть соответствует последнему элементу.

remove(x)

Удаляет из массива первый элемент равный x.

reverse()

Меняет порядок следования элементов массива на обратный.

tofile(f)

write()

Записывает все элементы массива (машинное представление) в файл, представленный файловым объектом f. Имя write() присутствует для совместимости со старыми версиями.

tolist()

Возвращает список элементов массива.

tostring()

Возвращает строку с машинным представлением элементов массива (та же самая последовательность байтов, которая записывается в файл методом tofile()).

19. Интерфейсные классы к встроенным типам

Модули, описанные в этой главе, позволяют определять новые классы, наследующие возможности встроенных типов.

19.1. UserString — интерфейсный класс для создания строковых объектов

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

UserString([initialdata])

Возвращает экземпляр класса, который ведет себя аналогично объектам встроенного типа string (обычная строка) или unicode (строка Unicode). Экземпляр инициализируется из initialdata (объект произвольного типа). Если initialdata не является строкой (string или unicode), экземпляр инициализируется строковым представлением объекта (str(initialdata)). Если аргумент initialdata опущен, экземпляр инициализируется пустой строкой. Данные из initialdata сохраняются в виде строки в атрибуте data созданного экземпляра.

В дополнение к методам и операциям, характерным для строк (см. раздел 11.2.1), экземпляры класса UserString имеют следующий атрибут:

data

Строка (string или unicode), в которой хранятся данные.

В качестве примера класса, производного от UserString модуль определяет еще один класс:

MutableString([initialdata])

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

Помимо унаследованных от UserString, экземпляры класса MutableString поддерживают операции, позволяющие изменить объект: изменение и удаление символа (элемента последовательности) и подстроки (среза последовательности) — часть операций, характерных для изменяемых последовательностей (см. раздел 11.2.6).

19.2. UserList — интерфейсный класс для создания последовательностей

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

Модуль определяет единственное имя — класс UserList:

UserList([initialdata])

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

В дополнение к методам и операциям, характерным для всех изменяемых последовательностей (см. раздел 11.2.6), экземпляры класса UserList имеют следующий атрибут:

data

Список, в котором хранятся данные.

19.3. UserDict — интерфейсный класс для создания отображений

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

Модуль определяет единственное имя — класс UserDict:

UserDict([initialdata])

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

В дополнение к методам и операциям, характерным для всех отображений (см. раздел 11.3), экземпляры класса UserDict имеют следующий атрибут:

data

Словарь, в котором хранятся данные.

20. Сохранение и копирование объектов

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

20.1. pickle и cPickle — представление объектов в виде последовательности байтов

Модуль pickle реализует простой, но мощный алгоритм “консервирования” (pickling, преобразования объектов в последовательность байтов) почти любых объектов языка Python с возможностью дальнейшего восстановления (unpickling). Однако этот модуль не заботится о сохранении имен объектов и не обеспечивает к ним совместный доступ. Полученную последовательность байтов Вы можете записать в файле, сохранить в базе данных или переслать по сети на другую машину. Модуль shelve предоставляет простой интерфейс для сохранения “законсервированных” объектов в базе данных в стиле DBM.

В то время как реализованный на языке Python модуль pickle работает достаточно медленно, реализованный на C модуль cPickle работает иногда почти в 1000 раз быстрее. Модуль cPickle использует точно такой же алгоритм и имеет аналогичный интерфейс, за исключением того, что вместо классов Pickler и Unpickler используются функции, возвращающие объекты с аналогичным интерфейсом.

Хотя модули pickle и cPickle и используют внутри себя встроенный модуль marshal, они отличаются от этого модуля способом обработки данных:

• Модули pickle и cPickle отслеживают объекты, которые уже были обработаны, и никогда не обрабатывают их повторно. Это позволяет “консервировать” рекурсивные объекты (объекты, содержащие ссылки на себя), которые не могут быть обработаны модулем marshal. Аналогично обрабатываются совместно используемые объекты (различные объекты ссылаются на один и тот же объект): они остаются совместно используемыми, что очень важно для изменяемых объектов.
• Модуль marshal совсем не поддерживает экземпляры классов, в то время как модули pickle и cPickle позволяют с ними работать. Определение класса должно находиться в том же модуле, в котором оно было при “консервации” объекта.

Используемый формат данных характерен для языка Python и не имеет ограничений, характерных, например, для стандартного формата XDR (External Data Representation), который не позволяет представить совместное использование объектов. Однако это означает, что программы на других языках не смогут восстановить “законсервированный” объект.

По умолчанию для представления используются только печатные ASCII символы, что позволяет просматривать файл с данными с помощью обычного текстового редактора с целью отладки или восстановления данных. С другой стороны, такое представление занимает больше места, чем двоичный формат. Вы можете выбрать двоичный формат, используя ненулевое значение аргумента bin конструктора Pickler и функций dump() и dumps().

Модули pickle и cPickle не поддерживают объекты кода. В этом нет большой необходимости, так как для “консервирования” объектов кода традиционно используется модуль marshal. Кроме того, это позволяет избежать возможного включения в файлы данных троянских коней.

Для удобства работы с долгоживущими модулями предоставляется поддержка ссылок на объекты, которые не подлежат “консервированию”. Для таких объектов запоминается идентификатор, возвращаемый атрибутом-функцией или методом persistent_id(). Идентификатор может быть произвольной строкой из печатных ASCII символов. Для восстановления объекта по идентификатору необходимо определить атрибут-функцию persistent_load().

На “консервирование” экземпляров классов есть несколько ограничений. Вопервых, класс должен быть определен в глобальном пространстве имен одного из модулей. Во-вторых, все переменные экземпляра (то есть атрибут __dict__) должны поддерживать “консервацию” или же экземпляр класса должен иметь метод __getstate__() протокола копирования, возвращающий объект, который поддерживает “консервацию”.

При восстановлении экземпляра класса его метод __init__() обычно не вызывается. Для того, чтобы он вызывался, класс должен иметь метод __getinitargs__() протокола копирования. Другие методы протокола копирования __getstate__() и __setstate__() используются для сохранения и восстановления состояния объекта.

Обратите внимание, что при “консервации” экземпляра класса сам объект-класс и, соответственно, его атрибуты не сохраняются — сохраняются только атрибуты экземпляра и запоминается имя класса и модуля, в котором класс определен. Поэтому класс должен быть определен в глобальном пространстве имен модуля, который, однако, в момент восстановления может быть и не импортирован. Это сделано с целью иметь возможность исправить ошибки в определении класса или добавить новые методы и загрузить объект, созданный со старой версией класса. Если Вы собираетесь работать с долгоживущими объектами, которые переживут множество версий класса, разумно сохранить номер версии класса, чтобы затем необходимые преобразования могли быть выполнены методом __setstate__().

Модули pickle и cPickle определяют следующие конструкторы:

Pickler(file [, bin])

Класс (в модуле pickle) или функция (в модуле cPickle), возвращает объект, реализующий “консервирование”. Аргумент file должен быть файловым объектом, имеющим метод write(). Если задан отличный от нуля аргумент bin (целое число), используется более компактный двоичный формат.

Unpickler(file)

Класс (в модуле pickle) или функция (в модуле cPickle), возвращает объект, реализующий восстановление “законсервированного” объекта. Аргумент file должен быть файловым объектом, имеющим методы read() и readline().

Объекты, возвращаемые конструктором Pickler(), имеют следующие (основные) методы:

dump(object)

“Консервирует” объект object.

persistent_id(object)

Этот метод (функция или любой другой объект, поддерживающий вызов) вызывается для каждого из вложенных объектов. Должен возвращать строку-идентификатор постоянного объекта или None, если объект подлежит консервации. Изначально метод persistent_id() не определен (cPickle) или всегда возвращает None (pickle).

Объекты, возвращаемые конструктором Unpickler(), имеют методы, предназначенные для выполнения обратных действий:

load()

Восстанавливает и возвращает ранее “законсервированный” объект.

noload() (только в модуле cPickle)

Проходит весь цикл восстановления объекта, но сам объект не создает. Может быть полезен для тестирования persistent_load

persistent_load(id_string)

Этот метод (функция или любой другой объект, поддерживающий вызов) вызывается для восстановления ссылки на постоянный объект по строке-идентификатору id_string, которая при “консервации” была возвращена методом persistent_id(). Изначально метод persistent_load() не определен.

Вы можете несколько раз вызывать метод dump() объекта Pickler. Для восстановления всех “законсервированных” объектов необходимо будет столько же раз вызвать метод load() соответствующего объекта Unpickler(). Если один и тот же объект “консервируется” несколько раз методом dump() одного и того же объекта Pickler, метод load() восстановит ссылки на один и тот же объект. Предполагается, что “консервация” нескольких объектов производится без внесения в них изменений в промежутке между вызовами метода load(). Если Вы измените объект и затем повторно “законсервируете” его с помощью того же объекта Pickler, объект не будет “законсервирован” — сохранится лишь ссылка на старое значение.

Кроме конструкторов Pickler() и Unpickler(), модули определяют следующие функции и объекты данных:

dump(object, file [, bin])

“Консервирует” объект object в файл file. Эквивалентно вызову ‘Pickler(file, bin).dump(object)’.

load(file)

Восстанавливает “законсервированный” объект из файла file и возвращает его.

dumps(object [, bin])

Возвращает “законсервированное” представление объекта в виде строки вместо того, чтобы записывать его в файл.

loads(string)

Восстанавливает “законсервированный” объект из строки string и возвращает его.

format_version

Строка-версия формата, используемого при “консервации”.

compatible_formats

Список старых версий (строк) формата данных, которые, помимо текущей версии (format_version), могут быть восстановлены.

Ниже приведена иерархия исключений, которые используются модулями pickle и cPickle при возникновении ошибок (до версии 2.0 исключения определены в виде строк, что сильно затрудняет их обработку):

PickleError

Базовый класс для всех исключений, является производным от стандартного класса исключений Exception.

PicklingError

Класс исключений, которые генерируются при попытке “законсервировать” объект, который не может быть “законсервирован”.

UnpicklingError

Класс исключений, которые генерируются при восстановлении объекта, если его конструктор не зарегистрирован (см. описание модуля copy_reg).

Ниже приведен список объектов, которые могут быть “законсервированы”:

• None;
• Целые, длинные целые и вещественные числа.
• Простые строки и строки Unicode.
• Кортежи, списки и словари, содержащие только объекты, которые могут быть “законсервированы”.
• Классы и функции, определенные в глобальном пространств имен модуля (на самом деле запоминаются только имена модуля и функции).
• Экземпляры классов, атрибут __dict__ которых может быть “законсервирован”.
• Экземпляры классов, имеющих соответствующие методы протокола копирования.
• Объекты, поддержка которых зарегистрирована с помощью модуля copy_reg. Именно таким образом осуществляется поддержка комплексных чисел.

20.2. shelve — сохранение объектов в базе данных в стиле DBM

С помощью этого модуля Вы можете создать “стеллаж” (shelf) — объект с интерфейсом словаря, который позволяет сохранять в базе данных в стиле DBM объекты в “законсервированном” виде. Для консервации используется модуль cPickle или pickle, если первый недоступен.

open(filename [, flag])

Открывает файл filename с базой данных в стиле DBM и на его основе создает и возвращает объект-стеллаж. Флаг flag используется в качестве второго аргумента в функции anydbm.open() (см. описание модуля anydbm).

Объекты-стеллажи поддерживают большинство операций, характерных для отображений (см. раздел 11.3): доступ к объектам по ключу, добавление и удаление записей, методы has_key(), keys(), get(). В качестве ключа могут использоваться только обычные строки. Методы sync() и close() вызывают соответствующие методы объекта, представляющего базу данных.

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

20.3. marshal — байт-компилированное представление объектов

Этот модуль позволяет получить байт-компилированное представление объектов кода (code), а также сопутствующих им объектов: None; объектов, которые могут быть представлены литеральными выражениями (любые числа и строки); кортежей, списков и словарей, содержащих только объекты, для которых может быть получено байткомпилированное представление. Попытка получить байт-компилированное представление для рекурсивных объектов (содержащих ссылки на самих себя) приведет к зацикливанию. Формат байт-компилированного кода специфичен для языка Python, но не зависит от платформы. marshal не является модулем общего назначения. Для сохранения и передачи объектов следует использовать модули pickle, cPickle и shelve.

Модуль определяет следующие функции:

dump(object, file)

Записывает байт-компилированное представление объекта object в файл. Аргумент file должен быть объектом типа file, открытым для записи в двоичном режиме (’wb’ или ’w+b’). Если для объекта object не может быть получено байт-компилированное представление, генерируется исключение ValueError, но при этом в файл будет записан “мусор”, который не будет корректно считан функцией load().

load(file)

Считывает байт-компилированное представление для одного объекта из файла, восстанавливает его и возвращает. Если данные в файле не могут быть корректно обработаны, в зависимости от ситуации генерируется одно из исключений EOFError, ValueError или TypeError. Аргумент file должен быть объектом типа file, открытым для чтения в двоичном режиме (’rb’ или ’r+b’).

dumps(object)

Возвращает строку с байт-компилированным представлением объекта object.

loads(string)

Восстанавливает объект из байт-компилированного представления string. Лишние символы в строке игнорируются.

20.4. struct — преобразование объектов в структуры языка C

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

error

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

pack(format, value1 ...)

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

unpack(format, string)

Распаковывает строку string в соответствии с форматом format и возвращает кортеж объектов. Строка должна содержать ровно такое количество данных, которое требует строка формата, то есть длина строки должна быть равной calcsize(format).

calcsize(format)

Возвращает размер структуры (то есть длину строки), соответствующей формату format.

Символы строки формата имеют следующее значение:

Перед символом формата может идти число, обозначающее количество повторений. Например, строка формата ’4h’ полностью эквивалентна строке ’hhhh’. Символы пропуска между символами формата игнорируются, однако символы пропуска между числом и символом формата не допускаются.

Число перед символом формата ‘s’ интерпретируется как длина строки, а не число повторений. То есть ’10s’ обозначает строку из 10 символов, в то время как ’10c’ — 10 раз по одному символу. При упаковке строки урезаются или дополняются до нужной длины символами с кодом 0. При распаковке строки имеют указанную в строке формата длину.

Символ формата ‘p’ может быть использован для упаковки строк в стиле языка Pascal. В этом случае первый байт является длиной строки, затем следует сама строка. Число перед символом ‘p’ указывает на длину строки вместе с байтом, в котором сохранится длина строки.

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

Символ формата ‘P’ может быть использован только с “родным” порядком следования байтов.

Для того, чтобы выравнять конец структуры в соответствии с определенным типом, можно поместить в конец строки формата символ, определяющий этот тип с числом повторения равным 0. Например, формат ’llh0l’ определяет дополнительные два байта в конце (подразумевая, что тип long выравнивается в рамках четырех байтов). Этот способ работает только с “родными” размером и выравниванием.

Приведем небольшой пример использования модуля struct (платформа Intel, little-endian):

>>> from struct import *
>>> pack('hhl', 1, 2, 3)
'\001\000\002\000\003\000\000\000'
>>> unpack('hhl', '\001\000\002\000\003\000\000\000')
(1, 2, 3)
>>> calcsize('hhl')
8

21. Доступ к средствам, предоставляемым операционной системой

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

21.1. os — основные службы операционной системы

Модуль os позволяет переносимо использовать основные службы операционной системы (ОС). Этот модуль производит поиск встроенного модуля, характерного для данной ОС (posix, nt, mac и др.) и экспортирует определенные в нем функции и объекты данных. Модуль спроектирован таким образом, чтобы обеспечить одинаковый интерфейс в тех случаях, когда для разных ОС доступны одинаковые возможности. Функции, определенные только для некоторых ОС также доступны через модуль os, однако их использование не переносимо.

error

Является ссылкой на встроенный класс исключений OSError (см. раздел 13).

name

Имя зависящего от ОС модуля. В настоящее время могут быть использованы следующие имена: ’posix’, ’nt’, ’dos’, ’mac’, ’os2’, ’ce’, ’java’.

path

Ссылка на зависящий от операционной системы модуль для работы с именами файлов и путями, например, posixpath или macpath. Этот модуль может быть импортирован напрямую как os.path.

strerror(code) (UNIX, Windows)

Возвращает строку с сообщением о системной ошибке, соответствующим коду code.

21.1.1. Параметры процесса

Функции и объекты данных, описанные в этом разделе, предоставляют информацию и средства управления для текущего процесса.

environ

Отображение имен переменных окружения к их значениям. Например, environ[’HOME’] дает значение переменной окружения HOME. Если на используемой платформе доступна функция putenv(), отображение environ может быть также использовано для изменения значений переменных окружения. Функция putenv() автоматически вызывается при внесении изменений в environ. Если функция putenv() не доступна, Вы можете использовать измененное отображение в качестве аргумента функции, создающей дочерний процесс.

chdir(path)

getcwd()

Эти функции описаны в разделе 21.1.4.

ctermid() (UNIX)

Возвращает имя файла, соответствующего контролируемому текущим процессом терминалу.

getegid() (UNIX)

Возвращает идентификатор эффективной группы пользователей текущего процесса.

geteuid() (UNIX)

Возвращает идентификатор эффективного пользователя текущего процесса.

getgid() (UNIX)

Возвращает идентификатор группы пользователей текущего процесса.

getgroups() (UNIX)

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

getlogin() (UNIX)

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

getpgrp() (UNIX)

Возвращает идентификатор группы процессов текущего процесса.

getpid() (UNIX, Windows)

Возвращает идентификатор текущего процесса.

getppid() (UNIX)

Возвращает идентификатор родительского процесса.

getuid() (UNIX)

Возвращает идентификатор пользователя текущего процесса.

putenv(varname, value) (большинство вариантов UNIX, Windows)

Устанавливает значение переменной окружения с именем varname равным строке value. Эти изменения отражаются на дочерних процессах.

setegid(egid) (UNIX)

Устанавливает идентификатор эффективной группы пользователей текущего процесса равным egid.

seteuid(euid) (UNIX)

Устанавливает идентификатор эффективного пользователя текущего процесса равным euid.

setgid(gid) (UNIX)

Устанавливает идентификатор группы пользователей текущего процесса равным egid.

setpgrp() (UNIX)

Устанавливает идентификатор группы процессов текущего процесса равным идентификатору процесса (эквивалентно вызову ‘setpgid(0, 0)’).

setpgid(pid, pgrp) (UNIX)

Устанавливает идентификатор группы процессов процесса с идентификатором pid равным pgrp. Аргумент pid равный 0 обозначает текущий процесс. Если аргумент pgrp равен 0, в качестве идентификатора группы используется идентификатор процесса.

setreuid(ruid, euid) (UNIX)

Устанавливает идентификаторы реального и эффективного пользователей текущего процесса равными ruid и euid соответственно.

setregid(rgid, egid) (UNIX)

Устанавливает идентификаторы реальной и эффективной групп пользователей текущего процесса равными rgid и egid соответственно.

setsid() (UNIX)

Создает новые сессию и группу процессов с идентификаторами, равными идентификатору текущего процесса.

setuid(uid) (UNIX)

Устанавливает идентификатор пользователя текущего процесса равным uid.

umask(mask) (UNIX, Windows)

Устанавливает маску прав на доступ к файлам, которые будут созданы текущим процессом.

uname() (некоторые современные варианты UNIX)

Возвращает кортеж из пяти строк: имя системы, имя узла, выпуск, версия, тип машины. Некоторые системы обрезают имя узла, поэтому лучше воспользоваться вызовом socket.gethostname() или даже socket.gethostbyaddr(socket.gethostname()) (см. описание модуля socket).

21.1.2. Создание файловых объектов

Приведенные ниже функции создают новые файловые объекты.

fdopen(fd [, mode [, bufsize]]) (UNIX, Windows, Macintosh)

Возвращает файловый объект, связанный с файловым дескриптором fd. Аргументы mode и bufsize имеют такое же значение, как и соответствующие аргументы встроенной функции open().

popen(command [, mode [, bufsize]]) (UNIX, Windows)

Создает канал (pipe) с командой command и возвращает связанный с ним файловый объект. Вы можете читать вывод команды из файлового объекта или записывать в него входные данные в зависимости от режима mode: ’r’ (чтение, используется по умолчанию) или ’w’ (запись). Аргумент bufsize имеет такое же значение, как и соответствующий аргумент встроенной функции open(). Код завершения выполненной команды (в формате, аналогичном формату результата функции wait()) возвращается методом close() файлового объекта. Однако, если выполнение команды завершилось успешно (код завершения равен 0), метод close() возвращает None.

В предыдущих версиях под Windows эта функция вела себя ненадежно из-за некорректной работы функции _popen() библиотеки Windows. Начиная с версии 2.0, используется новая реализация.

tmpfile() (UNIX)

Создает и возвращает файловый объект для временного файла, открытого в режиме обновления (’w+’). Этот файл будет автоматически удален после уничтожения всех ассоциированных с ним файловых дескрипторов.

Для всех функций вида popen*() аргумент bufsize определяет размер буфера каналов и mode — режим, в котором будут открыты каналы (’t’ — текстовый, используется по умолчанию, или ’b’ — двоичный). Аналогичные функции доступны в модуле popen2, но элементы возвращаемого кортежа для них располагаются в ином порядке.

popen2(cmd [, bufsize [, mode]]) (UNIX, Windows)

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

popen3(cmd [, bufsize [, mode]]) (UNIX, Windows)

Выполняет команду cmd в качестве дочернего процесса и возвращает кортеж из файловых объектов, соответствующих его стандартным потокам ввода, вывода и ошибок. Функция доступна, начиная с версии 2.0.

popen4(cmd [, bufsize [, mode]]) (UNIX, Windows)

Выполняет команду cmd в качестве дочернего процесса и возвращает кортеж из двух файловых объектов: соответствующий его стандартному потоку ввода и объединенному потоку вывода и ошибок. Функция доступна, начиная с версии 2.0.

21.1.3. Операции с файловыми дескрипторами

В этом разделе описаны операции низкого уровня над потоками с использованием файловых дескрипторов.

close(fd) (UNIX, Windows, Macintosh)

Закрывает файловый дескриптор fd.

dup(fd) (UNIX, Windows, Macintosh)

Возвращает дубликат файлового дескриптора fd.

dup2(fd1, fd2) (UNIX, Windows)

Копирует файловый дескриптор fd1 в fd2, предварительно закрыв последний, если это необходимо.

fpathconf(fd, name) (UNIX)

Возвращает системную информацию, относящуюся к открытому файлу. Аргумент name должен быть строкой с именем системного значения или целым числом. Известные для данной ОС имена системных значений даны в словаре pathconf_names. Если имя name не известно, генерируется исключение ValueError. Если имя не поддерживается ОС (даже если оно включено в pathconf_names), генерируется исключение OSError с errno.EINVAL в качестве номера ошибки.

fstat(fd) (UNIX, Windows)

Возвращает информацию о файловом дескрипторе fd в виде, аналогичном тому, в котором возвращает результат функция stat().

fstatvfs(fd) (UNIX)

Возвращает информацию о файловой системе, на которой находится файл, ассоциированный с файловым дескриптором fd, в виде, аналогичном тому, в котором возвращает результат функция statvfs().

ftruncate(fd, length) (UNIX)

Укорачивает файл, соответствующий дескриптору fd, так, чтобы его длина была не более length байт.

isatty(fd) (UNIX)

Возвращает 1, если дескриптор файла fd открыт и связан с tty-подобным устройством, иначе возвращает 0.

lseek(fd, offset, whence) (UNIX, Windows, Macintosh)

Устанавливает текущую позицию в файле, соответствующего дескриптору fd. Аргумент whence указывает точку отсчета: 0 — начало файла, 1 — текущая позиция и 2 — конец файла.

open(filename, flags [, mode]) (UNIX, Windows, Macintosh)

Открывает файл с именем filename, устанавливает для него различные флаги в соответствии с аргументом flags и права на доступ в соответствии с аргументом mode (по умолчанию 0777) и текущим значением маски (umask). Возвращает дескриптор открытого файла. В качестве флагов могут быть использованы константы, описанные в конце раздела, объединенные оператором ‘|’.

openpty() (некоторые варианты UNIX)

Открывает новую пару псевдотерминалов и возвращает пару дескрипторов ‘(master, slave)’ для pty и tty соответственно.

pipe() (UNIX, Windows)

Создает канал и возвращает пару дескрипторов ‘(r, w)’, которые могут использоваться для чтения и записи соответственно.

read(fd, n) (UNIX, Windows, Macintosh)

Считывает не более n байт из файла, ассоциированного с дескриптором fd. Возвращает строку из считанных байтов.

tcgetpgrp(fd) (UNIX)

Возвращает идентификатор группы процессов, ассоциированной с терминалом, дескриптор которого использован в качестве аргумента fd.

tcsetpgrp(fd, pg) (UNIX)

Устанавливает идентификатор группы процессов, ассоциированной с терминалом, дескриптор которого использован в качестве аргумента fd, равным pg.

ttyname(fd) (UNIX)

Возвращает имя терминала, ассоциированного с дескриптором fd. Если fd не является дескриптором устройства tty, генерируется исключение.

write(fd, str) (UNIX, Windows, Macintosh)

Записывает строку str в файл, ассоциированный с дескриптором fd. Возвращает количество реально записанных байтов.

В качестве аргумента flags функции open() могут использоваться следующие константы, объединенные оператором ‘|’:

O_RDONLY (UNIX, Windows, Macintosh)

O_WRONLY (UNIX, Windows, Macintosh)

O_RDWR (UNIX, Windows, Macintosh)

Определяют доступ к файлу: только для чтения, только для записи или для чтения и записи.

O_APPEND (UNIX, Windows, Macintosh)

Дописывать данные в конец файла.

O_CREAT (UNIX, Windows, Macintosh)

Создать файл, если он не существует.

O_EXCL (UNIX, Windows, Macintosh)

Открывать файл только, если он не существует.

O_TRUNC (UNIX, Windows, Macintosh)

Если файл существует, его содержимое будет удалено.

O_NDELAY (UNIX)

O_NONBLOCK (UNIX)

Открыть файл без блокировки.

O_DSYNC (UNIX)

O_RSYNC (UNIX)

O_SYNC (UNIX)

Открыть файл для синхронного ввода/вывода.

O_NOCTTY (UNIX)

Если файл является устройством tty, он не станет терминалом, контролирующим текущий процесс.

O_BINARY (Windows, Macintosh)

O_TEXT (Windows, Macintosh)

Открыть файл в двоичном или текстовом режиме.

21.1.4. Файлы и каталоги

access(path, mode) (UNIX, Windows)

Проверяет доступ текущего процесса к файлу (каталогу) path на чтение, запись и/или выполнение. Аргумент mode должен быть равен F_OK для проверки существования файла или одна или несколько (объединенных оператором ‘|’) констант из R_OK, W_OK и X_OK для проверки доступа. Возвращает 1, если доступ разрешен, иначе возвращает 0.

F_OK

Используется в качестве аргумента mode функции access() для проверки наличия файла.

R_OK

Используется в качестве аргумента mode функции access() для проверки доступа к файлу на чтение.

W_OK

Используется в качестве аргумента mode функции access() для проверки доступа к файлу на запись.

X_OK

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

chdir(path) (UNIX, Windows, Macintosh)

Изменяет текущий рабочий каталог на path.

getcwd() (UNIX, Windows, Macintosh)

Возвращает строку, представляющую текущий рабочий каталог.

chmod(path, mode) (UNIX, Windows)

Изменяет режим доступа к файлу (каталогу) на mode (целое число).

chown(path, uid, gid) (UNIX)

Изменяет идентификаторы пользователя и группы пользователей файла (каталога) path на uid и gid соответственно.

link(src, dst) (UNIX)

Создает жесткую ссылку с именем dst, указывающую на src.

listdir(path) (UNIX, Windows, Macintosh)

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

lstat(path) (UNIX)

Работает аналогично функции stat(), но не следует символическим ссылкам.

mkfifo(path [, mode]) (UNIX)

Создает канал (FIFO) с именем path и режимом доступа mode (целое число, по умолчанию равен 0666) с учетом текущего значения маски доступа (umask). С именованными каналами работают как с обычными файлами. Созданный канал существует до тех пор, пока он не будет удален, например, с помощью функции unlink(). Обычно сервер открывает именованный канал для чтения и клиент — для записи.

mkdir(path [, mode]) (UNIX, Windows, Macintosh)

Создает каталог с именем path и режимом доступа mode (целое число, по умолчанию используется 0777) с учетом маски доступа (umask).

makedirs(path [, mode])

Функция для рекурсивного создания каталогов. Работает аналогично функции mkdir(), но автоматически создает все необходимые промежуточные каталоги. Генерирует исключение IOError, если каталог path уже присутствует или не может быть создан.

pathconf(path, name) (UNIX)

Возвращает системную информацию, относящуюся к файлу с именем path. Аргумент name должен быть строкой с именем системного значения или целым числом. Известные для данной ОС имена системных значений даны в словаре pathconf_names. Если имя name неизвестно, генерируется исключение ValueError. Если имя не поддерживается ОС (даже если оно включено в pathconf_names), генерируется исключение OSError с errno.EINVAL в качестве номера ошибки.

pathconf_names (UNIX)

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

readlink(path) (UNIX)

Возвращает строку с именем файла (каталога), на который указывает символическая ссылка path.

remove(path) (UNIX, Windows, Macintosh)

unlink(path) (UNIX, Windows, Macintosh)

Удаляют файл с именем path. Для удаления каталогов воспользуйтесь функцией rmdir().

removedirs(path)

Функция для рекурсивного удаления каталогов. Работает аналогично функции rmdir(), но также рекурсивно удаляет и пустые родительские каталоги (если это возможно). Генерирует исключение IOError, если каталог path не может быть удален.

rename(src, dst) (UNIX, Windows, Macintosh)

Переименовывает файл (каталог) src в dst.

renames(old, new)

Функция для рекурсивного переименования. Работает аналогично функции rename(), но сначала пытается создать родительские каталоги, необходимые для создания new. После переименования old в new удаляет правую часть пути old с помощью функции removedirs().

rmdir(path) (UNIX, Windows, Macintosh)

Удаляет каталог с именем path.

stat(path) (UNIX, Windows, Macintosh)

Возвращает информацию о файле (каталоге) path в виде кортежа, содержащего как минимум 10 наиболее важных (и переносимых) целочисленных элементов в следующем порядке: st_mode, st_ino, st_dev, st_nlink, st_uid, st_gid, st_size, st_atime, st_mtime, st_ctime. В стандартном модуле stat определены функции и константы, которые будут полезны для обработки результата. Под ОС Windows некоторые элементы будут иметь произвольные значения.

statvfs(path) (UNIX)

Возвращает информацию о файловой системе, на которую ссылается путь path, в виде кортежа из 10 наиболее общих целочисленных элементов в следующем порядке: f_bsize, f_frsize, f_blocks, f_bfree, f_bavail, f_files, f_ffree, f_favail, f_flag, f_namemax. В стандартном модуле statvfs определены функции и константы, которые будут полезны для обработки результата.

symlink(src, dst) (UNIX)

Создает символическую ссылку с именем dst, указывающую на src.

tempnam([dir [, prefix]]) (UNIX)

Возвращает уникальное имя, подходящее для создания временного файла в каталоге dir. Если аргумент dir опущен или равен None, используется общепринятое место для временных файлов. Если задан и не равен None аргумент prefix (строка), он используется в качестве приставки к имени временного файла. Функция доступна, начиная с версии 1.6.

tmpnam() (UNIX)

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

TMP_MAX

Максимальное количество уникальных имен, которые может сгенерировать функция tmpnam() перед тем, как использовать их снова. Эта константа доступна, начиная с версии 1.6.

utime(path, times) (UNIX, Windows, Macintosh)

Устанавливает время последнего доступа и последнего внесения изменений файла path. Начиная с версии 2.0, в качестве аргумента times Вы можете использовать None для того, чтобы установить текущее время. Иначе times должен быть кортежем вида ‘(atime, mtime)’, где atime — время последнего доступа и mtime — время последнего внесения изменений.

21.1.5. Управление процессами

Функции, описанные в этом разделе, предназначены для создания и управления процессами.

Функциям с именами вида exec*() передается список аргументов запускаемой программы. Во всех случаях первый из них передается как собственное имя программы, а не как аргумент командной строки, то есть sys.argv[0], если Вы запускаете программу на языке Python. Например, ‘os.execv('/bin/echo', ['foo', 'bar'])’ выведет слово “bar” на стандартный поток вывода, в то время как строка ’foo’ просто игнорируется.

abort() (UNIX, Windows)

Посылает сигнал SIGABRT текущему процессу. По умолчанию в UNIX сигнал SIGABRT приводит к прерыванию процесса и сохранению дампа памяти (‘core’), под Windows процесс прерывается с кодом завершения, равным 3. Программа может зарегистрировать другой обработчик сигнала с помощью функции signal.signal().

execl(path [, arg1 ...]) (UNIX, Windows)

Эквивалентно вызову ‘execv(path, (arg1, ...))’.

execle(path [, arg1 ...], env) (UNIX, Windows)

Эквивалентно вызову ‘execve(path, (arg1, ...), env)’.

execlp(path [, arg1 ...]) (UNIX, Windows)

Эквивалентно вызову ‘execvp(path, (arg1, ...))’.

execv(path, args) (UNIX, Windows)

Выполняет файл path со списком аргументов args (кортеж или список), заменяя текущий процесс (то есть интерпретатор).

execve(path, args, env) (UNIX, Windows)

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

execvp(path, args) (UNIX, Windows)

Ищет в путях (environ[’PATH’]) файл path и выполняет его аналогично функции execv().

execvpe(path, args, env) (UNIX, Windows)

Ищет в путях (env[’PATH’]) файл path и выполняет его аналогично функции execve().

_exit(code) (UNIX, Windows)

Прерывает выполнение программы с кодом завершения code без выполнения каких-либо дополнительных действий. Нормальным способом прерывания выполнения программы является вызов sys.exit(n). Функцию _exit() следует использовать только в дочернем процессе после вызова fork().

fork() (UNIX)

Создает ответвление от текущего процесса. Возвращает 0 в дочернем процессе и идентификатор дочернего процесса в родительском.

forkpty() (некоторые варианты UNIX)

Создает ответвление от текущего процесса, используя новый псевдотерминал в качестве терминала, контролирующего дочерний процесс. Возвращает пару ‘(pid, fd)’, где pid равен 0 в дочернем процессе и идентификатору дочернего процесса в родительском и fd является файловым дескриптором псевдотерминала. Для большей переносимости используйте модуль pty.

kill(pid, sig) (UNIX)

Посылает сигнал sig процессу с идентификатором pid. Смотрите также описание модуля signal.

nice(increment) (UNIX)

Добавляет значение increment к текущему приоритету процесса, возвращает новый приоритет.

plock(op) (UNIX)

Блокирует в памяти сегменты программы. Эта функция доступна, начиная с версии 2.0.

spawnv(mode, path, args) (UNIX, Windows)

Выполняет отдельным процессом файл path с аргументами args (кортеж или список). Аргумент mode может иметь значения, описанные ниже. На платформах UNIX эта функция доступна, начиная с версии 1.6.

spawnve(mode, path, args, env) (UNIX, Windows)

Выполняет отдельным процессом файл path с аргументами args (кортеж или список) и используя env в качестве окружения. Аргумент mode может иметь значения, описанные ниже. На платформах UNIX эта функция доступна, начиная с версии 1.6.

P_WAIT (UNIX, Windows)

P_NOWAIT (UNIX, Windows)

P_NOWAITO (UNIX, Windows)

P_OVERLAY (Windows)

P_DETACH (Windows)

Возможные значения аргумента mode функций spawnv() и spawnve().

startfile(path) (Windows)

Открывает файл, используя ассоциированную с расширением (или типом) path программу, аналогично команде start стандартного командного интерпретатора Windows (или двойному щелчку мыши в Explorer). Функция заканчивает свое выполнение сразу же после запуска. Не существует способа дождаться завершения выполнения программы или определения ее кода завершения. Используйте функцию os.path.normpath() для приведения пути к правильному виду. Функция startfile() доступна, начиная с версии 2.0.

system(command) (UNIX, Windows)

Выполняет в стандартном для данной платформы командном интерпретаторе команду command (строка). Возвращает код завершения в формате, аналогичном формату результата функции wait(), за исключением Windows 95 и 98 — в этих ОС всегда возвращает 0.

times() (UNIX, Windows)

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

wait() (UNIX)

Ждет завершения дочернего процесса и возвращает кортеж вида ‘(pid, code)’, где pid — идентификатор дочернего процесса и code — код, младший байт которого содержит номер сигнала, завершившего выполнение процесса (старший бит установлен, если был записан дамп памяти), а старший байт — код завершения (если номер сигнала равен 0).

waitpid(pid, options) (UNIX)

Ждет завершения дочернего процесса, заданного аргументом pid, и возвращает кортеж вида ‘(pid, code)’ (см. описание функции wait()). Точная семантика функции зависит от значения аргумента options, который должен быть равен 0 для обычных операций.

Если аргумент pid больше 0, waitpid() запрашивает информацию для процесса с идентификатором pid. Если аргумент pid равен 0, запрашивается информация для любого дочернего процесса из той же группы, что и текущий процесс. Если аргумент pid равен -1, запрашивается информация для любого дочернего процесса. Если аргумент pid меньше -1, запрашивается информация для любого процесса в группе с идентификатором -pid (абсолютное значение аргумента pid).

WNOHANG (UNIX)

При использовании этой опция функция waitpid() не ожидает завершения процесса, а возвращает информацию только, если она сразу доступна.

Следующие функции позволяют извлечь информацию из закодированного кода завершения, возвращаемого функциями system(), wait() и waitpid():

WIFSTOPPED(code) (UNIX)

Возвращает истину, если процесс был остановлен.

WIFSIGNALED(code) (UNIX)

Возвращает истину, если процесс был завершен сигналом.

WIFEXITED(code) (UNIX)

Возвращает истину, если процесс был завершен системным вызовом функции exit().

WEXITSTATUS(code) (UNIX)

Если выражение WIFEXITED(code) верно, возвращает целочисленный параметр, использованный при системном вызове функции exit(), в противном случае возвращаемое значение не несет какого-либо смысла.

WSTOPSIG(code) (UNIX)

Возвращает номер сигнала, который привел к остановке процесса.

WTERMSIG(code) (UNIX)

Возвращает номер сигнала, который привел к завершению процесса.

21.1.6. Различная системная информация

confstr(name) (UNIX)

Возвращает строку, содержащую системную конфигурационную информацию. Аргумент name должен быть строкой с именем системного значения или целым числом. Известные для данной ОС имена системных значений даны в словаре confstr_names. Если системное значение name не задано, возвращает пустую строку. Если имя name неизвестно, генерируется исключение ValueError. Если имя не поддерживается ОС (даже если оно включено в confstr_names), генерируется исключение OSError с errno.EINVAL в качестве номера ошибки.

confstr_names (UNIX)

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

sysconf(name) (UNIX)

Возвращает целое системное конфигурационное значение. Аргумент name должен быть строкой с именем системного значения или целым числом. Известные для данной ОС имена системных значений даны в словаре sysconf_names. Если системное значение name не задано, возвращает -1. Если имя name неизвестно, генерируется исключение ValueError. Если имя не поддерживается ОС (даже если оно включено в sysconf_names), генерируется исключение OSError с errno.EINVAL в качестве номера ошибки.

sysconf_names (UNIX)

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

Следующие константы используются при работе с именами путей. Операции высокого уровня над именами путей определены в модуле os.path.

curdir

Строка, используемая для ссылки на текущий каталог, например ’.’ или ’:’.

pardir

Строка, используемая для ссылки на родительский каталог, например ’..’ или ’::’.

sep

Символ, который используется ОС для разделения компонент пути, например, ’/’, ’\’ или ’:’.

altsep

Альтернативный символ, используемый ОС для разделения компонент пути, или None, если имеется только один символ. В DOS и Windows эта константа имеет значение ’/’.

pathsep

Символ, который обычно используется ОС для разделения имен путей в списке (как в переменной окружения PATH), например, ’:’ или ’;’.

defpath

Путь поиска исполняемых файлов по умолчанию, если не установлена переменная окружения PATH.

linesep

Последовательность символов, которая используется для завершения строк на данной платформе, например, ’\n’, ’\r’ или ’\r\n’.

21.2. os.path — работа с именами путей

Этот модуль определяет полезные операции над именами путей.

abspath(path)

Возвращает нормализованную абсолютную версию пути path. На большинстве платформ вызов этой функции эквивалентен вызову ‘normpath(join(os.getcwd(), path))’.

basename(path)

Возвращает основное имя (basename) пути path. Это второй элемент пары split(path). Обратите внимание, что поведение этой функции отличается от поведения программы basename, которая для ’/foo/bar/’ выводит ’bar’, в то время как функция basename() возвращает пустую строку.

commonprefix(list)

Возвращает наибольшую общую часть путей в списке list (произвольная последовательность), полученную посимвольным сравнением (то есть результат может и не быть корректным путем). Если список list пуст, возвращает пустую строку ('').

dirname(path)

Возвращает имя каталога в пути path. Это первый элемент пары split(path).

exists(path)

Возвращает 1, если путь с именем path (файл или каталог) существует, иначе возвращает 0.

expanduser(path)

Возвращает аргумент с компонентом вида ‘~’ или ‘~user’, замененным домашним каталогом пользователя. ‘~’ заменяется значением переменной окружения HOME, поиск имени домашнего каталога для пользователя user производится с помощью модуля pwd. Если замена по каким-либо причинам не может быть произведена или путь не начинается с символа ‘~’, возвращает path без изменений.

expandvars(path)

Возвращает аргумент с компонентами вида ‘$name’ и ‘${name}’, замененными значением переменной окружения name. Некорректные имена и имена, ссылающиеся на неопределенные переменные, оставляются в строке path без изменений. При использовании ОС Macintosh всегда возвращает path без изменений.

getatime(path)

Возвращает время (число секунд с начала эпохи, см. описание модуля time) последнего доступа к файлу (каталогу) path. Генерирует исключение IOError, если файл не существует или не доступен.

getmtime(path)

Возвращает время (число секунд с начала эпохи, см. описание модуля time) последнего внесения изменений в файл (каталог) path. Генерирует исключение IOError, если файл не существует или не доступен.

getsize(path)

Возвращает размер в байтах файла (каталога) path. Генерирует исключение IOError, если файл не существует или не доступен.

isabs(path)

Возвращает 1, если путь path является абсолютным.

isfile(path)

Возвращает 1, если путь path указывает на существующий обычный файл, иначе возвращает 0. Эта функция следует символическим ссылкам, то есть функции islink() и isfile() могут обе возвращать истину для одного и того же пути.

isdir(path)

Возвращает 1, если путь path указывает на существующий каталог, иначе возвращает 0. Эта функция следует символическим ссылкам, то есть функции islink() и isdir() могут обе возвращать истину для одного и того же пути.

islink(path)

Возвращает 1, если путь path является символической ссылкой, иначе возвращает 0. Всегда возвращает 0, если символические ссылки не поддерживаются.

ismount(path)

Возвращает 1, если путь path является точкой монтирования, то есть каталог path и родительский для него каталог находятся на разных устройствах (разделах) или ссылаются на один и тот же узел (i-node) одного устройства.

join(path1 [, path2 ...])

Объединяет компоненты пути. Если какой-либо компонент является абсолютным путем, все предыдущие компоненты отбрасываются и объединение продолжается. Возвращаемое значение является объединением всех непустых строк path1, path2 и т. д., в качестве разделителя используется os.sep. Если последний аргумент является пустой строкой, результат заканчивается символом os.sep.

normcase(path)

Возвращает path с нормализованным регистром букв. На платформах UNIX возвращает аргумент без изменений. Для файловых систем, нечувствительных к регистру букв, преобразует все буквы к нижнему регистру. Под Windows также заменяет символы косой черты (os.altsep) на символы обратной косой черты (os.sep).

normpath(path)

Возвращает нормализованное имя пути path. Эта функция сворачивает излишние разделители и ссылки на текущий и родительский каталоги, то есть имена путей ’A//B’, ’A/./B’ и ’A/foo/../B’ преобразуются к ’A/B’. Под Windows также заменяет символы косой черты (os.altsep) на символы обратной косой черты (os.sep). Функция normpath() не нормализует регистр букв — для этих целей используйте функцию normcase().

samefile(path1, path2) (UNIX, Macintosh)

Возвращает 1, если оба пути ссылаются на один и тот же файл (каталог), иначе возвращает 0. Генерирует исключение IOError, если вызов os.stat() для какого-либо пути заканчивается ошибкой.

sameopenfile(file1, file2) (UNIX, Macintosh)

Возвращает 1, если файловые объекты file1 и file2 ссылаются на один и тот же файл (файловые объекты могут представлять разные файловые дескрипторы), иначе возвращает 0.

samestat(stat1, stat2) (UNIX, Macintosh)

Возвращает 1, если кортежи stat1 и stat2 (результат, возвращаемый функциями fstat(), lstat() и stat()) ссылаются на один и тот же файл.

split(path)

Разбивает имя пути path на пару строк ‘(head, tail)’, где tail — последний компонент пути и head — остальная часть пути. tail никогда не содержит символа os.sep: если путь path заканчивается этим символом, tail будет пустой строкой. Завершающие символы os.sep в head отбрасываются, за исключением случаев, когда path ссылается на корневой каталог. В любом случае ‘join(head, tail)’ дает путь, эквивалентный path.

splitdrive(path)

Разбивает имя пути path на пару строк ‘(drive, tail)’, где drive — спецификатор логического диска или пустая строка и head — остальная часть пути. В системах, которые не используют спецификаторы логических дисков drive всегда является пустой строкой. В любом случае выражение ‘drive + tail == path’ всегда верно.

splitext(path)

Разбивает имя пути path на пару строк ‘(root, ext)’ так, чтобы выполнялось условие ‘root + ext == path’ и строка ext была пустой или начиналась с точки и содержала не более одной точки.

walk(path, visit, arg)

Вызывает ‘visit(arg, dirname, names)’ для каждого каталога в дереве, начиная с path (включая каталог path). Аргумент dirname указывает имя каталога, для которого вызывается функция visit, а names является списком файлов и каталогов в каталоге dirname (os.listdir(dirname), то есть используется путь относительно каталога dirname). Функция visit может вносить изменения в names и, тем самым, оказывать влияние на то, какие каталоги будут посещаться далее по дереву, то есть чтобы избежать посещения каких-либо частей дерева каталогов.

21.3. stat — интерпретация os.stat()

Этот модуль определяет константы и функции, необходимые для интерпретации элементов кортежа ‘(st_mode, st_ino, st_dev, st_nlink, st_uid, st_gid, st_size, st_atime, st_mtime, st_ctime ...)’, возвращаемого функциями os.stat(), os.lstat() и os.fstat().

S_ISDIR(st_mode)

Истина, если аргумент st_mode получен для каталога.

S_ISCHR(st_mode)

Истина, если аргумент st_mode получен для специального файла, представляющего устройство посимвольного ввода/вывода.

S_ISBLK(st_mode)

Истина, если аргумент st_mode получен для специального файла, представляющего блочное устройство.

S_ISREG(st_mode)

Истина, если аргумент st_mode получен для обычного файла.

S_ISFIFO(st_mode)

Истина, если аргумент st_mode получен для именованного канала (FIFO).

S_ISLNK(st_mode)

Истина, если аргумент st_mode получен для символической ссылки.

S_ISSOCK(st_mode)

Истина, если аргумент st_mode получен для канала сетевого соединения (socket).

S_IMODE(st_mode)

Возвращает часть состояния, которую можно установить с помощью функции os.chmod() — доступ, sticky bit, set-group-id и set-user-id.

S_IFMT(st_mode)

Возвращает часть состояния, описывающую тип файла (используется функциями S_IS*(), описанными выше).

Обычно гораздо удобнее воспользоваться функциями os.path.is*() (см. описание модуля os.path) для определения типа файла. Описанные в этом разделе функции полезны в тех случаях, когда необходимо выполнить несколько проверок для одного и того же файла, и Вы хотите избежать накладных расходов на вызов системной функции stat() для каждой проверки.

Следующие переменные являются символическими индексами для кортежа, возвращаемого функциями os.stat(), os.fstat() и os.lstat().

ST_MODE

Режим защиты файла.

ST_INO

Внутренний номер файла (i-node).

ST_DEV

Номер устройства, на котором файл расположен.

ST_NLINK

Количество (жестких) ссылок на файл.

ST_UID

Идентификатор пользователя-владельца.

ST_GID

Идентификатор группы-владельца.

ST_SIZE

Размер файла в байтах.

ST_ATIME

Время последнего доступа.

ST_MTIME

Время последнего внесения изменений.

ST_CTIME

Время последнего изменения статуса.

Приведем простой пример:

import os, sys
from stat import *

def visit(arg, dir, names):
    for name in names:
        fullname = os.path.join(dir, name)
        mode = os.stat(fullname)[ST_MODE]
        if S_ISDIR(mode):
            print 'Каталог', fullname
        elif S_ISREG(mode):
            print 'Обычный файл', fullname
        else:
            print 'Файл неизвестного типа', fullname

if __name__ == '__main__':
    os.path.walk(sys.argv[1], visit, None)

21.4. statvfs — интерпретация os.statvfs()

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

F_BSIZE

Предпочтительный размер блоков для данной файловой системы.

F_FRSIZE

Основной размер блоков для данной файловой системы.

F_BLOCKS

Общее число блоков.

F_BFREE

Число свободных блоков.

F_BAVAIL

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

F_FILES

Общее число файловых узлов (то есть максимальное возможное число файлов).

F_FFREE

Число свободных файловых узлов.

F_FAVAIL

Число файловых узлов, доступных рядовому пользователю.

F_FLAG

Флаги, их значение зависит от используемой системы.

F_NAMEMAX

Максимальная длина имен файлов.

21.5. filecmp — сравнение файлов и каталогов

Модуль filecmp предоставляет функции для быстрого и полного сравнения файлов и каталогов.

cmp(f1, f2 [, shallow])

Сравнивает файлы с именами f1 и f21. Возвращает 1, если они одинаковые, иначе возвращает 0. По умолчанию производится поверхностное сравнение, используя информацию, возвращаемую функцией os.stat(). Однако, если задан и является ложью аргумент shallow, при необходимости будет производиться полное сравнение содержимого файлов.

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

cmpfiles(dir1, dir2, common [, shallow])

Сравнивает файлы, имена которых перечислены в common (произвольная последовательность), в каталогах dir1 и dir2 [На самом деле функции cmp() и cmpfiles() имеет еще один необязательный аргумент. Мы намеренно его не документируем, так как его использование не переносимо, а иногда и опасно.]. Возвращает кортеж из трех списков имен ‘(match, mismatch, errors)’. Список match содержит имена файлов, одинаковых в обоих каталогах, список mismatch — разных и errros содержит имена файлов, которые по каким-либо причинам не удается сравнить (например, к ним нет доступа). Аргумент shallow имеет такое же значение, как и в функции cmp().

Кроме того, модуль определяет класс, позволяющий сравнивать содержимое каталогов (включая содержимое вложенных каталогов):

dircmp(dir1, dir2 [, ignore])

Конструирует новый объект, предназначенный для сравнения каталогов dir1 и dir2. Имена, перечисленные в списке ignore (по умолчанию равен ‘[’RCS’, ’CVS’, ’tags’]’), игнорируются.

Экземпляры класса dircmp имеют следующие методы и атрибуты данных:

report()

Выводит на стандартный поток вывода (sys.stdout) подробный отчет о сравнении каталогов.

report_partial_closure()

Выводит на стандартный поток вывода (sys.stdout) подробный отчет о сравнении каталогов и одного уровня вложенных каталогов.

report_full_closure()

Выводит на стандартный поток вывода (sys.stdout) подробный отчет о сравнении каталогов и рекурсивно всех вложенных каталогов.

left_list

Список имен файлов и каталогов в dir1, не указанных в аргументе ignore.

right_list

Список имен файлов и каталогов в dir2, не указанных в аргументе ignore.

common

Список имен файлов и каталогов, которые присутствуют как в dir1, так и в dir2.

left_only

Список имен файлов и каталогов, которые присутствуют только в dir1.

right_only

Список имен файлов и каталогов, которые присутствуют только в dir2.

common_dirs

Список имен каталогов, которые присутствуют как в dir1, так и в dir2.

common_files

Список имен файлов, которые присутствуют как в dir1, так и в dir2.

common_funny

Список имен, найденных в обоих каталогах, но имеющих разный тип или дающих ошибку при вызове функции os.stat().

same_files

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

diff_files

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

funny_files

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

subdirs

Словарь, отображающий имена каталогов из списка common_dirs в экземпляры класса dircmp для этих каталогов.

Заметим, что значения атрибутов вычисляются по мере необходимости, а не сразу при конструировании объекта. Это позволяет избежать излишних расходов при запросе значений только тех атрибутов, которые можно быстро вычислить. Однажды вычисленное значение сохраняется и используется при дальнейших запросах.

21.6. popen2 — доступ к потокам ввода/вывода дочерних процессов

Модуль доступен в операционных системах UNIX и Windows (начиная с версии 2.0).

Модуль popen2 позволяет порождать подпроцессы и иметь доступ к их стандартным потокам ввода, вывода и ошибок. Во всех случаях команда выполняется в стандартном для данной платформы интерпретаторе команд (устанавливается переменной окружения SHELL в UNIX и COMSPEC в Windows). Заметим, что, начиная с версии 2.0, функциональность этого модуля доступна через одноименные функции модуля os, имеющие аналогичный интерфейс, но возвращающие кортеж с другим порядком следования элементов.

Основной интерфейс модуля представлен тремя функциями. Для всех функций аргумент bufsize определяет размер буфера каналов и mode (начиная с версии 2.0) — режим, в котором будут открыты каналы (’t’ — текстовый, используется по умолчанию, или ’b’ — двоичный).

popen2(cmd [, bufsize [, mode]])

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

popen3(cmd [, bufsize [, mode]])

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

popen4(cmd [, bufsize [, mode]])

Выполняет команду cmd в качестве дочернего процесса и возвращает кортеж из двух файловых объектов: соответствующий его объединенному потоку вывода и ошибок и стандартному потоку ввода. Функция доступна, начиная с версии 2.0.

Кроме того, модуль определяет следующие классы (на платформе UNIX они используются для реализации описанных выше функций):

Popen3(cmd [, capturestderr [, bufsize]]) (UNIX)

Конструирует и возвращает объект, представляющий дочерний процесс. Если задан и является истиной аргумент capturestderr, возвращаемый объект будет перехватывать стандартный поток ошибок дочернего процесса. Аргумент bufsize указывает размер буфера потоков.

Popen4(cmd [, bufsize]) (UNIX)

Этот класс аналогичен классу Popen3, но всегда направляет стандартные потоки вывода и ошибок дочернего процесса в один файловый объект.

Экземпляры классов Popen3 и Popen4 имеют следующие методы и атрибуты данных:

poll()

Возвращает -1, если выполнение дочернего процесса еще не закончилось, в противном случае возвращает код завершения.

wait()

Ждет окончания выполнения дочернего процесса и возвращает код завершения.

fromchild

Файловый объект, представляющий стандартный поток вывода дочернего процесса. Для экземпляров класса Popen4 этот объект представляет объединение стандартных потоков вывода и ошибок дочернего процесса.

tochild

Файловый объект, представляющий стандартный поток ввода дочернего процесса.

childerr

Файловый объект, представляющий стандартный поток ошибок дочернего процесса, если аргумент capturestderr конструктора являлся истиной, иначе None. Для экземпляров класса Popen4 всегда равен None.

pid

Идентификатор дочернего процесса.

21.7. time — определение и обработка времени

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

Немного о терминологии и принятых соглашениях.

• Отсчет времени начинается с начала эпохи, 0 часов 1 января определенного года. Для платформ UNIX это 1970 год. Чтобы определить начало эпохи для Вашей платформы, взгляните на gmtime(0).
• Функции в этом модуле не могут работать с временем до начала эпохи и после некоторого момента в будущем. Последняя точка определяется библиотекой языка C, лежащей в основе реализации. Для платформы UNIX это обычно 2038 год.
• Реализация библиотек Python зависит от библиотеки языка C для данной платформы, которая обычно не имеет проблем с 2000 годом, так как время представляется числом секунд, прошедших с начала эпохи. Функции, работающие с представлением времени в виде кортежа, как правило, требуют все четыре цифры года. Для совместимости с предыдущими версиями допускается использование двух цифр, если переменная accept2dyear не равна нулю. По умолчанию эта переменная равна 1, однако, если переменная окружения PYTHONY2K установлена и равна непустой строке, accept2dyear инициализируется нулем. Таким образом, Вы можете запретить использование только двух цифр, установив переменную окружения PYTHONY2K равной непустой строке.
  Если представление года двумя цифрами воспринимается, оно преобразуется в соответствии со стандартами POSIX и X/Open: значения 69–99 преобразуются к 1969–1999 и 0–68 к 2000–2068. Значения 100–1899 в любом случае запрещены.
• UTC — Universal Coordinated Time, универсальное синхронизированное время, известное также как GMT (Greenwich Mean Time, среднее время по Гринвичу).
• DST—Daylight Saving Time, летнее время—корректировка часового пояса (обычно) на один час в течение части года. Правила перехода на летнее время определяются местными законами и могут меняться от года к году. Библиотека языка C имеет таблицу с локальными правилами и является в этом отношении единственным верным источником.
• Точность различных функций, работающих в реальном времени, может быть меньше, чем Вы могли бы предположить исходя из единиц, с которыми они работают.
  С другой стороны, точность функций time() и sleep() выше, чем точность одноименных функций библиотеки C на платформе UNIX: время в них выражается вещественным числом, функция time() наиболее точное время (используя функцию gettimeofday() языка C, если она доступна), функция sleep() воспринимает время с ненулевой дробной частью (используя функцию select() языка C, если она доступна).
• Представление времени в виде кортежа, возвращаемое функциями gmtime(), localtime() и strptime() и воспринимаемое функциями asctime(), mktime() и strftime(), содержит 9 целочисленных элементов:

Обратите внимание, что в отличие от аналогичной структуры в языке C, значения месяцев находится в диапазоне 1–12, а не 0–11. Значение года обрабатывается так, как описано выше. Флаг коррекции для летнего времени равный -1, как правило, приводит к автоматическому выбору правильного состояния.

Модуль определяет следующие функции и объекты данных:

accept2dyear

Если эта переменная не равна нулю, допускается использование представления года двумя цифрами. По умолчанию эта переменная равна 1, однако, если переменная окружения PYTHONY2K установлена и равна непустой строке, accept2dyear инициализируется нулем. Таким образом, Вы можете запретить использование только двух цифр, установив переменную окружения PYTHONY2K равной непустой строке. Вы можете также менять значение accept2dyear во время выполнения программы.

altzone()

Сдвиг локального часового пояса с учетом перехода на летнее время в секундах на запад от UTC. Это значение всегда отрицательно, если часовой пояс находится восточнее UTC (в том числе и Россия). Используйте эту функцию, только если значение переменной daylight не равно нулю.

asctime(time_tuple)

Преобразует кортеж time_tuple, представляющий время (возвращается функциями gmtime(), localtime() и strptime()), в строку из 24 символов вида ’Sun Jun 20 23:21:05 1993’. Обратите внимание, что в отличие от одноименной функции языка C, строка не завершается символом перехода на новую строку.

clock()

Возвращает текущее процессорное время в секундах в виде вещественного числа. Точность возвращаемого времени зависит от точности одноименной функции библиотеки языка C. Функция clock() может быть использована, например, для замера производительности.

ctime(secs)

Преобразует время secs, выраженное в секундах с начала эпохи в строку, представляющую локальное время. Эквивалентно asctime(localtime(secs)).

daylight

Эта переменная имеет ненулевое значение, если определен часовой пояс с переходом на летнее время (DST).

gmtime(secs)

Преобразует время secs, выраженное в секундах с начала эпохи в кортеж, представляющий универсальное время (UTC).

localtime(secs)

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

mktime(time_tuple)

Эта функция выполняет преобразование, обратное функции localtime(). Аргумент time_tuple должен быть кортежем из 9 элементов, представляющим локальное время. Для совместимости с функцией time() возвращает вещественное число. Если time_tuple не представляет корректного времени, генерирует исключение OverflowError.

sleep(secs)

Приостанавливает выполнение на secs секунд. Аргумент secs может быть вещественным числом для указания более точного времени. Реальное время, на которое приостанавливается выполнение программы, может быть меньше secs, так как любой перехваченный сигнал прерывает выполнение функции sleep(), после чего выполняется обработчик сигнала. Кроме того, время может быть и больше secs из-за планирования активности различных задач системы.

strftime(format, time_tuple)

Возвращает время, выраженное кортежем time_tuple, в виде строки в соответствии с форматом format. Строка формата помимо обычных символов может содержать следующие управляющие последовательности (названия месяцев, дней недели и т. п. зависят от текущих национальных установок — см. описание модуля locale):

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

strptime(string [, format]) (большинство современных вариантов UNIX)

Разбирает строковое представление времени string в соответствии с форматом format и возвращает кортеж с числами, описанный выше. В аргументе format должны использоваться такие же управляющие последовательности, как и в строке формата функции strftime(). По умолчанию format равен строке ’%a %b %d %H:%M:%S %Y’, соответствующей формату, используемому функцией ctime(). Если строка string не соответствует формату format, генерируется исключение ValueError.

time()

Возвращает универсальное время (UTC) в виде вещественного числа в секундах с начала эпохи. Заметим, что не все платформы предоставляют время с точностью большей, чем 1 секунда.

timezone

Сдвиг локального часового пояса (без учета перехода на летнее время) в секундах на запад от UTC (то есть положительное в США, равное нулю в Великобритании и отрицательное в России).

tzname

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

21.8. sched — планирование задач

Модуль sched определяет класс, позволяющий планировать запуск задач:

scheduler(timefunc, delayfunc)

Возвращает объект, являющийся планировщиком задач общего назначения. Аргументы — функции, взаимодействующие с внешним миром. Функция timefunc вызывается без аргументов и должна возвращать число (время, в любых единицах). Функция delayfunc вызывается с одним аргументом — временем (в тех же единицах, которые использует функция timefunc), должна осуществлять приостановку выполнения на указанное время. Кроме того, чтобы дать возможность выполняться другим потокам в многопоточных приложениях, после выполнения каждой задачи функция timefunc вызывается с аргументом 0.

Экземпляры класса scheduler имеют следующие методы:

enterabs(time, priority, action, arguments)

Планирует выполнение новой задачи в указанное время. Аргумент time должен быть числом, выражающим время в тех же единицах, которые использует функция timefunc. В указанное время будет вызвана функция action с аргументами arguments (кортеж). Задачи, запланированные на одно и то же время, будут выполняться в порядке их приоритетов (аргумент priority).

Метод возвращает объект, представляющий запланированную задачу, который может быть использован для ее снятия с помощью метода cancel(), описанного ниже.

enter(delay, priority, action, arguments)

Планирует выполнение новой задачи через указанное время. Аргумент delay должен быть числом, выражающим время в тех же единицах, которые использует функция timefunc, по прошествии которого должна быть запущена задача. Остальные аргументы и возвращаемое значение имеют такое же значение, как и для метода enterabs().

cancel(task)

Удаляет задачу из очереди. Если в очереди отсутствует задача task, генерирует исключение RuntimeError.

empty()

Возвращает 1, если очередь пуста, иначе возвращает 0.

run()

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

Исключения, сгенерированные функциями timefunc, delayfunc и action не обрабатываются. Если исключение сгенерировала функция action, планировщик не будет пытаться выполнить эту задачу при последующих вызовах метода run().

Приведем простой пример:

>>> import sched, time
>>> s=sched.scheduler(time.time, time.sleep)
>>> def print_time():
...     print "В функции print_time:", time.time()
...
>>> def print_some_times():
...     print time.time()
...     s.enter(5, 1, print_time, ())
...     s.enter(10, 1, print_time, ())
...     s.run()
...     print time.time()
...
>>> print_some_times()
930343690.257
В функции print_time: 930343695.274
В функции print_time: 930343700.273
930343700.276

21.9. getpass — запрос пароля и определение имени пользователя

Модуль getpass определяет две функции:

getpass([prompt]) (UNIX, Windows, Macintosh)

Запрашивает пароль у пользователя без отображения вводимых символов. В качестве приглашения используется строка prompt (по умолчанию равна ’Password: ’).

getuser() (UNIX, Windows)

Возвращает регистрационное имя пользователя. Эта функция последовательно проверяет переменные окружения LOGNAME, USER, LNAME и USERNAME и возвращает значение первой переменной, имеющей непустое значение. Если ни одна из этих переменных не установлена, используется модуль pwd там, где он доступен (в противном случае генерируется исключение ImportError).

21.10. getopt — обработка опций в командной строке

Модуль getopt помогает обрабатывать аргументы, переданные программе в командной строке (sys.argv). Функция getopt() модуля использует такие же правила, как и одноименная функция языка C в UNIX, включая специальное значение аргументов ‘-’ и ‘--’. Длинная запись опций, аналогичных тем, которые используются программами GNU, также может быть использована, если задан третий аргумент функции getopt().

getopt(args, options [, long_options])

Обрабатывает список аргументов args (обычно sys.argv[1:]).

Аргумент options должен быть строкой из букв, которые будут распознаваться как опции. Если опция требует наличия аргумента, после соответствующей буквы в строке options должно следовать двоеточие (‘:’).

Если задан аргумент long_options, он должен быть списком строк с именами опций, которые будут распознаваться в виде длинной записи, без приставки ‘--’. После имени опций, требующих аргумента, в строке должен следовать знак равенства (‘=’).

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

GetoptError

error

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

msg

Сообщение об ошибке.

opt

Имя опции, с которой связана ошибка, или пустая строка, если ошибка не связана с определенной опцией.

Имя GetoptError появилось в версии 1.6. Для совместимости с более старыми версиями присутствует имя error, ссылающееся на GetoptError.

Приведем небольшой пример, использующий только короткую запись опций:

>>> import getopt
>>> args = '-a -b -cfoo -d bar a1 a2'.split()
>>> args
['-a', '-b', '-cfoo', '-d', 'bar', 'a1', 'a2']
>>> optlist, args = getopt.getopt(args, 'abc:d:')
>>> optlist
[('-a', ''), ('-b', ''), ('-c', 'foo'), ('-d', 'bar')]
>>> args
['a1', 'a2']

Использовать длинную запись опций так же просто:

>>> s = '--condition=foo --testing --output-file
... abc.def -x a1 a2'
>>> args = s.split()
>>> args
['--condition=foo', '--testing', '--output-file',
'abc.def', '-x', 'a1', 'a2']
>>> optlist, args = getopt.getopt(args, 'x', [
...     'condition=', 'output-file=', 'testing'])
>>> optlist
[('--condition', 'foo'), ('--testing', ''),
('--output-file', 'abc.def'), ('-x', '')]
>>> args
['a1', 'a2']

В реальной программе модуль getopt используется обычно примерно следующим образом:

import getopt, sys
USAGE = """\
...
"""
def main():
    try:
        opts, args = getopt.getopt(sys.argv[1:],
                                   'ho:',
                                  ['help', 'output='])
    except getopt.GetoptError:
        # выводим подсказку и выходим:
        print << sys.stderr, USAGE
        sys.exit(2)
    output = None
    for o, a in opts:
        if o in ('-h', '--help'):
            print USAGE
            sys.exit()
        if o in ('-o', '--output'):
            output = a
    # ...
if __name__ == '__main__':
    main()

21.11. tempfile — создание временных файлов

Этот модуль предоставляет переносимый способ генерации уникальных имен для временных файлов и их создания:

mktemp([suffix])

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

TemporaryFile([mode [, bufsize [, suffix]]])

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

Аргумент mode указывает режим, в котором файл будет открыт. По умолчанию он равен ’w+b’, что позволяет как записывать, так и читать из файла не закрывая его. Аргумент bufsize имеет такое же значение, как и во встроенной функции open(). Если задан аргумент suffix, он будет использоваться в качестве последней части (суффикса) имени файла.

gettempprefix()

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

Модуль определяет следующие глобальные переменные, определяющие, каким образом будет конструироваться имя временного файла. Заметим, что присваивание им нового значения невозможно, если Вы использовали инструкцию вида ‘from tempfile import ...’ для импортирования модуля.

tempdir

Если эта переменная имеет значение отличное от None, определяет имя каталога, в котором будут создаваться временные файлы. Инициализируется при первом вызове функции mktemp(). Значение по умолчанию берется из переменной окружения TMPDIR, TEMP или TMP. Если ни одна из этих переменных не установлена, используется общепринятая для данной платформы (‘/var/tmp’, ‘/usr/tmp’ или ‘/tmp’ в UNIX) или текущий каталог.

template

Если эта переменная имеет значение, отличное от None, определяет приставку к именам временных файлов. Инициализируется при первом вызове функции mktemp(). По умолчанию используется ’@pid.’ в UNIX, ’~pid-’ в Windows NT, ’Python-Tmp-’ в Macintosh и ’tmp’ на других платформах.

21.12. errno — символические имена стандартных системных ошибок

Этот модуль предоставляет символические имена для стандартных системных ошибок. Значением каждой символической константы является целое число, которое используется в качестве кода ошибки в исключениях класса IOError (атрибут errno).

errorcode

Словарь, отображающий код ошибки к его имени в данной системе. Например, выражение errorcode[EPERM] дает ’EPERM’. Для получения сообщения об ошибке, соответствующего ее коду, используйте функцию os.strerror().

Ниже перечислены основные символические константы (в соответствии со стандартами POSIX.1, ISO C). Из этого списка модуль определяет только те константы, которые используются на данной платформе (Вы можете получить полный список имен доступных констант как результат выражения errno.errorcode.values()):

EPERM

Недопустимая операция.

ENOENT

Нет такого файла или каталога.

ESRCH

Нет такого процесса.

EINTR

Прерван системный вызов.

EIO

Ошибка ввода/вывода.

ENXIO

Нет такого устройства или адреса.

E2BIG

Слишком длинный список аргументов.

ENOEXEC

Неверный формат аргументов системного вызова exec().

EBADF

Неверный дескриптор файла.

ECHILD

Нет дочернего процесса.

EAGAIN

Ресурс временно недоступен.

ENOMEM

Не хватает памяти.

EACCES

Доступ запрещен.

EFAULT

Неверный адрес.

EBUSY

Устройство или ресурс занят.

EEXIST

Файл уже существует.

EXDEV

Неверная ссылка (на файл, находящийся на другом устройстве).

ENODEV

Нет такого устройства.

ENOTDIR

Не является каталогом.

EISDIR

Является каталогом.

EINVAL

Неверный аргумент.

ENFILE

Слишком много открытых файлов в системе (переполнение таблицы файлов).

EMFILE

Слишком много открытых файлов.

ENOTTY

Неверная операция управления вводом/выводом (устройство должно быть терминалом).

ETXTBSY

Текстовый файл занят (например, при попытке выполнить файл, открытый для записи).

EFBIG

Файл слишком большой.

ENOSPC

На устройстве не осталось свободного места.

ESPIPE

Неверное перемещение указателя.

EROFS

Файловая система доступна только для чтения.

EMLINK

Слишком много ссылок.

EPIPE

Нарушен канал (pipe).

EDOM

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

ERANGE

Результат математической операции не представим.

EDEADLK

Выполнение операции привело бы к взаимной блокировке.

ENAMETOOLONG

Слишком длинное имя файла.

ENOLCK

Блокировка записей недоступна.

ENOSYS

Функция не реализована.

ENOTEMPTY

Каталог не является пустым.

EBADMSG

Неверное сообщение.

EILSEQ

Неверная последовательность байтов.

EMSGSIZE

Слишком длинное сообщение.

ETIMEDOUT

Истекло время ожидания завершения операции.

EINPROGRESS

Операция в процессе выполнения.

21.13. glob — раскрытие шаблона имен путей

Модуль glob находит все имена путей, удовлетворяющих определенному шаблону, в соответствии с правилами, используемыми в UNIX shell. Этот модуль не раскрывает имя домашнего каталога, записанного с помощью символа ‘~’, но корректно сопоставляет имена, возвращаемые функцией os.listdir() с заданным шаблоном с помощью функции fnmatch.fnmatch() (см. описание модуля fnmatch для ознакомления с синтаксисом шаблонов). Если Вы хотите раскрыть имя домашнего каталога, воспользуйтесь функцией os.path.expanduser().

glob(pathname)

Возвращает (возможно, пустой) список имен путей, удовлетворяющих шаблону pathname. Аргумент pathname должен быть строкой, содержащей имя пути (абсолютное или относительное) и, возможно, групповые символы (см. описание модуля fnmatch). Групповые символы не удовлетворяют разделителю компонент имени пути [Специальные последовательности вида ’[seq]’ и ’![seq]’ не должны содержать символы разделителей имени пути, так как это приведет к некорректной работе функции.].

Допустим, к примеру, что текущий каталог содержит только файлы ‘1.gif’, ‘2.txt’ и ‘card.gif’. Тогда функция glob() будет работать следующим образом (обратите внимание, что запись начала пути сохраняется):

>>> from glob import glob
>>> glob('./[0-9].*')
['./1.gif', './2.txt']
>>> glob('*.gif')
['1.gif', 'card.gif']
>>> glob('?.gif')
['1.gif']

21.14. fnmatch — сопоставление имен файлов с шаблоном

Этот модуль предоставляет возможность сопоставления имен файлов (каталогов) с шаблоном, содержащим групповые символы в стиле UNIX shell. Возможность использования более сложных шаблонов (регулярных выражений) предоставляет модуль re.

Шаблон может содержать следующие специальные последовательности (групповые символы):

Обратите внимание, что разделители компонент имени пути (‘/’, ‘\’, ‘:’) не имеют специального значения. Точка в начале имени файла не рассматривается отдельно и удовлетворяет групповым символам ‘*’ и ‘?’.

fnmatch(filename, pattern)

Возвращает 1, если имя файла (каталога) удовлетворяет шаблону pattern, иначе возвращает 0. Если ОС не чувствительна к регистру имен файлов, оба аргумента перед сопоставлением будут приведены к одному регистру функцией os.path.normcase(). Функция os.path.normcase() также заменяет все вхождения os.altsep на os.sep, то есть, например в Windows, символы ‘\’ и ‘/’ могут использоваться взаимозаменяемо (шаблоны ’/’ и ’\\’ удовлетворяют как ’/’, так и ’\\’).

fnmatchcase(filename, pattern)

Возвращает 1, если имя файла (каталога) удовлетворяет шаблону pattern, иначе возвращает 0. Аргументы не подвергаются никакой обработке, сравнение всегда производится с учетом регистра букв.

Модуль glob позволяет раскрыть шаблон, то есть найти все файлы, удовлетворяющие шаблону.

21.15. shutil — операции над файлами высокого уровня

Модуль shutil предоставляет набор операций высокого уровня над файлами и коллекциями файлов.

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

copyfile(src, dst)

Копирует содержимое файла именем src в файл с именем dst. Если файл dst существует, он будет заменен.

copyfileobj(fsrc, fdst [, bufsize])

Копирует содержимое файлового (или подобного) объекта fsrc в файловый (или подобный) объект fdst. Если задан аргумент bufsize, он используется в качестве размера буфера (отрицательные значения означают, что файл не будет копироваться по частям).

copymode(src, dst)

Устанавливает у файла с именем dst биты разрешений доступа такие же, как у файла src.

copystat(src, dst)

Устанавливает у файла с именем dst биты разрешений доступа, время последнего доступа и время последнего внесения изменений такие же, как у файла src. Содержимое файла, владелец и группа остаются неизменными.

copy(src, dst)

Копирует файл с именем src в файл с именем dst. Если dst является каталогом, создает (или заменяет) в нем файл с таким же (основным) именем, как и src. Биты разрешения доступа также копируются.

copy2(src, dst)

Работает аналогично функции copy(), но также устанавливает у файла с именем dst время последнего доступа и время последнего внесения изменений такие же, как у файла src (то есть работает аналогично команде ‘cp -p’ в UNIX).

copytree(src, dst [, symlinks])

Рекурсивно копирует дерево каталогов src в dst. Каталог с именем dst не должен существовать — он будет создан. Копирование всех файлов производится с помощью функции copy2(). Если задан и является истиной аргумент symlinks, символические ссылки в исходном дереве будут представлены символическими ссылками в новом дереве, в противном случае, в новое дерево будет скопировано содержимое файлов, на которые указывают символические ссылки. Ошибки, возникающие при копировании, выводятся на стандартный поток ошибок. Эту функцию следует воспринимать скорее как пример (см. исходный текст модуля), нежели как реальное средство для работы с файлами.

rmtree(path [, ignore_errors [, onerror]])

Удаляет полностью дерево каталогов path. Если установлен и является истиной аргумент ignore_errors, ошибки, возникающие при удалении, будут проигнорированы, в противном случае для обработки ошибок вызывается функция onerror (или генерируется исключение, если аргумент onerror не задан).

Обработчик ошибок onerror должен поддерживать вызов с тремя аргументами: function, path и excinfo. function — функция, которая сгенерировала исключение (os.remove() или os.rmdir()), path — имя пути, которое было передано функции function, и excinfo — информация об исключении, возвращаемая функцией sys.exc_info(). Исключения, сгенерированные обработчиком ошибок, не обрабатываются.

21.16. signal — обработка асинхронных событий

Этот модуль предоставляет возможность устанавливать обработчики сигналов. Несколько общих правил:

• Однажды установленный обработчик сигнала остается до тех пор, пока Вы явно не восстановите исходный обработчик. Единственное исключение из этого правила — обработчик сигнала SIGCHLD, работа которого зависит от реализации на данной платформе.
• Не существует способа временно заблокировать сигналы в критических местах.
• Хотя обработчики сигналов и вызываются асинхронно, это может произойти только между атомными инструкциями интерпретатора Python. Это значит, что если сигнал поступает в момент длительной работы процедуры, полностью реализованной на языке C (например, использование регулярного выражения для поиска в длинном тексте), его обработка может быть отложена на произвольное время.
• При поступлении сигнала во время выполнения операции ввода/вывода после завершения обработки сигнала может быть сгенерировано исключение.
• Не имеет особого смысла обработка синхронных ошибок, таких как SIGFPE или SIGSEGV.
• Интерпретатор устанавливает некоторое количество обработчиков по умолчанию: сигнал SIGPIPE игнорируется (таким образом, уведомление об ошибках при работе с каналами и сетевыми соединениями может быть выполнено генерацией обычных исключений) и SIGINT генерирует исключение KeyboardInterrupt. Вы можете заменить любой из этих обработчиков.
• Следует проявлять некоторую осторожность при использовании модуля в многопоточных программах. Основное правило: всегда вызывайте функцию signal() только в основном потоке. Любой поток может использовать функции alarm(), getsignal() и pause(), но только основной — устанавливать обработчик и получать сигнал. Таким образом, сигналы не могут быть использованы для связи между потоками — для этих целей следует использовать блокировки.

Модуль signal определяет следующие константы и функции:

SIG_DFL

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

SIG_IGN

Используется в качестве аргумента функции signal() для обозначения обработчика, игнорирующего сигнал.

SIG*

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

NSIG

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

alarm(time) (UNIX)

Если аргумент time не равен нулю, запрашивает посылку сигнала SIGALRM текущему процессу через time секунд. Ранее запланированная посылка сигнала при этом отменяется. Возвращает время в секундах, которое оставалось до посылки ранее запланированного сигнала. Если аргумент time равен нулю, отменяет ранее запланированную посылку сигнала и возвращает время, которое оставалось до его посылки. Если функция alarm() возвращает 0, посылка сигнала до этого не была запланирована.

getsignal(signalnum)

Возвращает текущий обработчик сигнала с номером signalnum. Возвращаемое значение может быть объектом, поддерживающим вызов, или одним из специальных значений: signal.SIG_IGN, signal.SIG_DFL или None. Значение None означает, что обработчик не был установлен интерпретатором.

pause() (UNIX)

Приостанавливает выполнение процесса до получения сигнала, после чего будет вызван соответствующий обработчик.

signal(signalnum, handler)

Устанавливает handler в качестве обработчика сигнала с номером signalnum. Аргумент handler может объектом, поддерживающим вызов, или одним из специальных значений: SIG_IGN или SIG_DFL. Возвращает предыдущий обработчик сигнала.

Функция handler будет вызываться для обработки сигнала signalnum с двумя аргументами: номер сигнала и текущий кадр стека (или None).

В многопоточной программе при попытке вызвать эту функцию из неосновного потока генерируется исключение ValueError.

Приведем простой пример, использующий функцию alarm() для того, чтобы ограничить время ожидания открытия файла. Это может быть полезно, если файл является последовательным устройством, который может быть не включенным. Использование функции os.open() для таких файлов приведет к зависанию. Для того, чтобы решить эту проблему, можно перед открытием файла запросить посылку сигнала SIGALRM через 5 секунд: если операция займет слишком много времени, будет послан сигнал и обработчик сгенерирует исключение.

import signal, os

def handler(signum, frame):
    raise IOError("Couldn't open device!")

# Устанавливаем обработчик
signal.signal(signal.SIGALRM, handler)
# Запрашиваем посылку сигнала через 5 секунд
signal.alarm(5)

# Эта операция может привести к зависанию
fd = os.open('/dev/ttyS0', os.O_RDWR)

# Отключаем посылку сигнала
signal.alarm(0)

21.17. socket — сетевой интерфейс низкого уровня

Модуль socket предоставляет низкоуровневый доступ к сетевым соединениям. Этот модуль доступен для всех современных вариантов UNIX, Windows, Macintosh, BeOS, OS/2 и, возможно, для некоторых других платформ.

Адреса для сетевых соединений представляются одной строкой для семейства AF_UNIX и как пара ‘(host, port)’ для семейства AF_INET, где host — строка, содержащая имя узла (например, ’daring.cwi.nl’) или IP адрес (например, ’100.50.200.5’), и port — номер порта. Воспринимаются также две специальные формы IP адресов: пустая строка соответствует INADDR_ANY и строка ’<broadcast>’ соответствует INADDR_BROADCAST.

Поддержка режима без блокировки осуществляется через метод setblocking().

Модуль socket определяет следующие константы и функции:

error

Исключения этого класса генерируются в случае возникновения ошибок, связанных с сетевым соединением или адресом. Аргументами исключения являются строка, описывающая причину возникновения ошибки, и, возможно, системный код ошибки (см. описание модуля errno).

AF_UNIX (UNIX)

AF_INET

Эти константы используются в качестве первого аргумента конструктора socket() и указывают семейство, к которому относится адрес соединения (UNIX-соединение или соединение с Internet).

SOCK_STREAM

SOCK_DGRAM

SOCK_RAW

SOCK_RDM

SOCK_SEQPACKET

Эти константы используются в качестве второго аргумента конструктора socket() и указывают тип соединения (обычно используются только первые два типа).

INADDR_*

IP_*

IPPORT_*

IPPROTO_*

MSG_*

SO_*

SOL_*

SOMAXCONN

Множество констант такого вида определено в этом модуле и обычно используются в качестве аргументов методов setsockopt() и getsockopt() объектов, представляющих сетевое соединение. Информацию о них Вы можете получить в документации UNIX по сетевым соединениям и протоколу IP.

getfqdn([name])

Возвращает полное уточненное доменное имя для name. Если аргумент name опущен или является пустой строкой, он считается соответствующим локальному узлу. Для того, чтобы получить полное уточненное имя, проверяется сначала имя узла, возвращаемое функцией gethostbyaddr(), затем псевдонимы, если они имеются. Выбирается первое имя, содержащее точку. В случае, если уточненное имя не доступно, возвращает имя узла. Функция доступна, начиная с версии 2.0.

gethostbyname(hostname)

Возвращает строку, содержащую IP адрес узла с именем hostname. Если строка hostname содержит IP адрес, она возвращается без изменений.

gethostbyname_ex(hostname)

Возвращает кортеж ‘(mainhostname, aliaslist, ipaddrlist)’, где mainhostname — основное имя узла, соответствующего hostname, aliaslist — список (возможно пустой) альтернативных имен для того же адреса и ipaddrlist — список IP адресов для того же интерфейса к тому же узлу (обычно содержит одну строку).

gethostname()

Возвращает строку, содержащую имя узла машины, на которой в данный момент выполняется интерпретатор языка Python. Если Вы хотите получить IP адрес текущей машины, используйте gethostbyname(gethostname()). Заметим, что функция gethostname() не всегда возвращает полное имя — для этих целей следует использовать getfqdn(gethostname()).

gethostbyaddr(ip_address)

Возвращает кортеж ‘(hostname, aliaslist, ipaddrlist)’, где hostname — основное имя узла, соответствующего IP адресу ip_address, aliaslist — список (возможно пустой) альтернативных имен для того же адреса и ipaddrlist — список IP адресов для того же интерфейса к тому же узлу (обычно содержит одну строку).

getprotobyname(protocolname)

Возвращает число, подходящее для использования в качестве третьего аргумента функции socket() и соответствующее протоколу с именем protocolname. Это необходимо только, если Вы открываете соединение в “прямом” режиме (SOCK_RAW), для остальных типов соединений правильный протокол выбирается автоматически, если соответствующий аргумент опущен или равен нулю.

getservbyname(servicename, protocolname)

Возвращает номер порта для службы с именем servicename и протоколом с именем protocolname. Имя протокола должно быть равным ’tcp’ или ’udp’.

socket(family, type [, proto])

Создает новое сетевое соединение и возвращает соответствующий ему объект. family — семейство адресов (AF_INET или AF_UNIX), type — тип соединения (одна из констант SOCK_*) и proto — номер протокола. Если аргумент proto опущен, протокол выбирается автоматически.

fromfd(fd, family, type [, proto])

Создает объект сетевого соединения из файлового дескриптора fd и возвращает его. Файловый дескриптор должен соответствовать сетевому соединению (однако это не проверяется — последующие операции могут вызвать ошибку, если дескриптор непригоден). Остальные аргументы имеют такое же значение, как и для функции socket().

ntohl(x)

Преобразует представление 32-битового целого числа с общепринятым в сети порядком следования байтов к представлению с порядком следования байтов на данной машине.

ntohs(x)

Преобразует представление 16-битового целого числа с общепринятым в сети порядком следования байтов к представлению с порядком следования байтов на данной машине.

htonl(x)

Преобразует представление 32-битового целого числа с порядком следования байтов на данной машине к представлению с общепринятым в сети порядком следования байтов.

htons(x)

Преобразует представление 16-битового целого числа с порядком следования байтов на данной машине к представлению с общепринятым в сети порядком следования байтов.

inet_aton(ip_string)

Возвращает строку из четырех символов, содержащую IP адрес ip_string (строка вида ’123.45.67.89’) в упакованном двоичном виде. Эта функция может быть полезна для связи с программой, использующей стандартную библиотеку языка C.

inet_ntoa(packed_ip)

Возвращает строку с IP адресом, полученным распаковкой строки из четырех символов packed_ip, содержащей упакованное двоичное представление адреса.

SocketType

Тип объекта сетевого соединения, возвращаемого функцией socket().

Объекты сетевого соединения, возвращаемые функцией socket(), имеют следующие методы:

accept()

Принимает соединение и возвращает пару ‘(conn, address)’, где conn — новый объект сетевого соединения, подходящий для посылки и получения данных, и address — адрес другого конца сетевого соединения. Объект сетевого соединения, к которому применяется метод accept(), должен быть привязан к адресу (метод bind()) и ожидать соединения (метод listen()).

bind(address)

Привязывает сетевое соединение к адресу address. Перед вызовом этого метода объект не должен быть привязанным к адресу. Формат аргумента зависит от семейства, к которому относится адрес (см. начало раздела).

close()

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

connect(address)

Подсоединяется к удаленному узлу с адресом address. Формат аргумента зависит от семейства, к которому относится адрес (см. начало раздела).

connect_ex(address)

Работает аналогично методу connect(), но возвращает код ошибки, возвращаемый системной функцией connect() вместо того, чтобы генерировать исключение. Возвращаемое значение равно 0 в случае успешного выполнения операции и значению системной переменной errno при возникновении ошибки. Метод может быть полезен для асинхронных соединений.

fileno()

Возвращает файловый дескриптор сетевого соединения (целое число). Может быть полезен совместно с функцией select.select().

getpeername()

Возвращает адрес удаленного узла, с которым установлено соединение. Формат возвращаемого значения зависит от семейства, к которому относится адрес (см. начало раздела). Метод может быть полезен, например, для определения номера порта на другом конце IP соединения.

getsockname()

Возвращает собственный адрес. Формат возвращаемого значения зависит от семейства, к которому относится адрес (см. начало раздела). Метод может быть полезен, например, для определения номера порта.

getsockopt(level, optname [, buflen])

Возвращает значение опции optname. В качестве аргумента optname может быть использована одна из символических констант вида SO_*, определенных в модуле. Если аргумент buflen опущен, возвращает целочисленное значение опции. Если аргумент buflen задан, он указывает максимальную длину возвращаемой строки.

listen(backlog)

Ожидает установления сетевого соединения. Аргумент backlog определяет максимальное число соединений в очереди и должен быть не меньше единицы (максимальное значение зависит от системы, обычно равно 5).

makefile([mode [, bufsize]])

Возвращает файловый объект (типа file, см. раздел 11.7), ассоциированный с сетевым соединением. Файловый объект ссылается на дубликат файлового дескриптора для сетевого соединения, таким образом, файловый объект и объект сетевого соединения могут быть закрыты (в том числе неявно — при достижении нуля количества ссылок на объект) независимо друг от друга. Аргументы mode и bufsize имеют такое же значение, как и для встроенной функции open().

recv(bufsize [, flags])

Получает данные через сетевое соединение и возвращает их в виде строки. Максимальное количество данных, получаемое за один раз, определяется аргументом bufsize. Описание возможных значений аргумента flags смотрите в документации для системной функции recv().

recvfrom(bufsize [, flags])

Работает аналогично методу recv(), но возвращает пару ‘(string, address)’, где string — строка с полученными данными и address — адрес, с которого данные были посланы. Формат address зависит от семейства, к которому относится адрес (см. начало раздела).

send(string [, flags])

Посылает данные через сетевое соединение. Соединение должно быть установленным. Аргумент flags имеет такое же значение, как и для метода recv(). Возвращает размер посланных данных в байтах.

sendto(string [, flags], address)

Посылает данные на узел с адресом address. Соединение не должно быть установленным. Аргумент flags имеет такое же значение, как и для метода recv(). Возвращает размер посланных данных в байтах. Формат аргумента зависит от семейства, к которому относится адрес (см. начало раздела).

setblocking(flag)

Если flag равен 0, устанавливает режим без блокировки, иначе устанавливает режим с блокировкой. Изначально все сетевые соединения находятся в режиме с блокировкой. В режиме без блокировки, если операция recv() или send() не может быть выполнена немедленно, генерируется исключение error. В режиме с блокировкой вызов методов recv() или send() приведет к блокированию до тех пор, пока операция не будет выполнена.

setsockopt(varlevel, optname, value)

Устанавливает значение опции optname равным value. В качестве аргумента optname может быть использована одна из символических констант вида SO_*, определенных в модуле. Аргумент value может быть целым числом или строкой с упакованными данными.

shutdown(how)

Отключает одну или обе половины соединения. Если аргумент how равен 0, в дальнейшем получение данных будет запрещено. Если аргумент how равен 1, запрещена будет передача данных. Если аргумент how равен 2, в дальнейшем будет запрещено как получение, так и передача данных.

Приведем два простых примера, использующих TCP/IP протокол: сервера, посылающего назад полученные данные (обслуживая только одного клиента), и клиента, его использующего. Обратите внимание, что сервер должен вызвать последовательно методы socket(), bind(), listen(), accept() (возможно повторяя вызов accept(), если необходимо обслуживать несколько клиентов), в то время как клиенту необходимо выполнить только socket(), connect(). Кроме того, сервер применяет методы send() и recv() не к объекту, ожидающему соединения, а к новому объекту, возвращаемому методом accept().

# Сервер
import socket

# Локальный узел
HOST = ''
# Произвольный непривелегированный порт
PORT = 50007
s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
s.bind((HOST, PORT))
s.listen(1)
conn, addr = s.accept()
print 'Подсоединились с адреса', addr
while 1:
    data = conn.recv(1024)
    if not data: break
    conn.send(data)
conn.close()

# Клиент
import socket

# Удаленный узел
HOST = 'daring.cwi.nl'
# Тот же порт, что используется сервером
PORT = 50007

s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
s.connect((HOST, PORT))
s.send('Hello, world')
data = s.recv(1024)
s.close()
print 'Полученные данные:', ‘data‘

21.18. select — ожидание завершения ввода/вывода

Этот модуль предоставляет доступ к системным функциям select() и poll(). Заметим, что в Windows функция select() работает только для сетевых соединений. В UNIX средства, предоставляемые модулем, работают также с другими типами файлов, в частности, каналами. Однако эти средства не могут быть использованы для определения увеличения в размерах обычного файла.

error

Исключения этого класса генерируются при возникновении различных ошибок. В качестве аргументов при инициализации используются номер системной ошибки и соответствующая ему поясняющая строка.

select(iwtd, owtd, ewtd [, timeout])

Первые три аргумента — списки, которые могут содержать файловые дескрипторы или объекты с методом fileno(), возвращающим файловый дескриптор. iwtd — список объектов для ввода, owtd — для вывода и ewtd — для исключительных ситуаций (вывода ошибок). Аргумент timeout указывает максимальное время ожидания, если он опущен, функция блокирует выполнение до тех пор, пока один из дескрипторов не будет готов.

Функция select() возвращает кортеж из трех списков, являющихся подсписками аргументов iwtd, owtd и ewtd и содержащих объекты, готовые к вводу/выводу. При достижении максимального времени ожидания, возвращает кортеж из трех пустых списков.

poll() (большинство вариантов UNIX)

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

Объекты, возвращаемые функцией poll(), имеют следующие методы:

register(fd [, eventmask])

Регистрирует файловый дескриптор (или объект с методом fileno(), возвращающим файловый дескриптор) fd. При последующих вызовах метода poll() файловый дескриптор будет проверяться на предмет наступления событий ввода/вывода. Аргумент eventmask может быть комбинацией (с помощью оператора ‘|’) констант POLLIN, POLLPRI и POLLOUT и указывает интересующие типы событий. По умолчанию проверяется наступление событий всех трех типов. Повторная регистрация одного и того же файлового дескриптора не является ошибкой.

unregister(fd)

Снимает с регистрации файловый дескриптор (или объект с методом fileno(), возвращающим файловый дескриптор) fd. При попытке снять с регистрации объект, который не был зарегистрирован, будет сгенерировано исключение KeyError.

poll([timeout])

Опрашивает зарегистрированные файловые дескрипторы на предмет наступления событий ввода/вывода и возвращает список пар вида ‘(fd, event)’, где fd — файловый дескриптор, для которого наступило событие и возникла ошибка, и event — комбинация констант (см. ниже), описывающих наступившее событие или возникшую ошибку. Аргумент timeout указывает максимальное время ожидания, если он опущен, метод блокирует выполнение до тех пор, пока один из дескрипторов не будет готов. При достижении максимального времени ожидания, возвращает пустой список.

Ниже приведены константы, комбинации которых могут быть использованы в качестве аргумента eventmask метода register() и в результате, возвращаемом методом poll():

POLLIN

Имеются данные для чтения.

POLLPRI

Имеются экстренные данные для чтения.

POLLOUT

Файловый дескриптор готов к выводу (то есть запись не приведет к блокированию).

POLLERR

Исключительная ситуация.

POLLHUP

Зависание.

POLLNVAL

Неверный запрос: дескриптор не открыт.

21.19. mmap — отображение файлов в память

Модуль mmap доступен в операционных системах UNIX и Windows и позволяет отображать файлы в память. Объекты, представляющие отображенные в память файлы, ведут себя с одной стороны как изменяемые строки, с другой — как файловые объекты. В большинстве случаев вы можете использовать эти объекты вместо строк. Например, с помощью модуля re Вы можете осуществлять поиск в отображенном в память файле. Вы можете вносить изменения в файл как в изменяемую последовательность (например, ‘mapped_file[i] = char’ или ‘mapped_file[i:j] = string’) различными способами, если эти изменения не требуют изменения размера файла.

Модуль определяет следующий конструктор:

mmap(fd, size [, *platform_args])

Отображает в память size байт файла, соответствующего файловому дескриптору fd. Если Вы хотите отобразить файл, соответствующий файловому объекту, — используйте его метод fileno().

Назначение дополнительных аргументов (platform_args) зависит от используемой платформы. В Windows может быть указано имя создаваемого отображения (повторное использование имени приведет к использованию ранее созданного отображения). В UNIX могут быть указаны два дополнительных аргумента: flags и prot. Аргумент flags может иметь значение MAP_SHARED (используется по умолчанию) или MAP_PRIVATE и определяет характер отображения. В качестве аргумента prot может использоваться комбинация из констант PROT_* (по умолчанию используется PROT_READ | PROT_WRITE), определяющих желаемую степень защиты памяти.

В качестве значений аргументов, характерных для UNIX, Вы можете использовать следующие константы (наиболее важные):

MAP_SHARED

Отображение является общим для всех процессов.

MAP_PRIVATE

Отображение является частным. При внесении изменений создается копия. Таким образом, все изменения видны только текущему процессу.

PROT_READ

Обеспечивает доступ к отображению на чтение.

PROT_WRITE

Обеспечивает доступ к отображению на запись.

Объекты, представляющие отображенный в память файл, имеют следующие методы:

close()

Закрывает отображение. Последующие операции над объектом приведут к ошибке.

find(string [, start])

Возвращает наименьший индекс, указывающий, где найдена подстрока string. Аргумент start является индексом, указывающим с какого места необходимо производить поиск (по умолчанию он равен 0).

flush([offset, size])

Сбрасывает на диск изменения, внесенные в отображение файла. Без вызова этого метода не гарантируется, что внесенные изменения будут записаны до того, как объект отображения будет уничтожен. Если указаны аргументы offset и size, то сбрасываются только изменения в диапазоне (в байтах) от offset до offset + size, в противном случае сбрасывается все содержимое.

move(dest, src, count)

Копирует count байт из диапазона, начинающегося с индекса src, в диапазон, начинающийся с индекса dest.

read_byte()

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

readline()

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

resize(newsize)

Изменяет размер отображенного в память файла. Размер отображения становится равным newsize байт.

seek(pos [, whence])

Устанавливает текущую позицию в файле. Необязательный аргумент whence указывает на точку отсчета: 0 (по умолчанию) — начало файла, 1 — текущая позиция и 2 — конец файла.

size()

Возвращает размер файла в байтах, который может быть больше размера отображенной в память области.

tell()

Возвращает текущую позицию в файле.

write(string)

Записывает строку string в отображенный файл, начиная с текущей позиции. После этого указатель устанавливается на следующий после записанной строки байт.

write_byte(byte)

Записывает один символ byte в отображенный файл (перемещает указатель на 1).

22. Средства организации многопоточных программ

22.1. thread — создание нескольких потоков и управление ими

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

error

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

LockType

Объект типа для объектов блокировки.

start_new_thread(function, args [, kwargs])

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

exit()

exit_thread()

Генерирует исключение SystemExit. Если исключение (в данном потоке) не обрабатывается, выполнение потока будет молча завершено. Имя exit_thread() определено для совместимости со старыми версиями.

allocate_lock()

Возвращает новый объект, реализующий блокировку. Изначально объект не является заблокированным.

get_ident()

Возвращает идентификатор текущего потока (отличное от нуля целое число). После завершения работы потока его идентификатор может быть использован повторно для нового потока.

Объекты, возвращаемые функцией allocate_lock, имеют следующие методы:

acquire([waitflag])

При вызове без аргументов захватывает (блокирует) объект, дождавшись, если это необходимо, его освобождения другим потокам (возвращает None). Если задан аргумент waitflag (целое число), поведение функции зависит от его значения: 1 — функция ожидает освобождения объекта другим потокам (так же, как и с опущенным аргументом), 0 (и другие значения) — объект захватывается только, если это может быть сделано немедленно. При наличии аргумента функция возвращает 1, если захват объекта прошел успешно, в противном случае возвращает 0.

release()

Освобождает объект. Объект должен быть захвачен ранее, но не обязательно в этом же потоке.

locked()

Возвращает текущий статус объекта: 1, если объект захвачен (заблокирован), иначе — 0.

Замечания:

• Если доступен модуль signal, прерывание (исключение KeyboardInterrupt) получает основной поток. Однако, если модуль signal недоступен, прерывание может получить любой поток.
• Вызов функций sys.exit() и thread.exit() и генерация исключения SystemExit эквивалентны.
• Не все функции, реализованные на языке C, при ожидании ввода/вывода позволяют выполняться другим потокам, но наиболее популярные (функции time.sleep() и select.select(), метод read() файловых объектов) работают правильно.
• Невозможно прервать выполнение метода acquire() объектов, предназначенных для блокировки, — исключение KeyboardInterrupt будет сгенерировано только после захвата объекта.
• Поведение при завершении работы основного потока раньше других зависит от платформы. Обычно остальные потоки немедленно завершают свою работу без выполнения ветвей finally инструкций try и вызова деструкторов объектов.

22.2. threading — средства высокого уровня организации потоков

Модуль threading предоставляет средства высокого уровня для работы с несколькими потоками, реализованные поверх модуля thread. Этот модуль безопасен для импортирования с помощью инструкции ‘from threading import *’.

activeCount()

Возвращает число объектов, представляющих активные потоки. Это значение равно длине списка, возвращаемого функцией enumerate().

Condition([lock])

Создает и возвращает объект, реализующий условие. Этот объект позволяет одному или нескольким потокам ожидать уведомления от другого потока. Если задан аргумент lock, он должен быть объектом, возвращаемым функцией Lock() или RLock(). Этот объект будет использован для блокировки. По умолчанию создается новый объект с помощью функции RLock().

currentThread()

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

enumerate()

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

Event()

Создает и возвращает объект, реализующий событие. Этот объект позволяет потоку ожидать наступления (установки в другом потоке) события.

Lock()

Создает и возвращает объект, реализующий примитивную блокировку. В текущих реализациях является псевдонимом для функции thread.allocate_lock().

RLock()

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

Semaphore([count])

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

Thread([keyword_list])

Этот класс используется для представления потока. Конструктор воспринимает несколько именованных аргументов (keyword_list). Действия, выполняемые при запуске потока, могут быть установлены с помощью аргумента с именем target — должен быть объектом, поддерживающим вызов. Этот объект вызывается из метода run() с позиционными и именованными аргументами, заданными соответственно аргументами с именами args и kwargs (по умолчанию используются пустые кортеж и словарь). Аргумент с именем name указывает имя потока; по умолчанию используется ’Thread-N’, где N — десятичное представление небольшого целого числа.

Интерфейсы объектов описаны в следующих разделах.

22.2.1. Объекты, реализующие блокировку

Функции Lock() и RLock() возвращают объекты, имеющие одинаковый набор методов:

acquire([waitflag])

При вызове без аргументов захватывает (блокирует) объект, дождавшись, если это необходимо, его освобождения другим потокам (возвращает None). Если задан аргумент waitflag (целое число), поведение функции зависит от его значения: 1 — функция ожидает освобождения объекта другим потокам (так же, как и с опущенным аргументом), 0 (и другие значения) — объект захватывается только, если это может быть сделано немедленно. При наличии аргумента функция возвращает 1, если захват объекта прошел успешно, в противном случае возвращает 0.

release()

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

В то время как объекты, возвращаемые функцией Lock(), реализуют примитивную блокировку (объект может быть захвачен один раз), для объектов, возвращаемых функцией RLock(), метод acquire() может быть вызван многократно одним потоком — для того, чтобы объект мог быть захвачен другим потоком, необходимо ровно столько же раз вызвать метод release().

22.2.2. Условия

Объекты, возвращаемые функцией Condition() всегда ассоциированы с объектом, реализующим блокировку. Такой объект может быть указан в качестве аргумента при инициализации или, по умолчанию, будет создан конструктором.

Объект, представляющий условие, имеет методы acquire() и release(), которые вызывают соответствующие методы ассоциированного объекта, реализующего блокировку. Он также имеет методы wait(), notify() и notifyAll(), которые должны вызываться только после того, как будет вызван метод acquire(). При вызове метода wait() объект-условие освобождает ассоциированный объект и блокирует выполнение до тех пор, пока из другого потока не будет вызван метод notify() или notifyAll(). После пробуждения метод снова захватывает ассоциированный объект. Вы можете указать максимальное время ожидания.

Методы notify() и notifyAll() не освобождают ассоциированный объект, реализующий блокировку. Таким образом, поток или потоки, вызвавшие метод wait(), будут пробуждены только после того, как поток, вызвавший notify() или notifyAll() окончательно освободит ассоциированный объект.

Приведем простой пример с производством и потреблением объектов. Пусть функция make_an_item_available() производит объект, get_an_available_item() его потребляет и an_item_is_available() возвращает истину, если есть в наличии произведенные (но еще не употребленные) объекты. Тогда следующие фрагменты кода могут быть использованы в потоках производителя и потребителя соответственно:

# Производим один объект
cv.acquire()
make_an_item_available()
cv.notify()
cv.release()

# Потребляем один объект
cv.acquire()
while not an_item_is_available():
    cv.wait()
get_an_available_item()
cv.release()

acquire([...])

release()

Вызывают одноименные методы ассоциированного объекта, реализующего блокировку.

wait([timeout])

Освобождает ассоциированный объект, реализующий блокировку, ожидает, пока другим потоком не будет вызван метод notify() или notifyAll(), и снова захватывает ассоциированный объект. Если задан и не равен None аргумент timeout (вещественное число), он указывает максимальное время ожидания в секундах. По умолчанию время ожидания не ограничено.

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

notify()

Пробуждает один поток, ожидающий выполнения условия, если таковой имеется.

notifyAll()

Пробуждает все потоки, ожидающие выполнения условия.

22.2.3. Семафоры

Объекты, возвращаемые функцией Semaphore() имеют такой же набор методов, как и объекты, реализующие блокировку (см. раздел 22.2.1). Семафор управляет внутренним счетчиком, который уменьшается при каждом вызове метода acquire() и увеличивается при каждом вызове метода release(). Начальное значение счетчика определяет аргумент, переданный конструктору Semaphore(). Значение счетчика не может стать меньше нуля: вызов метода acquire() при значении счетчика равным нулю блокирует выполнение до тех пор, пока значение не увеличится, то есть пока другой поток не вызовет метод release().

22.2.4. События

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

isSet()

Возвращает 1, если событие наступило (внутренний флаг является истиной).

set()

Устанавливает наступление события (внутренний флаг становится истинным). Все потоки, ожидающие события, пробуждаются.

clear()

Отменяет наступление события (внутренний флаг становится ложным).

wait([timeout])

Ожидает наступления события, то есть, если внутренний флаг является ложью, блокирует выполнение потока до тех пор, пока другой поток не вызовет метод set(). Если задан и не равен None аргумент timeout (вещественное число), он указывает максимальное время ожидания в секундах. По умолчанию время ожидания не ограничено.

22.2.5. Объекты, представляющие потоки

Экземпляры класса Thread представляют действия, выполняемые в отдельном потоке. Существует два способа определить эти действия: передача объекта, поддерживающего вызов, в качестве аргумента с именем target или переопределение метода run() в производных классах. В производных классах не следует переопределять другие методы, за исключением, возможно, конструктора. Если Вы переопределяете конструктор, не забудьте вызвать конструктор дочернего класса (Thread.__init__()) до того, как Вы будете что-либо делать с потоком.

После создания объекта, представляющего поток, Вы можете запустить его с помощью метода start(). После запуска поток считается активным до тех пор, пока не закончится выполнение метода run().

Каждый поток, реализованный с помощью Thread или производного от него класса имеет имя. Имя может быть задано при инициализации или с помощью метода setName() и извлечено с помощью метода getName().

Поток может “присоединиться” к другому потоку, вызвав метод join() объекта, представляющего этот поток. При этом выполнение потока, вызвавшего метод join() приостанавливается до тех пор, пока не завершится выполнение потока, к объекту которого был применен метод.

Поток может быть помечен как фоновый (daemon). Выполнение всей программы будет завершено только после того, как активными останутся только фоновые потоки. Начальное значение наследуется от текущего потока. Этот флаг может быть изменен с помощью метода setDaemon() и извлечен с помощью метода getDaemon().

Существует также объект, соответствующий основному потоку. Основной поток не является фоновым. Возможно также создание объектов, соответствующих “посторонним” потокам, то есть потокам, созданным без помощи модуля threading. Такие объекты имеют ограниченную функциональность. Они всегда считаются активными, фоновыми и к ним нельзя присоединиться с помощью метода join().

start()

Запускает выполнение задачи (метод run() объекта) в отдельном потоке. Этот метод может быть вызван не более одного раза.

run()

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

join([timeout])

Этот метод приостанавливает работу текущего потока (который вызвал метод) до окончания выполнения потока, к объекту которого метод применяется. Если задан и не равен None аргумент timeout (вещественное число), он указывает максимальное время в секундах ожидания завершения работы потока. По умолчанию (и если аргумент timeout равен None) время ожидания не ограничено.

К одному потоку можно присоединиться несколько раз. Поток не может присоединиться к самому себе, так как это привело бы к (мертвой) блокировке самого себя. К потоку нельзя присоединиться до того, как он будет запущен.

getName()

Возвращает имя потока.

setName(name)

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

isAlive()

Возвращает 1, если поток активен. Поток считается активным с момента вызова метода start() и до завершения выполнения задачи (метода run()).

isDaemon()

Возвращает значение внутреннего флага, который является истиной, если поток выполняется в фоновом режиме.

setDaemon(daemonic)

Устанавливает значение внутреннего флага, определяющего, в каком режиме выполняется поток, равным daemonic: если флаг является истиной, поток будет выполняться в фоновом режиме. Этот метод должен вызываться до запуска потока. Начальное значение наследуется от потока, создавшего данный поток.

Работа всей программы может быть завершена только после завершения работы всех нефоновых потоков.

22.3. Queue — синхронизированные очереди

Модуль Queue определяет класс, реализующий очередь (FIFO), доступ к которой может осуществляться из нескольких потоков. Доступность этого модуля зависит от наличия модуля thread.

Queue(maxsize)

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

Empty

Исключения этого класса генерируются при попытке извлечь из пустой или заблокированной очереди элемент с помощью метода get_nowait() (или get() с аргументом block равным нулю).

Full

Исключения этого класса генерируются при попытке добавить в полную или заблокированную очередь элемент с помощью метода put_nowait() (или put() с аргументом block равным нулю).

Экземпляры класса Queue имеют следующие методы:

qsize()

Возвращает количество элементов в очереди (в момент вызова метода).

empty()

Возвращает 1, если очередь (в момент вызова метода) пуста, иначе возвращает 0.

full()

Возвращает 1, если очередь (в момент вызова метода) содержит максимальное количество элементов, иначе возвращает 0.

put(item [, block])

Добавляет элемент в очередь. Если аргумент block опущен или является истиной, выполнение потока при необходимости приостанавливается до тех пор, пока в очереди не появится свободное место. Если аргумент block является ложью, элемент добавляется в очередь только, если это можно сделать немедленно, в противном случае генерируется исключение Full.

put_nowait(item)

Эквивалентно вызову put(item, 0).

get([block])

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

get_nowait()

Эквивалентно вызову get(0).

Не следует полагаться на значения, возвращаемые методами qsize(), empty() и full(): к моменту их получения ситуация может уже измениться.

23. Работа с базами данных

Модули, описанные в этой главе, предоставляют доступ к простым базам данных, реализуя интерфейс, аналогичным словарям. Во всех случаях в качестве ключа и значения могут использоваться только обычные строки [Реализация некоторых из приведенных здесь модулей такова, что они позволяют использовать любые объекты с интерфейсом буфера. Однако использование этой возможности приведет к непереносимости базы данных, а также может привести к конфликтам ключей.]. Если Вы хотите хранить объекты языка Python другого типа, воспользуйтесь модулем shelve.

23.1. Интерфейс к базам данных в стиле DBM

Модуль anydbm предоставляет универсальный интерфейс в стиле DBM к различным вариантам баз данных: dbhash (требует наличие модуля bsddb), gdbm или dbm. Если ни один из этих модулей не доступен, будет использована медленная, но полностью переносимая реализация на языке Python в модуле dumbdbm.

Модуль dbhash доступен в операционных системах UNIX и Windows и предоставляет интерфейс в стиле DBM к библиотеке BSD db. Для работы этого модуля необходим модуль bsddb.

Модули dbm и gdbm доступны только в операционных системах UNIX.

Заметим, что форматы файлов, создаваемых различными модулями не совместимы друг с другом.

23.1.1. Общая для всех модулей часть интерфейса

Все перечисленные выше модули определяют функцию-конструктор и исключение:

open(filename [, flag [, mode]])

Открывает файл с именем filename базы данных и возвращает соответствующий ему объект. Если файл уже существует, функция anydbm.open() использует для определения его типа модуль whichdb и для файла используется соответствующий модуль. При создании нового файла anydbm.open() использует первый модуль из перечисленных выше, который может быть импортирован.

Аргумент flag может иметь одно из следующих значений:

• ’r’ - Открыть существующий файл только для чтения (используется по умолчанию).
• ’w’ - Открыть существующий файл для чтения и записи.
• ’c’ - Открыть файл для чтения и записи. Если файл не существует, он будет создан.
• ’n’ - Создать новую пустую базу данных (старый файл перезаписывается) и открыть ее для чтения и записи.

В функции dbhash.open() на платформах, поддерживающих блокировку, к флагу может быть добавлен символ ‘l’, если блокировка должна быть использована. В функции gdbm.open() к флагу может быть добавлен символ ‘f’ для открытия файла в “быстром” режиме: в этом случае измененные данные не будут автоматически записываться в файл при каждом внесении изменений (см. также описание метода sync() в разделе 23.1.3).

Аргумент mode указывает биты разрешений, которые будут установлены для файла, принимая во внимание маску разрешений (umask). По умолчанию используется 0666.

error

Класс исключений, которые генерируются в случае возникновения различных ошибок, характерных для данного модуля. Заметим, что если в базе данных отсутствует запись с определенным ключом, генерируется исключение KeyError.

Имя dbhash.error является псевдонимом для класса bsddb.error.

В модуле anydbm эта переменная ссылается на кортеж классов исключений, которые могут быть сгенерированы непосредственно модулем anydbm (первый элемент) или одним из модулей, реализующим доступ к базе данных. Это не вносит каких-либо неудобств, так как кортежи с классами исключений, указанные после ключевого слова except, могут быть вложенными произвольным образом.

Объекты, возвращаемые функциями open() всех перечисленных модулей, поддерживают большинство операций, характерных для отображений: извлечение, установка и удаление значений по ключу, а также методы has_key() и keys(). Ключи и значения должны быть обычными строками. Кроме того, эти объекты имеют еще один метод:

close()

Закрывает файл с базой данных.

Объекты, возвращаемые функциями dbhash.open() и gdbm.open(), имеют дополнительные методы, описанные ниже.

23.1.2. Дополнительные методы объектов, возвращаемых функцией dbhash.open()

first()

Возвращает кортеж с ключом и значением первой записи в базе данных. Если база данных не содержит ни одной записи, генерируется исключение KeyError. Используя методы first() и next() Вы можете обойти все записи в базе данных.

next()

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

k, v = db.first()
try:
    print k, v
    k, v = db.next()
except KeyError:
    pass

sync()

Сбрасывает на диск все не записанные данные.

23.1.3. Дополнительные методы объектов, возвращаемых функцией gdbm.open()

firstkey()

Возвращает ключ первой записи в базе данных. Вы можете перебрать все записи базы данных с помощью методов firstkey() и nextkey().

nextkey(key)

Возвращает ключ к записи, следующей за записью с ключом key. Следующий пример выводит ключи для всех записей, не создавая списка ключей в памяти:

k = db.firstkey()
while k != None:
    print k
    k = db.nextkey(k)

reorganize()

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

sync()

Сбрасывает на диск все не записанные данные.

23.2. whichdb — определение формата файла базы данных

Этот модуль определяет единственную функцию, которая пытается определить, какой модуль должен быть использован для открытия базы данных: dbm, gdbm или dbhash.

whichdb(filename)

Возвращает None — если файл filename отсутствует или к нему нет доступа на чтение, пустую строку (’’)—если формат файла неизвестен. В остальных случаях возвращает строку с именем модуля (например, ’gdbm’), который должен быть использован для открытия файла.

23.3. bsddb — интерфейс к библиотеке баз данных BSD

Модуль bsddb предоставляет интерфейс к библиотеке BSD db [Обычно используется библиотека версии 1.85. Начиная с Python 2.0, версия библиотеки может быть указана при сборке. Следует помнить, что версии 1.85 и 2.0 библиотеки db несовместимы.]. С помощью этого модуля Вы можете создавать и работать с файлами баз данных типа “Hash”, “BTree” и “Record”. Объекты, возвращаемые функциями модуля, ведут себя аналогично словарям.

Первые три аргумента всех функций одинаковы: filename — имя файла базы данных, flag — флаги, определяющие способ открытия файла, и mode — биты разрешений (по умолчанию используется 0666), которые будут установлены для файла, принимая во внимание маску разрешений (umask). Аргумент flag может иметь одно из следующих значений:

• ’r’ - Открыть существующий файл только для чтения (используется по умолчанию).
• ’w’ - Открыть существующий файл для чтения и записи.
• ’c’ - Открыть файл для чтения и записи. Если файл не существует, он будет создан.
• ’n’ - Создать новую пустую базу данных (старый файл перезаписывается) и открыть ее для чтения и записи.

На платформах, поддерживающих блокировку, к флагу может быть добавлен символ ‘l’, если блокировка должна быть использована.

Остальные аргументы используются достаточно редко, Вы можете узнать об их назначении из документации к функции dbopen() библиотеки BSD db.

hashopen(filename [, flag [, mode [, bsize [, ffactor [, nelem [, cachesize [, hash [, lorder]]]]]]]])

Открывает файл базы данных в формате “Hash” и возвращает соответствующий ему объект.

btopen(filename [, flag [, mode [, btflags [, cachesize [, maxkeypage [, minkeypage [, psize [, lorder]]]]]]]])

Открывает файл базы данных в формате “BTree” и возвращает соответствующий ему объект.

rnopen(filename [, flag [, mode [, rnflags [, cachesize [, psize [, lorder [, reclen [, bval [, bfname]]]]]]]]])

Открывает файл базы данных в формате “Record” и возвращает соответствующий ему объект.

error

Класс исключений, которые генерируются в случае возникновения различных ошибок, характерных для этого модуля. Заметим, что если в базе данных отсутствует запись с определенным ключом, генерируется исключение KeyError.

Объекты, возвращаемые функциями hashopen(), btopen() и rnopen(), поддерживают большинство операций, характерных для отображений: извлечение, установка и удаление значений по ключу, а также методы has_key() и keys() (ключи и значения должны быть обычными строками). Кроме того, доступны следующие методы:

close()

Закрывает файл с базой данных.

set_location(key)

Устанавливает указатель на запись с ключом key и возвращает кортеж, содержащий ключ и значение для этой записи. Этот метод не может быть применен к объектам, созданным с помощью функции hashopen().

first()

Возвращает кортеж с ключом и значением первой записи в базе данных. Если база данных не содержит ни одной записи, генерируется исключение KeyError. Используя методы first() и next() Вы можете обойти все записи в базе данных.

next()

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

k, v = db.first()
try:
    print k, v
    k, v = db.next()
except KeyError:
    pass

last()

Возвращает кортеж с ключом и значением последней записи в базе данных. Если база данных не содержит ни одной записи, генерируется исключение KeyError. Используя методы last() и previous() Вы можете обойти все записи в базе данных в обратном порядке. Этот метод не может быть применен к объектам, созданным с помощью функции hashopen().

previous()

Возвращает кортеж с ключом и значением предыдущей записи. Этот метод не может быть применен к объектам, созданным с помощью функции hashopen().

sync()

Сбрасывает на диск все не записанные данные.

Пример:

>>> import bsddb
>>> db = bsddb.btopen('/tmp/spam.db', 'c')
>>> for i in xrange(10): db['%d' % i] = '%d' % (i*i)
...
>>> db['3']
'9'
>>> db.keys()
['0', '1', '2', '3', '4', '5', '6', '7', '8', '9']
>>> db.first()
('0', '0')
>>> db.next()
('1', '1')
>>> db.last()
('9', '81')
>>> db.set_location('2')
('2', '4')
>>> db.previous()
('1', '1')
>>> db.sync()
0

24. Сжатие данных

24.1. zlib — алгоритм сжатия, совместимый с gzip

Функции, определенные в этом модуле, позволяют упаковывать (сжимать) и распаковывать данные с помощью библиотеки zlib (http://www.info-zip.org/pub/infozip/zlib/, RFC 1950). Версия используемой библиотеки zlib языка C определена в виде константы:

ZLIB_VERSION

Строка с версией библиотеки.

Аргумент level в описанных ниже функциях должен быть равным Z_DEFAULT_COMPRESSION, 0 (Z_NO_COMPRESSION) или целым числом от 1 (Z_BEST_SPEED) до 9 (Z_BEST_COMPRESSION) и определяет уровень сжатия:

Z_NO_COMPRESSION

Сохранить данные без сжатия.

Z_BEST_SPEED

Обеспечивает максимальную скорость при меньшем сжатии.

Z_BEST_COMPRESSION

Обеспечивает наилучшее сжатие с меньшей скоростью.

Z_DEFAULT_COMPRESSION

Использует уровень, обеспечивающий компромисс между скоростью и степенью сжатия. В текущей версии библиотеки соответствует уровню 6.

Аргумент wbits (в текущей версии может быть целым числом от 8 до 15) определяет размер окна буфера истории равным 2**wbits. Большее значение обеспечивает лучшее сжатие при больших затратах памяти. При использовании отрицательных значений подавляется стандартный заголовок (эта недокументированная возможность позволяет использовать модуль zlib для работы с zip-файлами). Использование значения отличного от MAX_WBITS при распаковке может привести к возникновению ошибки. По умолчанию всегда используется значение MAX_WBITS.

Текущая версия библиотеки позволяет использовать единственный метод (аргумент method) сжатия:

Z_DEFLATED

Метод DEFLATE (см. RFC 1951).

Модуль определяет следующие исключение и функции:

error

Исключения этого класса генерируются в случае возникновения ошибок при упаковке или распаковке.

adler32(string [, value])

Вычисляет контрольную сумму Adler-32 строки string. Контрольная сумма, вычисленная по этому алгоритму практически настолько же надежна, как и CRC32, но вычисляется гораздо быстрее. Если задано число value, оно используется в качестве начального значения контрольной суммы, в противном случае используется фиксированное значение по умолчанию. Это позволяет вычислять контрольную сумму длинного потока по частям. Алгоритм Adler-32 недостаточно сильный, чтобы использовать его в криптографических целях.

compress(string [, level])

Возвращает строку, полученную в результате упаковки строки string.

compressobj([level [, method [, wbits [, mem_level [, strategy]]]]])

Возвращает объект, реализующий упаковку потока данных. Аргумент mem_level определяет использование памяти: 1 — использовать минимум памяти, но что сильно замедляет процесс, 9 — использовать максимум памяти, что дает максимальную скорость. По умолчанию используется DEF_MEM_LEVEL (8). Аргумент strategy может иметь значение Z_DEFAULT_STRATEGY, Z_FILTERED или Z_HUFFMAN_ONLY и определяет стратегию сжатия (см. документацию к библиотеке zlib языка C).

crc32(string [, value])

Вычисляет контрольную сумму CRC32 (Cyclic Redundancy Check) строки string. Если задано число value, оно используется в качестве начального значения контрольной суммы, в противном случае используется фиксированное значение по умолчанию. Это позволяет вычислять контрольную сумму длинного потока по частям. Алгоритм CRC32 недостаточно сильный, чтобы использовать его в криптографических целях.

decompress(string [, wbits [, bufsize]])

Возвращает строку, полученную в результате распаковки строки string. Аргумент bufsize определяет начальный размер буфера вывода (при необходимости буфер будет увеличен).

decompressobj([wbits])

Возвращает объект, реализующий распаковку потока данных. Аргумент wbits имеет такое же значение, как и для функции decompress().

Объекты, реализующие упаковку потока данных, имеют следующие методы:

compress(string)

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

flush([mode])

Обрабатывает содержимое внутреннего буфера и возвращает строку с упакованным остатком данных.

В качестве аргумента mode метода flush() может быть использована одна из следующих констант:

Z_SYNC_FLUSH

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

Z_FULL_FLUSH

Аналогично Z_SYNC_FLUSH, но также сбрасывает состояние. Распаковка может быть перезапущена с этого уровня, если предыдущие сжатые данные оказались поврежденными или необходим произвольный доступ к сжатым данным.

Z_FINISH

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

Объекты, реализующие распаковку потока данных, имеют следующие атрибут данных и методы:

unused_data

Строка с неиспользованными данными. Должна быть пустой, если объекту была передана вся строка с упакованными данными.

decompress(string)

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

flush()

Обрабатывает содержимое внутреннего буфера и возвращает строку с распакованным остатком данных. После вызова этого метода объект не может быть использован для распаковки данных.

24.2. gzip — работа с файлами, сжатыми программой gzip

Метод сжатия, предоставляемый модулем zlib, совместим с методом, используемым программой GNU gzip. Модуль gzip реализован поверх модуля zlib и предоставляет класс GzipFile, реализующий чтение и запись файлов в gzip-формате (RFC 1952). Упаковка и распаковка данных происходит автоматически, так что экземпляры класса GzipFile ведут себя аналогично обычным файловым объектам. Заметим, что этот модуль не позволяет работать с файлами дополнительных форматов (созданных программами compress и pack), которые могут быть распакованы программой gzip (gunzip).

GzipFile(filename [, mode [, compresslevel [, fileobj]]])

Возвращает объект аналогичный файловому, обеспечивающий прозрачную упаковку и распаковку данных. Экземпляры класса GzipFile имеют большинство методов, характерных для файловых объектов, кроме seek() и tell().

Если задан и не равен None аргумент fileobj (файловый или подобный объект), он будет использован для чтения/записи (аргумент filename в этом случае будет использован только в заголовке gzip-файла и может быть равен None), иначе будет открыт файл с именем filename.

Аргумент mode должен иметь одно из трех значений: ’rb’, ’ab’ или ’wb’. По умолчанию используется ’rb’.

Уровень сжатия устанавливается аргументом compresslevel, который должен быть целым числом от 1 до 9. По умолчанию используется значение 9, обеспечивающее максимальную степень сжатия.

Вызов метода close() экземпляра класса GzipFile не закрывает файловый объект fileobj. Это позволяет добавить дополнительные данные, а также извлечь результат, используя метод getvalue() экземпляра класса StringIO.

open(filename [, mode [, compresslevel]])

Эквивалентно вызову ‘GzipFile(filename, mode, compresslevel)’.

24.3. zipfile — работа с zip-архивами

Этот модуль доступен, начиная с версии 1.6, и позволяет записывать и читать zip-архивы.

error

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

is_zipfile(path)

Возвращает 1, если path является zip-архивом, иначе возвращает 0. Текущая реализация модуля не позволяет работать с архивами, содержащими комментарий.

ZipFile(filename [, mode [, compression]])

Возвращает объект, реализующий автоматическую упаковку/распаковку при чтении/записи файла с именем filename. Аргумент mode может иметь одно из трех значений: ’r’ (чтение), ’w’ (запись в новый архив) или ’a’ (добавление к существующему архиву). По умолчанию используется ’r’. В качестве аргумента compression может быть использована одна из приведенных ниже констант, при попытке использования недоступного метода генерируется исключение RuntimeError.

PyZipFile(filename [, mode [, compression]])

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

ZipInfo([filename [, date_time]])

Создает и возвращает объект, описывающий файл в архиве. Аргумент filename определяет имя файла (по умолчанию используется ’NoName’), date_time — дату и время создания файла (кортеж из целых чисел: год, месяц, число, час, минута, секунда).

В настоящий момент модуль поддерживает только два метода сжатия (аргумент compression конструктора ZipFile):

ZIP_STORED

Упаковка данных без сжатия (используется по умолчанию).

ZIP_DEFLATED

Наиболее часто используемый в zip-файлах метод сжатия. Этот метод требует наличия модуля zlib.

Экземпляры классов ZipFile и PyZipFile имеют следующие атрибуты данных и методы:

namelist()

Возвращает список имен файлов, содержащихся в архиве.

infolist()

Возвращает список экземпляров класса ZipInfo, представляющих описание файлов, содержащихся в архиве.

printdir()

Выводит в стандартный поток вывода (sys.stdout) оглавление архива.

testzip()

Считывает все файлы архива и проверяет для них контрольные суммы. Возвращает имя первого файла, для которого контрольная сумма не сходится или None, если тест прошел успешно.

getinfo(name)

Возвращает экземпляр класса ZipInfo, представляющий описание файла name.

read(name)

Считывает файл с именем name из архива и возвращает его содержимое в виде строки.

write(filename [, arcname [, compress_type]])

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

writestr(zinfo, bytes)

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

close()

Закрывает файл (если архив был открыт для записи, дописывает завершающую запись).

Экземпляры класса PyZipFile имеют дополнительный метод:

writepy(pathname [, basename])

Если pathname является каталогом пакета, рекурсивно добавляет все ‘.py’-файлы в архив, если pathname является обычным каталогом — добавляет в архив файлы, находящиеся в этом каталоге, в противном случае pathname должен быть ‘.py’-файлом, который будет добавлен в архив. Все модули (‘.py’-файлы) добавляются в архив в компилированном виде (‘.pyo’ или ‘.pyc’).

Экземпляры класса ZipInfo имеют следующие (основные) атрибуты, описывающие файл в архиве, и метод:

filename

Имя файла.

date_time

Дата и время создания файла, кортеж из целых чисел: год, месяц, число, час, минута, секунда.

compress_type

Метод сжатия.

comment

Комментарий (для каждого файла).

extra

Строка дополнительных данных.

CRC

Контрольная сумма CRC32 распакованного файла.

compress_size

Размер сжатого представления файла.

file_size

Размер распакованного файла.

FileHeader()

Печатает строку информации о файле в архиве.

25. Отладка и оптимизация кода на языке Python

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

25.1. Отладчик кода на языке Python

Модуль pdb реализует интерактивный отладчик программ, написанных на языке Python. Он позволяет устанавливать точки останова, использовать пошаговое выполнение строк исходного кода, исследовать кадры стека, выводить исходный код и выполнять инструкции языка Python в контексте любого кадра стека. Этот модуль также позволяет осуществить “вскрытие трупа” программы или интерактивных инструкций, выполнение которых завершилось генерацией исключения.

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

Запуск под контролем отладчика производится следующим образом (в качестве приглашения отладчика используется ‘(Pdb) ’):

>>> import pdb
>>> import mymodule
>>> pdb.run('mymodule.test()')
> <string>(0)?()
(Pdb) continue
> <string>(1)?()
(Pdb) continue
NameError: "There is no ... named 'spam'"
> <string>(1)?()
(Pdb)

Или Вы можете осуществить “вскрытие” уже после возникновения ошибки:

>>> import mymodule
>>> mymodule.test()
Traceback (most recent call last):
  File "<stdin>", line 1, in ?
  File "mymodule.py", line 2, in test
    print spam
NameError: There is no variable named 'spam'
>>> import pdb
>>> pdb.pm()
> mymodule.py(2)test()
-> print spam
(Pdb)

Файл ‘pdb.py’ может быть также использован в качестве программы для отладки других программ:

/usr/local/lib/python1.5/pdb.py myscript.py

25.1.1. Функции запуска отладчика

Модуль pdb определяет следующие функции, запускающие отладчик различными способами:

run(statements [, globals [, locals]])

Выполняет инструкции в строке statements (аналогично инструкции exec) под контролем отладчика. Приглашение отладчика появляется перед выполнением первой инструкции: Вы можете установить точки останова или использовать пошаговый режим выполнения. Аргументы globals и locals определяют окружение, в котором выполняются инструкции; по умолчанию используются пространства имен модуля __main__ (см. также раздел 10.3.11).

runeval(expression [, globals [, locals]])

Вычисляет выражение в строке expression (аналогично встроенной функции eval()) под контролем отладчика и (если вычисление прошло успешно) возвращает его значение. В остальном поведение этой функции аналогично поведению функции run().

runcall(function [, arg1 ...])

Вызывает функцию function (или другой объект, поддерживающий вызов) с указанными аргументами под контролем отладчика и (если вызов функции прошел успешно) возвращает значение, возвращаемое этой функцией. Приглашение отладчика появляется перед выполнением первой инструкции тела функции.

set_trace()

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

post_mortem(tb)

Производит “вскрытие” объекта tb (типа traceback).

pm()

Производит “вскрытие” объекта sys.last_traceback.

25.1.2. Команды отладчика

Ниже описаны команды, распознаваемые отладчиком. Большинство команд можно ввести в сокращенном виде; например, запись ‘h(elp)’ означает, что для выполнения данной команды следует ввести ‘h’ или ‘help’ (но не ‘he’, ‘hel’, ‘H’, ‘Help’ или ‘HELP’). Аргументы команды должны быть отделены символами пропуска. Необязательные аргументы команды указаны в квадратных скобках (‘[аргумент]’), альтернативные варианты разделены вертикальной чертой (‘|’).

При вводе пустой строки отладчик повторяет последнюю выполненную команду. Исключение: если последней была команда ‘list’, при вводе пустой строки выводятся следующие 11 строк исходного кода.

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

Вы можете ввести несколько команд отладчика в одной строке, используя в качестве разделителя ‘;;’ (‘;’ используется в качестве разделителя инструкций языка Python). Заметим, что отладчик не располагает “интеллектом”, достаточным для того, чтобы распознать ‘;;’ в середине строк, заключенных в кавычки.

Если в текущем и/или домашнем каталоге пользователя присутствует конфигурационный файл ‘.pdbrc’, его строки выполняются при запуске отладчика, как если бы Вы вводили их в ответ на приглашение интерпретатора (сначала читается файл в домашнем каталоге пользователя, затем — в текущем). Такая возможность особенно полезна для определения псевдонимов.

h(elp) [command]

?[command]

При использовании этой команды без аргументов выводит список всех возможных команд. С аргументом — выводит подсказку об использовании команды command. Команда ‘help pdb’ выводит полностью файл документации отладчика, используя программу постраничного просмотра, заданную в переменной окружения PAGER. Так как аргумент command должен быть идентификатором, для получения подсказки об использовании команды ‘!’ необходимо ввести ‘help exec’.

w(here)

Выводит информацию о месте, на котором выполнение было приостановлено.

d(own)

Перемещается на один кадр вниз по стеку (к более новому кадру стека).

u(p)

Перемещается на один кадр вверх по стеку (к более старому кадру стека).

b(reak) [([filename:]lineno | function) [, condition]]

Устанавливает точку останова в строке с номером lineno в файле filename (по умолчанию в текущем файле) или на первой инструкции функции function. Если указан аргумент condition, точка останова будет принята во внимание только в тех случаях, когда выражение condition является истиной. Каждой точке останова присваивается порядковый номер, который может быть использован для ее снятия. Без аргументов выводит информацию обо всех установленных точках останова.

tbreak [([filename:]lineno | function) [, condition]]

Эта команда работает аналогично команде ‘break’, но устанавливает временную точку останова, которая будет снята после первого использования.

cl(ear) [bpnumber [bpnumber ...]]

Если задан список номеров точек останова (bpnumber), снимает их. При использовании без аргументов снимает все точки останова, предварительно запросив подтверждение.

disable [bpnumber [bpnumber ...]]

Временно отключает точки останова с номерами, указанными в списке аргументов. Вы можете снова включить их с помощью команды ‘enable’.

enable [bpnumber [bpnumber ...]]

Включает точки останова, номера которых указаны в списке аргументов.

ignore bpnumber [count]

Указывает, что точка останова с номером bpnumber должна быть проигнорирована count (по умолчанию 0) раз.

condition bpnumber [condition]

Устанавливает условие, при котором точка останова будет приниматься во внимание: точка останова будет срабатывать только, если выражение condition является истиной. Если аргумент condition опущен, точка останова становится безусловной.

s(tep)

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

n(ext)

Продолжает выполнение до следующей строки в текущей функции или до возврата из нее. Разница между ‘next’ и ‘step’ состоит в том, что команда ‘step’ выполняет в пошаговом режиме вызываемые функции, в то время как команда ‘next’ выполняет их без остановок.

r(eturn)

Продолжает выполнение до возврата из текущей функции.

c(ont(inue))

Продолжает выполнение до первой (активной) точки останова.

l(ist) [first [, last]]

Выводит строки исходного кода. При использовании без аргументов выводит 11 строк вокруг текущей, с одним аргументом — вокруг указанной. Если указаны оба аргумента, выводит строки в диапазоне от first до last или, если число last меньше first, last строк, начиная с first.

a(rgs)

Выводит список аргументов текущей функции.

p expression

Вычисляет значение выражения expression и выводит его значение. Заметим, что для этих целей Вы можете использовать инструкцию print языка Python, однако ‘print’ не является командой отладчика.

alias [name [command]]

Создает псевдоним name для команды command. Команда не должна быть заключена в кавычки. Фрагменты ‘%1’, ‘%2’ и т. д. заменяются первым, вторым и т. д. аргументами, переданными команде name, а ‘%*’ — на все аргументы. Если аргумент command опущен, выводит команду для псевдонима name. При вызове без аргументов выводит список всех псевдонимов.

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

Приведем примеры двух полезных псевдонимов, которые можно поместить в конфигурационный файл ‘.pdbrc’: команда ‘alias pi for k, v in %1.__dict__.items(): print "%1.", k, -", v’ создает псевдоним ‘pi’, выводящий атрибуты указанного экземпляра, а команда ‘alias ps pi self’ создает псевдоним ‘ps’, выводящий атрибуты экземпляра, в теле метода которого псевдоним используется.

unalias name

Удаляет псевдоним name.

[!]statements

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

(Pdb) global list_options; list_options = ['-l']
(Pdb)

q(uit)

Выходит из отладчика. Выполнение отлаживаемой программы прерывается.

25.2. Замер производительности

Модули profile и pstats, описанные в этом разделе, позволяют осуществлять замер производительности программ на языке Python, анализировать результат и выводить отчет.

Copyright © 1994, by InfoSeek Corporation, all rights reserved.

Permission to use, copy, modify, and distribute this Python software and its associated documentation for any purpose (subject to the restriction in the following sentence) without fee is hereby granted, provided that the above copyright notice appears in all copies, and that both that copyright notice and this permission notice appear in supporting documentation, and that the name of InfoSeek not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission. This permission is explicitly restricted to the copying and modification of the software to remain in Python, compiled Python, or other languages (such as C) wherein the modified or derived code is exclusively imported into a Python module.

INFOSEEK CORPORATION DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL INFOSEEK CORPORATION BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

25.2.1. Введение

Настоящее введение предоставляет краткий обзор основных средств. Он позволит Вам быстро осуществить замер производительности, не вникая в подробности.

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

import profile
profile.run('foo()')

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

import profile
profile.run('foo()', 'fooprof')

Вы можете также использовать файл ‘profile.py’ в качестве программы для замера производительности другой программы, например:

python /usr/local/lib/python1.5/profile.py myscript.py

Для обработки статистических данных профиля большой программы могут быть полезны средства модуля pstats. Чтобы загрузить профиль из файла, воспользуйтесь следующим кодом:

import pstats
p = pstats.Stats('fooprof')

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

p.sort_stats('name')
p.print_stats()

А следующий пример выведет 10 наиболее важных строк, отсортированных по совокупному затраченному времени (методы экземпляров класса pstats.Stats возвращают ссылку на экземпляр, что позволяет вызывать последовательно несколько методов в одной инструкции):

p.sort_stats('cumulative').print_stats(10)

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

Вы можете ограничить вывод с помощью регулярного выражения, например, вывести статистику для конструкторов классов:

p.print_stats('__init__')

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

p.print_callers('__init__')
p.print_callees('__init__')

25.2.2. profile — замер производительности

Основная функция модуля:

run(string [, filename ...])

Выполняет инструкции в строке string (с помощью инструкции exec) и выводит статистическую информацию в файл с именем filename (по умолчанию используется sys.stdout). В заголовке выводимого профиля указывается строка с инструкциями string, общее число вызовов функций, число примитивных вызовов (без рекурсии) и затраченное время. Далее следует шесть колонок с подробной информацией для каждой функции:

ncalls

число вызовов (может быть два числа: общее число вызовов функции, число примитивных вызовов);

tottime

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

percall

среднее время, затрачиваемое на один вызов функции, исключая время, затраченное на вызовы из нее других функций (tottime/ncalls);

cumtime

суммарное время, затраченное на выполнение функции и вызовы из нее других функций;

percall

среднее время, затрачиваемое на один вызов функции и на вызовы из нее других функций (cumtime/ncalls);

filename:lineno(function)

имя файла, номер строки и имя функции.

Для реализации функции run() используется определенный в этом модуле класс Profile. Кроме того, модуль profile определяет класс HotProfile производный от Profile, который обеспечивает более быстрый замер производительности, но не подсчитывает зависимости между функциями и суммарное время, затраченное на выполнение функции и вызовы из нее других функций (колонка cumtime).

Для сортировки собранных статистических данных и вывода отчета функция run() использует класс pstats.Stats.

25.2.3. pstats — обработка статистических данных и вывод отчетов

Stats([filename ...])

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

Экземпляры класса Stats имеют следующие методы:

strip_dirs()

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

add([filename ...])

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

sort_stats([key ...])

Сортирует статистические данные объекта в соответствии с указанными критериями. Если указано более одного ключа, дополнительные ключи используются в качестве вторичного и т. д. критериев. Например, ‘sort_stats('name', 'file')’ сортирует данные по имени функции и данные для функций с одинаковыми именами по имени файла, в которой функция определена.

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

• ’calls’ - число вызовов (по убыванию);
• ’cumulative’ - суммарное время, затраченное на выполнение функции, исключая время, затраченное на вызовы из нее других функций (по убыванию);
• ’file’ - имя файла;
• ’module’ - имя модуля;
• ’pcalls’ - число примитивных вызовов (по убыванию);
• ’line’ - номер строки;
• ’name’ - имя функции;
• ’nfl’ - имя функции, имя файла, номер строки (вызовы ‘sort_stats('nfl')’ и ‘sort_stats('name', 'file', 'line')’ эквивалентны);
• ’stdname’ - стандартное имя, содержащее имя файла, номер строки и имя функции;
• ’time’ - суммарное время, затраченное на выполнение функции, исключая время, затраченное на вызовы из нее других функций (по убыванию).

reverse_order()

Меняет порядок следования данный на обратный.

print_stats([restriction ...])

Выводит отчет (аналогично функции profile.run()). Порядок следования данных определяется последним вызовом метода sort_stats(). Аргументы могут быть использованы для ограничения вывода информации. Каждый аргумент может быть целым числом (максимальное количество строк с данными), вещественное число от 0.0 до 1.0 (доля выводимой информации) или строка с регулярным выражением (выводятся только строки, ему удовлетворяющие). Если указано несколько ограничений, они применяются последовательно.

print_callers([restriction ...])

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

print_callees([restriction ...])

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

Все описанные здесь методы возвращают ссылку на экземпляр, поэтому несколько операций могут быть записаны одной инструкцией.

26. Выполнение в защищенном режиме

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

С другой стороны, существует класс приложений, для которых такая “открытость” нежелательна. Представьте: Web-броузер (например, Grail) загружает код, написанный на языке Python, с различных адресов в Internet и выполняет его на локальной машине. Так как автор кода неизвестен, очевидно, что Вы не можете доверить ему все ресурсы своей машины.

При выполнении кода в защищенном режиме (restricted execution) происходит разделение потенциально опасного кода и безопасного кода. Идея состоит в создании “надсмотрщиком” окружения с ограниченными полномочиями и выполнении в нем кода, которому Вы не доверяете. Заметим, что код, выполняемый в таком окружении, может создать новое окружения с меньшими (но не большими) полномочиями.

Особенность модели защищенного режима в языке Python состоит в том, что интерфейс, представленный потенциально опасному коду, обычно такой же, как и в обычном режиме. Таким образом, нет необходимости в изучении каких-либо особенностей для написания кода, который будет выполняться в защищенном режиме. Так как окружение для защищенного режима создается “надсмотрщиком”, Вы можете накладывать различные ограничения в зависимости от назначения приложения. Например, в определенной ситуации Вы можете посчитать безопасным чтение файлов в определенном каталоге, но не запись в них. В этом случае “надсмотрщик” может переопределить встроенную функцию open() таким образом, чтобы она генерировала исключение IOError, если открываемый файл находится за пределами разрешенного каталога или файл открывается для записи.

Интерпретатор языка Python для каждого блока проверяет переменную __builtins__ и, если она не является ссылкой на встроенный модуль __builtin__ или словарь, представляющий пространство его имен, считает, что блок кода выполняется в защищенном режиме. В защищенном режиме действуют некоторые ограничения, которые не позволяют программе выйти из окружения с ограниченными полномочиями. Например, становятся недоступными атрибут функций func_globals и атрибут классов и экземпляров __dict__.

Следующие два модуля предоставляют средства для настройки окружения защищенного режима:

26.1. rexec — основные средства настройки защищенного режима

Этот модуль определяет класс RExec, предоставляющий методы r_eval(), r_execfile(), r_exec() и r_import(), являющиеся ограниченными версиями встроенных функций eval() и execfile() и инструкций exec и import. Код, выполняемый в созданном этим классом окружении, имеет доступ только к модулям и функциям, которые считаются безопасными. Вы можете определить производный от RExec класс, если необходимо добавить или убрать какие-либо возможности.

Заметим, что класс RExec предотвращает использование кодом опасных операций (например, чтение и запись файлов или использование сетевых соединений), но не может защитить от использования слишком большого количества памяти или процессорного времени.

RExec([hooks [, verbose]])

Создает и возвращает объект, предоставляющий окружение с ограниченными возможностями. Аргумент hooks должен быть экземпляром RHooks (в настоящий момент не документирован) или производного от него класса, который реализует загрузку модулей. Если аргумент hooks опущен или равен None, автоматически создается новый экземпляр (используются аргументы по умолчанию). Если задан и является истиной аргумент verbose, на стандартный поток вывода будет выводиться отладочная информация.

Используя альтернативный объект в качестве аргумента hooks, Вы можете обеспечить переадресацию запросов к файловой системе через механизм RPC (Remote Procedure Call) или реализовать загрузку модулей с определенного URL (как это сделано в браузере Grail).

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

nok_builtin_names

Имена встроенных функций, которые не будут доступны в защищенном режиме. Для класса RExec это ‘(’open’, ’reload’, ’__import__’)’. Добавлять имена в производных классах следует следующим способом:

class MyRExec(RExec):
    ...
    nok_builtin_names = RExec.nok_builtin_names +

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

ok_builtin_modules

Имена встроенных и динамически подгружаемых модулей, использование которых безопасно. Для класса RExec это ‘('audioop', 'array', 'binascii', 'cmath', 'errno', 'imageop', 'marshal', 'math', 'md5', 'operator', 'parser', 'regex', 'pcre', 'rotor', 'select', 'strop', 'struct', 'time')’.

ok_path

Каталоги, в которых будет производиться поиск модулей при импортировании в защищенном режиме. Для класса RExec берется значение sys.path на момент инициализации модуля rexec.

ok_posix_names

Имена, определенные в модуле os, которые будут доступны в защищенном режиме. Для класса RExec это ‘('error', 'fstat', 'listdir', 'lstat', 'readlink', 'stat', 'times', 'uname', 'getpid', 'getppid', 'getcwd', 'getuid', 'getgid', 'geteuid', 'getegid')’.

ok_sys_names

Имена, определенные в модуле sys, которые будут доступны в защищенном режиме. Для класса RExec это ‘('ps1', 'ps2', 'copyright', 'version', 'platform', 'exit', 'maxint')’.

Экземпляры класса RExec поддерживают следующие методы. Отличие методов с приставками ‘r_’ и ‘s_’ состоит в том, что последние после выполнения кода восстанавливают исходные значения переменных sys.stdin, sys.stderr и sys.stdout в созданном окружении.

r_eval(code)

s_eval(code)

Вычисляет и возвращает значение выражения языка Python, представленного строкой или объектом кода code. Вычисление производится в модуле __main__ созданного окружения.

r_exec(code)

s_exec(code)

Выполняет в модуле __main__ созданного окружения инструкции языка Python, представленные строкой или объектом кода code.

r_execfile(filename)

s_execfile(filename)

Выполняет в модуле __main__ созданного окружения код языка Python, содержащийся в файле filename.

Класс RExec также определяет следующие методы, которые неявно вызываются при выполнении кода в защищенном режиме. Вы можете переопределить их в производном классе, чтобы изменить накладываемые ограничения (достаточно переопределить метод с приставкой ‘r_’).

r_import(modulename [, globals [, locals [, fromlist]]])

s_import(modulename [, globals [, locals [, fromlist]]])

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

r_open(filename [, mode [, bufsize]])

s_open(filename [, mode [, bufsize]])

Этот метод используется вместо встроенной функции open() (см. главу 12). По умолчанию метод r_open() позволяет открыть любой файл только для чтения (режимы ’r’ и ’rb’). Смотрите пример в конце раздела, реализующий метод r_open() с меньшими ограничениями.

r_reload(module)

s_reload(module)

Этот метод используется вместо встроенной функции reload() (см. главу 12) для перезагрузки модуля.

r_unload()

s_unload()

Вы можете использовать эти методы для выгрузки модуля (удаления его из словаря sys.modules созданного окружения).

Приведем пример класса, позволяющего открывать файлы на запись в каталоге ‘/tmp’:

from rexec import RExec
from os.path import normpath, islink

class TmpWriterRExec(RExec):
    def r_open(self, file, mode='r', bufsize=-1):
    if mode not in ('r', 'rb'):
        file = normpath(file)
    if file[:5]!='/tmp/' or islink(file):
        raise IOError(
              "Can't write outside /tmp")
    return open(file, mode, bufsize)

26.2. Bastion — ограничение доступа к экземплярам классов

Этот модуль предназначен для использования совместно с модулем rexec и предоставляет возможность запретить доступ ко всем атрибутам данных и небезопасным методам экземпляра класса.

Bastion(object [, filter [, name [, bastionclass]]])

Возвращает экземпляр класса bastionclass (по умолчанию используется BastionClass), который ведет себя аналогично объекту object, но предоставляет доступ только к методам, для имен attr_name которых filter(attr_name) является истиной. Функция filter, используемая по умолчанию, запрещает доступ к методам, имена которых начинаются с символа подчеркивания (‘_’). При попытке доступа к атрибутам данных или запрещенным методам генерируется исключение AttributeError. Строковым представлением (результатом применения встроенной функции repr() или при заключении в обратные кавычки) защищенного объекта будет ’<Bastion for name>’. Если аргумент name опущен или равен None, вместо name используется repr(object).

BastionClass(getfunc, name)

Этот (или производный от него) класс используется в качестве аргумента bastionclass функции Bastion() и реализует защиту объекта. Аргумент getfunc должен быть функцией (тип function), возвращающей значение атрибута с именем, переданным в качестве единственного аргумента, если атрибут считается безопасным, и генерирующей исключение AttributeError, если доступ к атрибуту запрещен. Аргумент name используется при конструировании строкового представления объекта.

27. Поддержка протоколов Internet

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

27.1. cgi — протокол CGI

Этот модуль предоставляет средства, которые будут полезны при написании программ, использующих интерфейс CGI (Common Gateway Interface, общий шлюзовой интерфейс), на языке Python.

27.1.1. Введение

CGI-программа вызывается HTTP-сервером, обычно для обработки данных, переданных пользователем через элементы ‘<FORM>’ и ‘<ISINDEX>’ языка HTML. HTTP-сервер помещает информацию о запросе (имя узла клиента, запрашиваемый URL, строка параметров запроса и др.) в переменные окружения программы, выполняет программу и пересылает клиенту его вывод. Часть данных от клиента может также поступать на стандартный поток ввода программы. Модуль cgi берет на себя заботу обо всех возможных способах передачи данных и предоставляет их программе через простой интерфейс. Модуль также предоставляет набор средств, которые будут полезны при отладке.

Вывод CGI-программы должен состоять из двух частей, разделенных пустой строкой. Первая часть содержит набор заголовков, которые описывают тип данных, следующих во втором разделе. Простейшая программа может выглядеть следующим образом:

# Заголовок: далее следует HTML-документ
print "Content-Type: text/html"
# Пустая строка: конец заголовков
print
# Вторая часть: HTML-документ
print "<html>"
print "<title>Вывод CGI-программы</title>"
print "<body>"
print "<h1>Это моя первая CGI-программа</h1>"
print "Привет всему миру!"
print "</body>"
print "</html>"

27.1.2. Использование модуля cgi

Начните с инструкции ‘import cgi’. Никогда не используйте ‘from cgi import *’ — модуль определяет множество имен для внутреннего использования и для совместимости с предыдущими версиями, появление которых нежелательно в вашем пространстве имен.

FieldStorage([**keyword_args])

В этом классе сосредоточена наиболее часто используемая функциональность модуля cgi. При инициализации его без аргументов происходит обработка данных со стандартного потока ввода и/или из переменных окружения в соответствии со стандартом CGI [С одним исключением: при использовании метода POST не обрабатываются данные в строке запроса (часть URL после символа ‘?’).]. Так как при этом поглощаются данные со стандартного ввода, следует создавать только один экземпляр класса FieldStorage за все время работы программы.

Конструктор класса воспринимает следующие именованные аргументы (keyword_args):

fp

Указывает альтернативный файловый (или подобный) объект, из которого будут считываться данные. По умолчанию используется sys.stdin. Этот аргумент игнорируется при использовании метода GET.

headers

Отображение с информацией о HTTP-заголовках. По умолчанию извлекается из переменных окружения.

environ

Отображение с информацией о переменных окружения. По умолчанию используется os.environ.

keep_blank_values

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

strict_parsing

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

Помимо представления всей формы, экземпляры класса FieldStorage используются для представления полей формы, переданных в виде ‘multipart/formdata’.

MiniFieldStorage

Экземпляры этого класса используются для представления полей формы, переданных в виде ‘application/x-www-form-urlencoded’.

Экземпляры классов FieldStorage и MiniFieldStorage имеют следующие общие атрибуты данных:

name

Имя поля или None.

filename

Имя файла, указанное клиентом, или None.

value

Значение поля в виде строки, список значений (если используется несколько полей с одинаковым именем) или None. Если объект соответствует загружаемому файлу, при каждом обращении к этому атрибуту производится чтение всего содержимого файла.

file

Файловый (или подобный) объект, из которого Вы можете считывать данные, или None, если данные представлены строкой.

type

Тип содержимого поля (заголовок ‘Content-Type’) или None, если тип не указан.

type_options

Словарь параметров, указанных в заголовке ‘Content-Type’.

disposition

Размещение содержимого поля (заголовок ‘Content-Disposition’) или None.

disposition_options

Словарь параметров, указанных в заголовке ‘Content-Disposition’.

headers

Отображение, содержащее записи для всех заголовков.

Экземпляры класса FieldStorage являются отображениями имен полей к представляющим их объектам и поддерживают основные операции, характерные для отображений, а также методы has_key() и keys(). Помимо этого они имеют следующие методы:

getvalue(key [, default])

Возвращает строковое значение поля с именем key или default, если нет поля с таким именем. Если форма содержит несколько полей с таким именем, возвращает список их строковых значений. По умолчанию в качестве аргумента default используется None.

make_file(binary)

Этот метод используется реализацией класса для создания временного хранилища данных. По умолчанию используется tempfile.TemporaryFile(). Вы можете переопределить этот метод в производном классе, предоставив альтернативный способ временного хранения данных. В качестве аргумента binary используется строка ’b’, если файл должен быть открыт в двоичном режиме, в противном случае он равен пустой строке. Метод должен возвращать файловый (или подобный) объект, доступный для чтения и записи.

Приведем простой пример CGI-программы, который проверяет, чтобы были заполнены поля ‘name’ и ‘addr’:

import cgi

print """\
Content-Type: text/html

<html>
  <body>"""

form = cgi.FieldStorage()
if form.has_key("name") and form.has_key("addr"):
    print """\
    <p>eIN: %s</p>
    <p>aAOAO: %s</p>"""
else:
    print """\
    <h1>Ошибка</h1>
    <p>Введите, пожалуйста, имя и адрес.</p>"""
print """\
  </body>
</html>"""

Поля формы, доступные через form[key], могут быть представлены экземплярами класса FieldStorage, MiniFieldStorage (в зависимости от способа кодирования) или списком экземпляров, если форма содержит несколько полей с указанным именем. В последнем случае метод getvalue() также возвращает список строковых значений полей. Если в Вашем случае возможно присутствие нескольких полей с одинаковым именем, используйте встроенную функцию type() для определения типа:

value = form.getvalue("username", "")
if type(value) is type([]):
    # Заполнено несколько полей с именем пользователя
    usernames = ",".join(value)
else:
    # Заполнено не более одного поля с именем
    # пользователя
    usernames = value

Если объект представляет загружаемый файл, при обращении к атрибуту value весь файл считывается в память в виде строки. Такое поведение не всегда желательно. Вы можете определить, представляет ли объект загружаемый файл, по значению атрибута filename или file:

fileitem = form["userfile"]
if fileitem.file:
    # Объект fileitem представляет загружаемый файл.
    # Подсчитываем строки, не сохраняя весь файл в
    # памяти.
    linecount = 0
    while 1:
        if fileitem.file.readline()
            linecount += 1
        else:
            break

Проект стандарта по организации загрузки файлов принимает во внимание возможность загрузки нескольких файлов из одного поля HTML-формы (рекурсивно используя ‘multipart/*’). В этом случае объект будет являться отображением, с которым можно работать аналогично объекту, представляющему всю форму. Вы можете определить такой объект по значению атрибута type (‘obj.type and obj.type.startswith('multipart/')’).

27.1.3. Дополнительные возможности модуля

Модуль cgi определяет также дополнительные функции, которые будут полезны, если необходим более тонкий контроль.

parse([**keyword_args])

Обрабатывает данные со стандартного потока ввода и/или из переменных окружения в соответствии со стандартом CGI1 и возвращает словарь, отображающий имена полей к спискам значений. Функция воспринимает именованные аргументы fp, environ, keep_blank_values и strict_parsing, которые имеют такое же значения, как и для конструктора класса FieldStorage (см. раздел 27.1.2).

parse_qs(qs [, **keyword_args])

Обрабатывает строку запроса, переданную в качестве аргумента qs (данные типа ‘application/x-www-form-urlencoded’), и возвращает словарь, отображающий имена полей к спискам значений. Функция воспринимает именованные аргументы keep_blank_values и strict_parsing, которые имеют такое же значение, как и для конструктора класса FieldStorage (см. раздел 27.1.2).

parse_qsl(qs [, **keyword_args])

Работает аналогично функции parse_qs(), но возвращает список кортежей с именем поля и его значением.

parse_multipart(fp, pdict)

Обрабатывает данные в виде ‘multipart/form-data’ из потока fp и возвращает словарь, отображающий имена полей к спискам значений. Аргумент pdict должен быть словарем, содержащим параметры из заголовка ‘Content-Type’.

Заметим, что эта функция не обрабатывает вложенные ‘multipart/*’ части. Кроме того, она полностью считывает файл в память, что может быть нежелательным при загрузке больших файлов. Класс FieldStorage не обладает этими недостатками.

parse_header(string)

Обрабатывает MIME-заголовок в строке string и возвращает кортеж, содержащий основное значение и словарь параметров. Предполагается, что строка string не содержит самого имени заголовка, то есть для заголовка ‘Content-Type: text/plain; encoding=koi8-r’ аргумент должен быть равен ’text/plain; encoding=koi8-r’.

test()

Эта функция реализует готовую CGI-программу, предназначенный для тестирования: выводит минимальный HTTP-заголовок и всю переданную программе информацию в формате HTML. Функция test() вызывается при использовании файла модуля ‘cgi.py’ в качестве программы.

print_environ()

Выводит информацию о переменных окружения в формате HTML.

print_form(form)

Выводит значения полей формы, представленной объектом form (должен быть экземпляром класс FieldStorage), в формате HTML.

print_directory()

Выводит содержимое текущего каталога в формате HTML.

print_environ_usage()

Выводит список переменных окружения, которые могут быть использованы CGI-программой.

escape(s [, quote])

Заменяет символы ‘&’, ‘<’ и ‘>’ в строке s на соответствующие сущности HTML. Используйте эту функцию для вывода текста, который может содержать такие символы. Если задан и является истиной аргумент quote, также заменяет символ двойной кавычки (‘"’), что может быть полезно для вывода значений атрибутов (например, ‘'a href=" + escape(url, 1) + ' '’).

Кроме того, модуль предоставляет средства для ведения log-файла:

logfile

Если эта переменная имеет непустое значение, она определяет имя log-файла. Используется только, если переменная logfp является ложью.

logfp

Файловый (или подобный) объект, соответствующий log-файлу.

log(format [, *args])

Записывает строку ‘format % args + '\n'’ в log-файл, определяемый значениями переменных logfile и logfp при первом вызове функции. Если в момент первого вызова этой функции обе переменный являются ложью, этот и все последующие вызовы функции ничего не делают.

27.1.4. Вопросы безопасности

Существует одно важное правило: если Вы запускаете внешнюю программу или считывает или записываете файл, убедитесь, чтобы в качестве параметров соответствующих функций (например, os.system(), os.popen*(), os.exec*(), os.spawn*(), open()) не использовались произвольные строки, полученные от клиента. Не следует доверять даже частям URL и именам полей, так как они могут поступить вовсе не из Вашей формы.

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

27.1.5. Установка CGI-программы

Поместите Вашу программу в каталог, предназначенный для CGI-программ (обычно это ‘cgi-bin’). Убедитесь, что пользователь, от имени которого запущен HTTP-сервер, имеет доступ на чтение и выполнение программы. В операционных системах UNIX первая строка программы должна начинаться с ‘#!’, после чего должен следовать полный путь к интерпретатору, например:

#!/usr/local/bin/python

Для систем, отличных от UNIX, потребуется дополнительная настройка HTTP-сервера для того, чтобы он “знал”, каким образом необходимо выполнять программы на языке Python.

Если Ваша программа должна читать или записывать файлы, убедитесь, что пользователь, от имени которого запущен HTTP-сервер, имеет соответствующий доступ к каталогам и файлам. Следует также помнить, что значения переменных окружения пользователя, от имени которого будет выполняться программа (в том числе переменных PATH и PYTHONPATH) могут отличаться от тех, которые имеете Вы сами.

Для того, чтобы импортировать модули из каталогов, которые не включены в пути поиска модулей по умолчанию, измените переменную sys.path перед тем, как импортировать другие модули. Например:

import sys
sys.path.insert(0, "/usr/home/joe/lib/python")

Следует помнить, что поиск производится в каталогах в том порядке, в котором они следуют в списке sys.path. Таким образом, в приведенном примере поиск будет производиться сначала в ‘/usr/home/joe/lib/python’, а затем в путях по умолчанию.

27.1.6. Отладка

К сожалению, часто CGI-программа работает в командной строке и, при этом, ведет себя странно при запуске сервером. Существует как минимум одна причина, по которой Вам следует сначала попробовать запустить программу из командной строки: это позволит Вам исключить синтаксические ошибки.

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

http://hostname/cgi-bin/cgi.py?name=Joe&addr=At+Home

Если при этом Вы получаете ошибку 404 — сервер не может найти программу; вероятно, необходимо установить его в другой каталог. Если же Вы получаете другую ошибку (например, 500) — у Вас проблемы с установкой программы или настройкой сервера, которые необходимо устранить перед тем, как идти дальше. И, наконец, если Вы получили форматированный вывод переменных окружения и содержимого формы (в нашем примере это поле ‘addr’ со значением ‘At home’ и поле ‘name’ со значением ‘Joe’) — файл ‘cgi.py’ установлен правильно.

Следующим шагом вызовите функцию test() модуля cgi из Вашей программы, то есть замените его код следующими двумя инструкциями:

import cgi
cgi.test()

Вы должны получить точно такой же результат, как и при обращении к ‘cgi.py’.

Когда обычная программа на языке Python генерирует исключение, которое не обрабатывается, интерпретатор выводит информацию об исключении и прерывает выполнение. Однако вывод информации об исключении производится на стандартный поток ошибок (sys.stderr), который перенаправляется в log-файл сервера или вовсе игнорируется. Чтобы этого не происходило, Вы можете поместить в начало программы инструкцию

import sys
sys.stderr = sys.stdout

или поместить основной текст программы в блок try ... except и самостоятельно выводить информацию об исключении, например:

import cgi
print 'Content-Type: text/html\n'
try:
    # Основной текст CGI-программы
    ...
except:
    cgi.print_exception(limit=10)

27.2. urllib — чтение произвольных ресурсов по URL

Этот модуль предоставляет средства высокого уровня для чтения сетевых ресурсов, используя различные протоколы. В частности функция urlopen() ведет себя аналогично встроенной функции open(), но воспринимает URL (Uniform Resource Locator, единообразный указатель ресурса) вместо имени файла. При этом, естественно, налагаются некоторые ограничения: Вы можете открыть ресурс только для чтения и полученный “файловый” объект не имеет метода seek().

Определенные в этом модуле средства позволяют обращаться к ресурсам через proxy-сервер, не требующий аутентификации. Если proxy-сервера не указаны явно, они определяются через переменные окружения, системный реестр (Windows) или Internet Config (Macintosh). В операционных системах UNIX для использования proxy необходимо перед запуском интерпретатора установить переменные окружения (регистр букв имен переменных может быть произвольным) http_proxy, ftp_proxy и gopher_proxy равными URL, указывающим на proxy-сервера для соответствующих протоколов.

urlopen(url [, data])

Создает и возвращает объект, реализующий чтение ресурса url. Если URL не содержит идентификатора протокола (scheme identifier) или в качестве идентификатора используется ‘file’, открывается локальный файл. В остальных случаях открывается сетевое соединение. Если соединение не может быть установлено или сервер сообщает об ошибке, генерируется исключение IOError.

По умолчанию для протокола HTTP используется метод GET. Для того, чтобы использовался метод POST, необходимо указать аргумент data с данными в формате ‘application/x-www-form-urlencoded’ (см. описание функции urlencode() ниже).

urlretrieve(url [, filename [, reporthook [, data]]])

Копирует ресурс url в локальный файл. Если URL указывает на локальный файл или кэш уже содержит свежую копию ресурса, копирование не производится. Функция возвращает кортеж вида ‘(filename, headers)’, где filename — имя локального файла с копией ресурса и headers — None, если url ссылается на локальный файл, иначе — объект, возвращаемый методом info() объекта, реализующего чтение ресурса.

Аргумент filename указывает имя локального файла, в который будет производиться копирование. По умолчанию имя файла генерируется с помощью функции tempfile.mktemp(). Задав аргумент reporthook Вы можете отслеживать процесс копирования. Функция (или другой объект, поддерживающий вызов) reporthook вызывается при установлении сетевого соединения и после загрузки каждого блока ресурса с тремя аргументами: число загруженных блоков, размер блока в байтах и размер файла (-1, если размер неизвестен). Аргумент data имеет такое же значение, как и для функции urlopen().

urlcleanup()

Очищает кэш, созданный предыдущими вызовами функции urlretrieve() [В текущих реализациях модуля кэширование по умолчанию отключено, так как еще не реализован механизм проверки срока хранения копий ресурсов.].

quote(string [, safe])

Заменяет специальные символы в строке string на последовательности вида ‘%xx’ и возвращает результат. Преобразованию никогда не подвергаются буквы, цифры и символы ‘_’, ‘,’, ‘.’ и ‘-’. Аргумент safe указывает дополнительные символы, которые должны быть оставлены без изменений; по умолчанию он равен '/'.

quote_plus(string [, safe])

Работает аналогично функции quote(), но также заменят пробелы на ‘+’, как это необходимо для обработки значений полей форм. Если символ ‘+’ не содержится в строке safe, то он заменяется на ‘%2b’.

unquote(string)

Заменяет специальные последовательности вида ‘%xx’ на соответствующие символы и возвращает результат.

unquote_plus(string)

Работает аналогично функции unquote(), но также заменяет символы ‘+’ пробелами, как это необходимо для восстановления значений полей форм.

urlencode(dict)

Возвращает строку с данными dict (отображение строк-имен переменных к строкам-значениям) в формате ‘application/x-www-form-urlencoded’. Результат может быть использован в качестве аргумента data функций urlopen() и urlretrieve() и метода open() экземпляров URLopener и производных от него классов. Эта функция полезна для преобразования значений полей формы в строку запроса. Возвращаемая строка состоит из последовательности фрагментов вида ‘key=value’ для каждой записи в словаре, разделенных символом ‘&’, где key и value обрабатываются с помощью функции quote_plus().

Объекты, реализующие чтение ресурса, помимо read(), readline(), readlines(), fileno() и close(), характерных для файловых объектов (см. раздел 11.7), имеют следующие методы:

info()

Возвращает экземпляр класса mimetools.Message, содержащий метаинформацию о ресурсе. При использовании протокола HTTP этот объект содержит информацию обо всех заголовках. При использовании протокола FTP заголовок ‘Content-Length’ будет присутствовать, если сервер посылает информацию о длине файла. При обращении к локальному файлу возвращаемый этим методом объект будет содержать заголовок ‘Date’ с датой и временем последнего изменения, заголовок ‘Content-Length’ с размером файла и заголовок ‘Content-Type’ с предполагаемым типом файла.

geturl()

Возвращает истинный URL ресурса. В некоторых случаях HTTP-сервер перенаправляет клиента на другой URL. Такие перенаправления автоматически обрабатываются, и Вы получаете ресурс с новым URL, узнать который можно с помощью этого метода.

Функции urlopen() и urlretrieve() создают и используют экземпляр класса FancyURLopener. Созданный объект сохраняется для дальнейшего использования этими функциями. Если Вам необходим более тонкий контроль — используйте FancyURLopener, URLopener или производные от них классы.

URLopener([proxies [, **x509]])

Базовый класс, реализующий чтение ресурсов. Если Вам не нужна поддержка каких-либо дополнительных протоколов — используйте класс FancyURLopener. Если задан и не равен None аргумент proxies, он должен быть отображением идентификаторов протоколов (scheme identifier) к URL соответствующих proxy-серверов и будет использован для определения способа соединения. По умолчанию URL proxy-серверов определяются по схеме, описанной в начале раздела.

Для аутентификации при использовании протокола HTTPS должны быть указаны именованные аргументы (x509) key_file и cert_file.

FancyURLopener([proxies [, **x509]])

Этот класс является производным от класса URLopener и предоставляет обработку HTTP-ответов с кодами 301, 302 и 401. При получении ответов с кодами 301 и 302 используется заголовок ‘Location’ для переадресации на другой URL. Для ответов с кодом 401 используется базовая аутентификация. Аргументы конструктора этого класса имеют такое же значение, как и для конструктора класса URLopener.

Экземпляры классов URLopener и FancyURLopener имеют следующие методы и атрибуты данных:

open(url [, data])

Открывает ресурс url и возвращает объект, аналогичный файловому, реализующий чтение ресурса (см. выше). Этот метод проверяет кэш, обрабатывает информацию о proxy-сервере и вызывает один из методов open_scheme(), где scheme заменяется идентификатором протокола (в котором символы ‘-’ заменены на ‘_’), или метод open_unknown(), если используемый идентификатор протокола неизвестен. Аргумент data имеет такое же значение, как и для функции urlopen().

open_unknown(url [, data])

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

retrieve(url [, filename [, reporthook [, data]]])

Копирует ресурс url в локальный файл. Если URL указывает на локальный файл или кэш уже содержит свежую копию ресурса, копирование не производится. Метод возвращает кортеж вида ‘(filename, headers)’, где filename — имя локального файла с копией ресурса и headers — None, если url ссылается на локальный файл, иначе — объект, возвращаемый методом info() объекта, реализующего чтение ресурса (см. выше).

Аргумент filename указывает имя локального файла, в который будет производиться копирование. По умолчанию имя файла генерируется с помощью функции tempfile.mktemp(). Задав аргумент reporthook Вы можете отслеживать процесс копирования. Функция (или другой объект, поддерживающий вызов) reporthook вызывается при установлении сетевого соединения и после загрузки каждого блока ресурса с тремя аргументами: число загруженных блоков, размер блока в байтах и размер файла (-1, если размер неизвестен). Аргумент data имеет такое же значение, как и для функции urlopen().

version

Этот атрибут класса является строкой с именем программы клиента, которое будет использовано при конструировании HTTP-запросов. По умолчанию используется строка ’Python-urllib/urllib_ver’, где urllib_ver — версия модуля urllib. Вы можете переопределить атрибут version в определении производного класса, чтобы изменить имя программы, посылаемое серверу.

Для совместимости с предыдущими версиями, если URL без идентификатора протокола (scheme identifier) не соответствует существующему локальному файлу, производится попытка использовать его для FTP протокола. Это может привести к сбивающим с толку сообщениям об ошибках.

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

Следующий пример использует метод GET для загрузки ресурса по протоколу HTTP:

>>> import urllib
>>> params = urllib.urlencode({'spam' : 1,
...                            'eggs' : 2,
...                            'bacon': 0})
>>> f = urllib.urlopen(
...     "http://www.musi-cal.com/cgi-bin/query?" +
...     params)
>>> print f.read()

И тот же самый ресурс, используя метод POST:

>>> import urllib
>>> params = urllib.urlencode({'spam' : 1,
...                            'eggs' : 2,
...                            'bacon': 0})
>>> f = urllib.urlopen(
...     "http://www.musi-cal.com/cgi-bin/query?",
...     params)
>>> print f.read()

27.3. urlparse — операции над URL

Этот модуль определяет средства для разбиения URL (Uniform Resource Locator, единообразный указатель ресурса, RFC 1738) на компоненты, конструирования URL из компонент и преобразования относительных URL в абсолютные (RFC 1808).

urlparse(urlstring [, default_scheme [, allow_fragments]])

Разбивает URL на компоненты и возвращает кортеж из шести строк: идентификатор протокола (scheme identifier), положение в сети, путь, параметры, строка запроса и идентификатор фрагмента. То есть применение функции к строке общего вида

’scheme://netloc/path;parameters?query#fragment’

дает ‘(scheme, netloc, path, parameters, query, fragment)’. Если URL не содержит какого-либо компонента, соответствующий элемент возвращаемого кортежа будет равен пустой строке. Разделители компонент не включаются в результат, за исключением косой черты в начале пути:

>>> import urlparse
>>> urlparse.urlparse(
...     'http://www.cwi.nl:80/%7Eguido/Python.html')
('http', 'www.cwi.nl:80', '/%7Eguido/Python.html', '',
'', '')

Если задан аргумент default_scheme, он будет использован в качестве идентификатора протокола (scheme identifier) по умолчанию — в том случае, если указанный URL не содержит идентификатора протокола.

Если задан и равен нулю аргумент allow_fragments, использование идентификатора фрагмента в URL (последний компонент) считается недопустимым.

urlunparse(tuple)

Восстанавливает и возвращает URL из компонент, переданных в кортеже tuple. При последовательном применении функций urlparse() и urlunparse() Вы можете получить другой (например, если исходный URL содержит излишние разделители), но эквивалентный URL.

urljoin(base, rel_url [, allow_fragments])

Конструирует и возвращает полный URL, комбинируя базовый URL base и относительный URL rel_url. Например:

>>> urljoin(
...     'http://www.cwi.nl/%7Eguido/Python.html',
...     'FAQ.html')
'http://www.cwi.nl/%7Eguido/FAQ.html'

Если задан и равен нулю аргумент allow_fragments, использование идентификатора фрагмента в URL (последний компонент) считается недопустимым.

28. Поддержка форматов, используемых в Internet

В этой главе описаны модули, обеспечивающих поддержку форматов, обычно используемых для передачи данных через Internet. Модули, предназначенные для обработки структурной разметки, описаны отдельно — в главе 29.

28.1. rfc822 — обработка заголовков электронных писем

Модуль rfc822 определяет класс Message, представляющий набор заголовков электронного письма (см. описание стандарта RFC 822). Он может быть использован в различных ситуациях, обычно для чтения таких заголовков из файла. Этот модуль также определяет класс AddressList, предназначенный для обработки адресов в соответствии с RFC 822, и несколько вспомогательных функций.

Message(file [, seekable])

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

Наличие методов seek() и tell() у объекта file позволяет использовать метод rewindbody() экземпляров класса Message. Кроме того, при наличии этих методов или метода unread() некорректные строки будут возвращены в поток. Таким образом, этот класс может быть использован для чтения буферизованных потоков.

Если аргумент seekable опущен или равен 1, наличие методов seek() и tell() определяется путем вызова tell(). Однако такой механизм не всегда хорошо работает. Поэтому, для обеспечения максимальной переносимости следует установить seekable равным нулю, если объект file не поддерживает установку указателя (например, если он представляет сетевое соединение).

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

AddressList(field)

При инициализации экземпляров этого класса используется единственный аргумент — строка, в которой, в соответствии с RFC 822, через запятую перечислены адреса. При использовании в качестве аргумента field значения None, созданный экземпляр будет представлять пустой список.

parsedate(date)

Пытается проанализировать строку с датой в соответствии с правилами, приведенными в RFC 822 (например, ’Mon, 20 Nov 1995 19:12:08 -0500’). В некоторых случаях эта функция срабатывает и для строк, в которых дата записана не в соответствии со стандартом. В случае удачного анализа возвращает кортеж из девяти элементов, пригодный для использования в качестве аргумента функции time.mktime() (назначение элементов кортежа смотрите в описании модуля time), иначе возвращает None. Заметим, что 6, 7 и 8 элементы возвращаемого кортежа не имеют полезных значений.

parsedate_tz(date)

Работает аналогично функции parsedate(), но возвращает либо None, либо кортеж из десяти элементов. Первые девять элементов такие же, десятый — сдвиг часового пояса в секундах относительно универсального времени. Заметим, что знак этого сдвига противоположен знаку time.timezone для того же часового пояса (time.timezone следует стандарту POSIX, в то время как данная функция — RFC 822). Если строка date не содержит информации о часовом поясе, последний элемент кортежа будет равен None. Заметим, что 6, 7 и 8 элементы возвращаемого кортежа не имеют полезных значений.

mktime_tz(tuple)

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

formatdate([tuple])

Возвращает строку с временем tuple (кортеж из девяти элементов — значение элементов смотри в описании модуля time), представленным в соответствии с RFC 822 и RFC 1123.

Экземпляры класса Message являются отображениями имен заголовков к их значениям (с доступом только на чтение) и поддерживают большинство характерных для отображений методов (has_key(), keys(), values(), items(), get()). Сопоставление имен заголовков производится независимо от используемого регистра букв, то есть выражения m[’From’], m[’from’] и m[’FROM’] полностью эквивалентны. Значением заголовка считается текст после двоеточия в первой строке заголовка плюс текст из строк продолжения с убранными символами пропуска в начале и конце. Кроме того, эти объекты имеют следующие методы и атрибуты данных:

rewindbody()

Перемещает указатель на начало сообщения. Этот метода работает только в том случае, если используемый файловый объект имеет методы tell() и seek().

isheader(line)

Возвращает канонизированное имя заголовка, если line является соответствующим RFC 822 заголовком, иначе возвращает None (предполагая, что анализ должен быть остановлен в этом месте и строка должна быть помещена обратно в поток). Вы можете переопределить этот метод в производном классе для обеспечения поддержки расширенных форматов заголовков.

islast(line)

Возвращает истину, если строка line является разделителем, на котором обработка заголовков должна быть остановлена, иначе возвращает ложь. При чтении разделительная строка поглощается, и указатель помещается непосредственно после нее. Вы можете переопределить этот метод в производном классе. Исходная реализация проверяет, является ли данная строка пустой.

iscomment(line)

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

getallmatchingheaders(name)

Возвращает список строк, составляющих все заголовки с именем name. Каждая строка, в том числе являющаяся продолжением заголовка, является отдельным элементом этого списка. Если нет заголовков с указанным именем, возвращает пустой список.

getfirstmatchingheader(name)

Возвращает список строк, составляющих первый заголовок с именем name. Если нет заголовков с указанным именем, возвращает None.

getrawheader(name)

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

getheader(name [, default])

Псевдоним стандартного метода get() отображений.

getaddr(name)

Возвращает кортеж из двух строк (возможно пустых) с полным именем и адресом электронной почты, взятых из первого заголовка с именем name. Если нет заголовков с указанным именем, возвращает ‘(None, None)’. Например, если первый заголовок, сохраненный объектом m, содержит строку ’jack@cwi.nl (Jack Jansen)’ (или ’Jack Jansen <jack@cwi.nl>’), m.getaddr('From') даст пару ‘('Jack Jansen', 'jack@cwi.nl')’.

getaddrlist(name)

Работает аналогично методу getaddr(), но обрабатывает заголовок (или заголовки) с именем name как содержащий список адресов (например, заголовок ‘To’ или серия заголовков ‘Cc’) и возвращает список кортежей с полным именем и адресом электронной почты. Если нет заголовков с указанным именем, возвращает пустой список.

getdate(name)

Анализирует первый заголовок с именем name на предмет содержания даты и времени и возвращает кортеж из девяти элементов (см. описание функции parsedate()) или None, если нет заголовков с указанным именем или первый такой заголовок не содержит даты (не может быть обработан функцией parsedate()).

getdate_tz(name)

Работает аналогично методу getdate(), но возвращает кортеж из десяти элементов; последний элемент равен сдвигу в секундах часового пояса относительно универсального времени (см. описание функции parsedate_tz()) или None.

headers

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

fp

Файловый (или подобный) объект, который был использован при инициализации. Может быть использован для чтения содержимого сообщения.

Экземпляры класса AddressList (обозначенные ниже как a и b) по поведению схожи с множествами (см. раздел 9.7.3) и поддерживают следующие операции:

len(a)

Количество адресов в списке.

str(a)

Канонизированное строковое представление списка (через запятую) адресов. Каждый адрес представляется в виде ‘"name" <e_mail>’.

a + b

Дает экземпляр класса AddressList с адресами из обоих списков, но без дубликатов (объединение множеств).

a - b

Дает экземпляр класса AddressList с адресами, которые содержаться в списке a, но не содержаться в списке b (разница множеств).

Кроме того, экземпляры класса AddressList имеют один публичный атрибут:

addresslist

Список кортежей (по одному на каждый адрес) из двух строк: канонизированного имени и электронного адреса.

28.2. mimetools — обработка сообщений в формате MIME

Этот модуль определяет класс Message, производный от rfc822.Message, а также набор функций, полезных при обработке сообщений в формате MIME (Multipurpose Internet Mail Extensions, многоцелевые расширения электронной почты).

Message(fp [, seekable])

Этот класс является производным от класса rfc822.Message и определяет несколько дополнительный методов, описанных ниже. Аргументы имеют такое же значение, как и для класса rfc822.Message (см. описание модуля rfc822).

choose_boundary()

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

decode(input, output, encoding)

Считывает данные в MIME-кодировке encoding из потока input и записывает раскодированные данные в поток output. Аргумент encoding может иметь одно из следующих значений: 'base64', 'quoted-printable', 'uuencode' (для большей совместимости воспринимаются также 'x-uuencode', 'uue' и 'x-uue'), '7bit' или '8bit'.

encode(input, output, encoding)

Считывает данные из потока input, преобразует в MIME-кодировку encoding и записывает в поток output. Поддерживаемые значения аргумента encoding такие же, как и для функции decode().

copyliteral(input, output)

Считывает строки текста из потока input (до конца файла) и записывает их в поток output.

copybinary(input, output)

Считывает блоки двоичных данных из потока input (до конца файла) и записывает их в поток output. В текущих реализациях размер блоков фиксирован и равен 8192 байт.

Экземпляры класса Message помимо унаследованных от rfc822.Message имеют следующие методы:

getplist()

Возвращает список параметров (строк) из заголовка ‘content-type’. Для параметров вида ‘name=value’ имя name преобразуется к нижнему регистру. Например, если сообщение содержит заголовок ‘Content-type: text/html; spam=1; Spam=2; Spam’, метод getplist() вернет список ['spam=1', 'spam=2', 'Spam'].

getparam(name)

Возвращает значение (value) первого параметра вида ‘name=value’ с указанным именем (сопоставление производится без учета регистра букв) из заголовка ‘content-type’. Если значение помещено в двойные кавычки ‘"value"’ или угловые скобки ‘<value>’, то они удаляются.

getencoding()

Возвращает строку с кодировкой сообщения, указанного в заголовке ‘contenttransfer-encoding’. Если сообщение не содержит такого заголовка, возвращает ’7bit’. Буквы в возвращаемой строке приводятся к нижнему регистру.

gettype()

Возвращает тип содержимого сообщения в виде строки ‘основной_тип/подтип’, указанный в заголовке content-type. Если сообщение не содержит такого заголовка, возвращает ’text/plain’. Буквы в возвращаемой строке приведены к нижнему регистру.

getmaintype()

Возвращает строку с основным типом содержимого сообщения, указанного в заголовке content-type. Если сообщение не содержит такого заголовка, возвращает ’text’. Буквы в возвращаемой строке приведены к нижнему регистру.

getsubtype()

Возвращает строку с подтипом содержимого сообщения, указанного в заголовке content-type. Если сообщение не содержит такого заголовка, возвращает ’plain’. Буквы в возвращаемой строке приведены к нижнему регистру.

28.3. MimeWriter — средства для записи в формате MIME

Этот модуль определяет класс MimeWriter, реализующий запись сообщений, состоящих из нескольких частей, в MIME-формате:

MimeWriter(fp)

Экземпляры этого класса реализуют запись в MIME-формате в поток fp (файловый или подобный объект).

Экземпляры класса MimeWriter имеют следующие методы:

addheader(name, value [, prefix])

Добавляет к сообщению заголовок name со значением value. Необязательный аргумент prefix указывает место, в которое заголовок будет добавлен: 0 (используется по умолчанию) — добавить в коней, 1 — вставить в начало.

flushheaders()

При вызове этого метода все накопленные (с помощью метода addheader()) заголовки записываются в поток и забываются. Такая операция может быть полезна, если Вы не собираетесь записывать основную часть (тело) сообщения, например, для блоков типа ‘message/rfc822’, которые иногда используется для представления информации, аналогичной заголовкам.

startbody(ctype [, plist [, prefix]])

Возвращает объект, аналогичный файловому, который может быть использован для записи основной части (тела) сообщения. Аргумент ctype указывает значение, которое будет использоваться в заголовке ‘content-type’ (тип данных). Если задан аргумент plist, он должен быть списком пар вида ‘(name, value)’, которые будут использованы в качестве дополнительных параметров в заголовке ‘contenttype’. Назначение аргумента prefix такое же, как и для метода addheader(), но по умолчанию он равен 0 (добавить в начало).

startmultipartbody(subtype [, boundary [, plist [, prefix]]])

Возвращает объект, аналогичный файловому, который может быть использован для записи тела сообщения, состоящего из нескольких частей. Аргумент указывает подтип сообщения типа ‘multipart’, boundary может быть использован для указания дружественного разделителя частей (по умолчанию используется mimetools.choose_boundary()), список plist задает дополнительные параметры заголовка ‘content-type’. Аргумент prefix имеет такое же значение, как и для метода startbody(). Подчасти должны создаваться с помощью метода nextpart().

nextpart()

Возвращает новый экземпляр класса MimeWriter, представляющий часть в сообщении типа ‘multipart/*’. Этот объект может быть использован, в том числе, и для вложенных сообщений, состоящих из нескольких частей. Перед использованием метода nextpart() должен быть вызван метод startmultipartbody().

lastpart()

Это метод всегда должен быть использован после записи сообщений, состоящих из нескольких частей (типа ‘multipart/*’).

28.4. multifile — чтение сообщений, состоящих из нескольких частей

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

MultiFile(fp [, seekable])

Создает и возвращает объект, реализующий чтение частей текста. Аргумент fp должен быть файловым (или подобным) объектом, из которого будет производиться чтение исходного текста. На самом деле достаточно наличия у fp методов readline(), seek() и tell(). Последние два метода требуются для обеспечения произвольного доступа к частям текста. Если задан и является ложью аргумент seekable, методы seek() и tell() объекта fp использоваться не будут.

Error

Это исключение генерируется в случае возникновения характерных для модуля ошибок.

С точки зрения реализации класса MultiFile исходный текст состоит из трех видов строк: данных, разделителей частей и метки конца. Этот класс приспособлен к обработке сообщений, части которых состоят из несколько вложенных частей. В каждом таком случае должен быть свой шаблон для разделительных строк и метки конца.

Экземпляры класса MultiFile имеют следующие методы:

push(str)

Записывает в стек разделительную строку. Если эта строка, соответствующим образом выделенная, будет найдена во входном потоке, она будет интерпретирована как разделитель частей или метка конца. Все последующие попытки чтения из экземпляра класса MultiFile будут возвращать пустую строку до тех пор, пока разделительная строка не будет удалена из стека с помощью метода pop() или ее использование не будет повторно разрешено с помощью метода next().

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

readline()

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

readlines()

Возвращает список всех оставшихся строк для данной части.

read()

Считывает и возвращает все оставшиеся данные для текущей части.

next()

Считывает строки до конца текущей части и, если достигнута метка конца, возвращает 0, в противном случае переходит к следующей части (разрешает повторное использование разделителя на вершине стека) и возвращает 1.

pop()

Удаляет с вершины стека разделительную строку.

seek(pos [, whence])

Перемещает указатель по текущей части. Аргументы имеют такое же значение, как и для метода seek() файловых объектов (см. раздел 11.7).

tell()

Возвращает текущую позицию в текущей части.

is_data(str)

Возвращает 1, если строка str точно не является разделителем или меткой конца (то есть является строкой с данными), иначе (если строка может быть разделителем или меткой конца) возвращает 0. Вы можете переопределить этот метод в производном классе, исходная реализация проверяет наличие ‘--’ в начале строки (для формата MIME).

Этот метод предназначен для быстрой проверки: если он будет всегда возвращать 0, это лишь замедлит обработку, но не приведет к ошибкам.

section_divider(str)

Преобразует разделительную строку str (в том виде, в котором она записывается в стек) в строку, которая используется для разделения частей. Вы можете переопределить этот метод в производном классе, исходная реализация добавляет ‘--’ в начало (для формата MIME). Нет необходимости добавлять в конец символ перехода на новую строку, так как при сравнении символы пропуска в конце строки игнорируются.

end_marker(str)

Преобразует разделительную строку str (в том виде, в котором она записывается в стек) в строку, которая используется в качестве метки конца. Вы можете переопределить этот метод в производном классе, исходная реализация добавляет ‘--’ в начало и конец (для формата MIME). Нет необходимости добавлять в конец символ перехода на новую строку, так как при сравнении символы пропуска в конце строки игнорируются.

Кроме того, экземпляры класса MultiFile имеют два публичных атрибута данных:

level

Уровень вложенности текущей части.

last

Является истиной (1), если последний разделитель являлся меткой конца.

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

import mimetools
import multifile
import StringIO

def extract_mime_part_matching(stream, mimetype):

    msg = mimetools.Message(stream)
    msgtype = msg.gettype()
    params = msg.getplist()

    data = StringIO.StringIO()
    if msgtype.startswith('multipart/'):

        file = multifile.MultiFile(stream)
        file.push(msg.getparam('boundary'))
        while file.next():
            submsg = mimetools.Message(file)
            try:
                data = StringIO.StringIO()
                mimetools.decode(file, data,
                                 submsg.getencoding())
            except ValueError:
                continue
            if submsg.gettype() == mimetype:
                break
        file.pop()
    return data.getvalue()

28.5. xdrlib — представление данных в формате XDR

Модуль xdrlib предоставляет средства для работы с данными в формате XDR (eXternal Data Representation, аппаратно-независимое представление данных) в соответствии с RFC 1014 [Формат XDR разработан фирмой Sun Microsystems в 1987 году, новая версия формата описана в RFC 1832.] и поддерживает большинство типов данных, описанных в стандарте. Другие (менее переносимые) способы получения представления объектов описаны в главе 20. Модуль определяет два класса: для упаковки данных в XDR-представление и для их распаковки.

Packer()

Экземпляры этого класса реализуют упаковку объектов в XDR-представление.

Unpacker(data)

Экземпляры этого класса позволяют получить объекты из их XDR-представления, заданного в строке (или другом объекте, имеющем интерфейс буфера) data.

Экземпляры класса Packer имеют следующие методы:

get_buffer()

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

reset()

Очищает буфер.

pack_uint(value)

pack_int(value)

pack_enum(value)

pack_bool(value)

pack_uhyper(value)

pack_hyper(value)

pack_float(value)

pack_double(value)

Записывают в буфер XDR-представление данных value соответствующих простых типов.

pack_fstring(n, s)

pack_fopaque(n, s)

Записывают в буфер XDR-представление строки s фиксированной длины n. Заметим, что длина строки не сохраняется в представлении. Если необходимо, строка дополняется нулевыми байтами для обеспечения выравнивания к 4 байтам.

pack_string(s)

pack_opaque(s)

pack_bytes(s)

Записывают в буфер XDR-представление строки s переменной длины (сначала упаковывается длина строки в виде беззнакового целого, затем сама строка).

pack_list(list, pack_item)

Записывают в буфер XDR-представление гомогенной последовательности list, длина которой заранее неизвестна. Для каждого элемента последовательности сначала упаковывается 1 (как беззнаковое целое), затем значение элемента, с помощью метода (функции) pack_item. По достижении конца списка упаковывается 0 (как беззнаковое целое).

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

import xdrlib
p = xdrlib.Packer()
p.pack_list([1, 2, 3], p.pack_int)

pack_farray(n, array, pack_item)

Записывают в буфер XDR-представление гомогенной последовательности array фиксированной длины n. Длина последовательности не сохраняется, но, если указанная длина последовательности не равна len(array), генерируется исключение ValueError. Для упаковки каждого элемента используется метод (функция) pack_item.

pack_array(array, pack_item)

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

Экземпляры класса Unpacker предоставляют методы для выполнения обратного преобразования:

reset(data)

Устанавливает буфер с упакованными данными равным строке data.

get_position()

Возвращает текущую позицию в буфере.

set_position(pos)

Устанавливает указатель на позицию pos в буфере. Будьте осторожны, используя этот метод.

get_buffer()

Возвращает текущее значение буфера с упакованными данными в виде строки.

done()

Указывает на завершение распаковки данных. Генерирует исключение, если не все данные были распакованы.

unpack_uint()

unpack_int()

unpack_enum()

unpack_bool()

unpack_uhyper()

unpack_hyper()

unpack_float()

unpack_double()

Интерпретирует данные в буфере как XDR-представление значения соответствующего простого типа и возвращает распакованное значение.

unpack_fstring(n)

unpack_fopaque(n)

Интерпретирует данные в буфере как XDR-представление строки фиксированной длины n. Ожидается, что представление строки дополнено нулевыми байтами для обеспечения выравнивания к 4 байтам. Возвращает распакованное значение в виде строки.

unpack_string()

unpack_opaque()

unpack_bytes()

Интерпретирует данные в буфере как XDR-представление строки переменной длины. Ожидается, что длина строки упакована в виде целого беззнакового числа. Возвращает распакованное значение в виде строки.

unpack_list(unpack_item)

Интерпретирует данные в буфере как XDR-представление последовательности неизвестной длины. Ожидается, что перед каждым элементом последовательности упакована 1 в виде целого беззнакового, а в конце последовательности упакован 0. Для распаковки элементов последовательности использует метод (функцию) unpack_item, распакованную последовательность возвращает в виде списка.

unpack_farray(n, unpack_item)

Интерпретирует данные в буфере как XDR-представление последовательности фиксированной длины n. Для распаковки элементов последовательности использует метод (функцию) unpack_item, распакованную последовательность возвращает в виде списка.

unpack_array(unpack_item)

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

Модуль также определяет иерархию исключений:

Error

Базовый класс для всех исключений модуля. Его экземпляры имеют один публичный атрибут данных msg, содержащий пояснение к ошибке.

ConversionError

Исключения этого класса генерируются методами unpack_*() экземпляров класса Unpacker, если данные в буфере с XDR-представлением не соответствуют ожидаемому формату, и методами pack_*() класса Packer, если указанное значение не может быть упаковано данным методом.

29. Средства работы с языками структурной разметки

Модули, описанные в этой главе, предоставляют средства для работы с различными языками структурной разметки: SGML (Standard Generalized Markup Language, стандартный язык обобщенной разметки), HTML (Hypertext Markup Language, язык разметки гипертекста) и XML (Extensible Markup Language, расширяемый язык разметки).

29.1. sgmllib — обработка SGML-документов

Этот модуль определяет класс SGMLParser, реализующий обработку текста в формате SGML (Standard Generalized Markup Language, стандартный язык обобщенной разметки). На самом деле он воспринимает только ту часть синтаксиса SGML, которая используется в HTML (модуль sgmllib служит базой для модуля htmllib).

SGMLParser()

Возвращает объект, реализующий обработку текста в формате SGML. Воспринимаются следующие конструкции:

• Открывающие и закрывающие теги в виде ‘<тег атрибут="зачение"...>’ и ‘</тег>’ соответственно.
• Ссылки на символы в виде ‘&#код;’.
• Ссылки на сущности (entity) в виде ‘&имя;’.
• Комментарии в виде ‘<!--текст->’.

Экземпляры класса SGMLParser имеют следующие интерфейсные методы (переопределяя эти методы в производных классах, Вы контролируете обработку размеченного текста, то есть, определяете тип документа — DTD):

reset()

Возвращает экземпляр в исходное состояние. Все необработанные данные теряются. Этот метод неявно вызывается при инициализации.

setnomoretags()

Останавливает обработку тегов. Весь последующий текст воспринимается без обработки (CDATA). Этот метод необходим для реализации обработки тега ‘<PLAINTEXT>’ в HTML.

setliteral()

Временно приостанавливает обработку тегов. Последующий текст воспринимается без обработки (CDATA).

feed(data)

Передает экземпляру размеченный текст data для обработки. Обрабатываются только завершенные данные, остальное остается в буфере до тех пор, пока не будет передана следующая порция данных или не будет вызван метод close().

close()

Завершает обработку всех данных в буфере. Вы можете переопределить этот метод в производном классе, добавив дополнительные действия. Переопределенный метод всегда должен вызывать исходную версию метода.

get_starttag_text()

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

handle_starttag(tag, method, attributes)

Вызывается для обработки открывающих тегов, для которых определен метод start_tag() или do_tag(). Аргумент tag является строкой с именем тега, приведенном к нижнему регистру, method — метод, который должен быть вызван для интерпретации открывающего тега. Атрибут attributes является списком пар ‘(name, value)’ для всех атрибутов, найденных внутри угловых скобок тега, где name — имя атрибута, приведенное к нижнему регистру, и value — его значение. Исходная реализация этого метода вызывает method(attributes).

handle_endtag(tag, method)

Вызывается для обработки закрывающих тегов, для которых определен метод end_tag(). Аргумент tag является строкой с именем тега, приведенном к нижнему регистру, method —метод, который должен быть вызван для интерпретации закрывающего тега. Исходная реализация этого метода просто вызывает method().

handle_data(data)

Вызывается для обработки простого текста. Вам следует переопределить его в производном классе: исходная реализация ничего не делает.

handle_charref(ref)

Вызывается для обработки ссылок на символы в виде ‘&#ref;’. Исходная реализация преобразует число в диапазоне от 0 до 255 в символ с помощью встроенной функции chr() и вызывает с ним метод handle_data(). Если аргумент ref неверен или выходит за пределы указанного диапазона, вызывает unknown_charref(ref) для обработки ошибки.

handle_entityref(ref)

Вызывается для обработки ссылок на сущности в виде ‘&ref;’. Исходная реализация использует атрибут экземпляра (или класса) entitydefs, являющийся отображением имен сущностей к строкам. Если это отображение содержит запись с ключом ref, вызывает метод handle_data() с результатом в качестве аргумента, в противном случае вызывает unknown_entityref(ref). По умолчанию атрибут entitydefs содержит записи с ключами ’amp’, ’apos’, ’gt’, ’lt’ и ’quot’.

handle_comment(comment)

Вызывается для обработки комментария. В качестве аргумента comment используется строка с текстом, содержащимся между ‘<!--’ и ‘-->’. Исходная реализация ничего не делает.

report_unbalanced(tag)

Этот метод вызывается, если в размеченном тексте найден закрывающий тег tag, для которого не было открывающего тега.

unknown_starttag(tag)

Вызывается для обработки неизвестного открывающего тега (если нет соответствующего метода start_tag() или do_tag()). Вам следует переопределить этот метод в производном классе: исходная реализация ничего не делает.

unknown_endtag(tag)

Вызывается для обработки неизвестного закрывающего тега (если нет соответствующего метода end_tag()). Вам следует переопределить этот метод в производном классе: исходная реализация ничего не делает.

unknown_charref(ref)

Вызывается для обработки неверной ссылки на символ в виде ‘&#ref;’ (см. описание метода handle_charref()). Вам следует переопределить этот метод в производном классе: исходная реализация ничего не делает.

unknown_entityref(ref)

Вызывается для обработки ссылки на сущность с неизвестным именем в виде ‘&ref;’ (см. описание метода handle_entityref()). Вам следует переопределить этот метод в производном классе: исходная реализация ничего не делает.

Помимо переопределения некоторых из перечисленных выше методов, в производных классах Вам следует определить методы для обработки тегов. Имена тегов в размеченном тексте могут содержать буквы в любом регистре: перед вызовом метода имя будет приведено к нижнему регистру (то есть tag в именах методов, описанных ниже, является именем тега, приведенного к нижнему регистру). В качестве атрибута attributes используется список пар ‘(name, value)’ для всех атрибутов, найденных внутри угловых скобок тега, где name — имя атрибута, приведенное к нижнему регистру, и value — его значение.

start_tag(attributes)

Вызывается для обработки открывающего тега tag. Этот метод имеет преимущество над методом do_tag().

do_tag(attributes)

Вызывается для обработки открывающего тега tag, для которого не должно быть соответствующего закрывающего тега.

end_tag()

Вызывается для обработки закрывающего тега tag.

Обработчик хранит стек открытых элементов, для которых еще не было закрывающих тегов. В этот стек помещаются только теги, для которых есть соответствующий метод start_tag(). Определение метода end_tag() не является обязательным. Для тегов, обрабатываемых методами do_tag() и unknown_tag() нет смысла определять соответствующие методы end_tag() — они не будут использованы.

29.2. htmllib — обработка HTML-документов

Этот модуль определяет класс HTMLParser (производный от sgmllib.SGMLParser), который может быть использован в качестве базового для класса, реализующего обработку текста в формате HTML (Hypertext Markup Language, язык разметки гипертекста). В настоящий момент этот класс поддерживает HTML 2.0 [http://www.w3.org/hypertext/WWW/MarkUp/html-spec/html-spec_toc.html]. Для получения вывода экземпляры HTMLParser и производных от него классов вызывают методы указанного объекта, реализующего форматирование текста. Стандартный модуль formatter предоставляет два варианта таких объектов (смотрите описание модуля для получения информации об интерфейсе объектов, реализующих форматирование).

HTMLParser(formatter)

Создает и возвращает объект, реализующий обработку текста в формате HTML. Этот класс поддерживает все имена сущностей, требуемых спецификацией HTML 2.0 (определены в модуле htmlentitydefs), и определяет обработчики для всех элементов HTML 2.0 и многих элементов HTML 3.0 и 3.2.

В дополнение к методам, реализующий обработку тегов (как того требует интерфейс класса sgmllib.SGMLParser), класс HTMLParser предоставляет следующие дополнительные методы и атрибуты данных:

formatter

Объект, реализующий форматирование текста, который был передан в качестве аргумента при инициализации.

nofill

Если этот флаг является ложью, идущие друг за другом символы пропуска будут свернуты в один пробел методом handle_data() или save_end(), в противном случае будут оставлены без изменений. Обычно он должен быть истинным только внутри элемента <pre>.

anchor_bgn(href, name, type)

Вызывается в начале региона, помеченного якорем. В качестве аргументов используются значения одноименных атрибутов тега <a> (если тег не содержит какоголибо атрибута, в качестве аргумента для него используется пустая строка). Исходная реализация сохраняет все ссылки, содержащиеся в документе, в списке, доступном через атрибут anchorlist.

anchor_end()

Вызывается в конце региона, помеченного якорем. Исходная реализация добавляет текстовую ссылку в виде ‘[index]’, где index — индекс соответствующего элемента в списке ссылок (атрибут anchorlist).

handle_image(src, alt [, ismap [, align [, width [, height]]]])

Вызывается для обработки вставок изображений. В качестве аргументов используются значения одноименных атрибутов тега <img> (аргументы width и height являются целыми числами). Исходная реализация вызывает handle_data(alt).

save_bgn()

Устанавливает режим, в котором все символьные данные сохраняются во внутреннем буфере вместо того, чтобы быть переданными объекту, реализующему форматирование (аргумент formatter конструктора). Вы можете извлечь сохраненные данные с помощью метода save_end().

save_end()

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

29.3. htmlentitydefs — определения сущностей HTML

Этот модуль определяет один словарь, который используется модулем htmllib в качестве значения атрибута entitydefs класса htmllib.HTMLParser. Этот словарь содержит записи для всех сущностей (entity) HTML 2.0, отображая их имена в символы в кодировке Latin-1 (ISO-8859-1). Сущности, которые не могут быть представлены литерально в рамках Latin-1, отображаются в запись вида ‘&#ref;’, где ref — код символа в Unicode.

entitydefs

Словарь, отображающий имена сущностей HTML 2.0 в символ кодировки Latin-1 или ссылку на символ Unicode в виде ‘&#ref;’.

29.4. xml.parsers.expat — быстрая обработка XML-документов с помощью библиотеки Expat

Модуль xml.parsers.expat доступен, начиная с версии 2.0 и предоставляет интерфейс библиотеке Expat, реализующей быструю обработку XML-документов без проверки на соответствие DTD [Модуль xml.parsers.expat является надстройкой над модулем pyexpat. Использовать модуль pyexpat напрямую не рекомендуется.]. Модуль определяет следующие две функции, исключение и подмодуль:

ErrorString(err_code)

Возвращает строку с пояснением к ошибке с кодом err_code.

ParserCreate([encoding [, namespace_separator]])

Создает и возвращает объект, реализующий обработку текста в формате XML. Если задан и не равен None, он должен быть строкой, указывающей кодировку: ’UTF-8’, ’UTF-16’ или ’ISO-8859-1’ (по умолчанию обработчик автоматически выбирает между UTF-8 и UTF-16).

Если задан и не равен None аргумент namespace_separator (должен быть строкой из одного символа), включается обработка пространств имен. В этом случае имена элементов и атрибутов, определенных в каком-либо пространстве имен, будут передаваться функциям StartElementHandler() и EndElementHandler() в виде ‘namespace_URI + namespace_separator + name’, где namespace_URI — URI пространства имен и name — имя элемента или атрибута. Если аргумент namespace_separator равен ’\000’, в качестве разделителя используется пустая строка.

Например, пусть в качестве аргумента namespace_separator используется ' ' и обрабатывается следующий документ:

<?xml version="1.0"?>
<root xmlns = "http://default-namespace.org/"
xmlns:py = "http://www.python.org/ns/">
<py:elem1 />
<elem2 xmlns="" />
</root>

В этом случае функция StartElementHandler() получит следующие строки в качестве аргументов:

http://default-namespace.org/ root
http://www.python.org/ns/ elem1
elem2

error

Исключения этого класса генерируются, если XML-документ содержит ошибки.

errors

Подмодуль, в котором определены константы вида XML_ERROR_* для возможных ошибок обработки. Вы можете использовать их для сравнения со значением атрибута ErrorCode объектов, возвращаемых функцией-конструктором ParserCreate().

XMLParserType

Тип объектов, возвращаемых функцией ParserCreate().

Объекты, возвращаемые функцией-конструктором ParserCreate(), имеют следующие методы:

Parse(data [, isfinal])

Обрабатывает содержимое строки data, вызывая соответствующие функции. При последнем вызове аргумент isfinal должен являться истиной.

ParseFile(file)

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

SetBase(base)

Устанавливает базовый адрес, который должен быть использован для относительных URI в системных объявлениях: он будет передан в качестве аргумента base функциям ExternalEntityRefHandler, NotationDeclHandler и UnparsedEntityDeclHandler.

GetBase()

Возвращает строку с базовым адресом, установленным ранее с помощью метода SetBase(), или None, если метод SetBase() не был использован.

Объекты, возвращаемые функцией-конструктором ParserCreate(), имеют следующие атрибуты:

returns_unicode

Если этот атрибут равен 1 (по умолчанию), функциям-обработчикам, описанным ниже, будут передаваться строки Unicode, если же он равен 0 — обычные строки, содержащие данные в кодировке UTF-8. Вы можете изменять значение этого атрибута в любое время, задавая таким образом тип результата.

Значения следующих атрибутов относятся к последней ошибке. Эти атрибуты имеют корректные значения только после того, как метод Parse() или ParseFile() сгенерировал исключение error.

ErrorByteIndex

Индекс (в байтах), указывающий на место, в котором возникла ошибка.

ErrorCode

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

ErrorColumnNumber

Позиция в строке, в которой возникла ошибка.

ErrorLineNumber

Номер строки, в которой возникла ошибка.

Ниже приведен список обработчиков, которые Вы можете установить для объекта obj с помощью инструкций вида ‘obj.handler = func’, где handler должен быть одним из перечисленных атрибутов и func — объектом, поддерживающим вызов с указанным количеством аргументов. Все аргументы, если не указано иного, являются строками.

StartElementHandler(name, attributes)

Вызывается для обработки открывающего тега каждого элемента. Аргумент name содержит имя элемента и attributes — словарь, отображающий имена атрибутов к их значениям.

EndElementHandler(name)

Вызывается для обработки закрывающего тега каждого элемента. Аргумент name содержит имя элемента.

ProcessingInstructionHandler(name, data)

Вызывается для каждой инструкции обработки (PI, Processing Instruction) в виде ‘<?name data?>’ (но не для ‘<?xml data?>’).

CharacterDataHandler(data)

Вызывается для обработки простого текста.

UnparsedEntityDeclHandler(entityName, base, systemId, publicId, notationName)

Вызывается для необрабатываемых объявлений сущностей (NDATA).

NotationDeclHandler(notationName, base, systemId, publicId)

Вызывается для обработки объявлений примечаний (‘<!NOTATION ...>’).

StartNamespaceDeclHandler(prefix, uri)

Вызывается, если элемент (открывающий тег) содержит объявление пространства имен.

EndNamespaceDeclHandler(prefix)

Вызывается для закрывающего тега элемента, содержащего объявление пространства имен.

CommentHandler(data)

Вызывается для комментариев.

StartCdataSectionHandler()

Вызывается в начале секции CDATA.

EndCdataSectionHandler()

Вызывается в конце секции CDATA.

DefaultHandler(data)

Вызывается для частей XML-документа, для которых не определен соответствующий обработчик. Части документа передаются в качестве аргумента data в исходном виде.

DefaultHandlerExpand(data)

Вызывается для частей XML-документа, для которых не определен соответствующий обработчик. Части документа передаются в качестве аргумента data после замены ссылок на сущности.

NotStandaloneHandler()

Вызывается, если XML-документ был объявлен как несамостоятельный (‘standalone="no"’ в заголовке).

ExternalEntityRefHandler(context, base, systemId, publicId)

Вызывается для обработки ссылок на внешние сущности.

Приведем простейший пример использования модуля:

from xml.parsers import expat

def start_element(name, attrs):
    print 'Начало элемента:', name, attrs
def end_element(name):
    print 'Конец элемента:', name
def char_data(data):
    print 'Символьные данные:', repr(data)
p = expat.ParserCreate()

p.returns_unicode = 0
p.StartElementHandler = start_element
p.EndElementHandler = end_element
p.CharacterDataHandler = char_data

p.Parse("""\
<?xml version="1.0"?>
<parent id="top">
  <child1 name="paul">Text goes here</child1>
  <child2 name="fred">More text</child2>
</parent>""")

Вывод этой программы будет следующим:

Начало элемента: parent {'id': 'top'}
Начало элемента: child1 {'name': 'paul'}
Символьные данные: 'Text goes here'
Конец элемента: child1
Символьные данные: '\012'
Начало элемента: child2 {'name': 'fred'}
Символьные данные: 'More text'
Конец элемента: child2
Символьные данные: '\012'
Конец элемента: parent

29.5. xml.sax — SAX2 интерфейс к синтаксическим анализаторам XML-документов

Этот модуль доступен, начиная с версии 2.0 и реализует SAX (Simple API for XML, простой программный интерфейс для XML) интерфейс.

Модуль xml.sax определяет следующие функции:

make_parser([parser_list])

Создает и возвращает объект с SAX интерфейсом (экземпляр xml.sax.xmlreader.XMLReader или производного от него класса), реализующий синтаксический анализ XML-документа. Для этого используется первый найденный анализатор. Поиск модулей синтаксических анализаторов производится в списке parser_list (список имен модулей), если он задан, затем в списке модулей по умолчанию.

parse(filename_or_stream, handler [, error_handler])

Создает объект, реализующий синтаксический анализ XML-документа, и использует его для анализа файла filename_or_stream. Аргумент filename_or_stream должен быть файловым (или подобным) объектом или строкой с именем файла. Аргумент handler должен быть экземпляром класса ContentHandler, реализующим обработку событий для содержимого документа. С помощью аргумента error_handler (должен быть экземпляром класса ErrorHandler) Вы можете задать способ обработки ошибок, по умолчанию для всех ошибок будет генерироваться исключение SAXParseException.

parseString(string, handler [, error_handler])

Работает аналогично функции parse(), но обрабатывает XML-документ, содержащийся в строке string.

Типичное SAX-приложение состоит из объекта, реализующего чтение и синтаксический анализ документа, преобразуя его в поток SAX-событий, объектов-обработчиков событий и объекта, представляющего сам XML-документ. Для всех этих объектов существенными являются только интерфейсы, формально представленные различными классами. Классы InputSource, Locator, + AttributesImpl и XMLReader определены в модуле xml.sax.xmlreader, интерфейсные классы обработчиков событий — в модуле xml.sax.handler. Для удобства модуль xml.sax импортирует в свое глобальное пространство имен классы InputSource, ContentHandler и ErrorHandler.

Модуль также определяет иерархию исключений:

SAXException

Этот класс является базовым для всех исключений модуля. Экземпляры SAXException и производных от него классов заключают в себе сообщение об ошибке и, часто, реальное исключение, сгенерированное выбранным синтаксическим анализатором. Эта информация доступна через методы исключения getMessage() и getException() соответственно (последний может возвращать None).

SAXParseException

Исключения этого класса генерируются при обнаружении синтаксических ошибок в анализируемом XML-документе. Экземпляры класса SAXParseException имеют дополнительные методы getColumnNumber(), getLineNumber(), getPublicId() и getSystemId(), которые возвращают, соответственно, позицию в строке и номер строки, в которой возникла ошибка, и публичный и системный идентификаторы сущностей или None.

SAXNotRecognizedException

Исключения этого класса генерируются, если синтаксический анализатор сталкивается с неизвестной особенностью или свойством.

SAXNotSupportedException

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

SAXReaderNotAvailable

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

29.6. xml.sax.handler — базовые классы для обработчиков SAX-событий

Этот модуль (доступен, начиная с версии 2.0) определяет базовые классы с интерфейса SAX (см. описание модуля xml.sax) для обработки содержимого XML-документа, его DTD (Document Type Definition, определение типа документа), ошибок и ссылок на сущности. В производных классах необходимо переопределить только методы для интересующих Вас событий.

ContentHandler()

Этот класс определяет интерфейс обработчиков SAX-событий для содержимого XML-документа и является наиболее важным в SAX.

DTDHandler()

Определяет интерфейс обработчика событий для DTD (объявлений необрабатываемых сущностей и примечаний).

ErrorHandler()

Определяет интерфейс обработчика ошибок.

EntityResolver()

Определяет интерфейс обработчика ссылок на внешние сущности.

Помимо интерфейсных классов модуль xml.sax.handler определяет символические константы для имен функциональных особенностей (feature_*) и свойств (property_*). Эти константы могут быть использованы в качестве аргументов методов getFeature(), setFeature(), getProperty() и setProperty() экземпляров xml.sax.xmlreader.XMLReader или производных от него классов. Заметим, что включение/выключение используемых особенностей возможно только до начала синтаксического анализа XML-документа.

feature_namespaces

Выполнять обработку пространств имен (является истиной по умолчанию).

feature_namespace_prefixes

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

feature_string_interning

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

feature_validation

Сообщать о несоответствии документа DTD.

feature_external_ges

Подключать внешние объявления текстовых сущностей.

feature_external_pes

Подключать внешние объявления сущностей параметров, включая внешнее подмножество DTD.

all_features

Список, содержащий все известные особенности.

property_lexical_handler

Необязательный обработчик лексических событий (например, комментариев). В версии 2.0 не поддерживается.

property_declaration_handler

Необязательный обработчик событий, связанных с DTD (кроме необрабатываемых сущностей и примечаний). В версии 2.0 не поддерживается.

property_dom_node

До начала синтаксического анализа — корневой, во время анализа — текущий узел объектной модели документа (DOM). Изменение этого свойства возможно только до начала анализа документа.

property_xml_string

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

all_properties

Список всех известных имен свойств.

29.6.1. Интерфейс класса ContentHandler

Интерфейс класса ContentHandler составляют следующие методы:

setDocumentLocator(locator)

Вызывается синтаксическим анализатором XML-документа перед началом анализа. Объект locator (должен быть экземпляром xml.sax.xmlreader.Locator) предоставляет возможность получить информацию о позиции в документе соответствующей текущему событию. Эта информация обычно используется для вывода сообщений об ошибке. Заметим, что методы объекта locator должны возвращать корректный результат только во время обработки события.

startDocument()

Вызывается один раз для извещения о начале документа.

endDocument()

Вызывается один раз для извещения о конце документа (при достижении конца ввода или возникновении ошибки, не допускающей восстановления).

startPrefixMapping(prefix, uri)

Вызывается в начале области действия пространства имен. Обработка этого события не является необходимой: синтаксический анализатор XML-документа автоматически заменяет приставку prefix на URI uri в именах элементов и атрибутов, если включена возможность feature_namespaces (эта возможность включена по умолчанию). Метод startPrefixMapping() всегда вызывается до соответствующего метода startElement(), однако правильный порядок следования нескольких событий startPrefixMapping() не гарантируется.

endPrefixMapping(prefix)

Вызывается в конце области действия пространства имен. Метод endPrefixMapping() всегда вызывается до соответствующего метода endElement(), однако правильный порядок следования нескольких событий endPrefixMapping() не гарантируется.

startElement(name, attrs)

Вызывается в начале элемента (без учета пространств имен). В качестве аргумента name используется строка с необработанным именем элемента, в качестве attrs — экземпляр класса xml.sax.xmlreader.AttributesImpl, описывающий атрибуты элемента.

endElement(name)

Вызывается в начале элемента (без учета пространств имен). В качестве аргумента name используется строка с необработанным именем элемента.

startElementNS(name, qname, attrs)

Вызывается в начале элемента (с учетом пространств имен). В качестве аргумента name используется кортеж, содержащий URI и имя элемента, в качестве qname — строка с необработанным именем элемента (может быть None, если отключена возможность feature_namespaces) и в качестве attrs — экземпляр класса xml.sax.xmlreader.AttributesNSImpl, описывающий атрибуты элемента.

endElementNS(name, qname)

Вызывается в конце элемента (с учетом пространств имен). В качестве аргумента name используется кортеж, содержащий URI и имя элемента, в качестве qname — строка с необработанным именем элемента (может быть None, если отключена возможность feature_namespaces).

characters(content)

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

ignorableWhitespace(whitespace)

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

processingInstruction(target, data)

Вызывается для инструкций обработки вида ‘<?target data?>’. Этот метод не должен вызываться для объявлений вида ‘<?xml ...>’.

skippedEntity(name)

Вызывается для всех сущностей, обработка которых синтаксическим анализатором не выполняется (например, если сущность объявлена во внешнем подмножестве DTD).

29.6.2. Интерфейс класса DTDHandler

Интерфейс класса DTDHandler составляют следующие методы:

notationDecl(name, publicId, systemId)

Вызывается для обработки объявлений примечаний (‘<!NOTATION ...>’).

unparsedEntityDecl(name, publicId, systemId, ndata)

Вызывается для обработки объявлений необрабатываемых сущностей (NDATA).

29.6.3. Интерфейс класса ErrorHandler

Интерфейс класса ErrorHandler составляют следующие методы:

error(exception)

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

fatalError(exception)

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

warning(exception)

Вызывается для предупреждений. Исходная реализация выводит на стандартный поток вывода (sys.stdout) строковое представление исключения exception.

29.6.4. Интерфейс класса EntityResolver

Интерфейс класса EntityResolver составляют следующие методы:

resolveEntity(publicId, systemId)

Вызывается для необрабатываемых сущностей. Должен возвращать либо строку с системным идентификатором, либо экземпляр класса xml.sax.xmlreader.InputSource, который будет использован для считывания данных. Исходная реализация возвращает systemId.

29.7. xml.sax.saxutils — вспомогательные средства для приложений, использующих SAX

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

escape(data [, entities])

Заменяет символы ‘&’, ‘<’ и ‘>’ в строке data соответствующими ссылками на сущности и возвращает полученную строку. Вы можете произвести дополнительные замены, передав в качестве аргумента entities словарь, ключи которого будут заменены соответствующими им значениями.

XMLGenerator([out [, encoding]])

Этот класс является производным от ContentHandler, его методы реализуют запись SAX-событий назад в XML-документ. Другими словами, при использовании экземпляра класса XMLGenerator в качестве объекта, реализующего обработку содержимого XML-документа, будет воспроизведен исходный документ. Запись документа производится в файловый (или подобный) объект out, по умолчанию используется sys.stdout. Аргумент encoding задает кодировку создаваемого документа (по умолчанию используется ’iso-8859-1’).

XMLFilterBase(base)

Этот класс предназначен для использования в качестве “прослойки” между объектом base (экземпляр xml.sax.xmlreader.XMLReader или производного от него класса), реализующим синтаксический анализ XML-документа, и обработчиками SAX-событий. Исходная реализация просто переадресует события соответствующим обработчикам. В производных классах Вы можете переопределить определенные методы для того, чтобы изменять поток событий при их поступлении.

prepare_input_source(source [, base])

Возвращает экземпляр класса xml.sax.xmlreader.InputSource, готовый для чтения документа. Аргумент source может быть строкой с системным идентификатором, файловым (или подобным) объектом или экземпляром класса xml.sax.xmlreader.InputSource. Аргумент base (по умолчанию равен пустой строке) используется в качестве основы URL (точки отсчета).

Функция prepare_input_source() обычно используется для реализации полиморфного восприятия аргумента source метода parse() объектов, реализующих чтение и синтаксический анализ XML-документов.

29.8. xml.sax.xmlreader — интерфейс объектов, реализующих чтение и синтаксический анализ XML-документов

Каждый синтаксический анализатор XML-документов с SAX-интерфейсом должен быть реализован в виде модуля на языке Python, в котором должна быть определена функция create_parser(), возвращающая объект-анализатор. Эта функция вызывается без аргументов функцией xml.sax.make_parser() для создания нового объекта. Все синтаксические анализаторы XML-документов должны иметь интерфейс, аналогичный классу XMLReader.

Модуль xml.sax.xmlreader определяет следующие классы:

XMLReader()

Базовый класс для всех синтаксических анализаторов XML-документов. Его методы ничего не делают и лишь определяют SAX-интерфейс.

IncrementalParser()

Метод parse() блокирует выполнение до тех пор, пока не будет прочитан весь документ. Данный класс предоставляет несколько дополнительных методов, которые позволяют подавать документ анализатору по частям. Класс IncrementalParser() также определяет метод parse(), реализованный с использованием этих методов. Этот класс является наиболее удобным для использования в качестве базового при написании синтаксических анализаторов.

Locator()

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

InputSource([systemId])

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

AttributesImpl(attrs)

Экземпляры этого класса используются для представления атрибутов элемента при вызове метода startElement() обработчика событий. Аргумент attrs должен быть отображением имен атрибутов к их значениям.

AttributesNSImpl(attrs, qnames)

Этот класс является производным от AttributesImpl, его экземпляры используются для представления атрибутов элемента с учетом пространства имен при вызове метода startElement() обработчика событий. Аргументы attrs и qnames должны быть отображениями, в качестве ключей в которых используются кортежи с URI пространства имен и локальным именем, а в качестве значений — значения и полные имена атрибутов соответственно.

29.8.1. Интерфейс класса XMLReader

Интерфейс класса XMLReader составляют следующие методы:

parse(source)

Анализирует XML-документ, формируя поток событий. Аргумент source должен быть строкой с системным идентификатором (обычно имя файла или URL), файловым (или подобным) объектом или экземпляром класса InputSource.

getContentHandler()

Возвращает текущий объект, реализующий обработку событий, касающихся содержимого документа (экземпляр xml.sax.handler.ContentHandler или производного от него класса).

setContentHandler(handler)

Запоминает handler как объект, реализующий обработку событий, касающихся содержимого документа (экземпляр xml.sax.handler.ContentHandler или производного от него класса). По умолчанию (до вызова этого метода) используется объект, игнорирующий все события.

getDTDHandler()

Возвращает текущий объект, реализующий обработку событий, касающихся DTD (экземпляр xml.sax.handler.DTDHandler или производного от него класса).

setDTDHandler(handler)

Запоминает handler как объект, реализующий обработку событий, касающихся DTD (экземпляр xml.sax.handler.DTDHandler или производного от него класса). По умолчанию (до вызова этого метода) используется объект, игнорирующий все события.

getEntityResolver()

Возвращает текущий объект, реализующий обработку ссылок на внешние сущности (экземпляр xml.sax.handler.EntityResolver или производного от него класса).

setEntityResolver(resolver)

Запоминает resolver как объект, реализующий обработку ссылок на внешние сущности (экземпляр xml.sax.handler.EntityResolver или производного от него класса). По умолчанию (до вызова этого метода) используется объект, открывающий документ, на который указывает системный идентификатор (отсутствие в определении сущности системного идентификатора приведет к ошибке).

getErrorHandler()

Возвращает текущий обработчик ошибок (экземпляр xml.sax.handler.ErrorHandler или производного от него класса).

setErrorHandler(handler)

Устанавливает handler в качестве текущего обработчика ошибок. По умолчанию (до вызова этого метода) используется объект, генерирующий исключение в случае ошибок и выводящий предупреждения на стандартный поток вывода (sys.stdout).

setLocale(locale)

Устанавливает язык и кодировку сообщений об ошибках и предупреждений.

getFeature(featurename)

Возвращает текущие установки для особенности с именем featurename. Если особенность неизвестна, генерирует исключение SAXNotRecognizedException. Символические константы для наиболее известных имен особенностей определены в модуле xml.sax.handler.

setFeature(featurename, value)

Изменяет установки для особенности с именем featurename. Для неизвестных особенностей генерирует исключение SAXNotRecognizedException, если синтаксический анализатор не поддерживает указанную особенность — генерирует исключение SAXNotSupportedException.

getProperty(propertyname)

Возвращает текущие установки для свойства propertyname. Если свойство неизвестно, генерирует исключение SAXNotRecognizedException. Символические константы для наиболее известных имен свойств определены в модуле xml.sax.handler.

setProperty(propertyname, value)

Изменяет установки для свойства propertyname. Для неизвестных свойств генерирует исключение SAXNotRecognizedException, если синтаксический анализатор не поддерживает указанное свойство — генерирует исключение SAXNotSupportedException.

29.8.2. Интерфейс класса IncrementalParser

Класс IncrementalParser является производным от XMLReader, его интерфейс имеет несколько дополнительных методов:

feed(data)

Анализирует порцию данных data.

close()

Вызов этого метода указывает на конец документа.

reset()

Этот метод должен быть вызван после метода close() для подготовки к анализу следующего документа.

29.8.3. Интерфейс класса Locator

Интерфейс класса Locator составляют следующие методы:

getColumnNumber()

Возвращает номер позиции в строке, в которой заканчиваются данные, соответствующие текущему событию (-1, если позиция неизвестна).

getLineNumber()

Возвращает номер строки, в которой заканчиваются данные, соответствующие текущему событию (-1, если номер строки неизвестен).

getPublicId()

Возвращает публичный идентификатор для текущего события (None, если публичный идентификатор не может быть установлен).

getSystemId()

Возвращает системный идентификатор для текущего события (None, если системный идентификатор не может быть установлен).

29.8.4. Экземпляры класса InputSource

Экземпляры класса InputSource имеют следующие методы:

setPublicId(id)

Устанавливает публичный идентификатор документа равным строке id.

getPublicId()

Возвращает публичный идентификатор документа.

setSystemId(id)

Устанавливает системный идентификатор документа равным строке id.

getSystemId()

Возвращает системный идентификатор документа.

setEncoding(encoding)

Устанавливает кодировку документа. Аргумент encoding должен быть строкой, применимой для использования в объявлении кодировки XML-документа. Установленная кодировка будет проигнорирована синтаксическим анализатором документа, если установлен символьный поток, осуществляющий автоматическое преобразование.

getEncoding()

Возвращает кодировку документа или None, если кодировка неизвестна.

setByteStream(bytefile)

Устанавливает байтовый поток (файловый или подобный объект, не выполняющий преобразование байтов в символы), из которого будет производиться чтение документа. Кодировка потока может быть установлена с помощью метода setEncoding. Байтовый поток не будет использоваться синтаксическим анализатором документа, если установлен символьный поток, осуществляющий автоматическое преобразование байтов (в определенной кодировке) в символы Unicode.

getByteStream()

Возвращает байтовый поток, из которого должно производиться чтение документа. Кодировка этого потока может быть получена с помощью метода getEncoding.

setCharacterStream(charfile)

Устанавливает символьный поток (файловый или подобный объект, осуществляющий автоматическое преобразование байтов в определенной кодировке в символы Unicode), из которого должно производиться чтение документа.

getCharacterStream()

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

29.8.5. Экземпляры классов AttributesImpl и AttributesNSImpl

Экземпляры классов AttributesImpl и AttributesNSImpl являются отображениями, в качестве ключей в которых выступают именами атрибутов, и в качестве значений — их значения. Для экземпляров класса AttributesImpl имена атрибутов (а также аргумент name описанных ниже методов) являются строками, для экземпляров AttributesNSImpl — кортежами из двух строк: с URI пространства имен и локального имени атрибута. Полное имя атрибута (аргумент qname методов) в обоих случаях является строкой. Помимо общих для всех отображений операций и основных методов (copy(), get(), has_key(), items(), keys() и values()) они имеют следующие методы:

getLength()

Возвращает число атрибутов.

getNames()

Возвращает список имен атрибутов (ключей отображения).

getType(name)

Возвращает тип атрибута с именем name (обычно ’CDATA’).

getValue(name)

Возвращает значение атрибута с именем name.

getValueByQName(qname)

Возвращает значения атрибута по его полному имени qname. Для экземпляров класса AttributesImpl этот метод эквивалентен методу getValue().

getNameByQName(qname)

Возвращает имя атрибута (строку или кортеж) по его полному имени qname. Для экземпляров класса AttributesImpl этот метод возвращает свой аргумент без изменений или генерирует исключение KeyError.

getQNameByName(name)

Возвращает полное имя атрибута с именем name. Для экземпляров класса AttributesImpl этот метод возвращает свой аргумент без изменений или генерирует исключение KeyError.

getQNames()

Возвращает список полных имен атрибутов. Для экземпляров класса AttributesImpl этот метод эквивалентен методу getNames().

29.9. xmllib — обработка XML-документов

Модуль xmllib считается устаревшим — используйте вместо него модуль xml.sax. Этот модуль определяет класс XMLParser, который может служить в качестве базового для класса, реализующего обработку размеченного текста в формате XML [3http://www.w3.org/TR/REC-xml, http://www.w3.org/XML/] (Extensible Markup Language, расширяемый язык разметки).

XMLParser([**keyword_args])

Создает и возвращает объект, реализующий обработку текста в формате XML. В настоящий момент воспринимаются следующие именованные аргументы (keyword_args):

accept_unquoted_attributes

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

accept_missing_endtag_name

Если этот аргумент является истиной, обработчик будет воспринимать закрывающие безымянные теги (‘</>’). По умолчанию равен 0.

map_case

Если этот аргумент является истиной, обработчик будет приводить имена тегов и атрибутов к нижнему регистру. По умолчанию равен 0.

accept_utf8

Если этот аргумент является истиной, обработчик допускает использование входной кодировки UTF-8. По умолчанию равен 0.

translate_attribute_references

Если этот аргумент является истиной, обработчик будет заменять ссылки на символы и сущности в значениях атрибутов. По умолчанию равен 1.

Класс XMLParser имеет следующие интерфейсные атрибуты данных и методы, которые определяют тип документа (DTD):

attributes

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

elements

Отображение имен элементов к кортежам из функций (или других объектов, поддерживающих вызов), предназначенных для обработки открывающего и закрывающего тега для этого элемента или None, если должен быть вызван метод unknown_starttag() или unknown_endtag(). Вам следует переопределить этот атрибут в производном классе — в исходной реализации он равен пустому словарю.

entitydefs

Отображение имен сущностей к их значениям. В исходной реализации равен словарю, в котором есть записи с ключами ’lt’, ’gt’, ’amp’, ’quot’ и ’apos’ (обязательный набор для всех типов документов).

reset()

Возвращает экземпляр в исходное состояние. Все необработанные данные теряются. Этот метод неявно вызывается при инициализации.

setnomoretags()

Останавливает обработку тегов. Весь последующий текст воспринимается без обработки (CDATA).

setliteral()

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

feed(data)

Передает экземпляру размеченный текст data для обработки. Обрабатываются только завершенные данные, остальное остается в буфере до тех пор, пока не будет передана следующая порция данных или не будет вызван метод close().

close()

Завершает обработку всех данных в буфере. Вы можете переопределить этот метод в производном классе, добавив дополнительные действия. Переопределенный метод всегда должен вызывать исходную версию метода.

translate_references(data)

Преобразует все ссылки на символы (‘&#ref;’) и сущности (‘&ref;’) в строке data и возвращает полученный текст.

getnamespace()

Возвращает отображение аббревиатур для (активных в настоящий момент) пространств имен к их URI (Uniform Resource Identifier, универсальный идентификатор ресурса).

handle_xml(encoding, standalone)

Вызывается для обработки тега ‘<?xml ...?>’. В качестве аргументов используются значения одноименных атрибутов тега (по умолчанию используются None и строка ’no’ соответственно). Исходная реализация ничего не делает.

handle_doctype(tag, pubid, syslit, data)

Вызывается для обработки объявления типа документа. Аргумент tag является строкой с именем корневого элемента, pubid — формальный публичный идентификатор (или None, если не задан), syslit — системный идентификатор и data — необработанный текст встроенного в документ DTD (Document Type Definition, определение типа документа) или None, если документ не содержит DTD. Исходная реализация ничего не делает.

handle_starttag(tag, method, attributes)

Вызывается для обработки открывающих тегов, для которых задан обработчик в атрибуте elements. Аргумент tag является строкой с именем тега, method — функция (метод), предназначенная для обработки открывающего тега, и attributes — словарь, отображающий имена атрибутов, найденных внутри угловых скобок тега, к их значениям (после обработки ссылок на символы и сущности). Например, для обработки открывающего тега ‘<A HREF="http://www.cwi.nl/»’ вызывается ‘obj.handle_starttag('A', obj.elements['A'][0], {'HREF': 'http://www.cwi.nl/'})’. Исходная реализация метода handle_starttag вызывает method(attributes).

handle_endtag(tag, method)

Вызывается для обработки закрывающих тегов, для которых задан обработчик в атрибуте elements. Аргумент tag является строкой с именем тега, method — функция (метод), предназначенная для обработки закрывающего тега. Например, для обработки закрывающего тега ‘</A>’ вызывается ‘obj.handle_endtag('A', obj.elements['A'][1])’. Исходная реализация метода handle_endtag просто вызывает method().

handle_data(data)

Вызывается для обработки простого текста. Вам следует переопределить его в производном классе: исходная реализация ничего не делает.

handle_charref(ref)

Вызывается для обработки ссылок на символы в виде ‘&#ref;’. Исходная реализация преобразует число в диапазоне от 0 до 255 в символ с помощью встроенной функции chr() и вызывает с ним метод handle_data(). Если аргумент ref неверен или выходит за пределы указанного диапазона, вызывает unknown_charref(ref) для обработки ошибки.

handle_comment(comment)

Вызывается для обработки комментария. В качестве аргумента comment используется строка с текстом, содержащимся между ‘<!--’ и ‘-->’. Исходная реализация ничего не делает.

handle_cdata(data)

Вызывается для обработки элементов CDATA (текста между ‘<![CDATA[’ и ‘]]>’). Вам следует переопределить его в производном классе: исходная реализация ничего не делает.

handle_proc(name, data)

Вызывается для инструкций обработки (PI, Processing Instruction) в виде ‘<?name data?>’. Обратите внимание, что ‘<?xml data?>’ обрабатывается отдельно — с помощью метода handle_xml(). Вам следует переопределить метод handle_proc() в производном классе: исходная реализация ничего не делает.

handle_special(data)

Вызывается для обработки объявлений в виде ‘<!data>’. Обратите внимание, что ‘<!DOCTYPE ...>’ в начале документа обрабатывается отдельно — с помощью метода handle_doctype(). Вам следует переопределить метод handle_special() в производном классе: исходная реализация ничего не делает.

syntax_error(message)

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

unknown_starttag(tag)

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

unknown_endtag(tag)

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

unknown_charref(ref)

Вызывается для обработки неверной ссылки на символ в виде ‘&#ref;’. Вам следует переопределить этот метод в производном классе: исходная реализация ничего не делает.

unknown_entityref(ref)

Вызывается для обработки ссылки на сущность с неизвестным именем в виде ‘&ref;’. Вам следует переопределить этот метод в производном классе: исходная реализация вызывает метод syntax_error() для обработки ошибки.

Модуль xmllib поддерживает пространства имен XML. Полные имена тегов и атрибутов (то, что используется в качестве аргументов методов), определенных в пространстве имен, состоит URI, определяющего пространство имен, и самого имени тега или атрибута, разделенных пробелом. Например, запись ‘<html xmlns='http://www.w3.org/TR/REC-html40'>’ воспринимается как тег с именем ’http://www.w3.org/TR/REC-html40 html’ и запись ‘<html:a href=’http://frob.com'>’ внутри этого элемента воспринимается как тег с именем ’http://www.w3.org/TR/REC-html40 a’ и атрибутом ’http://www.w3.org/TR/REC-html40 href’.

30. Разное

30.1. fileinput — перебор строк из нескольких входных потоков

Модуль fileinput определяет класс и функции, помогающие перебирать строки, полученные со стандартного потока и/или файлов, указанных списков. Чаще всего этот модуль используется примерно следующим образом:

import fileinput
for line in fileinput.input():
    process(line)

В этом случае перебираются строки файлов, имена которых указаны в качестве аргументов в командной строке (sys.argv[1:]), или стандартного потока ввода, если этот список пуст. Имя файла ’-’ считается ссылающимся на стандартный поток ввода sys.stdin. Вы можете указать альтернативный список имен файлов (или имя одного файла) в качестве первого аргумента функции input().

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

input([files [, inplace [, backup]]])

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

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

filename()

Возвращает имя файла, для которого была прочитана последняя строка. До того, как прочитана первая строка (в том числе непосредственно после вызова функции nextfile()), возвращает None. Для стандартного потока ввода возвращает ’<stdin>’.

lineno()

Возвращает суммарный номер последней прочитанной строки. До того, как прочитана первая строка (в том числе непосредственно после вызова функции nextfile()), возвращает 0.

filelineno()

Возвращает номер последней прочитанной строки в текущем файле. До того, как прочитана первая строка (в том числе непосредственно после вызова функции nextfile()), возвращает 0.

isfirstline()

Возвращает 1, если последняя прочитанная строка является первой в текущем файле, иначе возвращает 0.

isstdin()

Возвращает 1, если последняя строка была прочитана со стандартного потока ввода (sys.stdin), иначе возвращает 0.

nextfile()

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

close()

Вызывает метод close() экземпляра, сохраненного функцией input().

Следующий класс реализует чтение из нескольких файлов и может быть использован для определения производных классов:

FileInput([files [, inplace [, backup]]])

Создает и возвращает объект, обеспечивающий чтение строк из нескольких файлов. Аргумент files должен быть списком имен файлов или строкой с именем файла. По умолчанию используется sys.argv[1:] или стандартный поток ввода, если список аргументов командной строки пуст. Имя ’-’ является специальным, для него используется поток sys.stdin.

Если задан и является истиной аргумент inplace, файл переименовывается в резервную копию с именем, полученным добавлением суффикса backup (по умолчанию используется ’.bak’) к исходному имени файла, стандартный поток вывода перенаправляется в исходный файл, и перебираются строки резервной копии. Таким образом, одновременно с чтением строк Вы можете безопасно изменять исходный файл, выводя в него информацию, например, инструкцией print. Резервная копия удаляется при закрытии выходного файла. Такое редактирование файла (“in-place filtering”) невозможно при чтении из стандартного потока ввода.

Текущая реализация не позволяет работать с файловой системой MS-DOS, которая налагает сильные ограничения на имена файлов.

Экземпляры класса FileInput ведут себя аналогично последовательностям, но предоставляют доступ к элементам в определенном порядке (этого достаточно для использования в инструкции for), а также имеют следующие методы:

filename()

Возвращает имя файла, для которого была прочитана последняя строка. До того, как прочитана первая строка (в том числе непосредственно после вызова метода nextfile()), возвращает None. Для стандартного потока ввода возвращает ’<stdin>’.

lineno()

Возвращает суммарный номер последней прочитанной строки. До того, как прочитана первая строка (в том числе непосредственно после вызова метода nextfile()), возвращает 0.

filelineno()

Возвращает номер последней прочитанной строки в текущем файле. До того, как прочитана первая строка (в том числе непосредственно после вызова метода nextfile()), возвращает 0.

isfirstline()

Возвращает 1, если последняя прочитанная строка является первой в текущем файле, иначе возвращает 0.

isstdin()

Возвращает 1, если последняя строка была прочитана со стандартного потока ввода (sys.stdin), иначе возвращает 0.

nextfile()

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

close()

“Закрывает” объект.

readline()

Считывает и возвращает следующую строку. Этот метод увеличивает счетчик строк на единицу, поэтому вызов obj.readline() внутри цикла ‘for line in obj’ приведет к ошибке (исключение RuntimeError).

30.2. ConfigParser — чтение конфигурационных файлов

Этот модуль определяет класс ConfigParser, реализующий чтение и обработку простых конфигурационных файлов, аналогичных по структуре ‘.ini’-файлам в Windows.

Конфигурационный файл состоит из разделов, начинающихся с заголовка вида ‘[раздел]’ и содержащий строки вида ‘имя: значение’. Длинные значения могут быть записаны в несколько строк в стиле RFC 822. Также допускается использование строк вида ‘имя=значение’. Обратите внимание, что начальные символы пропуска из значения удаляются. Значения могут содержать строки формата, ссылающиеся на другие значения в этом же разделе или разделе DEFAULT (раздел значений по умолчанию):

foodir: %(dir)s/whatever
dir=frob

В приведенном примере последовательность ‘%(dir)s’ будет заменена значением ‘dir’ (здесь оно равно ‘frob’). Дополнительные значения по умолчанию могут быть указаны при инициализации и извлечении. Строки, начинающиеся с символа ‘#’ или ‘;’ считаются комментариями и игнорируются.

ConfigParser([defaults])

Возвращает объект, отвечающий за чтение конфигурационного файла. Отображение defaults определяет значения по умолчанию: ключи в нем должны быть строками, определяющие имена, значения могут содержать последовательности вида ‘%(имя)s’. Заметим, что имя __name__ всегда имеет значение, равное имени раздела.

MAX_INTERPOLATION_DEPTH

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

Модуль также определяет следующую иерархию исключений:

Error

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

NoSectionError

Указанный раздел (атрибут section экземпляра исключения) не найден.

DuplicateSectionError

Раздел с таким именем (атрибут section экземпляра исключения) уже существует.

NoOptionError

Опция с указанным именем (атрибут option экземпляра исключения) не найдена в указанном разделе (атрибут section).

InterpolationError

Проблемы при раскрытии специальной последовательности вида ‘%(имя)s’ (атрибут reference экземпляра исключения, имена раздела и опции доступны через атрибуты section и option).

InterpolationDepthError

Достигнута максимальная глубина рекурсии (MAX_INTERPOLATION_DEPTH) при раскрытии специальных последовательностей в значении опции (имена раздела и опции доступны через атрибуты section и option экземпляра исключения).

MissingSectionHeaderError

Конфигурационный файл не содержит заголовков. Имя файла, номер строки и сама строка, в которой обнаружена ошибка, доступны через атрибуты filename, lineno и line экземпляра исключения.

ParsingError

Ошибка при анализе конфигурационного файла. Атрибут filename экземпляра исключения содержит имя конфигурационного файла и атрибут errors — список пар из номера и содержимого строки для всех строк, в которых обнаружены ошибки.

Экземпляры класса ConfigParser имеют следующие методы:

defaults()

Возвращает отображение со значениями по умолчанию.

sections()

Возвращает список имен доступных разделов. Имя DEFAULT в список не включается.

add_section(section)

Добавляет раздел с именем section. Если раздел с таким именем уже существует, генерируется исключение DuplicateSectionError.

has_section(section)

Возвращает 1, если есть раздел с именем section, иначе возвращает 0. Имя раздела ’DEFAULT’ не распознается.

options(section)

Возвращает имен доступных опций в разделе section.

has_option(section, option)

Возвращает 1, если существует раздел с именем section и содержит опцию с именем option, иначе возвращает 0. Этот метод доступен, начиная с версии 1.6.

read(filenames)

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

readfp(fp [, filename])

Считывает и обрабатывает конфигурационный файл, представленный файловым (или подобным) объектом fp (должен иметь метод readline()). Аргумент filename используется в качестве имени файла в сообщениях об ошибках. Если аргумент filename не задан, используется fp.name или ’<???>’, если объект fp не имеет атрибута name.

get(section, option [, raw [, vars]])

Возвращает значение опции option в разделе section. Если аргумент raw опущен или является ложью, метод get() раскрывает специальные последовательности, начинающиеся с символа ‘%’. При этом принимаются во внимание значения по умолчанию, переданные конструктору и этому методу в качестве аргумента vars. Значения, указанные в отображении vars имеют преимущество над значениями по умолчанию, переданными конструктору.

getint(section, option)

Возвращает значение опции option в разделе section в виде целого числа.

getfloat(section, option)

Возвращает значение опции option в разделе section в виде вещественного числа.

getboolean(section, option)

Возвращает значение опции option в разделе section в виде целого числа 0 или 1. В конфигурационном файле значение опции должно быть указано строкой ‘0’ или ‘1’, во всех остальных случаях генерируется исключение ValueError.

set(section, option, value)

Если существует раздел с именем section, устанавливает в нем значение опции option равным value. Если аргумент section является ложью или равен строке ’DEFAULT’, value запоминается как значение опции option по умолчанию. В остальных случаях генерируется исключение NoSectionError. Метод set() доступен, начиная с версии 1.6.

write(fp)

Записывает текущее состояние объекта в конфигурационный файл, представленный файловым (или подобным) объектом fp. Этот метод доступен, начиная с версии 1.6.

remove_option(section, option)

Удаляет опцию option из раздела section. Если аргумент section является ложью или равен строке ’DEFAULT’, удаляет значение опции option по умолчанию. В остальных случаях, если раздел section отсутствует, генерируется исключение NoSectionError. Если опция присутствовала, возвращает 1, иначе возвращает 0. Метод remove_option() доступен, начиная с версии 1.6.

remove_section(section)

Полностью удаляет раздел section. Если раздел присутствовал, возвращает 1, иначе возвращает 0.

30.3. shlex — простой синтаксический анализатор

Класс shlex, определенный в этом модуле, значительно упрощает написание синтаксических анализаторов для командных языков с простым синтаксисом, подобных UNIX shell. Такая возможность часто полезна для написания мини-языков, используемых, например, для написания конфигурационных файлов (см. также описание модуля ConfigParser).

shlex([stream [, file]])

Инициализирует и возвращает объект, представляющий лексический анализатор. Аргумент stream должен быть файловым объектом (или подобным, с методами read() и readline()) и определяет поток ввода анализатора, по умолчанию используется sys.stdin. Если задан аргумент file, он определяет имя файла (используется для инициализации атрибута infile).

Экземпляры класса shlex имеют следующие методы:

get_token()

Возвращает очередную лексему. Лексема может быть считана из стека (если она была записана туда с помощью метода push_token()) или из входного потока. При достижении конца файла возвращает пустую строку.

push_token(str)

Записывает строку str в качестве лексемы в стек.

read_token()

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

sourcehook(filename)

Этот метод вызывается для обработки запросов на включение файла. Аргумент filename является строкой, следующей за лексемой включения файла (атрибут source). Метод sourcehook() должен возвращать кортеж, содержащий имя файла и файловый (или подобный) объект.

error_leader([file [, line]])

Возвращает начало сообщения об ошибке в формате ’"file", line line: ’. Если аргументы file и/или line опущены, используются текущие имя файла и номер строки. Такой формат сообщения об ошибке является общепринятым и воспринимается редактором Emacs и другими инструментами UNIX.

Экземпляры класса shlex также имеют следующие атрибуты, управляющие процессом лексического анализа:

commenters

Строка символов, которые воспринимаются как начало комментария. Все символы от начала комментария до конца строки игнорируются. По умолчанию включает только символ ‘#’.

wordchars

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

whitespace

Строка из символов, которые считаются разделителями лексем (символы пропуска). По умолчанию этот атрибут равен ’ \t\r\n’.

quotes

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

infile

Имя текущего входного файла (или None, если имя файла не установлено). Полезен при конструировании сообщений об ошибке.

instream

Файловый объект, представляющий текущий входной поток.

source

По умолчанию этот атрибут равен None. Если ему присвоить строку, то эта строка будет восприниматься как лексема запроса на включение файла. Следующая после source лексема будет восприниматься как имя файла, содержимое которого должно быть обработано лексическим анализатором. После обработки включенного файла лексический анализатор продолжает обработку текущего потока.

debug

Целое число, определяющее, насколько подробной должна быть выводимая отладочная информация. Если атрибут debug равен 0, отладочная информация не выводится.

lineno

Номер текущей строки (число прочитанных символов перехода на новую строку плюс 1).

token

Буфер лексем. Может быть полезен при обработке исключений.

Обратите внимание, что символы, не входящие в строки wordchars, whitespace и quotes, воспринимаются как односимвольные лексемы. Кроме того, символы кавычек внутри слов теряют свое значение, а комментарии маскируют также и символ перехода на новую строку. Так, ввод ‘ain’t’ и ain#d\n’t будут восприняты как одна и та же лексема — строка "ain’t".

30.4. cmd — создание командных интерпретаторов

Этот модуль определяет класс Cmd, который может служить основой при написании командных интерпретаторов, ориентированных на строки. Хорошим примером использования этого метода может послужить отладчик языка Python (модуль pdb).

Cmd()

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

Экземпляры класса Cmd имеют следующие методы и атрибуты данных:

cmdloop([intro])

Выполняет в цикле следующие операции: выводит приглашение, воспринимает ввод, обрабатывает начало введенной команды и вызывает для ее выполнения соответствующий метод, передавая в качестве аргумента остаток строки. Аргумент intro (строка) определяет выводимый перед первым приглашением заголовок, по умолчанию используется атрибут intro.

Интерпретатор будет воспринимать команду ‘foo’ только, если объект имеет метод do_foo(). Символы ‘?’ и ‘!’ в начале строки воспринимаются как команды ‘help’ и ‘shell’ соответственно, конец файла — как команда ‘EOF’.

Предопределенный метод do_help с аргументом ’bar’ вызывает метод help_bar(). Без аргументов do_help() выводит список всех доступных тем, для которых может быть получена помощь (определен соответствующий метод help_*()), и список недокументированных команд. Класс Cmd не определяет методы do_shell() и do_EOF().

Большинство методов do_*() должно возвращать None. Если возвращаемое значение является истиной (и метод postcmd() не переопределен), работа интерпретатора будет завершена.

onecmd(str)

Воспринимает строку str, как если бы она была введена в ответ на приглашение интерпретатора.

emptyline()

Этот метод вызывается, если в ответ на приглашение введена пустая строка. По умолчанию повторяет последнюю введенную непустую команду.

default(line)

Этот метод вызывается, если первая лексема команды не распознана (не имеет соответствующего метода do_*()). По умолчанию выводит сообщение об ошибке.

precmd(line)

Этот метод вызывается для предварительной обработки введенной строки (аргумент line). По умолчанию возвращает строку без изменений.

postcmd(stop, line)

Этот метод вызывается после обработки и выполнения команды. В качестве аргументов stop и line используются значение, возвращаемое соответствующим методом do_*(), и строка ввода, обработанная методом precmd(). Если значение, возвращаемое этим методом, является истиной, работа интерпретатора будет завершена. По умолчанию возвращает свой аргумент stop без изменений.

preloop()

Этот метод вызывается один раз при запуске интерпретатора (вызове метода cmdloop()) перед выводом заголовка. По умолчанию ничего не делает.

postloop()

Этот метод вызывается один раз при завершении работы интерпретатора. По умолчанию ничего не делает.

prompt

Строка, выводимая в качестве приглашения. По умолчанию используется ’(Cmd) ’.

identchars

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

lastcmd

Строка, содержащая последнюю непустую команду (первую лексему введенной строки).

intro

Строка, которая используется в качестве заголовка, выводимого при запуске интерпретатора. Этот атрибут может быть переопределен, если при вызове метода cmdloop() использован аргумент, отличный от None.

doc_header

Заголовок к списку документированных команд (для которых есть соответствующие методы do_*() и help_*()).

misc_header

Заголовок к списку доступных тем помощи, не являющихся командами (то есть, для которых есть метод help_*(), но нет соответствующего метода do_*()).

undoc_header

Заголовок к списку недокументированных команд (для которых есть соответствующий метод do_*(), но нет метода help_*()).

ruler

Символ, который используется для линий под заголовком помощи. Если является пустой строкой, линия не будет использована. По умолчанию атрибут ruler равен ’=’.

30.5. calendar — функции для работы с календарем

Этот модуль предоставляет функции для работы с календарем, а также позволяет выводить календарь аналогично программе cal. По умолчанию считается, что неделя начинается с понедельника. Чтобы установить иной день, например воскресенье, используйте функцию setfirstweekday().

MONDAY

TUESDAY

WEDNESDAY

THURSDAY

FRIDAY

SATURDAY

SUNDAY

Константы со значениями от 0 (понедельник) до 6 (воскресенье), представляющие дни недели.

setfirstweekday(weekday)

Устанавливает использование weekday (целое число от 0 до 6) в качестве первого дня недели. Например, следующий фрагмент устанавливает использование в качестве первого дня недели воскресенья:

import calendar
calendar.setfirstweekday(calendar.SUNDAY)

firstweekday()

Возвращает целое число от 0 до 6, определяющее день недели, с которого (согласно текущим установкам) неделя начинается.

isleap(year)

Возвращает 1, если год year (целое число) является високосным, иначе возвращает 0.

leapdays(y1, y2)

Возвращает число високосных лет в промежутке с y1 по y2 - 1 год (включительно).

weekday(year, month, day)

Возвращает целое число, определяющее день недели для указанной даты. year — год (см. замечания в описании модуля time), month — месяц (от 1 до 12) и day — число (от 1 до 31). Например, следующий код позволяет вывести номера месяцев 2000 года, в которых 13 число приходится на пятницу:

>>> from calendar import weekday, FRIDAY
>>> for month in xrange(1, 13):
...     if weekday(2000, month, 13)==FRIDAY:
...         print month
...
10

monthrange(year, month)

Возвращает кортеж, содержащий первый день недели месяца (целое число от 0 до 6) и число дней в месяце для указанного года (аргумент year) и месяца (аргумент month).

monthcalendar(year, month)

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

month(theyear, themonth [, datewidth [, linesperweek]])

Возвращает строковое представление календаря на месяц для указанного года (аргумент theyear) и месяца (аргумент themonth). Аргументы datewidth и linesperweek определяют ширину поля даты и число строк, используемых для одной недели.

prmonth(theyear, themonth [, datewidth [, linesperweek]])

Выводит на стандартный поток вывода (sys.stdout) календарь на месяц. Аргументы имеют такое же значение, как и для функции month().

calendar(year [, datewidth [, linesperweek [, spaces]]])

Возвращает строковое представление в три колонки календаря на год year. Аргументы datewidth, linesperweek и spaces определяют ширину поля даты, число строк, используемых для одной недели, и количество пробелов между колонками с календарями на месяц.

prcal()

Выводит на стандартный поток вывода (sys.stdout) календарь на год. Аргументы имеют такое же значение, как и для функции calendar().

timegm(time_tuple)

Возвращает число секунд, прошедших с начала эпохи (независимо от системы начало эпохи считается равным началу 1970 года) до времени, которое представлено кортежем из девяти чисел time_tuple (см. описание модуля time).

Перейти на главную страничку сайта (список статей, файлы для скачивания)

© 2007 http://www.script-coding.com При любом использовании материалов сайта обязательна ссылка на него как на источник информации, а также сохранение целостности и авторства материалов.