API Python
djlint.api formatta e analizza testo da un programma Python, con gli stessi risultati della riga di comando. È pensato per editor, strumenti di build e qualsiasi altra cosa che tenga un template in memoria. Tutto il resto del pacchetto può cambiare in qualsiasi release, quindi usa questo modulo anziché djlint.settings o djlint.lint. Continuano a funzionare anche gli helper che importa l’esempio di regola personalizzata: djlint.lint.get_line, djlint.helpers.inside_ignored_rule e 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
Sezione intitolata “load_config”load_config(folder=".", *, python_rules=True, on_warning=None, **options) legge la configurazione che si applica ai file di una cartella. La cerca risalendo a partire dalla cartella, come fa la riga di comando a partire dal primo percorso che riceve, e non cambia la directory corrente.
Le opzioni usano i nomi delle opzioni della riga di comando, con i trattini bassi, e funzionano allo stesso modo: un valore impostato ha la precedenza sul file di configurazione, mentre False, una stringa vuota e, per la maggior parte delle opzioni, 0 contano come non specificati. I percorsi si passano come pathlib.Path.
La lettura della configurazione richiede un po’ di tempo, quindi conserva il risultato finché i file da cui è stata letta non cambiano. Si può usare per un numero qualsiasi di testi.
Con python_rules=False, le regole personalizzate con un python_module non vengono caricate, il che impedisce l’esecuzione del codice di un progetto di cui non ti fidi. I loro nomi si trovano in config.skipped_rules.
on_warning, una funzione che riceve un messaggio, riceve ogni avviso sulle impostazioni, come un nome scritto male o un codice che non corrisponde a nessuna regola. Senza di essa, ogni avviso va su stderr una volta per processo. Un file di configurazione che non si riesce a leggere, o un valore non valido, solleva click.UsageError.
format_text
Sezione intitolata “format_text”format_text(config, text) restituisce il testo formattato. Un testo la cui prima riga termina con CRLF viene restituito con CRLF, qualsiasi altro con LF. Con require_pragma, un testo senza il pragma viene restituito invariato. Se né le opzioni di load_config né il file di configurazione impostano indent o max_line_length, li prende dalle sezioni del .editorconfig che si applicano a un file dell’estensione configurata nella cartella passata a load_config, mentre la riga di comando li prende per ogni file in base al suo percorso.
lint_text
Sezione intitolata “lint_text”lint_text(config, text, filename="-") restituisce una lista di Finding, nell’ordine del documento. filename è ciò con cui viene confrontato per-file-ignores. Con require_pragma, un testo senza il pragma non ha segnalazioni.
Finding è una named tuple con questi campi:
code: il codice della regola, ad esempioH013.message: ciò che dice la regola.match: l’inizio del testo trovato, fino a 20 caratteri.line,column: dove inizia la segnalazione. Le righe si contano da 1 e le colonne da 0.end_line,end_column: subito dopo il punto in cui finisce, che può trovarsi su una riga successiva.
Le colonne contano i caratteri, non i byte né le unità di codice UTF-16.
is_excluded
Sezione intitolata “is_excluded”is_excluded(config, path) indica se exclude, extend_exclude o il gitignore escludono un file, come fa la riga di comando. format_text e lint_text non effettuano questo controllo da sé.
Moduli delle regole
Sezione intitolata “Moduli delle regole”Il python_module di una regola personalizzata viene importato una volta per processo, dalla radice del progetto della configurazione. Per leggere le regole di un altro progetto, un programma che resta in esecuzione deve rimuovere da sys.modules tutto ciò che ha importato dal primo progetto, e togliere la radice di quel progetto dalla fine di sys.path.