seoslug 1.0.0__tar.gz

seoslug-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 seoslug contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

seoslug-1.0.0/PKG-INFO

@@ -0,0 +1,77 @@
+Metadata-Version: 2.4
+Name: seoslug
+Version: 1.0.0
+Summary: Framework-agnostic canonical URL normalization and SEO payload generation
+Author: seoslug contributors
+License-Expression: MIT
+Project-URL: Documentation, https://deepwiki.com/emiliano-gandini-outeda/seoslug/
+Keywords: seo,canonical,urls,metadata,open-graph,twitter-cards
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# seoslug
+
+[![DeepWiki](https://img.shields.io/badge/DeepWiki-Documentation-blue)](https://deepwiki.com/emiliano-gandini-outeda/seoslug/)
+
+Canonical URL normalization and deterministic SEO payload generation for content platforms.
+
+## Installation
+
+```bash
+pip install seoslug
+```
+
+For local development:
+
+```bash
+pip install -e .
+```
+
+## Quick usage
+
+```python
+from seoslug import SEOConfig, URLPolicy, SEOEntity, build_seo_payload
+
+config = SEOConfig(
+    canonical_host="portal.example.com",
+    public_base_url="https://portal.example.com",
+    url_policy=URLPolicy(
+        enforce_https=True,
+        lowercase_paths=True,
+        trailing_slash="never",
+        collapse_duplicate_slashes=True,
+        strip_tracking_params=True,
+        allowed_query_params=["page", "q"],
+    ),
+    default_og_image="https://cdn.example.com/default.jpg",
+)
+
+entity = SEOEntity(
+    entity_type="post",
+    slug="my-post",
+    title="My Post",
+    excerpt="Example excerpt",
+    body_html="<p>Body content</p>",
+    status="published",
+    featured_image="https://cdn.example.com/post.jpg",
+)
+
+payload = build_seo_payload(entity, "/posts/my-post", config)
+```
+
+Full docs, API reference, and usage examples are in `docs/` and published with MkDocs.
+
+## License
+
+MIT, see `LICENSE`.

seoslug-1.0.0/README.md

@@ -0,0 +1,55 @@
+# seoslug
+
+[![DeepWiki](https://img.shields.io/badge/DeepWiki-Documentation-blue)](https://deepwiki.com/emiliano-gandini-outeda/seoslug/)
+
+Canonical URL normalization and deterministic SEO payload generation for content platforms.
+
+## Installation
+
+```bash
+pip install seoslug
+```
+
+For local development:
+
+```bash
+pip install -e .
+```
+
+## Quick usage
+
+```python
+from seoslug import SEOConfig, URLPolicy, SEOEntity, build_seo_payload
+
+config = SEOConfig(
+    canonical_host="portal.example.com",
+    public_base_url="https://portal.example.com",
+    url_policy=URLPolicy(
+        enforce_https=True,
+        lowercase_paths=True,
+        trailing_slash="never",
+        collapse_duplicate_slashes=True,
+        strip_tracking_params=True,
+        allowed_query_params=["page", "q"],
+    ),
+    default_og_image="https://cdn.example.com/default.jpg",
+)
+
+entity = SEOEntity(
+    entity_type="post",
+    slug="my-post",
+    title="My Post",
+    excerpt="Example excerpt",
+    body_html="<p>Body content</p>",
+    status="published",
+    featured_image="https://cdn.example.com/post.jpg",
+)
+
+payload = build_seo_payload(entity, "/posts/my-post", config)
+```
+
+Full docs, API reference, and usage examples are in `docs/` and published with MkDocs.
+
+## License
+
+MIT, see `LICENSE`.

seoslug-1.0.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "seoslug"
+version = "1.0.0"
+description = "Framework-agnostic canonical URL normalization and SEO payload generation"
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [{ name = "seoslug contributors" }]
+license = "MIT"
+keywords = ["seo", "canonical", "urls", "metadata", "open-graph", "twitter-cards"]
+classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Internet :: WWW/HTTP",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = []
+license-files = ["LICENSE"]
+
+[project.urls]
+Documentation = "https://deepwiki.com/emiliano-gandini-outeda/seoslug/"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]

seoslug-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

seoslug-1.0.0/src/seoslug/__init__.py

@@ -0,0 +1,16 @@
+"""Public API for seoslug."""
+
+from .builder import build_seo_payload
+from .config import SEOConfig, URLPolicy
+from .normalization import normalize_path, normalize_public_url
+from .schemas import SEOEntity, SEOOverrides
+
+__all__ = [
+    "SEOConfig",
+    "URLPolicy",
+    "SEOEntity",
+    "SEOOverrides",
+    "normalize_public_url",
+    "normalize_path",
+    "build_seo_payload",
+]

seoslug-1.0.0/src/seoslug/builder.py

@@ -0,0 +1,81 @@
+"""SEO payload builder for seoslug."""
+
+from .config import SEOConfig
+from .jsonld import normalize_schema_jsonld
+from .normalization import normalize_public_url
+from .schemas import SEOEntity, SEOOverrides
+from .text import build_description_snippet
+
+
+def _pick(*values: str | None) -> str | None:
+    for value in values:
+        if isinstance(value, str) and value.strip():
+            return value.strip()
+    return None
+
+
+def _entity_default_robots(entity: SEOEntity, config: SEOConfig) -> str:
+    if entity.entity_type == "search":
+        return config.search_robots
+    if (entity.status or "").lower() == "published":
+        return "index,follow"
+    return config.default_robots
+
+
+def _og_type(entity: SEOEntity) -> str:
+    if entity.entity_type in {"post", "video"}:
+        return "article"
+    return "website"
+
+
+def build_seo_payload(
+    entity: SEOEntity,
+    route_path: str,
+    config: SEOConfig,
+    overrides: SEOOverrides | None = None,
+) -> dict:
+    ov = overrides or SEOOverrides()
+
+    title = _pick(ov.meta_title, entity.title, "Untitled")
+    if config.title_template:
+        title = config.title_template.format(title=title)
+
+    description = _pick(
+        ov.meta_description,
+        entity.excerpt,
+        build_description_snippet(entity.body_html),
+        "",
+    )
+
+    canonical = _pick(ov.canonical_url, normalize_public_url(route_path, config))
+    robots = _pick(ov.robots, _entity_default_robots(entity, config))
+
+    og_title = _pick(ov.og_title, title)
+    og_description = _pick(ov.og_description, description)
+    og_image = _pick(ov.og_image, entity.featured_image, config.default_og_image)
+
+    twitter_title = _pick(ov.twitter_title, og_title)
+    twitter_description = _pick(ov.twitter_description, og_description)
+    twitter_image = _pick(ov.twitter_image, og_image)
+    twitter_card = _pick(ov.twitter_card, "summary_large_image")
+
+    return {
+        "title": title,
+        "description": description,
+        "canonical": canonical,
+        "robots": robots,
+        "og": {
+            "type": _og_type(entity),
+            "title": og_title,
+            "description": og_description,
+            "url": canonical,
+            "image": og_image,
+        },
+        "twitter": {
+            "card": twitter_card,
+            "title": twitter_title,
+            "description": twitter_description,
+            "image": twitter_image,
+        },
+        "schema_jsonld": normalize_schema_jsonld(ov.schema_jsonld),
+    }

seoslug-1.0.0/src/seoslug/config.py

@@ -0,0 +1,97 @@
+"""Configuration models for seoslug."""
+
+from dataclasses import dataclass, field
+from typing import Literal
+from urllib.parse import urlparse
+
+
+@dataclass(slots=True)
+class URLPolicy:
+    enforce_https: bool = True
+    lowercase_paths: bool = True
+    trailing_slash: Literal["always", "never", "preserve"] = "never"
+    collapse_duplicate_slashes: bool = True
+    strip_tracking_params: bool = True
+    allowed_query_params: list[str] = field(default_factory=list)
+
+    def __post_init__(self) -> None:
+        if self.trailing_slash not in {"always", "never", "preserve"}:
+            raise ValueError(
+                "trailing_slash must be one of: 'always', 'never', 'preserve'"
+            )
+
+        cleaned_params: list[str] = []
+        seen: set[str] = set()
+        for param in self.allowed_query_params:
+            if not isinstance(param, str):
+                raise ValueError("allowed_query_params must contain only strings")
+            normalized = param.strip()
+            if not normalized:
+                continue
+            if normalized not in seen:
+                seen.add(normalized)
+                cleaned_params.append(normalized)
+        self.allowed_query_params = cleaned_params
+
+
+@dataclass(slots=True)
+class SEOConfig:
+    canonical_host: str
+    public_base_url: str
+    url_policy: URLPolicy
+    default_robots: str = "index,follow"
+    default_og_image: str | None = None
+    site_name: str | None = None
+    title_template: str | None = "{title}"
+    search_robots: str = "noindex,follow"
+
+    def __post_init__(self) -> None:
+        self.canonical_host = _validate_canonical_host(self.canonical_host)
+        self.public_base_url = _validate_public_base_url(self.public_base_url)
+
+        if not isinstance(self.url_policy, URLPolicy):
+            raise ValueError("url_policy must be a URLPolicy instance")
+
+        if not _is_nonempty_string(self.default_robots):
+            raise ValueError("default_robots must be a non-empty string")
+        if not _is_nonempty_string(self.search_robots):
+            raise ValueError("search_robots must be a non-empty string")
+
+        if self.default_og_image is not None and not _is_nonempty_string(
+            self.default_og_image
+        ):
+            raise ValueError("default_og_image must be a non-empty string when set")
+
+        if self.site_name is not None and not _is_nonempty_string(self.site_name):
+            raise ValueError("site_name must be a non-empty string when set")
+
+        if self.title_template is not None:
+            if not _is_nonempty_string(self.title_template):
+                raise ValueError("title_template must be a non-empty string when set")
+            if "{title}" not in self.title_template:
+                raise ValueError("title_template must include '{title}' placeholder")
+
+
+def _is_nonempty_string(value: object) -> bool:
+    return isinstance(value, str) and bool(value.strip())
+
+
+def _validate_canonical_host(canonical_host: str) -> str:
+    if not _is_nonempty_string(canonical_host):
+        raise ValueError("canonical_host must be a non-empty string")
+
+    value = canonical_host.strip().lower()
+    if "://" in value or "/" in value or "?" in value or "#" in value:
+        raise ValueError("canonical_host must be host-only (no scheme/path/query)")
+    return value
+
+
+def _validate_public_base_url(public_base_url: str) -> str:
+    if not _is_nonempty_string(public_base_url):
+        raise ValueError("public_base_url must be a non-empty string")
+
+    value = public_base_url.strip()
+    parsed = urlparse(value)
+    if parsed.scheme not in {"http", "https"} or not parsed.netloc:
+        raise ValueError("public_base_url must be an absolute http(s) URL")
+    return value

seoslug-1.0.0/src/seoslug/jsonld.py

@@ -0,0 +1,13 @@
+"""JSON-LD helpers for seoslug."""
+
+from copy import deepcopy
+
+
+def normalize_schema_jsonld(value: dict | list[dict] | None) -> dict | list[dict]:
+    if value is None:
+        return {}
+    if isinstance(value, dict):
+        return deepcopy(value)
+    if isinstance(value, list) and all(isinstance(item, dict) for item in value):
+        return deepcopy(value)
+    raise ValueError("schema_jsonld must be dict, list[dict], or None")

seoslug-1.0.0/src/seoslug/normalization.py

@@ -0,0 +1,85 @@
+"""URL normalization functions for seoslug."""
+
+from urllib.parse import parse_qsl, urlencode, urlsplit, urlunsplit
+
+from .config import SEOConfig, URLPolicy
+
+_TRACKING_KEYS = {"gclid", "fbclid"}
+
+
+def _collapse_duplicate_slashes(path: str) -> str:
+    out: list[str] = []
+    prev_slash = False
+    for char in path:
+        if char == "/":
+            if prev_slash:
+                continue
+            prev_slash = True
+            out.append(char)
+        else:
+            prev_slash = False
+            out.append(char)
+    return "".join(out)
+
+
+def _apply_trailing_slash(path: str, mode: str) -> str:
+    if mode == "preserve":
+        return path
+    if path == "/":
+        return path
+    if mode == "always":
+        return path if path.endswith("/") else path + "/"
+    return path.rstrip("/") or "/"
+
+
+def normalize_path(path: str, policy: URLPolicy) -> str:
+    if not isinstance(path, str):
+        raise ValueError("path must be a string")
+    value = path.strip() or "/"
+    if not value.startswith("/"):
+        value = "/" + value
+    if policy.collapse_duplicate_slashes:
+        value = _collapse_duplicate_slashes(value)
+    if policy.lowercase_paths:
+        value = value.lower()
+    value = _apply_trailing_slash(value, policy.trailing_slash)
+    return value
+
+
+def _filter_query(query: str, policy: URLPolicy) -> str:
+    pairs = parse_qsl(query, keep_blank_values=True)
+    filtered: list[tuple[str, str]] = []
+    allowlist = set(policy.allowed_query_params)
+    for key, value in pairs:
+        k = key.lower()
+        if policy.strip_tracking_params and (k.startswith("utm_") or k in _TRACKING_KEYS):
+            continue
+        if allowlist and key not in allowlist:
+            continue
+        filtered.append((key, value))
+    return urlencode(filtered, doseq=True)
+
+
+def normalize_public_url(url_or_path: str, config: SEOConfig) -> str:
+    if not isinstance(url_or_path, str) or not url_or_path.strip():
+        raise ValueError("url_or_path must be a non-empty string")
+
+    value = url_or_path.strip()
+    parsed_input = urlsplit(value)
+    parsed_base = urlsplit(config.public_base_url)
+
+    if parsed_input.scheme and not parsed_input.netloc:
+        raise ValueError("Malformed URL input")
+
+    path = parsed_input.path
+    query = parsed_input.query
+    if not parsed_input.scheme and not parsed_input.netloc:
+        path = value.split("?", 1)[0]
+        query = value.split("?", 1)[1] if "?" in value else ""
+
+    normalized_path = normalize_path(path or "/", config.url_policy)
+    normalized_query = _filter_query(query, config.url_policy)
+
+    scheme = "https" if config.url_policy.enforce_https else (parsed_base.scheme or "https")
+    netloc = config.canonical_host
+    return urlunsplit((scheme, netloc, normalized_path, normalized_query, ""))

seoslug-1.0.0/src/seoslug/schemas.py

@@ -0,0 +1,87 @@
+"""Input schemas for seoslug."""
+
+from dataclasses import dataclass
+from typing import Literal
+
+
+_ENTITY_TYPES = {"home", "post", "page", "video", "taxonomy", "search", "other"}
+
+
+def _normalize_optional_string(value: object, field_name: str) -> str | None:
+    if value is None:
+        return None
+    if not isinstance(value, str):
+        raise ValueError(f"{field_name} must be a string or None")
+    normalized = value.strip()
+    return normalized or None
+
+
+@dataclass(slots=True)
+class SEOEntity:
+    entity_type: Literal["home", "post", "page", "video", "taxonomy", "search", "other"]
+    slug: str | None = None
+    title: str | None = None
+    excerpt: str | None = None
+    body_html: str | None = None
+    status: str | None = None
+    featured_image: str | None = None
+    published_at: str | None = None
+    updated_at: str | None = None
+
+    def __post_init__(self) -> None:
+        if self.entity_type not in _ENTITY_TYPES:
+            raise ValueError("entity_type must be one of home/post/page/video/taxonomy/search/other")
+
+        self.slug = _normalize_optional_string(self.slug, "slug")
+        self.title = _normalize_optional_string(self.title, "title")
+        self.excerpt = _normalize_optional_string(self.excerpt, "excerpt")
+        self.body_html = _normalize_optional_string(self.body_html, "body_html")
+        self.status = _normalize_optional_string(self.status, "status")
+        self.featured_image = _normalize_optional_string(self.featured_image, "featured_image")
+        self.published_at = _normalize_optional_string(self.published_at, "published_at")
+        self.updated_at = _normalize_optional_string(self.updated_at, "updated_at")
+
+
+@dataclass(slots=True)
+class SEOOverrides:
+    meta_title: str | None = None
+    meta_description: str | None = None
+    canonical_url: str | None = None
+    robots: str | None = None
+    og_title: str | None = None
+    og_description: str | None = None
+    og_image: str | None = None
+    twitter_card: str | None = None
+    twitter_title: str | None = None
+    twitter_description: str | None = None
+    twitter_image: str | None = None
+    schema_jsonld: dict | list[dict] | None = None
+
+    def __post_init__(self) -> None:
+        self.meta_title = _normalize_optional_string(self.meta_title, "meta_title")
+        self.meta_description = _normalize_optional_string(
+            self.meta_description, "meta_description"
+        )
+        self.canonical_url = _normalize_optional_string(self.canonical_url, "canonical_url")
+        self.robots = _normalize_optional_string(self.robots, "robots")
+        self.og_title = _normalize_optional_string(self.og_title, "og_title")
+        self.og_description = _normalize_optional_string(
+            self.og_description, "og_description"
+        )
+        self.og_image = _normalize_optional_string(self.og_image, "og_image")
+        self.twitter_card = _normalize_optional_string(self.twitter_card, "twitter_card")
+        self.twitter_title = _normalize_optional_string(self.twitter_title, "twitter_title")
+        self.twitter_description = _normalize_optional_string(
+            self.twitter_description, "twitter_description"
+        )
+        self.twitter_image = _normalize_optional_string(self.twitter_image, "twitter_image")
+
+        if self.schema_jsonld is None:
+            return
+        if isinstance(self.schema_jsonld, dict):
+            return
+        if isinstance(self.schema_jsonld, list) and all(
+            isinstance(item, dict) for item in self.schema_jsonld
+        ):
+            return
+        raise ValueError("schema_jsonld must be dict, list[dict], or None")

seoslug-1.0.0/src/seoslug/text.py

@@ -0,0 +1,34 @@
+"""Text extraction utilities for seoslug."""
+
+import re
+from html import unescape
+
+_SCRIPT_STYLE_RE = re.compile(
+    r"<(script|style)\b[^>]*>.*?</\1>", re.IGNORECASE | re.DOTALL
+)
+_TAG_RE = re.compile(r"<[^>]+>")
+_WS_RE = re.compile(r"\s+")
+
+
+def html_to_text(html: str | None) -> str:
+    if html is None:
+        return ""
+    if not isinstance(html, str):
+        raise ValueError("html must be a string or None")
+    if not html:
+        return ""
+    text = _SCRIPT_STYLE_RE.sub(" ", html)
+    text = _TAG_RE.sub(" ", text)
+    text = unescape(text)
+    return _WS_RE.sub(" ", text).strip()
+
+
+def build_description_snippet(body_html: str | None, max_length: int = 160) -> str:
+    if not isinstance(max_length, int) or max_length <= 0:
+        raise ValueError("max_length must be a positive integer")
+    text = html_to_text(body_html)
+    if len(text) <= max_length:
+        return text
+    if max_length <= 3:
+        return "." * max_length
+    return text[: max_length - 3].rstrip() + "..."

seoslug-1.0.0/src/seoslug.egg-info/PKG-INFO

@@ -0,0 +1,77 @@
+Metadata-Version: 2.4
+Name: seoslug
+Version: 1.0.0
+Summary: Framework-agnostic canonical URL normalization and SEO payload generation
+Author: seoslug contributors
+License-Expression: MIT
+Project-URL: Documentation, https://deepwiki.com/emiliano-gandini-outeda/seoslug/
+Keywords: seo,canonical,urls,metadata,open-graph,twitter-cards
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# seoslug
+
+[![DeepWiki](https://img.shields.io/badge/DeepWiki-Documentation-blue)](https://deepwiki.com/emiliano-gandini-outeda/seoslug/)
+
+Canonical URL normalization and deterministic SEO payload generation for content platforms.
+
+## Installation
+
+```bash
+pip install seoslug
+```
+
+For local development:
+
+```bash
+pip install -e .
+```
+
+## Quick usage
+
+```python
+from seoslug import SEOConfig, URLPolicy, SEOEntity, build_seo_payload
+
+config = SEOConfig(
+    canonical_host="portal.example.com",
+    public_base_url="https://portal.example.com",
+    url_policy=URLPolicy(
+        enforce_https=True,
+        lowercase_paths=True,
+        trailing_slash="never",
+        collapse_duplicate_slashes=True,
+        strip_tracking_params=True,
+        allowed_query_params=["page", "q"],
+    ),
+    default_og_image="https://cdn.example.com/default.jpg",
+)
+
+entity = SEOEntity(
+    entity_type="post",
+    slug="my-post",
+    title="My Post",
+    excerpt="Example excerpt",
+    body_html="<p>Body content</p>",
+    status="published",
+    featured_image="https://cdn.example.com/post.jpg",
+)
+
+payload = build_seo_payload(entity, "/posts/my-post", config)
+```
+
+Full docs, API reference, and usage examples are in `docs/` and published with MkDocs.
+
+## License
+
+MIT, see `LICENSE`.

seoslug-1.0.0/src/seoslug.egg-info/SOURCES.txt

@@ -0,0 +1,22 @@
+LICENSE
+README.md
+pyproject.toml
+src/seoslug/__init__.py
+src/seoslug/builder.py
+src/seoslug/config.py
+src/seoslug/jsonld.py
+src/seoslug/normalization.py
+src/seoslug/schemas.py
+src/seoslug/text.py
+src/seoslug.egg-info/PKG-INFO
+src/seoslug.egg-info/SOURCES.txt
+src/seoslug.egg-info/dependency_links.txt
+src/seoslug.egg-info/top_level.txt
+tests/test_builder.py
+tests/test_fallbacks.py
+tests/test_jsonld.py
+tests/test_normalization.py
+tests/test_regression_fixtures.py
+tests/test_robots_rules.py
+tests/test_schemas.py
+tests/test_text.py

seoslug-1.0.0/src/seoslug.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

seoslug-1.0.0/src/seoslug.egg-info/top_level.txt

@@ -0,0 +1 @@
+seoslug

seoslug-1.0.0/tests/test_builder.py

@@ -0,0 +1,105 @@
+"""Tests for SEO payload builder."""
+
+from seoslug import SEOConfig, SEOEntity, SEOOverrides, URLPolicy, build_seo_payload
+
+
+def _config() -> SEOConfig:
+    return SEOConfig(
+        canonical_host="portal.example.com",
+        public_base_url="https://portal.example.com",
+        url_policy=URLPolicy(),
+        default_og_image="https://cdn.example.com/default.jpg",
+        site_name="Portal",
+        title_template="{title}",
+    )
+
+
+def test_payload_contract_shape() -> None:
+    entity = SEOEntity(
+        entity_type="post",
+        slug="my-post",
+        title="My Post",
+        excerpt="Example excerpt",
+        body_html="<p>Body</p>",
+        status="published",
+        featured_image="https://cdn.example.com/post.jpg",
+    )
+    payload = build_seo_payload(entity, "/posts/my-post", _config())
+
+    assert set(payload.keys()) == {
+        "title",
+        "description",
+        "canonical",
+        "robots",
+        "og",
+        "twitter",
+        "schema_jsonld",
+    }
+    assert payload["canonical"] == "https://portal.example.com/posts/my-post"
+    assert payload["og"]["url"] == payload["canonical"]
+    assert payload["twitter"]["card"] == "summary_large_image"
+
+
+def test_canonical_override_and_schema_passthrough() -> None:
+    entity = SEOEntity(entity_type="page", title="About")
+    overrides = SEOOverrides(
+        canonical_url="https://portal.example.com/custom-about",
+        schema_jsonld={"@context": "https://schema.org", "@type": "WebPage"},
+    )
+    payload = build_seo_payload(entity, "/about", _config(), overrides)
+    assert payload["canonical"] == "https://portal.example.com/custom-about"
+    assert payload["schema_jsonld"]["@type"] == "WebPage"
+
+
+def test_twitter_override_precedence() -> None:
+    entity = SEOEntity(entity_type="post", title="Entity Title", excerpt="Entity Excerpt")
+    overrides = SEOOverrides(
+        og_title="OG Title",
+        twitter_title="Twitter Title",
+        twitter_description="Twitter Description",
+    )
+    payload = build_seo_payload(entity, "/posts/t", _config(), overrides)
+    assert payload["og"]["title"] == "OG Title"
+    assert payload["twitter"]["title"] == "Twitter Title"
+    assert payload["twitter"]["description"] == "Twitter Description"
+
+
+def test_schema_list_passthrough() -> None:
+    entity = SEOEntity(entity_type="page", title="Docs")
+    schema = [{"@type": "BreadcrumbList"}, {"@type": "WebPage"}]
+    payload = build_seo_payload(entity, "/docs", _config(), SEOOverrides(schema_jsonld=schema))
+    assert payload["schema_jsonld"] == schema
+
+
+def test_title_template_is_applied() -> None:
+    config = SEOConfig(
+        canonical_host="portal.example.com",
+        public_base_url="https://portal.example.com",
+        url_policy=URLPolicy(),
+        title_template="{title} | Portal",
+    )
+    payload = build_seo_payload(SEOEntity(entity_type="page", title="About"), "/about", config)
+    assert payload["title"] == "About | Portal"
+
+
+def test_description_prefers_excerpt_over_body_snippet() -> None:
+    entity = SEOEntity(
+        entity_type="post",
+        excerpt="Excerpt text",
+        body_html="<p>Body fallback text</p>",
+    )
+    payload = build_seo_payload(entity, "/posts/p", _config())
+    assert payload["description"] == "Excerpt text"
+
+
+def test_twitter_falls_back_to_og_values() -> None:
+    entity = SEOEntity(entity_type="post", title="Entity")
+    overrides = SEOOverrides(
+        og_title="OG T",
+        og_description="OG D",
+        og_image="https://cdn.example.com/og.jpg",
+    )
+    payload = build_seo_payload(entity, "/posts/p", _config(), overrides)
+    assert payload["twitter"]["title"] == "OG T"
+    assert payload["twitter"]["description"] == "OG D"
+    assert payload["twitter"]["image"] == "https://cdn.example.com/og.jpg"

seoslug-1.0.0/tests/test_fallbacks.py

@@ -0,0 +1,79 @@
+"""Tests for fallback hierarchy behavior."""
+
+from seoslug import SEOConfig, SEOEntity, SEOOverrides, URLPolicy, build_seo_payload
+
+
+def _config() -> SEOConfig:
+    return SEOConfig(
+        canonical_host="portal.example.com",
+        public_base_url="https://portal.example.com",
+        url_policy=URLPolicy(),
+        default_og_image="https://cdn.example.com/default.jpg",
+    )
+
+
+def test_title_and_description_fallbacks() -> None:
+    entity = SEOEntity(entity_type="post", title=None, excerpt=None, body_html="<p>Hello body</p>")
+    payload = build_seo_payload(entity, "/x", _config())
+    assert payload["title"] == "Untitled"
+    assert payload["description"] == "Hello body"
+
+
+def test_override_precedence() -> None:
+    entity = SEOEntity(entity_type="post", title="Entity title", excerpt="Entity desc")
+    ov = SEOOverrides(meta_title="Override title", meta_description="Override desc")
+    payload = build_seo_payload(entity, "/x", _config(), ov)
+    assert payload["title"] == "Override title"
+    assert payload["description"] == "Override desc"
+
+
+def test_og_and_twitter_image_fallbacks() -> None:
+    entity = SEOEntity(entity_type="post", featured_image=None)
+    payload = build_seo_payload(entity, "/x", _config())
+    assert payload["og"]["image"] == "https://cdn.example.com/default.jpg"
+    assert payload["twitter"]["image"] == "https://cdn.example.com/default.jpg"
+
+
+def test_canonical_fallback_uses_normalized_route() -> None:
+    entity = SEOEntity(entity_type="page", title="About")
+    payload = build_seo_payload(entity, "/About//Team?utm_source=x", _config())
+    assert payload["canonical"] == "https://portal.example.com/about/team"
+
+
+def test_og_image_precedence_override_then_entity_then_default() -> None:
+    base_entity = SEOEntity(entity_type="post", featured_image="https://cdn.example.com/entity.jpg")
+    with_override = build_seo_payload(
+        base_entity,
+        "/x",
+        _config(),
+        SEOOverrides(og_image="https://cdn.example.com/override.jpg"),
+    )
+    assert with_override["og"]["image"] == "https://cdn.example.com/override.jpg"
+
+    without_override = build_seo_payload(base_entity, "/x", _config())
+    assert without_override["og"]["image"] == "https://cdn.example.com/entity.jpg"
+
+    no_entity_image = build_seo_payload(SEOEntity(entity_type="post"), "/x", _config())
+    assert no_entity_image["og"]["image"] == "https://cdn.example.com/default.jpg"
+
+
+def test_twitter_override_fields_take_highest_precedence() -> None:
+    entity = SEOEntity(entity_type="post", title="Entity", excerpt="Excerpt")
+    payload = build_seo_payload(
+        entity,
+        "/x",
+        _config(),
+        SEOOverrides(
+            twitter_card="summary",
+            twitter_title="Tw Title",
+            twitter_description="Tw Desc",
+            twitter_image="https://cdn.example.com/tw.jpg",
+            og_title="OG Title",
+            og_description="OG Desc",
+            og_image="https://cdn.example.com/og.jpg",
+        ),
+    )
+    assert payload["twitter"]["card"] == "summary"
+    assert payload["twitter"]["title"] == "Tw Title"
+    assert payload["twitter"]["description"] == "Tw Desc"
+    assert payload["twitter"]["image"] == "https://cdn.example.com/tw.jpg"

seoslug-1.0.0/tests/test_jsonld.py

@@ -0,0 +1,28 @@
+"""Tests for JSON-LD normalization helpers."""
+
+import pytest
+
+from seoslug.jsonld import normalize_schema_jsonld
+
+
+def test_normalize_schema_jsonld_none_to_empty_dict() -> None:
+    assert normalize_schema_jsonld(None) == {}
+
+
+def test_normalize_schema_jsonld_returns_copy_for_dict() -> None:
+    schema = {"@type": "WebPage", "name": "Home"}
+    normalized = normalize_schema_jsonld(schema)
+    assert normalized == schema
+    assert normalized is not schema
+
+
+def test_normalize_schema_jsonld_returns_copy_for_list() -> None:
+    schema = [{"@type": "WebPage"}, {"@type": "BreadcrumbList"}]
+    normalized = normalize_schema_jsonld(schema)
+    assert normalized == schema
+    assert normalized is not schema
+
+
+def test_normalize_schema_jsonld_rejects_invalid_type() -> None:
+    with pytest.raises(ValueError):
+        normalize_schema_jsonld("bad")  # type: ignore[arg-type]

seoslug-1.0.0/tests/test_normalization.py

@@ -0,0 +1,86 @@
+"""Tests for URL normalization."""
+
+from seoslug import SEOConfig, URLPolicy, normalize_path, normalize_public_url
+import pytest
+
+
+def _config(policy: URLPolicy | None = None) -> SEOConfig:
+    return SEOConfig(
+        canonical_host="portal.example.com",
+        public_base_url="https://portal.example.com",
+        url_policy=policy or URLPolicy(),
+    )
+
+
+def test_normalize_path_lowercase_and_slashes() -> None:
+    policy = URLPolicy(lowercase_paths=True, collapse_duplicate_slashes=True)
+    assert normalize_path("//Blog//My-Post//", policy) == "/blog/my-post"
+
+
+def test_trailing_slash_modes() -> None:
+    assert normalize_path("/blog/post", URLPolicy(trailing_slash="always")) == "/blog/post/"
+    assert normalize_path("/blog/post/", URLPolicy(trailing_slash="never")) == "/blog/post"
+    assert normalize_path("/blog/post/", URLPolicy(trailing_slash="preserve")) == "/blog/post/"
+
+
+def test_normalize_public_url_enforces_host_https_and_query_rules() -> None:
+    config = _config(URLPolicy(allowed_query_params=["page", "q"]))
+    url = "http://other.example.com//Blog/Post?utm_source=x&gclid=1&page=2&q=abc&bad=1"
+    assert (
+        normalize_public_url(url, config)
+        == "https://portal.example.com/blog/post?page=2&q=abc"
+    )
+
+
+def test_normalize_public_url_idempotent() -> None:
+    config = _config()
+    first = normalize_public_url("/A//B/?utm_campaign=x", config)
+    second = normalize_public_url(first, config)
+    assert first == second
+
+
+def test_accepts_relative_path_with_query() -> None:
+    config = _config()
+    assert (
+        normalize_public_url("posts/My-Post?fbclid=123&page=1", config)
+        == "https://portal.example.com/posts/my-post?page=1"
+    )
+
+
+def test_enforce_https_toggle_uses_public_base_scheme() -> None:
+    config = SEOConfig(
+        canonical_host="portal.example.com",
+        public_base_url="http://portal.example.com",
+        url_policy=URLPolicy(enforce_https=False),
+    )
+    assert normalize_public_url("https://other.example.com/a", config) == "http://portal.example.com/a"
+
+
+def test_tracking_strip_toggle() -> None:
+    config = _config(URLPolicy(strip_tracking_params=False))
+    assert (
+        normalize_public_url("/p?utm_source=x&gclid=1&fbclid=2", config)
+        == "https://portal.example.com/p?utm_source=x&gclid=1&fbclid=2"
+    )
+
+
+def test_no_allowlist_keeps_non_tracking_params() -> None:
+    config = _config(URLPolicy())
+    assert normalize_public_url("/p?a=1&b=2&utm_campaign=x", config) == "https://portal.example.com/p?a=1&b=2"
+
+
+def test_malformed_url_raises_value_error() -> None:
+    config = _config()
+    with pytest.raises(ValueError):
+        normalize_public_url("https:///broken", config)
+
+
+def test_host_is_always_enforced_for_absolute_input() -> None:
+    config = _config()
+    normalized = normalize_public_url("https://evil.example.org/path", config)
+    assert normalized == "https://portal.example.com/path"
+
+
+def test_can_disable_duplicate_slash_collapse_and_lowercase() -> None:
+    policy = URLPolicy(collapse_duplicate_slashes=False, lowercase_paths=False, trailing_slash="preserve")
+    assert normalize_path("//Blog//Post//", policy) == "//Blog//Post//"

seoslug-1.0.0/tests/test_regression_fixtures.py

@@ -0,0 +1,179 @@
+"""Regression fixtures for representative entity types."""
+
+import pytest
+
+from seoslug import SEOConfig, SEOEntity, URLPolicy, build_seo_payload
+
+
+def _config() -> SEOConfig:
+    return SEOConfig(
+        canonical_host="portal.example.com",
+        public_base_url="https://portal.example.com",
+        url_policy=URLPolicy(),
+        default_og_image="https://cdn.example.com/default.jpg",
+        search_robots="noindex,follow",
+    )
+
+
+@pytest.mark.parametrize(
+    ("entity_type", "route", "expected"),
+    [
+        (
+            "home",
+            "/",
+            {
+                "title": "home title",
+                "description": "home excerpt",
+                "canonical": "https://portal.example.com/",
+                "robots": "index,follow",
+                "og": {
+                    "type": "website",
+                    "title": "home title",
+                    "description": "home excerpt",
+                    "url": "https://portal.example.com/",
+                    "image": "https://cdn.example.com/default.jpg",
+                },
+                "twitter": {
+                    "card": "summary_large_image",
+                    "title": "home title",
+                    "description": "home excerpt",
+                    "image": "https://cdn.example.com/default.jpg",
+                },
+                "schema_jsonld": {},
+            },
+        ),
+        (
+            "post",
+            "/posts/p",
+            {
+                "title": "post title",
+                "description": "post excerpt",
+                "canonical": "https://portal.example.com/posts/p",
+                "robots": "index,follow",
+                "og": {
+                    "type": "article",
+                    "title": "post title",
+                    "description": "post excerpt",
+                    "url": "https://portal.example.com/posts/p",
+                    "image": "https://cdn.example.com/default.jpg",
+                },
+                "twitter": {
+                    "card": "summary_large_image",
+                    "title": "post title",
+                    "description": "post excerpt",
+                    "image": "https://cdn.example.com/default.jpg",
+                },
+                "schema_jsonld": {},
+            },
+        ),
+        (
+            "page",
+            "/about",
+            {
+                "title": "page title",
+                "description": "page excerpt",
+                "canonical": "https://portal.example.com/about",
+                "robots": "index,follow",
+                "og": {
+                    "type": "website",
+                    "title": "page title",
+                    "description": "page excerpt",
+                    "url": "https://portal.example.com/about",
+                    "image": "https://cdn.example.com/default.jpg",
+                },
+                "twitter": {
+                    "card": "summary_large_image",
+                    "title": "page title",
+                    "description": "page excerpt",
+                    "image": "https://cdn.example.com/default.jpg",
+                },
+                "schema_jsonld": {},
+            },
+        ),
+        (
+            "video",
+            "/videos/v",
+            {
+                "title": "video title",
+                "description": "video excerpt",
+                "canonical": "https://portal.example.com/videos/v",
+                "robots": "index,follow",
+                "og": {
+                    "type": "article",
+                    "title": "video title",
+                    "description": "video excerpt",
+                    "url": "https://portal.example.com/videos/v",
+                    "image": "https://cdn.example.com/default.jpg",
+                },
+                "twitter": {
+                    "card": "summary_large_image",
+                    "title": "video title",
+                    "description": "video excerpt",
+                    "image": "https://cdn.example.com/default.jpg",
+                },
+                "schema_jsonld": {},
+            },
+        ),
+        (
+            "taxonomy",
+            "/topics/python",
+            {
+                "title": "taxonomy title",
+                "description": "taxonomy excerpt",
+                "canonical": "https://portal.example.com/topics/python",
+                "robots": "index,follow",
+                "og": {
+                    "type": "website",
+                    "title": "taxonomy title",
+                    "description": "taxonomy excerpt",
+                    "url": "https://portal.example.com/topics/python",
+                    "image": "https://cdn.example.com/default.jpg",
+                },
+                "twitter": {
+                    "card": "summary_large_image",
+                    "title": "taxonomy title",
+                    "description": "taxonomy excerpt",
+                    "image": "https://cdn.example.com/default.jpg",
+                },
+                "schema_jsonld": {},
+            },
+        ),
+        (
+            "search",
+            "/search?q=x",
+            {
+                "title": "search title",
+                "description": "search excerpt",
+                "canonical": "https://portal.example.com/search?q=x",
+                "robots": "noindex,follow",
+                "og": {
+                    "type": "website",
+                    "title": "search title",
+                    "description": "search excerpt",
+                    "url": "https://portal.example.com/search?q=x",
+                    "image": "https://cdn.example.com/default.jpg",
+                },
+                "twitter": {
+                    "card": "summary_large_image",
+                    "title": "search title",
+                    "description": "search excerpt",
+                    "image": "https://cdn.example.com/default.jpg",
+                },
+                "schema_jsonld": {},
+            },
+        ),
+    ],
+)
+def test_regression_entity_type_snapshots(
+    entity_type: str,
+    route: str,
+    expected: dict,
+) -> None:
+    entity = SEOEntity(
+        entity_type=entity_type,
+        title=f"{entity_type} title",
+        excerpt=f"{entity_type} excerpt",
+        status="published",
+    )
+    payload = build_seo_payload(entity, route, _config())
+    assert payload == expected

seoslug-1.0.0/tests/test_robots_rules.py

@@ -0,0 +1,38 @@
+"""Tests for robots rule behavior."""
+
+from seoslug import SEOConfig, SEOEntity, SEOOverrides, URLPolicy, build_seo_payload
+
+
+def _config() -> SEOConfig:
+    return SEOConfig(
+        canonical_host="portal.example.com",
+        public_base_url="https://portal.example.com",
+        url_policy=URLPolicy(),
+        default_robots="index,follow",
+        search_robots="noindex,follow",
+    )
+
+
+def test_published_content_defaults_to_index_follow() -> None:
+    entity = SEOEntity(entity_type="post", status="published")
+    payload = build_seo_payload(entity, "/posts/x", _config())
+    assert payload["robots"] == "index,follow"
+
+
+def test_search_uses_search_robots() -> None:
+    entity = SEOEntity(entity_type="search", status="published")
+    payload = build_seo_payload(entity, "/search?q=x", _config())
+    assert payload["robots"] == "noindex,follow"
+
+
+def test_override_robots_wins() -> None:
+    entity = SEOEntity(entity_type="post", status="draft")
+    ov = SEOOverrides(robots="noindex,nofollow")
+    payload = build_seo_payload(entity, "/posts/x", _config(), ov)
+    assert payload["robots"] == "noindex,nofollow"
+
+
+def test_non_published_uses_default_robots() -> None:
+    entity = SEOEntity(entity_type="post", status="draft")
+    payload = build_seo_payload(entity, "/posts/x", _config())
+    assert payload["robots"] == "index,follow"

seoslug-1.0.0/tests/test_schemas.py

@@ -0,0 +1,36 @@
+"""Tests for SEOEntity and SEOOverrides models."""
+
+import pytest
+
+from seoslug import SEOEntity, SEOOverrides
+
+
+def test_entity_normalizes_optional_string_fields() -> None:
+    entity = SEOEntity(
+        entity_type="post",
+        slug=" my-post ",
+        title="  Hello ",
+        excerpt="   ",
+    )
+    assert entity.slug == "my-post"
+    assert entity.title == "Hello"
+    assert entity.excerpt is None
+
+
+def test_entity_rejects_invalid_entity_type() -> None:
+    with pytest.raises(ValueError):
+        SEOEntity(entity_type="invalid")
+
+
+def test_entity_rejects_non_string_optional_field() -> None:
+    with pytest.raises(ValueError):
+        SEOEntity(entity_type="post", title=123)  # type: ignore[arg-type]
+
+
+def test_overrides_normalize_and_validate_schema_type() -> None:
+    overrides = SEOOverrides(meta_title="  A ", robots="  ")
+    assert overrides.meta_title == "A"
+    assert overrides.robots is None
+
+    with pytest.raises(ValueError):
+        SEOOverrides(schema_jsonld=[{"@type": "WebPage"}, "bad"])  # type: ignore[list-item]

seoslug-1.0.0/tests/test_text.py

@@ -0,0 +1,29 @@
+"""Tests for text extraction utilities."""
+
+import pytest
+
+from seoslug.text import build_description_snippet, html_to_text
+
+
+def test_html_to_text_strips_tags_and_script_content() -> None:
+    html = "<h1>Hello</h1><script>alert('x')</script><p>World</p>"
+    assert html_to_text(html) == "Hello World"
+
+
+def test_snippet_truncation() -> None:
+    text = "<p>" + ("a" * 200) + "</p>"
+    snippet = build_description_snippet(text, max_length=20)
+    assert snippet.endswith("...")
+    assert len(snippet) == 20
+
+
+def test_html_to_text_normalizes_whitespace_and_style() -> None:
+    html = "<style>.x{color:red;}</style><p> Hello\n\tWorld </p>"
+    assert html_to_text(html) == "Hello World"
+
+
+def test_invalid_inputs_raise_value_error() -> None:
+    with pytest.raises(ValueError):
+        html_to_text(123)  # type: ignore[arg-type]
+    with pytest.raises(ValueError):
+        build_description_snippet("<p>ok</p>", max_length=0)