Python API
djlint.api форматирует и проверяет текст из программы на Python и даёт те же результаты, что и командная строка. Он предназначен для редакторов, инструментов сборки и всего остального, что держит шаблон в памяти. Всё остальное в пакете может измениться в любом релизе, поэтому используйте этот модуль, а не djlint.settings или djlint.lint. Вспомогательные функции, которые импортирует пример пользовательского правила, djlint.lint.get_line, djlint.helpers.inside_ignored_rule и djlint.helpers.inside_ignored_linter_block, тоже продолжат работать.
from djlint.api import format_text, lint_text, load_config
config = load_config("templates", profile="django", indent=2)
formatted = format_text(config, "<div><p>hi</p></div>")
for finding in lint_text(config, '<img src="a.png">', "templates/home.html"): print(finding.line, finding.column, finding.code, finding.message)load_config
Заголовок раздела «load_config»load_config(folder=".", *, python_rules=True, on_warning=None, **options) читает конфигурацию, которая действует для файлов папки. Он ищет её вверх от этой папки, как командная строка ищет от первого переданного пути, и не меняет текущий каталог.
Параметры называются так же, как параметры командной строки, только с подчёркиваниями, и работают так же: заданное значение важнее файла конфигурации, а False, пустая строка и, для большинства параметров, 0 считаются не заданными. Пути передаются как pathlib.Path.
Чтение конфигурации занимает некоторое время, поэтому храните результат, пока не изменятся файлы, из которых она прочитана. Его можно использовать для любого количества текстов.
С python_rules=False пользовательские правила с python_module не загружаются, поэтому код проекта, которому вы не доверяете, не запускается. Их имена находятся в config.skipped_rules.
on_warning, функция, принимающая сообщение, получает каждое предупреждение о настройках, например об опечатке в имени или о коде, которого нет ни у одного правила. Без неё каждое предупреждение выводится в stderr один раз за процесс. Файл конфигурации, который не удалось прочитать, или недопустимое значение вызывают click.UsageError.
format_text
Заголовок раздела «format_text»format_text(config, text) возвращает отформатированный текст. Текст, первая строка которого заканчивается на CRLF, возвращается с CRLF, а любой другой с LF. С require_pragma текст без прагмы возвращается без изменений. Если ни параметры load_config, ни файл конфигурации не задают indent или max_line_length, функция берёт их из секций .editorconfig, которые действуют для файла с заданным в конфигурации расширением в папке, переданной в load_config, а командная строка берёт их для каждого файла по его пути.
lint_text
Заголовок раздела «lint_text»lint_text(config, text, filename="-") возвращает список Finding в том порядке, в каком они встречаются в документе. С filename сопоставляется per-file-ignores. С require_pragma у текста без прагмы замечаний нет.
Finding — именованный кортеж со следующими полями:
code: код правила, напримерH013.message: что сообщает правило.match: начало найденного текста, не более 20 символов.line,column: где начинается замечание. Строки считаются с 1, а столбцы — с 0.end_line,end_column: позиция сразу за его концом; она может оказаться на одной из следующих строк.
Столбцы считаются в символах, а не в байтах или кодовых единицах UTF-16.
is_excluded
Заголовок раздела «is_excluded»is_excluded(config, path) сообщает, исключают ли файл exclude, extend_exclude или gitignore, так же как это делает командная строка. Сами format_text и lint_text этого не проверяют.
Модули правил
Заголовок раздела «Модули правил»python_module пользовательского правила импортируется один раз за процесс, из корня проекта, к которому относится конфигурация. Чтобы прочитать правила другого проекта, долго работающая программа должна удалить из sys.modules всё, что импортировала из первого проекта, и убрать корень этого проекта из конца sys.path.