Find Images Missing Alt Text Across Your Sitemap with Python (Standard Library Only)

#!/usr/bin/env python3 """Find images with missing, empty, or placeholder alt text across a sitemap. Standard library only. Usage: python3 alt_audit.py https://example.com/sitemap.xml --out alt_report.csv """ import argparse import csv import re import sys import urllib.error import urllib.request import xml.etree.ElementTree as ET from concurrent.futures import ThreadPoolExecutor from html.parser import HTMLParser from urllib.parse import urljoin UA = "alt-audit/1.0 (+stdlib python)" SM_NS = "{http://www.sitemaps.org/schemas/sitemap/0.9}" PLACEHOLDERS = {"image", "img", "photo", "picture", "graphic", "logo", "icon", "banner", "spacer", "untitled", "alt", "placeholder", "null"} FILENAME_RE = re.compile(r"^[\w\-. ]+\.(jpe?g|png|gif|webp|avif|svg|bmp)$", re.I) CAMERA_RE = re.compile(r"^(img|dsc|image|screenshot|photo)[\s_\-]?\d+", re.I) def fetch(url, timeout=15): req = urllib.request.Request(url, headers={"User-Agent": UA}) with urllib.request.urlopen(req, timeout=timeout) as resp: charset = resp.headers.get_content_charset() or "utf-8" return resp.status, resp.geturl(), resp.read().decode(charset, "replace") def sitemap_urls(sitemap_url, seen=None): """Return page URLs from a urlset, following sitemap indexes.""" seen = seen if seen is not None else set() if sitemap_url in seen: return [] seen.add(sitemap_url) _, _, body = fetch(sitemap_url) root = ET.fromstring(body.encode("utf-8")) if root.tag == SM_NS + "sitemapindex": urls = [] for sm in root.findall(SM_NS + "sitemap"): loc = sm.find(SM_NS + "loc") if loc is not None and loc.text: urls.extend(sitemap_urls(loc.text.strip(), seen)) return urls # direct <url><loc> children only, so image:loc entries are skipped return [u.find(SM_NS + "loc").text.strip() for u in root.findall(SM_NS + "url") if u.find(SM_NS + "loc") is not None and u.find(SM_NS + "loc").text] class ImgParser(HTMLParser): """Collect every <img> and <input type=image>, plus link context.""" def __init__(self, base): super().__init__(convert_charrefs=True) self.base = base self.images = [] self._skip = 0 # inside <script>/<style>/<template>/<noscript> self._links = [] # stack of open <a> elements def handle_starttag(self, tag, attrs): a = dict(attrs) if tag in ("script", "style", "template", "noscript"): self._skip += 1 return if self._skip: return if tag == "a" and "href" in a: self._links.append({"text": [], "imgs": []}) elif tag == "img" or (tag == "input" and (a.get("type") or "").lower() == "image"): src = a.get("src") or "" if a.get("data-src") and (not src or src.startswith("data:")): src = a["data-src"] # lazy-loaded image placeholder img = { "tag": tag, "src": urljoin(self.base, src) if src else "", "alt": a.get("alt"), # None means the attribute is absent "hidden": (a.get("role") in ("presentation", "none") or a.get("aria-hidden") == "true"), "aria_name": bool((a.get("aria-label") or "").strip() or a.get("aria-labelledby")), "in_link": bool(self._links), } self.images.append(img) if self._links: self._links[-1]["imgs"].append(img) def handle_startendtag(self, tag, attrs): if tag in ("img", "input"): self.handle_starttag(tag, attrs) def handle_endtag(self, tag): if tag in ("script", "style", "template", "noscript"): if self._skip: self._skip -= 1 elif tag == "a" and self._links and not self._skip: link = self._links.pop() text = "".join(link["text"]).strip() alts = "".join((i["alt"] or "") for i in link["imgs"]).strip() if link["imgs"] and not text and not alts: for i in link["imgs"]: i["empty_link"] = True def handle_data(self, data): if self._links and not self._skip: self._links[-1]["text"].append(data) def classify(img): """Return a list of issue codes for one image.""" alt = img["alt"] issues = [] if alt is None: issues.append("labelled_no_alt" if img["aria_name"] else "hidden_no_alt" if img["hidden"] else "missing_alt") elif not alt.strip(): issues.append("empty_alt_in_link" if img.get("empty_link") else "empty_alt") else: a = alt.strip() name = img["src"].rsplit("/", 1)[-1].split("?")[0] if a.casefold() in PLACEHOLDERS: issues.append("placeholder_alt") elif FILENAME_RE.match(a) or CAMERA_RE.match(a) or (name and a == name): issues.append("filename_alt") if len(a) > 150: issues.append("long_alt") if img.get("empty_link") and alt is None: issues.append("link_has_no_text") return issues def audit(url): rows = [] try: status, final_url, body = fetch(url) except urllib.error.HTTPError as e: return [{"page": url, "status": e.code, "image": "", "alt": "", "issues": "http_error"}], 0 except (urllib.error.URLError, TimeoutError) as e: return [{"page": url, "status": "error", "image": "", "alt": "", "issues": f"fetch_failed:{e}"}], 0 p = ImgParser(final_url) p.feed(body) p.close() for img in p.images: issues = classify(img) if issues: rows.append({"page": url, "status": status, "image": img["src"], "alt": "" if img["alt"] is None else img["alt"], "issues": ";".join(issues)}) return rows, len(p.images) def main(): ap = argparse.ArgumentParser(description=__doc__) ap.add_argument("sitemap") ap.add_argument("--out", default="alt_report.csv") ap.add_argument("--workers", type=int, default=8) ap.add_argument("--limit", type=int, default=0, help="check only the first N URLs") ap.add_argument("--include-empty", action="store_true", help="also report alt=\"\" (often correct for decorative images)") args = ap.parse_args() try: urls = sitemap_urls(args.sitemap) except (urllib.error.URLError, ET.ParseError) as e: print(f"Could not read sitemap: {e}", file=sys.stderr) return 2 if args.limit: urls = urls[:args.limit] print(f"Checking {len(urls)} URLs from {args.sitemap}") with ThreadPoolExecutor(max_workers=args.workers) as pool: results = list(pool.map(audit, urls)) rows, total = [], 0 for page_rows, n in results: total += n rows.extend(r for r in page_rows if args.include_empty or r["issues"] != "empty_alt") with open(args.out, "w", newline="", encoding="utf-8") as f: w = csv.DictWriter(f, fieldnames=["page", "status", "image", "alt", "issues"]) w.writeheader() w.writerows(rows) counts = {} for r in rows: for code in r["issues"].split(";"): counts[code] = counts.get(code, 0) + 1 pages = len({r["page"] for r in rowsSource：https://dev.to/appierun_66/find-images-missing-alt-text-across-your-sitemap-with-python-standard-library-only-5abc
My favorites