Accessibility (axe-core) API

Deterministic WCAG 2.1 A/AA accessibility checks via a vendored axe-core bundle, injected into a Playwright-rendered page. This engine requires no API key or LLM call.

AxeAuditor

class layoutlens.AxeAuditor(run_only=None, disabled_rules=None)[source]

Bases: object

Run axe-core against a Playwright page and return structured findings.

Parameters:
async audit_page(page, source=None, viewport='desktop')[source]

Inject axe-core into an already-loaded page and run the audit.

Parameters:

  • page (Page) – A loaded Playwright page.

  • source (str | None) – Optional source label recorded in the report; defaults to the page URL.

  • viewport (str) – Viewport name recorded in the report.

Returns:

The structured accessibility report.

Raises:

AnalysisError – If axe injection or execution fails.

Return type:

A11yReport

async audit(source, viewport='desktop')[source]

Audit a URL or local HTML file, owning the browser lifecycle.

Parameters:

  • source (str | Path) – A URL or path to a local HTML file.

  • viewport (ViewportType) – Viewport name or Viewport enum member.

Returns:

The structured accessibility report.

Raises:

AnalysisError – If axe injection or execution fails.

Return type:

A11yReport

Report Types

Field documentation for these dataclasses lives in the class docstrings below (:members: is scoped to methods only, to avoid duplicating the dataclass-field docs that Napoleon already renders from the docstring).

class layoutlens.A11yReport(source, viewport, engine_version, violations, incomplete, passes_count, timestamp=<factory>)[source]

Bases: object

Structured accessibility report for a single page and viewport.

Parameters:
source

The URL or file path that was audited.

Type:

str

viewport

The viewport name used for the audit.

Type:

str

engine_version

Version of the underlying engine (e.g. axe-core).

Type:

str

violations

Findings that definitively fail a rule.

Type:

list[layoutlens.a11y.types.A11yFinding]

incomplete

Findings axe could not decide automatically (needs review).

Type:

list[layoutlens.a11y.types.A11yFinding]

passes_count

Number of rules that passed.

Type:

int

timestamp

ISO-8601 timestamp of when the report was created.

Type:

str

property ok: bool

Return True if there are no violations.

to_json()[source]

Serialize the report to an indented JSON string.

Return type:

str

summary()[source]

Return a compact, human/LLM-readable summary of the report.

Lists each violation’s rule id, impact, WCAG references, the number of affected nodes, and a snippet (target selector + HTML) of the first affected node.

Return type:

str

class layoutlens.A11yFinding(rule_id, impact, wcag_refs, description, help_url, nodes, engine='axe-core')[source]

Bases: object

A single accessibility rule outcome affecting one or more DOM nodes.

Parameters:
rule_id

The axe-core rule identifier (e.g. "color-contrast").

Type:

str

impact

Severity as reported by axe: "critical", "serious", "moderate", or "minor" (may be an empty string for incomplete results without a determined impact).

Type:

str

wcag_refs

WCAG / Section 508 tags for the rule (e.g. ["wcag2aa", "wcag143"]).

Type:

list[str]

description

Human-readable description of the rule.

Type:

str

help_url

URL to Deque’s documentation for the rule.

Type:

str

nodes

Affected DOM nodes, each a dict with "target" (list of selectors) and "html" (truncated outer HTML snippet).

Type:

list[dict[str, Any]]

engine

Name of the engine that produced the finding.

Type:

str

Engine Version

layoutlens.AXE_VERSION = '4.10.3'

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to ‘strict’.