PyPI - seobuddy - Versions diffs - 0.2.0__py3-none-any.whl - Mend

seobuddy 0.2.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (31) hide show

seobuddy/__init__.py +10 -0
seobuddy/__main__.py +3 -0
seobuddy/auditor.py +85 -0
seobuddy/checks/__init__.py +1 -0
seobuddy/checks/base.py +167 -0
seobuddy/checks/canonical.py +64 -0
seobuddy/checks/content.py +61 -0
seobuddy/checks/headings.py +57 -0
seobuddy/checks/hreflang.py +155 -0
seobuddy/checks/images.py +49 -0
seobuddy/checks/jsonld.py +100 -0
seobuddy/checks/links.py +119 -0
seobuddy/checks/meta.py +59 -0
seobuddy/checks/opengraph.py +37 -0
seobuddy/checks/robots_check.py +51 -0
seobuddy/checks/sitemap_check.py +100 -0
seobuddy/checks/technical.py +53 -0
seobuddy/checks/title.py +59 -0
seobuddy/cli.py +225 -0
seobuddy/crawler.py +180 -0
seobuddy/display.py +257 -0
seobuddy/html_utils.py +47 -0
seobuddy/models.py +99 -0
seobuddy/report.py +148 -0
seobuddy/site_resources.py +251 -0
seobuddy/url_utils.py +155 -0
seobuddy-0.2.0.dist-info/METADATA +449 -0
seobuddy-0.2.0.dist-info/RECORD +31 -0
seobuddy-0.2.0.dist-info/WHEEL +4 -0
seobuddy-0.2.0.dist-info/entry_points.txt +2 -0
seobuddy-0.2.0.dist-info/licenses/LICENSE +21 -0

seobuddy/__init__.py ADDED Viewed

@@ -0,0 +1,10 @@
+"""SEObuddy — technical SEO audit CLI."""
+__version__ = "0.2.0"
+AUTHOR_NAME = "NikitaY.com"
+AUTHOR_URL = "https://nikitay.com/"
+GITHUB_URL = "https://github.com/nikitaycs50/SEObuddy"
+COPYRIGHT = f"Copyright © 2026 {AUTHOR_NAME}. All rights reserved."
+CREATED_BY = f"Created by {AUTHOR_NAME}"
+CLI_EPILOG = f"{CREATED_BY} — {AUTHOR_URL}"

seobuddy/__main__.py ADDED Viewed

@@ -0,0 +1,3 @@
+from seobuddy.cli import run
+run()

seobuddy/auditor.py ADDED Viewed

