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 https://example.com
uvx is-aes https://example.com
is-aes https://example.com --wait --timeout 120
is-aes https://example.com --json --wait
python -m is_aes https://example.com

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("https://example.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.