documentation-checker 0.1.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- documentation_checker/__init__.py +9 -0
- documentation_checker/__main__.py +7 -0
- documentation_checker/audit/__init__.py +7 -0
- documentation_checker/audit/accessibility.py +481 -0
- documentation_checker/audit/engine.py +136 -0
- documentation_checker/audit/images.py +416 -0
- documentation_checker/audit/links.py +224 -0
- documentation_checker/audit/prose.py +475 -0
- documentation_checker/audit/sides.py +234 -0
- documentation_checker/audit/spelling.py +433 -0
- documentation_checker/audit/structure.py +864 -0
- documentation_checker/audit/style.py +208 -0
- documentation_checker/audit/text.py +428 -0
- documentation_checker/audit/typography.py +597 -0
- documentation_checker/cli.py +413 -0
- documentation_checker/compare/__init__.py +2 -0
- documentation_checker/compare/aggregate.py +234 -0
- documentation_checker/compare/align.py +1062 -0
- documentation_checker/compare/classify.py +452 -0
- documentation_checker/compare/drafts.py +161 -0
- documentation_checker/compare/engine.py +833 -0
- documentation_checker/compare/images.py +1007 -0
- documentation_checker/compare/links.py +370 -0
- documentation_checker/compare/structure.py +376 -0
- documentation_checker/compare/textdiff.py +369 -0
- documentation_checker/compare/verdicts.py +185 -0
- documentation_checker/config.py +736 -0
- documentation_checker/errors.py +18 -0
- documentation_checker/extract/__init__.py +6 -0
- documentation_checker/extract/common.py +387 -0
- documentation_checker/extract/html/__init__.py +6 -0
- documentation_checker/extract/html/chrome.py +46 -0
- documentation_checker/extract/html/css.py +87 -0
- documentation_checker/extract/html/dom.py +762 -0
- documentation_checker/extract/html/facts.py +374 -0
- documentation_checker/extract/html/images.py +511 -0
- documentation_checker/extract/html/links.py +379 -0
- documentation_checker/extract/html/loader.py +616 -0
- documentation_checker/extract/html/ordering.py +167 -0
- documentation_checker/extract/html/profiles.py +291 -0
- documentation_checker/extract/html/site.py +225 -0
- documentation_checker/extract/loader.py +93 -0
- documentation_checker/extract/pdf/__init__.py +6 -0
- documentation_checker/extract/pdf/blocks.py +747 -0
- documentation_checker/extract/pdf/catalog.py +52 -0
- documentation_checker/extract/pdf/chrome.py +778 -0
- documentation_checker/extract/pdf/figures.py +1113 -0
- documentation_checker/extract/pdf/headings.py +339 -0
- documentation_checker/extract/pdf/joining.py +323 -0
- documentation_checker/extract/pdf/kinds.py +312 -0
- documentation_checker/extract/pdf/layout.py +334 -0
- documentation_checker/extract/pdf/loader.py +1140 -0
- documentation_checker/extract/pdf/reader.py +2059 -0
- documentation_checker/extract/pdf/segments.py +248 -0
- documentation_checker/extract/pdf/table_blocks.py +784 -0
- documentation_checker/extract/pdf/table_process.py +292 -0
- documentation_checker/extract/pdf/table_work.py +559 -0
- documentation_checker/extract/pdf/tables.py +549 -0
- documentation_checker/extract/pdf/tags.py +838 -0
- documentation_checker/images/__init__.py +2 -0
- documentation_checker/images/hashing.py +181 -0
- documentation_checker/images/load.py +737 -0
- documentation_checker/images/metrics.py +581 -0
- documentation_checker/images/objects.py +111 -0
- documentation_checker/images/pixels.py +330 -0
- documentation_checker/images/refs.py +285 -0
- documentation_checker/images/streams.py +371 -0
- documentation_checker/images/svg.py +344 -0
- documentation_checker/images/thumbnail.py +73 -0
- documentation_checker/model/__init__.py +2 -0
- documentation_checker/model/document.py +348 -0
- documentation_checker/model/facts.py +146 -0
- documentation_checker/model/findings.py +217 -0
- documentation_checker/pipeline.py +442 -0
- documentation_checker/report/__init__.py +2 -0
- documentation_checker/report/context.py +530 -0
- documentation_checker/report/html.py +152 -0
- documentation_checker/report/markdown.py +350 -0
- documentation_checker/report/templates/report.css +301 -0
- documentation_checker/report/templates/report.html.j2 +170 -0
- documentation_checker/report/templates/report.js +36 -0
- documentation_checker/report/templates/report.md.j2 +110 -0
- documentation_checker/report/terminal.py +260 -0
- documentation_checker/rules.py +429 -0
- documentation_checker/spell/__init__.py +2 -0
- documentation_checker/spell/data/fr/LICENSE +373 -0
- documentation_checker/spell/data/fr/README_dict_fr.txt +67 -0
- documentation_checker/spell/data/fr/SOURCE.txt +16 -0
- documentation_checker/spell/data/fr/fr-toutesvariantes.aff +6596 -0
- documentation_checker/spell/data/fr/fr-toutesvariantes.dic +87073 -0
- documentation_checker/spell/dictionary.py +88 -0
- documentation_checker/spell/speller.py +412 -0
- documentation_checker/spell/words.py +377 -0
- documentation_checker/text/__init__.py +2 -0
- documentation_checker/text/lang.py +204 -0
- documentation_checker/text/lexicon.py +200 -0
- documentation_checker/text/normalize.py +229 -0
- documentation_checker/text/numbers.py +81 -0
- documentation_checker/text/tokenize.py +70 -0
- documentation_checker-0.1.0.dist-info/METADATA +1049 -0
- documentation_checker-0.1.0.dist-info/RECORD +106 -0
- documentation_checker-0.1.0.dist-info/WHEEL +4 -0
- documentation_checker-0.1.0.dist-info/entry_points.txt +3 -0
- documentation_checker-0.1.0.dist-info/licenses/LICENSE +202 -0
- documentation_checker-0.1.0.dist-info/licenses/THIRD_PARTY_NOTICES.md +71 -0
- documentation_checker-0.1.0.dist-info/licenses/src/documentation_checker/spell/data/fr/LICENSE +373 -0
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
# Copyright 2026 Christophe Le Douarec
|
|
2
|
+
"""Audit of a single document: its structure, its links, its accessibility.
|
|
3
|
+
|
|
4
|
+
`audit_document` of `documentation_checker.audit.engine` runs the families of
|
|
5
|
+
checks that the configuration asks for, and finalizes their drafts as `compare`
|
|
6
|
+
does.
|
|
7
|
+
"""
|
|
@@ -0,0 +1,481 @@
|
|
|
1
|
+
# Copyright 2026 Christophe Le Douarec
|
|
2
|
+
"""Check the accessibility of a document.
|
|
3
|
+
|
|
4
|
+
A PDF without a structure tree, one that does not declare a tag structure
|
|
5
|
+
or whose catalog has no ``/StructTreeRoot``, is untagged; a tree that was
|
|
6
|
+
read in part, or not at all for another reason, is not. A PDF declares its
|
|
7
|
+
language in its catalog and its title in its metadata; an HTML page, its
|
|
8
|
+
language in the ``lang`` of its ``html`` element, which has to be a
|
|
9
|
+
language tag, and its title in its head. A document that declares French
|
|
10
|
+
or English, but whose prose, its first `LANG_SAMPLE_BLOCKS` blocks of
|
|
11
|
+
`PROSE_KINDS`, plainly reads as the other language, as `strong_language`
|
|
12
|
+
tells, has a language mismatch. The characters of a PDF without a Unicode
|
|
13
|
+
mapping give one finding, at the first page that has some, which is major
|
|
14
|
+
from a share of the characters of the document; each scanned page gives
|
|
15
|
+
one.
|
|
16
|
+
|
|
17
|
+
An image of an HTML page needs an alternative text, an inline SVG a title
|
|
18
|
+
or a label, and an alternative text that is a file name, `FILE_NAME_ALT`,
|
|
19
|
+
says nothing; an empty alternative text marks a decorative image. Each
|
|
20
|
+
``Figure`` of the structure tree of a PDF needs a ``/Alt`` or an
|
|
21
|
+
``/ActualText``, and its ``/Alt`` is no file name; each ``Table`` of the
|
|
22
|
+
tree, like each table of the content of an HTML page, needs a header cell.
|
|
23
|
+
The image blocks of a PDF, whose alternative texts the tree holds, are not
|
|
24
|
+
judged by themselves.
|
|
25
|
+
|
|
26
|
+
A link of the content of an HTML page needs a name, and the text of a link
|
|
27
|
+
of a block, or under a link annotation of a PDF, has to tell where the link
|
|
28
|
+
leads: a text of `GENERIC_LINK_TEXTS`, compared by its loose key, does not.
|
|
29
|
+
|
|
30
|
+
The texts of the document that a detail quotes are cut.
|
|
31
|
+
"""
|
|
32
|
+
|
|
33
|
+
import re
|
|
34
|
+
from collections import Counter
|
|
35
|
+
from itertools import islice
|
|
36
|
+
from typing import TYPE_CHECKING, Final
|
|
37
|
+
|
|
38
|
+
from documentation_checker.audit.sides import LinkMarks, quote
|
|
39
|
+
from documentation_checker.compare.drafts import Draft, marked_side
|
|
40
|
+
from documentation_checker.images.refs import describe
|
|
41
|
+
from documentation_checker.model.document import BlockKind, SourceRef
|
|
42
|
+
from documentation_checker.model.facts import NO_STRUCTURE_TREE
|
|
43
|
+
from documentation_checker.model.findings import Severity
|
|
44
|
+
from documentation_checker.text.lang import (
|
|
45
|
+
LANG_SAMPLE_BLOCKS,
|
|
46
|
+
LANGUAGE_NAMES,
|
|
47
|
+
declared_language,
|
|
48
|
+
strong_language,
|
|
49
|
+
)
|
|
50
|
+
from documentation_checker.text.normalize import (
|
|
51
|
+
ELLIPSIS,
|
|
52
|
+
loose_key,
|
|
53
|
+
normalize_display,
|
|
54
|
+
printable,
|
|
55
|
+
strict_key,
|
|
56
|
+
)
|
|
57
|
+
|
|
58
|
+
if TYPE_CHECKING:
|
|
59
|
+
from documentation_checker.config import AuditThresholds
|
|
60
|
+
from documentation_checker.model.document import Block, Document
|
|
61
|
+
from documentation_checker.model.facts import HtmlPageFacts, TaggedElement
|
|
62
|
+
from documentation_checker.model.findings import Side
|
|
63
|
+
|
|
64
|
+
FILE_NAME_ALT: Final = re.compile(
|
|
65
|
+
r"(?i)^[\w\-./\\]+\.(?:png|jpe?g|gif|svg|webp|bmp|tiff?|pdf|eps|avif)$",
|
|
66
|
+
)
|
|
67
|
+
GENERIC_LINK_TEXTS: Final = frozenset(
|
|
68
|
+
{
|
|
69
|
+
"click here",
|
|
70
|
+
"here",
|
|
71
|
+
"click",
|
|
72
|
+
"read more",
|
|
73
|
+
"learn more",
|
|
74
|
+
"more",
|
|
75
|
+
"this link",
|
|
76
|
+
"link",
|
|
77
|
+
"this page",
|
|
78
|
+
"cliquez ici",
|
|
79
|
+
"ici",
|
|
80
|
+
"cliquer ici",
|
|
81
|
+
"lire la suite",
|
|
82
|
+
"en savoir plus",
|
|
83
|
+
"ce lien",
|
|
84
|
+
"lien",
|
|
85
|
+
"cette page",
|
|
86
|
+
},
|
|
87
|
+
)
|
|
88
|
+
# The blocks whose text tells the language of a document: headings,
|
|
89
|
+
# paragraphs, items, captions, quotes and admonitions.
|
|
90
|
+
PROSE_KINDS: Final = frozenset(
|
|
91
|
+
{
|
|
92
|
+
BlockKind.HEADING,
|
|
93
|
+
BlockKind.PARAGRAPH,
|
|
94
|
+
BlockKind.LIST_ITEM,
|
|
95
|
+
BlockKind.CAPTION,
|
|
96
|
+
BlockKind.QUOTE,
|
|
97
|
+
BlockKind.ADMONITION,
|
|
98
|
+
},
|
|
99
|
+
)
|
|
100
|
+
UNMAPPED_PAGES_SHOWN: Final = 10
|
|
101
|
+
|
|
102
|
+
_UNTAGGED: Final = "a11y.pdf_untagged"
|
|
103
|
+
_LANG_MISSING: Final = "a11y.lang_missing"
|
|
104
|
+
_LANG_MISMATCH: Final = "a11y.lang_mismatch"
|
|
105
|
+
_TITLE_MISSING: Final = "a11y.title_missing"
|
|
106
|
+
_UNMAPPED: Final = "a11y.unmapped_chars"
|
|
107
|
+
_SCANNED: Final = "a11y.scanned_page"
|
|
108
|
+
_ALT_MISSING: Final = "a11y.alt_missing"
|
|
109
|
+
_ALT_FILENAME: Final = "a11y.alt_filename"
|
|
110
|
+
_SVG_TITLE: Final = "a11y.svg_title"
|
|
111
|
+
_TABLE_HEADERS: Final = "a11y.table_headers"
|
|
112
|
+
_LINK_EMPTY: Final = "a11y.link_empty"
|
|
113
|
+
_LINK_TEXT: Final = "a11y.link_text"
|
|
114
|
+
|
|
115
|
+
_NO_TREE: Final = (
|
|
116
|
+
"the PDF has no structure tree: assistive technologies read it without"
|
|
117
|
+
" headings, lists, tables or figures"
|
|
118
|
+
)
|
|
119
|
+
_FILE_NAME: Final = "file name"
|
|
120
|
+
_SUBTAG: Final = "-"
|
|
121
|
+
_MORE_PAGES: Final = f", {ELLIPSIS}"
|
|
122
|
+
|
|
123
|
+
|
|
124
|
+
def _link_key(text: str) -> str:
|
|
125
|
+
"""Return the loose key of the text of a link."""
|
|
126
|
+
counter: Counter[str] = Counter()
|
|
127
|
+
return loose_key(strict_key(normalize_display(text, counter), counter))
|
|
128
|
+
|
|
129
|
+
|
|
130
|
+
def _document_side(doc: Document) -> Side:
|
|
131
|
+
"""Return the side of a finding about the whole document.
|
|
132
|
+
|
|
133
|
+
It shows the name of a PDF, or the first page of a site.
|
|
134
|
+
"""
|
|
135
|
+
name = doc.parts[0] if doc.format == "html" and doc.parts else ""
|
|
136
|
+
name = name or doc.path.name
|
|
137
|
+
return marked_side(SourceRef(name), printable(name))
|
|
138
|
+
|
|
139
|
+
|
|
140
|
+
def _is_untagged(doc: Document) -> bool:
|
|
141
|
+
"""Return whether a PDF has no structure tree.
|
|
142
|
+
|
|
143
|
+
A tree that was not read, or read in part, for another reason, such as
|
|
144
|
+
encryption or a budget, is no proof that the PDF is untagged.
|
|
145
|
+
"""
|
|
146
|
+
tags = doc.tags
|
|
147
|
+
return doc.tagged is False or (
|
|
148
|
+
tags is not None and tags.problem == NO_STRUCTURE_TREE
|
|
149
|
+
)
|
|
150
|
+
|
|
151
|
+
|
|
152
|
+
def prose_sample(doc: Document) -> str:
|
|
153
|
+
"""Return the prose whose text tells the language of a document.
|
|
154
|
+
|
|
155
|
+
Args:
|
|
156
|
+
doc: The document.
|
|
157
|
+
|
|
158
|
+
Returns:
|
|
159
|
+
The texts of its first `LANG_SAMPLE_BLOCKS` blocks of `PROSE_KINDS`,
|
|
160
|
+
joined by spaces.
|
|
161
|
+
"""
|
|
162
|
+
return " ".join(
|
|
163
|
+
islice(
|
|
164
|
+
(block.text for block in doc.blocks if block.kind in PROSE_KINDS),
|
|
165
|
+
LANG_SAMPLE_BLOCKS,
|
|
166
|
+
),
|
|
167
|
+
)
|
|
168
|
+
|
|
169
|
+
|
|
170
|
+
def _language_mismatch(doc: Document, side: Side) -> Draft | None:
|
|
171
|
+
"""Return the draft of a document whose prose reads as another language.
|
|
172
|
+
|
|
173
|
+
Args:
|
|
174
|
+
doc: The audited document.
|
|
175
|
+
side: The side of a finding about the whole document.
|
|
176
|
+
|
|
177
|
+
Returns:
|
|
178
|
+
The draft when the document declares French or English and its
|
|
179
|
+
`prose_sample` plainly reads as the other language; else ``None``.
|
|
180
|
+
"""
|
|
181
|
+
declared = doc.declared_lang
|
|
182
|
+
if declared is None:
|
|
183
|
+
return None
|
|
184
|
+
primary = declared.partition(_SUBTAG)[0].casefold()
|
|
185
|
+
if primary not in LANGUAGE_NAMES:
|
|
186
|
+
return None
|
|
187
|
+
found = strong_language(prose_sample(doc))
|
|
188
|
+
if found is None or found == primary:
|
|
189
|
+
return None
|
|
190
|
+
detail = (
|
|
191
|
+
f'the document declares "{quote(declared)}" but its text reads as'
|
|
192
|
+
f" {LANGUAGE_NAMES[found]}"
|
|
193
|
+
)
|
|
194
|
+
return Draft(_LANG_MISMATCH, None, side, None, detail)
|
|
195
|
+
|
|
196
|
+
|
|
197
|
+
def _unmapped(doc: Document, thresholds: AuditThresholds) -> Draft | None:
|
|
198
|
+
"""Return the draft of the characters of a PDF without Unicode mapping.
|
|
199
|
+
|
|
200
|
+
Args:
|
|
201
|
+
doc: The PDF.
|
|
202
|
+
thresholds: Thresholds of the audit.
|
|
203
|
+
|
|
204
|
+
Returns:
|
|
205
|
+
One draft at the first page with such characters, which counts them
|
|
206
|
+
and lists the labels of the first `UNMAPPED_PAGES_SHOWN` pages that
|
|
207
|
+
have some; major when they reach ``unmapped_major`` of the
|
|
208
|
+
characters of the document. ``None`` without such characters.
|
|
209
|
+
"""
|
|
210
|
+
touched = [page for page in doc.pdf_pages if page.unmapped]
|
|
211
|
+
if not touched:
|
|
212
|
+
return None
|
|
213
|
+
total = sum(page.unmapped for page in touched)
|
|
214
|
+
chars = sum(page.chars for page in doc.pdf_pages)
|
|
215
|
+
labels = ", ".join(
|
|
216
|
+
quote(page.label) for page in touched[:UNMAPPED_PAGES_SHOWN]
|
|
217
|
+
)
|
|
218
|
+
if len(touched) > UNMAPPED_PAGES_SHOWN:
|
|
219
|
+
labels += _MORE_PAGES
|
|
220
|
+
severity = (
|
|
221
|
+
Severity.MAJOR if total >= thresholds.unmapped_major * chars else None
|
|
222
|
+
)
|
|
223
|
+
source = SourceRef(doc.path.name, page=touched[0].number)
|
|
224
|
+
detail = (
|
|
225
|
+
f"{total} of {chars} characters have no Unicode mapping,"
|
|
226
|
+
f" on page(s) {labels}"
|
|
227
|
+
)
|
|
228
|
+
side = marked_side(source, printable(doc.path.name))
|
|
229
|
+
return Draft(_UNMAPPED, severity, side, None, detail)
|
|
230
|
+
|
|
231
|
+
|
|
232
|
+
def _document_drafts(
|
|
233
|
+
doc: Document,
|
|
234
|
+
thresholds: AuditThresholds,
|
|
235
|
+
) -> list[Draft]:
|
|
236
|
+
"""Return the drafts about the whole document.
|
|
237
|
+
|
|
238
|
+
Returns:
|
|
239
|
+
For a PDF, its missing tree, its missing language, a language
|
|
240
|
+
mismatch, its missing title and its unmapped characters; for a site,
|
|
241
|
+
a language mismatch.
|
|
242
|
+
"""
|
|
243
|
+
side = _document_side(doc)
|
|
244
|
+
mismatch = _language_mismatch(doc, side)
|
|
245
|
+
if doc.format != "pdf":
|
|
246
|
+
return [] if mismatch is None else [mismatch]
|
|
247
|
+
drafts: list[Draft] = []
|
|
248
|
+
if _is_untagged(doc):
|
|
249
|
+
drafts.append(Draft(_UNTAGGED, None, side, None, _NO_TREE))
|
|
250
|
+
if doc.declared_lang is None:
|
|
251
|
+
detail = "the PDF declares no language"
|
|
252
|
+
drafts.append(Draft(_LANG_MISSING, None, side, None, detail))
|
|
253
|
+
if mismatch is not None:
|
|
254
|
+
drafts.append(mismatch)
|
|
255
|
+
if not doc.title:
|
|
256
|
+
detail = "the PDF has no title in its metadata"
|
|
257
|
+
drafts.append(Draft(_TITLE_MISSING, None, side, None, detail))
|
|
258
|
+
unmapped = _unmapped(doc, thresholds)
|
|
259
|
+
if unmapped is not None:
|
|
260
|
+
drafts.append(unmapped)
|
|
261
|
+
return drafts
|
|
262
|
+
|
|
263
|
+
|
|
264
|
+
def _bare_table(side: Side) -> Draft:
|
|
265
|
+
"""Return the draft of a table without a header cell."""
|
|
266
|
+
detail = "the table has no header cell"
|
|
267
|
+
return Draft(_TABLE_HEADERS, None, side, None, detail, "table")
|
|
268
|
+
|
|
269
|
+
|
|
270
|
+
def _html_page_drafts(page: HtmlPageFacts) -> list[Draft]:
|
|
271
|
+
"""Return the drafts of an HTML page.
|
|
272
|
+
|
|
273
|
+
Returns:
|
|
274
|
+
Its missing or wrong language, its missing title, then its tables
|
|
275
|
+
without header cell and its links without a name, in order.
|
|
276
|
+
"""
|
|
277
|
+
side = marked_side(SourceRef(page.file), printable(page.file))
|
|
278
|
+
drafts: list[Draft] = []
|
|
279
|
+
lang = page.lang or ""
|
|
280
|
+
if not lang.strip():
|
|
281
|
+
detail = "the page declares no language"
|
|
282
|
+
drafts.append(Draft(_LANG_MISSING, None, side, None, detail, "lang"))
|
|
283
|
+
elif declared_language(lang) is None:
|
|
284
|
+
detail = (
|
|
285
|
+
f'the page declares "{quote(lang)}", which is not a language tag'
|
|
286
|
+
)
|
|
287
|
+
drafts.append(Draft(_LANG_MISSING, None, side, None, detail, "lang"))
|
|
288
|
+
if not page.title:
|
|
289
|
+
detail = "the page has no title"
|
|
290
|
+
drafts.append(Draft(_TITLE_MISSING, None, side, None, detail, "title"))
|
|
291
|
+
for spot in page.bare_tables:
|
|
292
|
+
source = SourceRef(page.file, line=spot.line)
|
|
293
|
+
table = marked_side(source, spot.text, kind=BlockKind.TABLE)
|
|
294
|
+
drafts.append(_bare_table(table))
|
|
295
|
+
for spot in page.empty_links:
|
|
296
|
+
link = marked_side(SourceRef(page.file, line=spot.line), spot.text)
|
|
297
|
+
target = quote(spot.text) or '""'
|
|
298
|
+
detail = f"the link to {target} has neither text nor label"
|
|
299
|
+
drafts.append(Draft(_LINK_EMPTY, None, link, None, detail, "empty"))
|
|
300
|
+
return drafts
|
|
301
|
+
|
|
302
|
+
|
|
303
|
+
def _scanned_drafts(doc: Document) -> list[Draft]:
|
|
304
|
+
"""Return one draft for each scanned page of a PDF, shown by its label."""
|
|
305
|
+
return [
|
|
306
|
+
Draft(
|
|
307
|
+
_SCANNED,
|
|
308
|
+
None,
|
|
309
|
+
marked_side(
|
|
310
|
+
SourceRef(doc.path.name, page=page.number),
|
|
311
|
+
f"page {quote(page.label)}",
|
|
312
|
+
),
|
|
313
|
+
None,
|
|
314
|
+
"the page is an image without text",
|
|
315
|
+
"scanned",
|
|
316
|
+
)
|
|
317
|
+
for page in doc.pdf_pages
|
|
318
|
+
if page.scanned
|
|
319
|
+
]
|
|
320
|
+
|
|
321
|
+
|
|
322
|
+
def _image_draft(block: Block) -> Draft | None:
|
|
323
|
+
"""Return the draft of the alternative text of an HTML image, if wrong.
|
|
324
|
+
|
|
325
|
+
Returns:
|
|
326
|
+
For an image without an alternative text, an untitled inline SVG,
|
|
327
|
+
whose format is SVG and which has no name, or else a missing
|
|
328
|
+
alternative text; for one that is a file name, its draft; else
|
|
329
|
+
``None``. An empty alternative text marks a decorative image.
|
|
330
|
+
"""
|
|
331
|
+
image = block.image
|
|
332
|
+
if image is None:
|
|
333
|
+
return None
|
|
334
|
+
side = marked_side(
|
|
335
|
+
block.source,
|
|
336
|
+
describe(image),
|
|
337
|
+
kind=block.kind,
|
|
338
|
+
image=image,
|
|
339
|
+
)
|
|
340
|
+
alt = image.alt
|
|
341
|
+
if alt is None:
|
|
342
|
+
if image.format == "svg" and not image.name:
|
|
343
|
+
detail = "the drawing has no title nor label"
|
|
344
|
+
return Draft(_SVG_TITLE, None, side, None, detail, "svg")
|
|
345
|
+
detail = "the image has no alternative text"
|
|
346
|
+
return Draft(_ALT_MISSING, None, side, None, detail, "img")
|
|
347
|
+
if FILE_NAME_ALT.match(alt):
|
|
348
|
+
detail = f'the alternative text "{quote(alt)}" is a file name'
|
|
349
|
+
return Draft(_ALT_FILENAME, None, side, None, detail, _FILE_NAME)
|
|
350
|
+
return None
|
|
351
|
+
|
|
352
|
+
|
|
353
|
+
def _link_text_draft(side: Side, text: str, key: str) -> Draft:
|
|
354
|
+
"""Return the draft of a link whose text tells nothing.
|
|
355
|
+
|
|
356
|
+
Args:
|
|
357
|
+
side: The side of the link.
|
|
358
|
+
text: The text of the link.
|
|
359
|
+
key: Its loose key, a text of `GENERIC_LINK_TEXTS`, which is the
|
|
360
|
+
pattern of the draft.
|
|
361
|
+
|
|
362
|
+
Returns:
|
|
363
|
+
The draft.
|
|
364
|
+
"""
|
|
365
|
+
detail = f'the text "{quote(text)}" does not tell where the link leads'
|
|
366
|
+
return Draft(_LINK_TEXT, None, side, None, detail, key)
|
|
367
|
+
|
|
368
|
+
|
|
369
|
+
def _block_drafts(doc: Document) -> list[Draft]:
|
|
370
|
+
"""Return the drafts of the blocks, in order.
|
|
371
|
+
|
|
372
|
+
Returns:
|
|
373
|
+
For each block, that of its image, on an HTML page, then that of
|
|
374
|
+
each of its links whose text tells nothing. The text of a link is
|
|
375
|
+
judged first; only a block with a link whose text tells nothing has
|
|
376
|
+
its links placed, as `LinkMarks` does.
|
|
377
|
+
"""
|
|
378
|
+
html = doc.format == "html"
|
|
379
|
+
drafts: list[Draft] = []
|
|
380
|
+
for block in doc.blocks:
|
|
381
|
+
if html and block.kind is BlockKind.IMAGE:
|
|
382
|
+
image = _image_draft(block)
|
|
383
|
+
if image is not None:
|
|
384
|
+
drafts.append(image)
|
|
385
|
+
marks: LinkMarks | None = None
|
|
386
|
+
for index, link in enumerate(block.links):
|
|
387
|
+
key = _link_key(link.text)
|
|
388
|
+
if key not in GENERIC_LINK_TEXTS:
|
|
389
|
+
continue
|
|
390
|
+
marks = marks or LinkMarks(block, [o.text for o in block.links])
|
|
391
|
+
drafts.append(_link_text_draft(marks.side(index), link.text, key))
|
|
392
|
+
return drafts
|
|
393
|
+
|
|
394
|
+
|
|
395
|
+
def _tagged_draft(doc: Document, element: TaggedElement) -> Draft | None:
|
|
396
|
+
"""Return the draft of a figure or a table of the structure tree.
|
|
397
|
+
|
|
398
|
+
Returns:
|
|
399
|
+
For a figure without a ``/Alt`` nor an ``/ActualText`` that is not
|
|
400
|
+
blank, a missing alternative text; for one whose ``/Alt`` is a file
|
|
401
|
+
name, that draft; for a table without a ``TH``, a missing header.
|
|
402
|
+
The side shows the type of the element, or the file name, at its
|
|
403
|
+
page.
|
|
404
|
+
"""
|
|
405
|
+
source = SourceRef(doc.path.name, page=element.page)
|
|
406
|
+
if element.role == "table" and not element.headers:
|
|
407
|
+
return _bare_table(
|
|
408
|
+
marked_side(source, element.type, kind=BlockKind.TABLE),
|
|
409
|
+
)
|
|
410
|
+
if element.role != "figure":
|
|
411
|
+
return None
|
|
412
|
+
alt = (element.alt or "").strip()
|
|
413
|
+
if not alt and not (element.actual or "").strip():
|
|
414
|
+
side = marked_side(source, element.type, kind=BlockKind.IMAGE)
|
|
415
|
+
detail = "the figure has no alternative text"
|
|
416
|
+
return Draft(_ALT_MISSING, None, side, None, detail, element.type)
|
|
417
|
+
if alt and FILE_NAME_ALT.match(alt):
|
|
418
|
+
side = marked_side(source, alt, kind=BlockKind.IMAGE)
|
|
419
|
+
detail = f'the alternative text "{quote(alt)}" is a file name'
|
|
420
|
+
return Draft(_ALT_FILENAME, None, side, None, detail, _FILE_NAME)
|
|
421
|
+
return None
|
|
422
|
+
|
|
423
|
+
|
|
424
|
+
def _tag_drafts(doc: Document) -> list[Draft]:
|
|
425
|
+
"""Return the drafts of the figures and tables of a structure tree.
|
|
426
|
+
|
|
427
|
+
Only the elements that were read are judged: a tree read in part gives
|
|
428
|
+
the drafts of its part; a missing tree gives none.
|
|
429
|
+
"""
|
|
430
|
+
tags = doc.tags
|
|
431
|
+
if tags is None or tags.problem == NO_STRUCTURE_TREE:
|
|
432
|
+
return []
|
|
433
|
+
return [
|
|
434
|
+
draft
|
|
435
|
+
for element in tags.elements
|
|
436
|
+
if (draft := _tagged_draft(doc, element)) is not None
|
|
437
|
+
]
|
|
438
|
+
|
|
439
|
+
|
|
440
|
+
def _annotation_drafts(doc: Document) -> list[Draft]:
|
|
441
|
+
"""Return the drafts of the link annotations of a PDF that tell nothing.
|
|
442
|
+
|
|
443
|
+
The text under an annotation is judged; an empty one, as when the text
|
|
444
|
+
of its page was not all read, is not.
|
|
445
|
+
"""
|
|
446
|
+
drafts: list[Draft] = []
|
|
447
|
+
for page in doc.pdf_pages:
|
|
448
|
+
for link in page.links:
|
|
449
|
+
key = _link_key(link.text)
|
|
450
|
+
if key not in GENERIC_LINK_TEXTS:
|
|
451
|
+
continue
|
|
452
|
+
source = SourceRef(doc.path.name, page=page.number)
|
|
453
|
+
side = marked_side(source, link.text)
|
|
454
|
+
drafts.append(_link_text_draft(side, link.text, key))
|
|
455
|
+
return drafts
|
|
456
|
+
|
|
457
|
+
|
|
458
|
+
def accessibility_drafts(
|
|
459
|
+
doc: Document,
|
|
460
|
+
thresholds: AuditThresholds,
|
|
461
|
+
) -> list[Draft]:
|
|
462
|
+
"""Return the drafts of the accessibility of a document.
|
|
463
|
+
|
|
464
|
+
Args:
|
|
465
|
+
doc: The audited document.
|
|
466
|
+
thresholds: Thresholds of the audit.
|
|
467
|
+
|
|
468
|
+
Returns:
|
|
469
|
+
The drafts about the whole document; then those of each HTML page,
|
|
470
|
+
or of each scanned PDF page; then those of the blocks, in order;
|
|
471
|
+
then those of the figures and tables of the structure tree of a
|
|
472
|
+
PDF; then those of its link annotations.
|
|
473
|
+
"""
|
|
474
|
+
drafts = _document_drafts(doc, thresholds)
|
|
475
|
+
for page in doc.html_pages:
|
|
476
|
+
drafts += _html_page_drafts(page)
|
|
477
|
+
drafts += _scanned_drafts(doc)
|
|
478
|
+
drafts += _block_drafts(doc)
|
|
479
|
+
drafts += _tag_drafts(doc)
|
|
480
|
+
drafts += _annotation_drafts(doc)
|
|
481
|
+
return drafts
|
|
@@ -0,0 +1,136 @@
|
|
|
1
|
+
# Copyright 2026 Christophe Le Douarec
|
|
2
|
+
"""Audit a document: run the families of checks it is asked for.
|
|
3
|
+
|
|
4
|
+
The family `STRUCTURE` checks the headings, the references, the captions and
|
|
5
|
+
the pages of the document, by `structure_drafts` of
|
|
6
|
+
`documentation_checker.audit.structure`, then its links, by
|
|
7
|
+
`broken_link_drafts` of `documentation_checker.audit.links`. The family `A11Y`
|
|
8
|
+
checks its accessibility, by `accessibility_drafts` of
|
|
9
|
+
`documentation_checker.audit.accessibility`, after the structure. The family
|
|
10
|
+
`IMAGES` checks its images, when they were read, by `image_quality_drafts` of
|
|
11
|
+
`documentation_checker.audit.images`, next, with a `PixelLoader` that reads
|
|
12
|
+
their pixels again. The family `TEXT` checks its text, by `text_drafts` of
|
|
13
|
+
`documentation_checker.audit.text`, last, with a `Speller` that knows the
|
|
14
|
+
personal words of the configuration. The drafts of the families then become
|
|
15
|
+
findings as those of `compare` do, by `finalize_drafts` of
|
|
16
|
+
`documentation_checker.compare.aggregate`: severities, filters, identifiers,
|
|
17
|
+
groups.
|
|
18
|
+
"""
|
|
19
|
+
|
|
20
|
+
from dataclasses import dataclass, replace
|
|
21
|
+
from typing import TYPE_CHECKING, Final
|
|
22
|
+
|
|
23
|
+
from documentation_checker.audit.accessibility import accessibility_drafts
|
|
24
|
+
from documentation_checker.audit.images import image_quality_drafts
|
|
25
|
+
from documentation_checker.audit.links import broken_link_drafts
|
|
26
|
+
from documentation_checker.audit.structure import structure_drafts
|
|
27
|
+
from documentation_checker.audit.text import TEXT, text_drafts
|
|
28
|
+
from documentation_checker.compare.aggregate import finalize_drafts
|
|
29
|
+
from documentation_checker.images.load import PixelLoader
|
|
30
|
+
from documentation_checker.model.document import BlockKind
|
|
31
|
+
from documentation_checker.spell.speller import Speller
|
|
32
|
+
|
|
33
|
+
if TYPE_CHECKING:
|
|
34
|
+
from documentation_checker.compare.drafts import Draft
|
|
35
|
+
from documentation_checker.config import Config
|
|
36
|
+
from documentation_checker.model.document import Document
|
|
37
|
+
from documentation_checker.model.findings import Finding
|
|
38
|
+
|
|
39
|
+
STRUCTURE: Final = "structure"
|
|
40
|
+
A11Y: Final = "a11y"
|
|
41
|
+
IMAGES: Final = "images"
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
@dataclass(frozen=True, slots=True)
|
|
45
|
+
class AuditStats:
|
|
46
|
+
"""Figures about an audit.
|
|
47
|
+
|
|
48
|
+
Attributes:
|
|
49
|
+
pages: Pages of the document: HTML pages or PDF pages.
|
|
50
|
+
blocks: Blocks that are not images.
|
|
51
|
+
images: Image blocks.
|
|
52
|
+
links: Links checked; ``None`` when the family `STRUCTURE`, which
|
|
53
|
+
checks them, did not run.
|
|
54
|
+
checks: Families of checks run, in the order they were asked: the
|
|
55
|
+
family `IMAGES` does not run when the images were not read.
|
|
56
|
+
profile: Profile of the audit, ``"screen"`` or ``"print"``.
|
|
57
|
+
images_read: Whether the images were read.
|
|
58
|
+
words: Words spelled; ``None`` when the family `TEXT`, which
|
|
59
|
+
spells them, did not run.
|
|
60
|
+
"""
|
|
61
|
+
|
|
62
|
+
pages: int
|
|
63
|
+
blocks: int
|
|
64
|
+
images: int
|
|
65
|
+
links: int | None
|
|
66
|
+
checks: tuple[str, ...]
|
|
67
|
+
profile: str
|
|
68
|
+
images_read: bool
|
|
69
|
+
words: int | None = None
|
|
70
|
+
|
|
71
|
+
|
|
72
|
+
@dataclass(slots=True)
|
|
73
|
+
class AuditResult:
|
|
74
|
+
"""Outcome of the audit of a document.
|
|
75
|
+
|
|
76
|
+
Attributes:
|
|
77
|
+
doc: The document, with the warnings of the family `TEXT` after
|
|
78
|
+
its own.
|
|
79
|
+
findings: The findings.
|
|
80
|
+
stats: Statistics.
|
|
81
|
+
words: The words that the dictionaries do not know, each once, as
|
|
82
|
+
`TextOutcome` lists them.
|
|
83
|
+
"""
|
|
84
|
+
|
|
85
|
+
doc: Document
|
|
86
|
+
findings: list[Finding]
|
|
87
|
+
stats: AuditStats
|
|
88
|
+
words: tuple[str, ...] = ()
|
|
89
|
+
|
|
90
|
+
|
|
91
|
+
def audit_document(doc: Document, cfg: Config) -> AuditResult:
|
|
92
|
+
"""Audit a document.
|
|
93
|
+
|
|
94
|
+
Args:
|
|
95
|
+
doc: The document, loaded with its audit facts.
|
|
96
|
+
cfg: Run configuration: its families of checks, its profile, its
|
|
97
|
+
thresholds, its severities and its filters.
|
|
98
|
+
|
|
99
|
+
Returns:
|
|
100
|
+
The findings, those of the structure first, then those of the
|
|
101
|
+
accessibility, of the images and of the text, each family in its
|
|
102
|
+
order, statistics, and the words that the dictionaries do not
|
|
103
|
+
know; the document is a copy that has the warnings of the text
|
|
104
|
+
after its own.
|
|
105
|
+
"""
|
|
106
|
+
drafts: list[Draft] = []
|
|
107
|
+
links = None
|
|
108
|
+
if STRUCTURE in cfg.checks:
|
|
109
|
+
drafts += structure_drafts(doc)
|
|
110
|
+
broken, links = broken_link_drafts(doc)
|
|
111
|
+
drafts += broken
|
|
112
|
+
if A11Y in cfg.checks:
|
|
113
|
+
drafts += accessibility_drafts(doc, cfg.audit)
|
|
114
|
+
if IMAGES in cfg.checks and cfg.images:
|
|
115
|
+
with PixelLoader(doc.path) as loader:
|
|
116
|
+
drafts += image_quality_drafts(doc, loader, cfg.audit, cfg.profile)
|
|
117
|
+
words = None
|
|
118
|
+
unknown: tuple[str, ...] = ()
|
|
119
|
+
if TEXT in cfg.checks:
|
|
120
|
+
outcome = text_drafts(doc, cfg, Speller(cfg.spelling.words))
|
|
121
|
+
drafts += outcome.drafts
|
|
122
|
+
doc = replace(doc, warnings=[*doc.warnings, *outcome.warnings])
|
|
123
|
+
words = outcome.checked
|
|
124
|
+
unknown = outcome.words
|
|
125
|
+
images = sum(block.kind is BlockKind.IMAGE for block in doc.blocks)
|
|
126
|
+
stats = AuditStats(
|
|
127
|
+
pages=len(doc.parts),
|
|
128
|
+
blocks=len(doc.blocks) - images,
|
|
129
|
+
images=images,
|
|
130
|
+
links=links,
|
|
131
|
+
checks=tuple(c for c in cfg.checks if c != IMAGES or cfg.images),
|
|
132
|
+
profile=cfg.profile,
|
|
133
|
+
images_read=cfg.images,
|
|
134
|
+
words=words,
|
|
135
|
+
)
|
|
136
|
+
return AuditResult(doc, finalize_drafts(drafts, cfg), stats, unknown)
|