Python API

djlint.api форматирует и проверяет текст из программы на Python с теми же результатами, что и командная строка. Он предназначен для редакторов, инструментов сборки и всего, что держит шаблон в памяти. Всё остальное в пакете может измениться в любом выпуске, поэтому используйте этот модуль, а не djlint.settings или djlint.lint.

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(folder=".", *, python_rules=True, **options) читает конфигурацию, которая действует для файлов папки. Поиск идёт вверх от этой папки, как у командной строки от текущего каталога, а сам текущий каталог не меняется.

Опции называются как в командной строке, с подчёркиваниями, и работают так же: заданное значение важнее файла конфигурации, а False, пустая строка и, для большинства опций, 0 считаются незаданными. Пути передаются как pathlib.Path.

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

С python_rules=False пользовательские правила с python_module не загружаются, поэтому код проекта, которому вы не доверяете, не запускается. Их имена находятся в config.skipped_rules.

format_text

format_text(config, text) возвращает отформатированный текст. Текст, первая строка которого заканчивается на CRLF, возвращается в CRLF, любой другой в LF. С require_pragma текст без прагмы возвращается без изменений.

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.

Модули правил

python_module пользовательского правила импортируется один раз на процесс, из корня проекта этой конфигурации. Программе, которая работает долго и с несколькими проектами, нужно удалить из sys.modules всё импортированное из проекта, а также корень проекта, который остаётся в конце sys.path, чтобы прочитать модуль другого проекта.