Metadata-Version: 2.5
Name: is-aes
Version: 0.1.0
Summary: Client for the is-aesthetic.com report API
Project-URL: Homepage, https://is-aesthetic.com
Project-URL: Methodology, https://is-aesthetic.com/methodology
Project-URL: Documentation, https://is-aesthetic.com/docs
Author: BenchFlow
License-Expression: MIT
License-File: LICENSE
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# is-aes

Command line and Python client for [is-aesthetic.com](https://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`:

```sh
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

```python
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](https://is-aesthetic.com/methodology)
for the rubric, sources, exclusions and scoring details.

See the [documentation](https://is-aesthetic.com/docs) for API usage.
