API reference¶

from seoslug import (
    SEOConfig,
    URLPolicy,
    SEOEntity,
    SEOEntityBuilder,
    SEOOverrides,
    OGImage,
    Breadcrumb,
    FAQItem,
    Robots,
    SchemaRegistry,
    normalize_public_url,
    normalize_path,
    build_seo_payload,
    build_seo_payload_dict,
    build_seo_payload_async,
    from_blog_post,
    from_product,
    from_faq,
    # Exceptions
    SEOError,
    SEOConfigError,
    SEOEntityError,
    URLPolicyError,
    SEOPayloadError,
    # Hooks
    hook,
    register_hook,
    clear_hooks,
    get_registered_hooks,
    run_hooks,
)

def build_seo_payload(
    entity: SEOEntity,
    route_path: str,
    config: SEOConfig,
    overrides: SEOOverrides | None = None,
) -> SEOPayload

def build_seo_payload_dict(
    entity: SEOEntity,
    route_path: str,
    config: SEOConfig,
    overrides: SEOOverrides | None = None,
) -> dict

payload_dict = build_seo_payload_dict(entity, "/post", config)
payload_dict["title"]   # "My Post"
payload_dict["og"]["type"]  # "article"

from seoslug.async_builder import build_seo_payload_async

async def build_seo_payload_async(
    entity: SEOEntity,
    route_path: str,
    config: SEOConfig,
    overrides: SEOOverrides | None = None,
    executor: ThreadPoolExecutor | None = None,
) -> SEOPayload

payload = await build_seo_payload_async(entity, "/post", config)

def normalize_public_url(
    url_or_path: str,
    config: SEOConfig,
) -> str

def normalize_path(
    path: str,
    policy: URLPolicy,
) -> str

normalize_path("/Blog//Post", URLPolicy())
# "/blog/post"

@dataclass(slots=True)
class SEOConfig:
    canonical_host: str
    public_base_url: str
    url_policy: URLPolicy
    default_robots: str | Robots = "index,follow"
    default_og_image: str | OGImage | None = None
    site_name: str | None = None
    title_template: str | None = "{title}"
    search_robots: str | Robots = "noindex,follow"
    schema_type_map: dict[str, str | None]
    auto_generate_schema: bool = True
    publisher_name: str | None = None
    publisher_logo: str | None = None
    locale: str | None = None
    locale_alternate: list[str] | None = None
    twitter_site: str | None = None
    schema_registry: SchemaRegistry | None = None
    hooks: HookRegistry | None = None
    emit_warnings: bool = False

{
    "post": "Article",
    "page": "WebPage",
    "video": "VideoObject",
    "home": "WebPage",
    "taxonomy": "CollectionPage",
    "search": "SearchResultsPage",
    "product": "Product",
    "organization": "Organization",
    "local_business": "LocalBusiness",
    "faq": "FAQPage",
}

@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)

@dataclass(slots=True)
class SEOEntity:
    entity_type: Literal["home", "post", "page", "video", "taxonomy", "search", "other",
                         "product", "organization", "local_business", "faq"]
    slug: str | None = None
    title: str | None = None
    excerpt: str | None = None
    body_html: str | None = None
    status: str | None = None
    featured_image: str | OGImage | None = None
    published_at: str | None = None
    updated_at: str | None = None
    author_name: str | None = None
    breadcrumbs: list[Breadcrumb] | None = None
    sku: str | None = None
    price: str | None = None
    price_currency: str | None = None
    availability: str | None = None
    same_as: list[str] | None = None
    address: str | None = None
    faq_items: list[FAQItem] | None = None

@dataclass(slots=True)
class SEOOverrides:
    meta_title: str | None = None
    meta_description: str | None = None
    canonical_url: str | None = None
    robots: str | Robots | None = None
    og_title: str | None = None
    og_description: str | None = None
    og_image: str | OGImage | None = None
    twitter_card: str | None = None
    twitter_title: str | None = None
    twitter_description: str | None = None
    twitter_image: str | OGImage | None = None
    schema_jsonld: dict | list[dict] | None = None
    omit_schema: bool = False
    skip_title_template: bool = False
    twitter_creator: str | None = None
    og_audio: str | None = None
    og_video: str | None = None

overrides = SEOOverrides(
    meta_title="Custom Title",
    skip_title_template=True,
    twitter_creator="@author",
    omit_schema=True,
)

@dataclass(slots=True)
class OGImage:
    url: str
    width: int | None = None
    height: int | None = None
    alt: str | None = None

@dataclass(slots=True)
class Breadcrumb:
    name: str
    url: str

@dataclass(slots=True)
class FAQItem:
    question: str
    answer: str

@dataclass(slots=True)
class Robots:
    index: bool = True
    follow: bool = True
    max_snippet: int | None = None
    max_image_preview: str | None = None
    max_video_preview: int | None = None