@@ -0,0 +1,85 @@
+"""Orchestrates all SEO checks for a single page."""
+from __future__ import annotations
+import httpx
+from bs4 import BeautifulSoup
+from seobuddy.checks import (
+    canonical,
+    content,
+    headings,
+    hreflang,
+    images,
+    jsonld,
+    links,
+    meta,
+    opengraph,
+    technical,
+    title,
+)
+from seobuddy.checks.base import CATEGORY_ORDER, weighted_page_score
+from seobuddy.html_utils import is_html_content, parse_html
+from seobuddy.models import AuditConfig, CheckResult, CheckStatus, PageAudit, PageData, SiteContext
+from seobuddy.url_utils import path_display
+def _empty_result(name: str, weight: float) -> CheckResult:
+    from seobuddy.checks.base import CATEGORY_WEIGHTS
+    w = CATEGORY_WEIGHTS.get(name, weight)
+    return CheckResult(
+        name=name,
+        score=0,
+        weight=w,
+        status=CheckStatus.FAIL,
+        findings=["No HTML content to analyze"],
+        suggestions=[],
+    )
+def _minimal_soup() -> BeautifulSoup:
+    return BeautifulSoup("<html></html>", "lxml")
+async def audit_page(
+    page: PageData,
+    context: SiteContext,
+    config: AuditConfig,
+    client: httpx.AsyncClient | None = None,
+) -> PageAudit:
+    html = page.html or ""
+    content_type = page.headers.get("content-type") or ""
+    is_html = page.status_code < 400 and html.strip() and is_html_content(content_type, html)
+    soup = parse_html(html, content_type) if is_html else None
+    results: dict[str, CheckResult] = {}
+    if not soup:
+        from seobuddy.checks.base import CATEGORY_WEIGHTS
+        for cat in CATEGORY_ORDER:
+            if cat == "technical":
+                results[cat] = technical.check(_minimal_soup(), page, context)
+            else:
+                results[cat] = _empty_result(cat, CATEGORY_WEIGHTS[cat])
+    else:
+        results["title"] = title.check(soup, page, context)
+        results["meta"] = meta.check(soup, page, context)
+        results["opengraph"] = opengraph.check(soup, page, context)
+        results["jsonld"] = jsonld.check(soup, page, context)
+        results["headings"] = headings.check(soup, page, context)
+        results["content"] = content.check(soup, page, context)
+        results["links"] = await links.check_async(soup, page, context, config, client)
+        results["images"] = images.check(soup, page, context)
+        results["canonical"] = canonical.check(soup, page, context)
+        results["hreflang"] = hreflang.check(soup, page, context)
+        results["technical"] = technical.check(soup, page, context)
+    score = weighted_page_score(results)
+    return PageAudit(
+        page=page,
+        results=results,
+        score=score,
+        path_display=path_display(page.final_url),
+    )

seobuddy/checks/__init__.py ADDED Viewed

	@@ -0,0 +1 @@
1	+ """SEO audit check modules."""

seobuddy/checks/base.py ADDED Viewed

