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: list[str] | None = None, disabled_rules: list[str] | None = None)

Bases: object

Runs axe-core against a Playwright page and returns structured findings.

Parameters:

• run_only – Optional list of axe tags to restrict the run to (e.g. ["wcag2a", "wcag2aa"]). Maps to axe’s runOnly: {type: "tag", values: [...]}. None uses axe defaults.

• disabled_rules – Optional list of rule ids to disable. Maps to axe’s rules: {<id>: {enabled: false}}.

__init__(run_only: list[str] | None = None, disabled_rules: list[str] | None = None)

Initialize the auditor with optional tag and rule filters.

async audit_page(page: Page, source: str | None = None, viewport: str = 'desktop') → A11yReport

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

Parameters:

• page – A loaded Playwright page.

• source – Optional source label recorded in the report; defaults to the page URL.

• viewport – Viewport name recorded in the report.

Returns:

The structured accessibility report.

Raises:

AnalysisError – If axe injection or execution fails.

async audit(source: str | Path, viewport: Viewport | str = 'desktop') → A11yReport

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

Parameters:

• source – A URL or path to a local HTML file.

• viewport – Viewport name or Viewport enum member.

Returns:

The structured accessibility report.

Raises:

AnalysisError – If axe injection or execution fails.

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: str, viewport: str, engine_version: str, violations: list[~layoutlens.a11y.types.A11yFinding], incomplete: list[~layoutlens.a11y.types.A11yFinding], passes_count: int, timestamp: str = <factory>)

Bases: object

Structured accessibility report for a single page and viewport.

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() → str

Serialize the report to an indented JSON string.

summary() → str

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.

__init__(source: str, viewport: str, engine_version: str, violations: list[~layoutlens.a11y.types.A11yFinding], incomplete: list[~layoutlens.a11y.types.A11yFinding], passes_count: int, timestamp: str = <factory>) → None

class layoutlens.A11yFinding(rule_id: str, impact: str, wcag_refs: list[str], description: str, help_url: str, nodes: list[dict[str, Any]], engine: str = 'axe-core')

Bases: object

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

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

__init__(rule_id: str, impact: str, wcag_refs: list[str], description: str, help_url: str, nodes: list[dict[str, Any]], engine: str = 'axe-core') → None

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’.