robots = Robots(index=True, follow=False, max_snippet=160)
robots.serialize()  # "index,nofollow,max-snippet:160"

class SchemaRegistry:
    def __init__(self) -> None: ...
    def register(self, schema_type: str, generator: SchemaGenerator) -> None: ...
    def unregister(self, schema_type: str) -> None: ...
    def get(self, schema_type: str) -> SchemaGenerator | None: ...

from seoslug import SchemaRegistry

registry = SchemaRegistry()
registry.register("Podcast", lambda entity, config, canonical, title, description, og_image: {
    "@context": "https://schema.org",
    "@type": "Podcast",
    "name": title,
    "url": canonical,
})

class SchemaGenerator(Protocol):
    def __call__(
        self,
        entity: SEOEntity,
        config: SEOConfig,
        canonical: str,
        title: str,
        description: str | None,
        og_image: str | None,
    ) -> dict | None: ...

class SEOEntityBuilder:
    def __init__(self) -> None: ...
    def entity_type(self, value: str) -> SEOEntityBuilder: ...
    def slug(self, value: str) -> SEOEntityBuilder: ...
    def title(self, value: str) -> SEOEntityBuilder: ...
    def excerpt(self, value: str) -> SEOEntityBuilder: ...
    def body_html(self, value: str) -> SEOEntityBuilder: ...
    def status(self, value: str) -> SEOEntityBuilder: ...
    def featured_image(self, value: str | OGImage) -> SEOEntityBuilder: ...
    def published_at(self, value: str) -> SEOEntityBuilder: ...
    def updated_at(self, value: str) -> SEOEntityBuilder: ...
    def author_name(self, value: str) -> SEOEntityBuilder: ...
    def breadcrumbs(self, value: list[Breadcrumb]) -> SEOEntityBuilder: ...
    def sku(self, value: str) -> SEOEntityBuilder: ...
    def price(self, value: str | float) -> SEOEntityBuilder: ...
    def price_currency(self, value: str) -> SEOEntityBuilder: ...
    def availability(self, value: str) -> SEOEntityBuilder: ...
    def same_as(self, value: list[str]) -> SEOEntityBuilder: ...
    def address(self, value: str) -> SEOEntityBuilder: ...
    def faq_items(self, value: list[FAQItem]) -> SEOEntityBuilder: ...
    def build(self) -> SEOEntity: ...

entity = (
    SEOEntityBuilder()
    .entity_type("product")
    .title("Widget")
    .sku("W-001")
    .price(29.99)
    .availability("InStock")
    .build()
)

from seoslug import from_blog_post, from_product, from_faq

def from_blog_post(
    title: str,
    body_html: str,
    slug: str | None = None,
    author: str = "",
    excerpt: str | None = None,
    breadcrumbs: list[dict] | None = None,
) -> SEOEntity

entity = from_blog_post(
    title="Hello World",
    body_html="<p>Content</p>",
    author="Jane",
    breadcrumbs=[{"name": "Blog", "url": "/blog"}],
)

def from_product(
    name: str,
    sku: str,
    price: str | float,
    currency: str = "USD",
    availability: str = "InStock",
    description: str | None = None,
    breadcrumbs: list[dict] | None = None,
) -> SEOEntity

def from_faq(
    questions: list[dict[str, str]],
    title: str = "FAQ",
    description: str | None = None,
    breadcrumbs: list[dict] | None = None,
) -> SEOEntity

seoslug.exceptions.SEOError

seoslug.exceptions.SEOConfigError

seoslug.exceptions.SEOEntityError

seoslug.exceptions.URLPolicyError

seoslug.exceptions.SEOPayloadError

hook(name: str) -> Callable

from seoslug import hook

@hook("post_process")
def add_breadcrumb(payload, entity, config):
    payload["breadcrumb"] = {"@type": "BreadcrumbList", ...}
    return payload

register_hook(name: str, fn: Callable) -> None

clear_hooks(name: str | None = None) -> None

get_registered_hooks() -> dict[str, list[Callable]]

run_hooks(name, payload, entity, config) -> dict

@dataclass(eq=False)
class SEOPayload:
    title: str
    description: str
    canonical: str
    robots: str
    og: OGPayload
    twitter: TwitterPayload
    schema_jsonld: dict | list[dict] | None = None

@dataclass(eq=False)
class OGPayload:
    type: str
    title: str | None
    description: str | None
    url: str | None
    image: str | None
    image_width: int | None = None
    image_height: int | None = None
    image_alt: str | None = None
    site_name: str | None = None
    locale: str | None = None
    locale_alternate: list[str] | None = None
    audio: str | None = None
    video: str | None = None

@dataclass(eq=False)
class TwitterPayload:
    card: str
    title: str | None
    description: str | None
    image: str | None
    image_alt: str | None = None
    site: str | None = None
    creator: str | None = None

from seoslug.payload import SEOPayloadTypedDict, OGPayloadTypedDict, TwitterPayloadTypedDict