@@ -0,0 +1,167 @@
+"""Scoring helpers and category metadata."""
+from __future__ import annotations
+from seobuddy.models import CheckResult, CheckStatus, PageAudit
+# Display order and labels for reports/UI
+CATEGORY_ORDER = [
+    "title",
+    "meta",
+    "opengraph",
+    "jsonld",
+    "headings",
+    "content",
+    "links",
+    "images",
+    "canonical",
+    "hreflang",
+    "technical",
+]
+CATEGORY_LABELS = {
+    "title": "Title",
+    "meta": "Meta Desc",
+    "opengraph": "Open Graph",
+    "jsonld": "JSON-LD",
+    "headings": "Headings",
+    "content": "Content",
+    "links": "Links",
+    "images": "Images",
+    "canonical": "Canonical",
+    "hreflang": "Hreflang",
+    "technical": "Technical",
+}
+SITE_CHECK_ORDER = ("robots", "sitemap")
+SITE_CATEGORY_LABELS = {
+    "robots": "Robots.txt",
+    "sitemap": "Sitemap",
+}
+def site_check_pages_ok(score: int) -> str:
+    """Pages OK column for site-wide checks (single site-level pass)."""
+    ok = 1 if score >= 80 else 0
+    return f"{ok}/1"
+CATEGORY_WEIGHTS = {
+    "title": 0.15,
+    "meta": 0.10,
+    "opengraph": 0.09,
+    "jsonld": 0.09,
+    "headings": 0.09,
+    "content": 0.15,
+    "links": 0.09,
+    "images": 0.09,
+    "canonical": 0.05,
+    "hreflang": 0.05,
+    "technical": 0.05,
+}
+def clamp_score(value: float) -> int:
+    return max(0, min(100, round(value)))
+def status_from_score(score: int) -> CheckStatus:
+    if score >= 80:
+        return CheckStatus.PASS
+    if score >= 60:
+        return CheckStatus.WARN
+    return CheckStatus.FAIL
+def weighted_page_score(results: dict[str, CheckResult]) -> int:
+    total = 0.0
+    for key, weight in CATEGORY_WEIGHTS.items():
+        result = results.get(key)
+        if result:
+            total += result.score * weight
+    return clamp_score(total)
+def letter_grade(score: int) -> str:
+    if score >= 90:
+        return "A"
+    if score >= 80:
+        return "B"
+    if score >= 70:
+        return "C+"
+    if score >= 60:
+        return "C"
+    if score >= 50:
+        return "D"
+    return "F"
+def aggregate_category_scores(
+    pages: list[PageAudit],
+) -> dict[str, dict[str, int]]:
+    """Per-category mean score and pages_ok count (score >= 80)."""
+    agg: dict[str, dict[str, int]] = {}
+    for cat in CATEGORY_ORDER:
+        scores = []
+        ok = 0
+        for page in pages:
+            r = page.results.get(cat)
+            if r:
+                scores.append(r.score)
+                if r.score >= 80:
+                    ok += 1
+        agg[cat] = {
+            "score": round(sum(scores) / len(scores)) if scores else 0,
+            "pages_ok": ok,
+            "pages_total": len(pages),
+        }
+    return agg
+def top_issues(pages: list[PageAudit], limit: int = 5) -> list[str]:
+    """Human-readable top issues sorted by impact."""
+    if not pages:
+        return []
+    agg = aggregate_category_scores(pages)
+    impacts: list[tuple[float, str]] = []
+    for cat in CATEGORY_ORDER:
+        data = agg[cat]
+        cat_score = data["score"]
+        weight = CATEGORY_WEIGHTS[cat]
+        impact = weight * (100 - cat_score)
+        label = CATEGORY_LABELS[cat]
+        ok = data["pages_ok"]
+        total = data["pages_total"]
+        if cat_score < 80:
+            line = f"{label} weak (avg {cat_score}/100, {ok}/{total} pages OK)"
+            impacts.append((impact, line))
+    impacts.sort(key=lambda x: x[0], reverse=True)
+    lines = []
+    for i, (_, line) in enumerate(impacts[:limit], 1):
+        circled = "①②③④⑤"[i - 1] if i <= 5 else str(i)
+        lines.append(f"{circled} {line}")
+    return lines
+def collect_recommendations(pages: list[PageAudit]) -> list[str]:
+    """Deduplicated suggestions sorted by category impact."""
+    agg = aggregate_category_scores(pages)
+    seen: set[str] = set()
+    items: list[tuple[float, str]] = []
+    for cat in CATEGORY_ORDER:
+        data = agg[cat]
+        impact = CATEGORY_WEIGHTS[cat] * (100 - data["score"])
+        for page in pages:
+            r = page.results.get(cat)
+            if r:
+                for s in r.suggestions:
+                    if s not in seen:
+                        seen.add(s)
+                        items.append((impact, s))
+    items.sort(key=lambda x: x[0], reverse=True)
+    return [s for _, s in items]

seobuddy/checks/canonical.py ADDED Viewed

@@ -0,0 +1,64 @@
+"""Canonical URL check."""
+from __future__ import annotations
+from urllib.parse import urlparse
+from bs4 import BeautifulSoup
+from seobuddy.checks.base import CATEGORY_WEIGHTS, clamp_score, status_from_score
+from seobuddy.models import CheckResult, CheckStatus, PageData, SiteContext
+from seobuddy.url_utils import normalize_url
+def check(soup: BeautifulSoup, page: PageData, context: SiteContext) -> CheckResult:
+    weight = CATEGORY_WEIGHTS["canonical"]
+    findings: list[str] = []
+    suggestions: list[str] = []
+    tag = soup.find("link", rel=lambda r: r and "canonical" in r.lower())
+    href = (tag.get("href") or "").strip() if tag else ""
+    if not href:
+        return CheckResult(
+            name="canonical",
+            score=0,
+            weight=weight,
+            status=CheckStatus.FAIL,
+            findings=["Missing canonical link tag"],
+            suggestions=["Add <link rel='canonical' href='...'> pointing to preferred URL"],
+        )
+    parsed = urlparse(href)
+    if not parsed.scheme:
+        return CheckResult(
+            name="canonical",
+            score=40,
+            weight=weight,
+            status=CheckStatus.WARN,
+            findings=["Canonical URL is not absolute"],
+            suggestions=["Use absolute URL in canonical tag"],
+        )
+    norm_canonical = normalize_url(href) or href
+    norm_page = normalize_url(page.final_url) or page.final_url
+    if norm_canonical == norm_page:
+        score = 100
+        findings.append("Canonical points to this page")
+    else:
+        score = 70
+        findings.append(f"Canonical points elsewhere: {href}")
+        suggestions.append("Ensure canonical matches preferred URL for this content")
+    context.canonicals_seen.add(norm_canonical)
+    score = clamp_score(score)
+    return CheckResult(
+        name="canonical",
+        score=score,
+        weight=weight,
+        status=status_from_score(score),
+        findings=findings,
+        suggestions=suggestions,
+    )

