seoslug 1.0__py3-none-any.whl

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/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/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/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/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/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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,12 @@
+seoslug/__init__.py,sha256=W-wZtWeyuRjrllG9i3DJWje6AbNMbld7ILw8E__LXSA,381
+seoslug/builder.py,sha256=3h8X119A1i0p-U1CKq6pRs4XK6jr9RSW81dLXBDHitc,2483
+seoslug/config.py,sha256=aNdazN3bYG-dL8r0ZC0V6BXJWnARCH6SCY6_ndn1bjw,3724
+seoslug/jsonld.py,sha256=nCMPcBfpxiBhIaIdTM6qVRE7vqWtwOut3JvdJdyRC2o,435
+seoslug/normalization.py,sha256=7JB5-Xy3j_aWL4KbVlNA8qiREsEHL8t0rLS5i_boytE,2796
+seoslug/schemas.py,sha256=cWpp6r67y3SqvwTKyVjZrEVKaTgsqX5eS6bmO0Cwh50,3619
+seoslug/text.py,sha256=8oiAZy6hmHYqcxreLRwB4gxXBZJ6Q87T-HtCdIKT88Y,1003
+seoslug-1.0.0.dist-info/licenses/LICENSE,sha256=THz31zp4msobGOcb9cCbBH0SxVMqS7pjNlBIRkNM7Nw,1077
+seoslug-1.0.0.dist-info/METADATA,sha256=Em3husAu55rXe1oO0ehjlT0SPA9blltiXOn-Xbm_L1M,2187
+seoslug-1.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+seoslug-1.0.0.dist-info/top_level.txt,sha256=Mx56Mld7Hi20eo5D6Ykk2uR2IQnHVwMv2-NZxrNFyd0,8
+seoslug-1.0.0.dist-info/RECORD,,

seoslug-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

seoslug-1.0.0.dist-info/licenses/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.dist-info/top_level.txt

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