Автостопом по Python

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

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

Документация к библиотеке Tablib в формате Sphinx

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

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

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

Каталог форматов содержит все определенные для ввода/вывода форматы файлов. Имена модулей _csv.py, _tsv.py, _json.py, _yaml.py, _xls.py, _xlsx.py, _ods.py и _xls.py начинаются с нижнего подчеркивания — это указывает пользователю библиотеки, что свойства не предназначены для непосредственного использования. Мы можем перейти в каталог formats и выполнять поиск классов и функций. Команда grep ^class formats/*.py показывает отсутствие определений классов, а команда grep ^def formats/*.py — что каждый модуль содержит одну или несколько следующих функций: • detect(stream) определяет формат файла, основываясь на содержимом потока;

• dset_sheet(dataset, ws) форматирует клетки для таблиц Excel;

• export_set(dataset) экспортирует набор данных в заданный формат, возвращая отформатированную строку в новом формате (для Excel возвращает объект bytes или бинарную строку в Python 2); • import_set(dset, in_stream, headers=True) заменяет содержимое набора данных содержимым входного потока;

• export_book(databook) экспортирует объекты Datasheet в Databook в заданном формате, возвращая объект типа string или bytes; • import_book(dbook, in_stream, headers=True) заменяет содержимое databook содержимым входного потока.