seobuddy/checks/content.py ADDED Viewed

@@ -0,0 +1,61 @@
+"""Content quality check (word count, text/HTML ratio)."""
+from __future__ import annotations
+from bs4 import BeautifulSoup
+from seobuddy.checks.base import CATEGORY_WEIGHTS, clamp_score, status_from_score
+from seobuddy.models import CheckResult, CheckStatus, PageData, SiteContext
+def _word_count(soup: BeautifulSoup) -> int:
+    for tag in soup(["script", "style", "noscript"]):
+        tag.decompose()
+    text = soup.get_text(separator=" ", strip=True)
+    words = [w for w in text.split() if w]
+    return len(words)
+def check(soup: BeautifulSoup, page: PageData, context: SiteContext) -> CheckResult:
+    weight = CATEGORY_WEIGHTS["content"]
+    findings: list[str] = []
+    suggestions: list[str] = []
+    # Parse copy so word-count decompose does not mutate caller's soup
+    from bs4 import BeautifulSoup as BS
+    words = _word_count(BS(str(soup), "lxml"))
+    if words < 300:
+        word_score = 0
+        findings.append(f"Thin content ({words} words; minimum 300)")
+        suggestions.append("Add substantive content (300+ words)")
+    elif words < 500:
+        word_score = 60
+        findings.append(f"Moderate content ({words} words)")
+    elif words < 800:
+        word_score = 80
+        findings.append(f"Good content depth ({words} words)")
+    else:
+        word_score = 100
+        findings.append(f"Strong content depth ({words} words)")
+    html_len = len(page.html or "")
+    visible = soup.get_text(separator=" ", strip=True)
+    ratio = (len(visible) / html_len * 100) if html_len else 0
+    ratio_score = 100 if ratio >= 15 else max(0, int(ratio / 15 * 100))
+    if ratio < 15:
+        findings.append(f"Low text/HTML ratio ({ratio:.1f}%; aim ≥15%)")
+        suggestions.append("Reduce boilerplate markup; increase visible text")
+    score = clamp_score((word_score + ratio_score) / 2)
+    return CheckResult(
+        name="content",
+        score=score,
+        weight=weight,
+        status=status_from_score(score),
+        findings=findings,
+        suggestions=suggestions,
+    )

seobuddy/checks/headings.py ADDED Viewed

