Таня Шлюссер - Автостопом по Python

Замыкание (функция sigint_handler()) отправляется обработчику сигналов; будет использовано для обработки сигналов SIGINT и SIGTERM.

Tablib — это библиотека Python, которая преобразует данные в различные форматы, сохраняет их в объекте класса Dataset, а несколько объектов типа Datasets — в объекте класса Databook. Объекты класса Dataset хранятся в форматах JSON, YAML, DBF и CSV (файлы в этих форматах можно импортировать), наборы данных могут быть экспортированы в форматах XLSX, XLS, ODS, JSON, YAML, DBF, CSV, TSV и HTML. Библиотека Tablib выпущена Кеннетом Ритцем (Kenneth Reitz) в 2010 году, имеет интуитивный дизайн API, характерный для всех проектов Ритца.

Tablib — это библиотека, а не приложение, поэтому не имеет четко определенной точки входа, как в случае с HowDoI и Diamond.

Загрузите Tablib из GitHub:

$ git clone https://github.com/kennethreitz/tablib.git

$ virtualenv — p python3 venv

$ source venv/bin/activate

(venv)$ cd tablib

(venv)$ pip install — editable.

(venv)$ python test_tablib.py # Run the unit tests.

Документация Tablib ( http://docs.python-tablib.org/) начинается с упоминания варианта использования, затем в ней более подробно описываются возможности библиотеки: она предоставляет объект типа Dataset, который имеет строки, столбцы и заголовки. Вы можете выполнять операции ввода/вывода из разных форматов для объекта типа Dataset. В разделе, содержащем более сложные варианты использования, говорится, что вы можете добавлять к строкам теги и создавать унаследованные столбцы, которые являются функциями других столбцов.

Tablib — это библиотека, а не исполняемый файл, как в случае с HowDoI или Diamond, поэтому вы можете открыть интерактивную сессию Python и использовать функцию help() для исследования API. Рассмотрим пример применения класса tablib.Dataset, разных форматов данных и способа работы I/O:

>>> import tablib

>>> data = tablib.Dataset()

>>> names = ('Black Knight', 'Killer Rabbit')

>>>

>>> for name in names:

… ····fname, lname = name.split()

… ····data.append((fname, lname))

…

>>> data.dict

[['Black', 'Knight'], ['Killer', 'Rabbit']]

>>>

>>> print(data.csv)

Black,Knight

Killer,Rabbit

>>> data.headers=('First name', 'Last name')

>>> print(data.yaml)

- {First name: Black, Last name: Knight}

- {First name: Killer, Last name: Rabbit}

>>> with open('tmp.csv', 'w') as outfile:

… ····outfile.write(data.csv)

…

64

>>> newdata = tablib.Dataset()

>>> newdata.csv = open('tmp.csv'). read()

>>> print(newdata.yaml)

- {First name: Black, Last name: Knight}

- {First name: Killer, Last name: Rabbit}

Структура файлов, находящихся в каталоге tablib/, выглядит так:

tablib

|- __init__.py

|- compat.py

|- core.py

|- formats/

|- packages/

Каталоги tablib/formats/ и tablib/packages/ рассматриваются в следующих разделах.

Python поддерживает строки документации на уровне модулей, как и строки документации, которые мы уже описали, — строковые литералы, являющиеся первым выражением в функции, классе или методе. На сайте Stack Overflow приведены полезные советы о том, как задокументировать модули ( http://stackoverflow.com/a/2557196). Для нас это означает, что существует еще один способ исследовать исходный код — мы можем ввести команду head *.py в терминальной оболочке, находясь на верхнем уровне пакета, чтобы показать все строки документации модуля. Вот что мы увидим для библиотеки Tablib:

Мы узнали следующее.

API высшего уровня (содержимое файла __init__.py доступно в каталоге tablib после выполнения оператора import tablib) имеет всего девять точек входа: классы Databook и Dataset упоминаются в документации, detect может использоваться для определения форматирования, import_set и import_book должны импортировать данные, а последние три класса — InvalidDatasetType, InvalidDimensions и UnsupportedFormat — выглядят как исключения (если код следует принципам PEP 8, мы можем сказать, какие объекты являются пользовательскими классами на основе их регистра).

tablib/compat.py — это модуль совместимости. Беглый взгляд на него покажет, что он обрабатывает проблемы совместимости между Python 2 и Python 3 аналогично HowDoI, разрешая разные местоположения и имена к одинаковым символам, которые будут использованы в tablib/core.py.

В файле tablib/core.py в соответствии с его именем реализуются объекты Tablib вроде Dataset и Databook.

Документация Tablib ( http://docs.python-tablib.org/) содержит хороший пример использования Sphinx ( http://www.sphinx-doc.org/en/stable/tutorial.html), поскольку это маленькая библиотека, которая применяет много расширений для Sphinx.

Документация к текущей версии Sphinx находится на странице документации Tablib ( http://docs.python-tablib.org/). Если вы хотите построить документацию самостоятельно (пользователям Windows понадобится команда male — она старая, но работает как надо), сделайте следующее:

(venv)$ pip install sphinx

(venv)$ cd docs

(venv)$ make html

(venv)$ open _build/html/index.html # Для просмотра результата.

Sphinx предоставляет несколько вариантов тем оформления ( http://www.sphinx-doc.org/en/stable/theming.html), которые настраиваются с помощью стандартных шаблонов представления кода и стилей CSS. Шаблоны Tablib для левой боковой панели находятся в каталоге docs/_templates/ в файле basic/layout.html. Вы можете найти этот файл в папке стилей Sphinx, введя в командной строке следующую команду:

(venv)$ python — c 'import sphinx.themes;print(sphinx.themes.__path__)'

Продвинутые пользователи также могут выполнять поиск в docs/_themes/kr/, пользовательском стиле, который расширяет базовую структуру. Его можно выбрать, добавив каталог _themes/ в системный путь, установив необходимые значения свойствам html_theme_path = ['_themes'] и html_theme = 'kr' в docs/conf.py.

Для включения в ваш код документации API, которая генерируется автоматически на основе строк документации, используйте autoclass::. Вам нужно скопировать форматирование строк документации в Tablib, чтобы это сработало:

.. autoclass:: Dataset

····:inherited-members:

Для получения этой функциональности следует ответить «да» на вопрос о включении расширения Sphinx autodoc при запуске sphinx-quickstart, чтобы создать новый проект Sphinx. Директива: inherited-members: также добавит документацию для атрибутов, унаследованных от классов-предков.

Главная особенность, которую мы хотим подчеркнуть в Tablib, — отсутствие использования классов в модулях в tablib/formats/ (это идеально иллюстрирует наше утверждение, что не нужно везде применять классы). Далее мы приведем фрагменты кода, демонстрирующие использование синтаксиса декоратора в Tablib, а также задействуем класс property ( https://docs.python.org/library/functions.html#property) для создания унаследованных атрибутов вроде ширины и высоты набора данных. Помимо этого, покажем, как динамически он регистрирует форматы файлов, чтобы избежать дупликации шаблонного кода для разных типов формата (CSV, YAML и т. д.).