urlhealth

A Python library to check whether a URL is live, dead, or likely hallucinated. When a URL is dead, it automatically checks the Wayback Machine for an archived snapshot.

Installation

pip install urlhealth

Dependencies

• requests

Usage

from urlhealth import inspect, URLStatus

result = inspect("https://example.com")
print(result["url_status"])   # URLStatus.LIVE, .DEAD, .UNKNOWN, or .LIKELY_HALLUCINATED
print(result["status_code"])  # HTTP status code (int or None)
print(result["wayback_url"])  # Wayback Machine archive URL (str or None)

Return value

inspect(url, timeout=10) returns a dict with three keys:

URLStatus enum

class URLStatus(str, Enum):
    LIVE = "LIVE"
    DEAD = "DEAD"
    UNKNOWN = "UNKNOWN"
    LIKELY_HALLUCINATED = "LIKELY_HALLUCINATED"

Since URLStatus is a str enum, you can compare directly with strings:

if result["url_status"] == "LIVE":
    print("URL is reachable")

How it works

1. Sends an HTTP HEAD request to the URL (falls back to GET if the server returns 405, 403, or 501).
2. If the response is 200, the URL is LIVE.
3. If the response is 404, queries the Wayback Machine API:
   • Archived snapshot found → DEAD (with wayback_url populated).
   • No snapshot → LIKELY_HALLUCINATED.
4. Any other status code or connection error → UNKNOWN.

License

See LICENSE for details.