@@ -0,0 +1,57 @@
+"""Heading hierarchy check."""
+from __future__ import annotations
+import re
+from bs4 import BeautifulSoup
+from seobuddy.checks.base import CATEGORY_WEIGHTS, clamp_score, status_from_score
+from seobuddy.models import CheckResult, CheckStatus, PageData, SiteContext
+def check(soup: BeautifulSoup, page: PageData, context: SiteContext) -> CheckResult:
+    weight = CATEGORY_WEIGHTS["headings"]
+    findings: list[str] = []
+    suggestions: list[str] = []
+    score = 100
+    h1s = [h for h in soup.find_all("h1") if h.get_text(strip=True)]
+    if len(h1s) == 0:
+        score = 20
+        findings.append("No H1 heading found")
+        suggestions.append("Add exactly one H1 with primary page topic")
+    elif len(h1s) > 1:
+        score = 40
+        findings.append(f"Multiple H1 headings ({len(h1s)})")
+        suggestions.append("Use a single H1 per page")
+    else:
+        findings.append("Single H1 present")
+    # Hierarchy: collect heading levels in document order
+    headings = soup.find_all(re.compile(r"^h[1-6]$", re.I))
+    levels = []
+    for h in headings:
+        if h.name:
+            levels.append(int(h.name[1]))
+    gap_penalty = 0
+    prev = 0
+    for level in levels:
+        if prev and level > prev + 1:
+            gap_penalty += 20
+            findings.append(f"Heading hierarchy skip (H{prev} → H{level})")
+        prev = level
+    score = clamp_score(max(0, score - gap_penalty))
+    if gap_penalty and not suggestions:
+        suggestions.append("Maintain sequential heading levels (e.g. H1 → H2 → H3)")
+    return CheckResult(
+        name="headings",
+        score=score,
+        weight=weight,
+        status=status_from_score(score),
+        findings=findings,
+        suggestions=suggestions,
+    )

seobuddy/checks/hreflang.py ADDED Viewed

@@ -0,0 +1,155 @@
+"""Hreflang alternate link audit."""
+from __future__ import annotations
+import re
+from urllib.parse import urlparse
+from bs4 import BeautifulSoup
+from seobuddy.checks.base import CATEGORY_WEIGHTS, clamp_score, status_from_score
+from seobuddy.models import CheckResult, PageAudit, PageData, SiteContext
+from seobuddy.url_utils import crawl_dedup_key, normalize_url
+HREFLANG_RE = re.compile(
+    r"^[a-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$|^x-default$",
+    re.IGNORECASE,
+)
+MAX_EDGES = 200
+def _page_key(url: str) -> str:
+    return crawl_dedup_key(url)
+def _extract_alternates(soup: BeautifulSoup, page_url: str) -> list[tuple[str, str]]:
+    alternates: list[tuple[str, str]] = []
+    for link in soup.find_all("link", rel=lambda v: v and "alternate" in v):
+        hreflang = (link.get("hreflang") or "").strip()
+        href = (link.get("href") or "").strip()
+        if not hreflang or not href:
+            continue
+        target = normalize_url(href, page_url) or href
+        alternates.append((hreflang.lower(), target))
+    return alternates
+def check(soup: BeautifulSoup, page: PageData, context: SiteContext) -> CheckResult:
+    weight = CATEGORY_WEIGHTS["hreflang"]
+    findings: list[str] = []
+    suggestions: list[str] = []
+    score = 100
+    alternates = _extract_alternates(soup, page.final_url)
+    if not alternates:
+        findings.append("No hreflang alternates")
+        return CheckResult(
+            name="hreflang",
+            score=100,
+            weight=weight,
+            status=status_from_score(100),
+            findings=findings,
+            suggestions=suggestions,
+        )
+    from_key = _page_key(page.final_url)
+    codes_seen: dict[str, str] = {}
+    has_x_default = False
+    lang_codes: set[str] = set()
+    self_ref = False
+    for code, target in alternates:
+        if len(context.hreflang_edges) < MAX_EDGES:
+            context.hreflang_edges.append((from_key, code, _page_key(target)))
+        if not HREFLANG_RE.match(code):
+            score -= 25
+            findings.append(f"Invalid hreflang code: {code}")
+            suggestions.append("Use BCP 47 tags (e.g. en, en-US) or x-default")
+        if code in codes_seen and codes_seen[code] != target:
+            score -= 20
+            findings.append(f"Duplicate hreflang '{code}' with different hrefs")
+        codes_seen[code] = target
+        if code == "x-default":
+            has_x_default = True
+        else:
+            lang_codes.add(code)
+        parsed = urlparse(target)
+        if not parsed.scheme:
+            score -= 15
+            findings.append(f"Non-absolute hreflang href: {target[:60]}")
+            suggestions.append("Use absolute URLs in hreflang link tags")
+        if _page_key(target) == from_key:
+            self_ref = True
+    if len(lang_codes) >= 2 and not has_x_default:
+        score -= 20
+        findings.append("Missing x-default with multiple language alternates")
+        suggestions.append("Add <link rel='alternate' hreflang='x-default' href='...'>")
+    if not self_ref:
+        score -= 15
+        findings.append("Page does not self-reference in hreflang cluster")
+        suggestions.append("Include a self-referencing hreflang link for this URL")
+    if not findings:
+        findings.append(f"Hreflang cluster OK ({len(alternates)} alternate(s))")
+    score = clamp_score(score)
+    return CheckResult(
+        name="hreflang",
+        score=score,
+        weight=weight,
+        status=status_from_score(score),
+        findings=findings,
+        suggestions=suggestions,
+    )
+def validate_hreflang_reciprocity(
+    context: SiteContext,
+    pages: list[PageAudit],
+) -> None:
+    """Augment page hreflang results when return links are missing."""
+    edges = context.hreflang_edges[:MAX_EDGES]
+    if not edges:
+        return
+    by_from: dict[str, list[tuple[str, str]]] = {}
+    for from_key, code, to_key in edges:
+        by_from.setdefault(from_key, []).append((code, to_key))
+    page_by_key: dict[str, PageAudit] = {}
+    for pa in pages:
+        page_by_key[_page_key(pa.page.final_url)] = pa
+    missing: list[tuple[str, str, str]] = []
+    for from_key, code, to_key in edges:
+        if code == "x-default":
+            continue
+        back = by_from.get(to_key, [])
+        if not any(c == code and t == from_key for c, t in back):
+            missing.append((from_key, code, to_key))
+    if not missing:
+        return
+    for from_key, code, to_key in missing[:10]:
+        pa = page_by_key.get(from_key)
+        if not pa:
+            continue
+        r = pa.results.get("hreflang")
+        if not r:
+            continue
+        msg = f"Missing return hreflang '{code}' from {to_key}"
+        if msg not in r.findings:
+            r.findings.append(msg)
+            r.suggestions.append(
+                "Ensure each hreflang target page links back with the same hreflang code"
+            )
+            r.score = clamp_score(r.score - 15)
+            r.status = status_from_score(r.score)

