Введение
В среде питонистов библиотека Pandas пользуется большой популярностью и по большей мере известна в контексте DataSciense и анализа данных. Как следует из русскоязычной википедии: "pandas — это программная библиотека на языке Python для обработки и анализа данных." Наверное, ни один Jupyter ноутбук не обходится без использования пандосовских DataFrame'ов. На самом деле, DataFrame пандас позволяет не только всячески манипулировать данными, но и выводить их в нужном формате, предоставляя широкие возможности для кастомизации. Например, использовали ли вы объекты класса Styler, входящего в состав Pandas? Мне показалось интересным взглянуть на Pandas с этой стороны.
На практике очень многие бизнес-задачи подразумевают работу с двумерными массивами данных или, проще говоря, таблицами. Как следствие, возникает потребность представлять такие данные в удобном для восприятия виде. Поэтому будет интересно поговорить о подходах к server-side рендеренгу таблиц в контексте веб-приложения на Python.
Актуальности данной теме добавляет тот факт, что подобной информации довольно мало как в интернете, так и в профессиональной литературе (возможность рендеринга таблиц в html не упоминается и в указанной выше статье википедии).
Проблема
Мы хотим отображать имеющиеся данные в виде html таблицы.
Часто одни и те же данные нужно представить в разных вариациях, например, отобразить на странице сайта, в email сообщении или формате Excel. Работая над одним из прошлых проектов, я столкнулся с трудно-поддерживаемыми, толстыми шаблонами веб-страниц, которые содержали html разметку для отображения таблиц с большим количеством данных. К тому же html шаблоны могли иметь различные вариации, например, для email уведомлений и т.д. Такой подход вызывает трудности при изменении структуры таблицы или данных.
Все последующие манипуляции будем проводить в контексте приложения на Django. В качестве адаптера БД имеется модель Customer, в качестве http представления имеем - CustomerListView. Код проекта с начальными условиями доступен на GitHub - commit# 8fdf785.
Решение в лоб - передать в контекст страницы итерируемый объект, содержащий строки данных, и средствами шаблонизатора итерироваться по нему формируя html код таблицы строка за строкой.
✅ Не требует использования дополнительных библиотек
❌ "Толстые" шаблоны таблиц
❌ Затруднена поддержка и внесение изменений
❌ Повторение работы при необходимости добавить вариацию таблицы (email, Excel и т.д.)
Используем DataFrame
Поскольку pandas уже входил в технологический стек проекта, было принято решение задействовать эту библиотеку для рендеринга таблиц в html.
DataFrame - это внутренняя структура Pandas для хранения таблицы и проведения операций над ней. Создадим новый объект DataFrame, передав нужные данные в конструктор класса, и отрендерим html воспользовавшись методом датафрейма - to_html():
# views.py
class CustomerListView(ListView):
model = Customer
paginate_by = 10
def get_context_data(self, *, object_list=None, **kwargs):
context = super().get_context_data(**kwargs)
context['table'] = self.get_html_table(context['object_list'])
return context
def get_html_table(self, object_list: QuerySet):
df = pd.DataFrame(
data=object_list.values_list(),
columns=[field.verbose_name for field in object_list.model._meta.get_fields()],
)
return df.to_html()
Метод get_html_table() возвращает html код таблицы, принимая на вход объект типа QuerySet - object_list из контекста ListView Django.
Конструктор класса DataFrame может принимать итерируемый объект, который содержит входные данные и список наименований столбцов.
Поэтому передаём данные в DataFrame, воспользовавшись методом QuerySet.values_list() для представления объектов БД в виде кортежей со значениями атрибутов объекта.
Таким образом, мы получили html таблицу, написав миниатюрный метод, состоящий из нескольких строк кода. Хотя стоит отметить, что в таком виде таблица не будет иметь какой-либо стилизации. Убедимся в этом, добавив полученный html в шаблон страницы, и взглянем на неё:
# customer_list.html
{% extends 'base.html' %}
{% block content %}
<div class="col-6">
{{ table|safe }}
</div>
{% endblock %}
Код проекта из этого раздела доступен на GitHub - commit# 2005e31.
Используем средства стилизации
На самом деле метод DataFrame.to_html может принимать определённый перечень аргументов для обеспечения удобочитаемости таблицы на выходе. Например, можно настроить ширину границ ячеек, отображение индекса, заполнение пустых ячеек, выравнивание наименований столбцов и т.д. (с полным перечнем возможностей можно ознакомиться на соответствующей странице в документации).
# views.py
# def get_html_table(queryset):
return df.to_html(
classes='table table-striped table-hover',
border=0,
index=False,
na_rep='-',
justify='left',
columns=(
Customer.id.field.verbose_name,
Customer.status.field.verbose_name,
Customer.name.field.verbose_name,
Customer.source.field.verbose_name,
Customer.target_volume.field.verbose_name,
Customer.problematic.field.verbose_name,
),
)
Аргумент columns определяет отображаемые столбцы таблицы, таким образом можно использовать один экземпляр DataFrame в различных сценариях вывода, когда требуется ограничить количество отображаемой информации (например для отправки таблицы в email).
С помощью аргумента classes можно определять css классы html элемента <table> и гибко управлять отображением таблицы с помощью css-правил. В приведённом примере я использую готовые стили css-библиотеки Bootstrap 5 для быстрой стилизации таблицы. Таким образом можно получить результат соотвтветсвующий стилю вашего проекта.
✅ Логика рендеринга объектов инкапсулирется в соответствующие классы
✅ Возможность изменения структуры таблиц без редактирования html шаблонов
❌ Ограниченные возможности контроля рендеринга html и стилизации
Код проекта из этого раздела доступен на GitHub - commit# 8108dd0.
Используем Styler
В предыдущем разделе мы получили html код, позволяющий отобразить удобочитаемую таблицу. Но чаще всего задачи разработки требуют более широкого контроля над процессом server-side рендеринга.
Класс Styler - это инcтрумент для гибкого контроля над процессом экспорта структур данных Pandas в различные сторонние форматы. Помимо рендеринга html, класс Styler позволяет экспортировать данные в формат Excel и др. Это весьма удобно, ведь в практике автоматизации бизнес-задач часто необходима возможность представления данных как в html так и в формате xlsx и др.
# views.py
# class CustomerListView(ListView):
def get_html_table(queryset: QuerySet) -> str:
df = pd.DataFrame(
data=queryset.values_list(),
columns=[field.verbose_name for field in queryset.model._meta.get_fields()],
)
columns = ('id', 'status', 'name', 'source', 'target_volume', 'problematic') # Список отображаемых столбцов
styler = Styler(df)
styler.format(na_rep='-')
styler.hide(axis='index')
styler.hide(
subset=[field.verbose_name for field in Customer._meta.get_fields() if field.name not in columns],
axis='columns',
)
return styler.to_html(table_attributes='class="table table-striped table-hover"')
Обновлённый метод возвращает идентичную таблицу, но может показаться немного более сложным по сравнению с тем, что мы использовали ранее. Несмотря на это, такой вариант является более предпочтительным, т.к. даёт намного больше возможностей контроля, в чём мы убедимся далее.
Конструктор класса Styler принимает в качестве обязательного аргумента DataFrame Pandas. После инициализации объект класса предоставляет широкий набор инструментов стилизации. C полным перечнем методов класса Styler вы можете ознакомиться в соответствующем разделе документации.
✅ Логика рендеринга объектов инкапсулирется в соответствующие классы
✅ Возможность изменения структуры таблиц без редактирования html шаблонов
🟨 Широкие, но ограниченные возможности контроля рендеринга html и стилизации
Код проекта из этого раздела доступен на GitHub - commit# 8ad47cc.
Препарируем Styler
Мы достигли определённого прогресса в деле оптимизации подхода к рендеренгу табличных данных в html. А теперь переходим к наиболее интересной части, в которой мы немного погрузимся в исходный код Pandas.
Перед этим поставим задачу - отрендерить чуть более интерактивную html-таблицу. Сделаем так, чтобы при клике на строку таблицы, которая по сути является представлением объекта ORM, открывалась страница с подробной информацией об объекте.
Под капотом Pandas использует стандартный для индустрии подход с использованием популярного шаблонизатора Jinja2. Посмотрим на шаблоны Jinja2 использующиеся для рендеренга html. Шаблоны используемые для вывода данных хранятся в модуле Pandas io.formats, папка templates. Таким образом, интересующий нас шаблон html_table.tpl можно найти в следующей дирктории:Pyhton/Lib/site-packages/pandas/io/formats/templates/html_table.tpl, где Python - директория установки вашего интерпретатора Python.
# venv/Lib/site-packages/pandas/io/formats/templates/html_table.tpl
...
{% block tr scoped %}
<tr>
{% if exclude_styles %}
{% for c in r %}{% if c.is_visible != False %}
<{{c.type}} {{c.attributes}}>{{c.display_value}}</{{c.type}}>
{% endif %}{% endfor %}
{% else %}
{% for c in r %}{% if c.is_visible != False %}
<{{c.type}} {%- if c.id is defined %} id="T_{{uuid}}_{{c.id}}" {%- endif %} class="{{c.class}}" {{c.attributes}}>{{c.display_value}}</{{c.type}}>
{% endif %}{% endfor %}
{% endif %}
</tr>
{% endblock tr %}
...
Для краткости, выше приведён только фрагмент файла html_table.tpl отвечающий за рендер элемента <tr>. Именно с этим блоком нам предстоит поработать, если мы хотим сделать строки таблицы кликабельными. Из приведённого фрагмента видно, что разработчики Pandas не предусмотрели возможность прямо добавлять атрибуты для html-элемента <tr>, поэтому нам предстоит создать свой шаблон html_table.tpl расширяющий существующий и, используя механизм наследования шаблонов Jinja2, переопределить блок {% block tr scoped %}:
# sales/templates/pandas/html_table.tpl
{% extends 'venv/Lib/site-packages/pandas/io/formats/templates/html_table.tpl' %}
{% block tr scoped %}
<tr {{ tr_attributes }}> <!-- customized element -->
{% if exclude_styles %}
{% for c in r %}{% if c.is_visible != False %}
<{{c.type}} {{c.attributes}}>{{c.display_value}}</{{c.type}}>
{% endif %}{% endfor %}
{% else %}
{% for c in r %}{% if c.is_visible != False %}
<{{c.type}} {%- if c.id is defined %} id="T_{{uuid}}_{{c.id}}" {%- endif %} class="{{c.class}}" {{c.attributes}}>{{c.display_value}}</{{c.type}}>
{% endif %}{% endfor %}
{% endif %}
</tr>
{% endblock tr %}
{% block after_table %}
{{ super() }}
<script>
function openDetailView($tr) {
let pk = $tr.find('td.col0').text();
window.location = `/sales/customer/${pk}/detail`;
}
</script>
{% endblock after_table %}
Новый шаблон html_table.tpl расширяет стандартный шаблон Pandas. Блок {% block tr scoped %} переопределяет аналогичный блок из стандарного шаблона и даёт возможность добавлять атрибуты для html-элемента <tr> передавая соответствующую переменную в контекст рендеринга. Далее мы добавляем функцию JavaScript, которая должна вызываться при клике на строку таблицы и перенаправлять пользователя на соответствующую страницу.
Теперь создадим кастомный класс-стайлер, который будет использовать новый шаблон, и непосредственно определим атрибут onclick элемента <tr>:
# views.py
# class CustomerListView(ListView):
def get_html_table(queryset: QuerySet) -> str:
df = pd.DataFrame(
data=queryset.values_list(),
columns=[field.verbose_name for field in queryset.model._meta.get_fields()],
)
columns = ('id', 'status', 'name', 'source', 'target_volume', 'problematic') # Список отображаемых столбцов
CustomStyler = Styler.from_custom_template(
searchpath=BASE_DIR,
html_table='sales/templates/pandas/html_table.tpl'
)
styler = CustomStyler(df)
styler.format(na_rep='-')
styler.hide(axis='index')
styler.hide(
subset=[field.verbose_name for field in Customer._meta.get_fields() if field.name not in columns],
axis='columns',
)
return styler.to_html(
table_attributes='class="table table-striped table-hover"',
tr_attributes=f'onclick="openDetailView($(this))" style="cursor:pointer;"',
)
Класс Styler предоставляет специальный метод - from_custom_template(), который возвращает новый класс - MyStyler. Новый класс наследуется от стандартного Styler, но обладает атрибутами класса определяющими кастомное окружение и шаблоны Jinja2.
Теперь стайлер использует для рендеринга новый шаблон, который позволяет использовать переменную tr_attributes, передаём ее в контекст шаблонизатора через именованный аргумент метода Styler.to_html().
Используя переменную tr_attributes мы добавляем атрибуты onclick и style всем элементам <tr> нашей таблицы.
Первый атрибут определяет поведение браузера при клике на строку. В нашем случае вызывается упомянутая выше функция - openDetailView($tr). При этом в качестве аргумента функции передаётся сам DOM-объект, для удобства обёрнутый в jQuery-селектор (я использую JavaScript библиотеку jQuery для краткости и повышения читаемости кода, хотя это не обязательно).
Атрибут style, в нашем случае, обеспечивает правильное поведение указателя мыши при наведении на кликабельный объект.
Таким образом, мы достигли желаемого результата: клик по строке таблицы перенаправляет нас на страницу с детальной информацией об объекте.
✅ Логика рендеринга объектов инкапсулирется в соответствующие классы
✅ Возможность изменения структуры таблиц без редактирования html шаблонов
✅ Не ограниченные возможности контроля рендеринга html и стилизации
Код проекта из этого раздела доступен на GitHub - commit#.
Заключение
Цель этого материала продемострировать функционал Pandas, который часто обходят вниманием. Описанный функционал особенно удобно использовать когда одни и те же данные необходимо представлять сразу в разных форматах, ведь пандосовский DataFrame, с помощью обёртки Styler, также легко экспортировать, например, в Excel. Аналогично примеру описанному в статье, можно реализовать практически любую задумку, например, добавить сортировку данных при клике на хедер и т.д. Хотя, во многих случаях, достаточно использования стандартных возможностей Styler.
Напишите в комментариях, интересные и нестандартные кейсы применения библиотеки Pandas :)
