is-aes

Command line and Python client for is-aesthetic.com. Requires Python 3.9 or later. No runtime dependencies. MIT licensed.

Install from PyPI, or run it without installing through uvx or pipx run:

pip install is-aes
is-aes vercel.com
uvx is-aes vercel.com
is-aes vercel.com --wait --timeout 120
is-aes vercel.com --json --wait
python -m is_aes vercel.com

Bare hosts and host/path inputs default to HTTPS: vercel.com becomes https://vercel.com/, and www.gov.uk/browse keeps its path. Explicit HTTP(S) URLs work too. Credentials, other schemes, malformed hosts, and localhost are refused by the client; the API also enforces public-URL safety checks.

The command fetches the latest report for the URL's host, or starts a scan if none exists. Without --wait, a queued/running job is printed immediately. With --wait, it polls at least every 3 seconds, respecting the API's Retry-After, until complete. --timeout s bounds requests and polling (default: 120 seconds). --json writes the raw JSON object (report or queued job), with no summary or progress text. Errors go to stderr and exit with status 1. --help and --version are available.

The API is public. If it is temporarily unavailable, the command asks you to try later. Findings are grouped by check id, ordered by reported points lost, and list the affected pages. Measurements come from the highest-loss occurrence.

Library

from is_aes import check, IsAesError

try:
    report = check("vercel.com", wait=True, timeout=120)
    if report["status"] == "complete":
        print(report["score"])
    else:
        print(report["status"])
except IsAesError as error:
    print(error.code, str(error))

check(url, *, wait=False, timeout=120, api_url=API_URL, poll_interval=3) is synchronous and returns the raw JSON dict. Time arguments are in seconds. api_url is the full endpoint for staging/tests; the CLI also accepts the IS_AES_API_URL environment override. Errors expose code (INVALID_URL, INVALID_OPTIONS, TIMEOUT, API_UNAVAILABLE, PRIVATE_SERVICE, HTTP_ERROR, or INVALID_REPORT) and status for HTTP errors. Failed scans include the API's explanation. Rate limits are surfaced; failed requests are not silently retried.

What the score means

The 0–100 score summarizes evaluated design checks across six domains: visual communication; information and findability; functional and interaction support; inclusion and adaptation; visual expression; transparency and agency. Essential checks carry most of the score. Recommended checks count only where the relevant surface exists. Bonus checks may raise the score but never lower it. Excluded checks do not count as failures. A null score means no trustworthy checks were evaluated, not a zero. The client displays the server's score and grade without recalculating them.

Reports reflect one public snapshot of up to 3 pages, at the viewports recorded in the report, with explicit coverage limits. Read the methodology for the rubric, sources, exclusions and scoring details.

See the documentation for API usage.