seobuddy/checks/images.py ADDED Viewed

@@ -0,0 +1,49 @@
+"""Image alt text and lazy loading check."""
+from __future__ import annotations
+from bs4 import BeautifulSoup
+from seobuddy.checks.base import CATEGORY_WEIGHTS, clamp_score, status_from_score
+from seobuddy.models import CheckResult, CheckStatus, PageData, SiteContext
+def check(soup: BeautifulSoup, page: PageData, context: SiteContext) -> CheckResult:
+    weight = CATEGORY_WEIGHTS["images"]
+    findings: list[str] = []
+    suggestions: list[str] = []
+    imgs = soup.find_all("img")
+    if not imgs:
+        return CheckResult(
+            name="images",
+            score=100,
+            weight=weight,
+            status=CheckStatus.PASS,
+            findings=["No images on page"],
+        )
+    with_alt = sum(1 for img in imgs if (img.get("alt") or "").strip())
+    missing = len(imgs) - with_alt
+    pct = with_alt / len(imgs) * 100
+    score = clamp_score(pct)
+    if missing:
+        findings.append(f"{missing}/{len(imgs)} images missing alt text")
+        suggestions.append("Add descriptive alt attributes to all images")
+    lazy = any((img.get("loading") or "").lower() == "lazy" for img in imgs)
+    if lazy:
+        findings.append("Lazy loading detected on at least one image")
+    if not missing:
+        findings.append("All images have alt text")
+    return CheckResult(
+        name="images",
+        score=score,
+        weight=weight,
+        status=status_from_score(score),
+        findings=findings,
+        suggestions=suggestions,
+    )