html5cc 0.3.0__py3-none-any.whl

html5/__init__.py

@@ -0,0 +1,42 @@
+"""HTML5 document and CSS3 helpers."""
+
+from .css import (
+    CSSAtRule,
+    CSSComment,
+    CSSDeclaration,
+    CSSLink,
+    CSSImportRule,
+    CSSInlineStyle,
+    CSSKeyframe,
+    CSSKeyframesRule,
+    CSSLayerRule,
+    CSSMediaRule,
+    CSSNode,
+    CSSRule,
+    CSSStyleElement,
+    CSSStyleSheet,
+    CSSSupportsRule,
+    BOOTSTRAP5_CSS_URL,
+    GOOGLE_FONTS_PRECONNECT_URL,
+    GOOGLE_FONTS_STATIC_URL,
+    TAILWIND_PLAY_CDN_URL,
+    bootstrap5_stylesheet,
+    google_fonts_assets,
+    google_fonts_url,
+    inline_style,
+    tailwind_script,
+    style_tag,
+)
+from .document import Comment, Doctype, Element, HtmlDocument, Node, Raw, Text, comment, doctype, doctype_node, element, raw, text
+from .elements import *
+from .version import __version__
+from .writer import MarkupWriter
+from .js import (
+    JSNode,
+    JSScript,
+    bootstrap5_bundle_script,
+    google_charts_loader,
+    google_charts_package_loader,
+    javascript_link,
+    javascript_script,
+)

html5/css.py

@@ -0,0 +1,384 @@
+"""CSS3 stylesheet helpers."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Mapping, Sequence
+from urllib.parse import quote_plus
+
+from .document import Raw, element, raw
+from .js import JSScript
+
+
+def _normalize_property_name(name: str) -> str:
+    return name.replace("_", "-")
+
+
+def _normalize_at_rule_name(name: str) -> str:
+    return name.removeprefix("@").replace("_", "-")
+
+
+class CSSNode:
+    """Base class for CSS document nodes."""
+
+    def render(self) -> str:
+        raise NotImplementedError
+
+
+@dataclass(frozen=True)
+class CSSComment(CSSNode):
+    """Render a CSS comment."""
+
+    value: str
+
+    def render(self) -> str:
+        return f"/* {self.value} */"
+
+
+@dataclass(frozen=True)
+class CSSDeclaration(CSSNode):
+    """Render a CSS declaration pair."""
+
+    property_name: str
+    value: Any
+    important: bool = False
+
+    def render(self) -> str:
+        if self.value is None:
+            return ""
+        suffix = " !important" if self.important else ""
+        return f"{_normalize_property_name(self.property_name)}: {self.value}{suffix};"
+
+
+def _coerce_declaration(value: CSSDeclaration | tuple[str, Any] | Mapping[str, Any]) -> CSSDeclaration:
+    if isinstance(value, CSSDeclaration):
+        return value
+    if isinstance(value, Mapping):
+        if len(value) != 1:
+            raise ValueError("CSS declaration mapping must contain exactly one property")
+        property_name, property_value = next(iter(value.items()))
+        return CSSDeclaration(property_name=str(property_name), value=property_value)
+    property_name, property_value = value
+    return CSSDeclaration(property_name=str(property_name), value=property_value)
+
+
+def _render_declarations(declarations: tuple[CSSDeclaration | tuple[str, Any] | Mapping[str, Any], ...]) -> str:
+    parts: list[str] = []
+    for declaration in declarations:
+        rendered = _coerce_declaration(declaration).render()
+        if rendered:
+            parts.append(rendered)
+    return " ".join(parts)
+
+
+def _render_nodes(nodes: tuple[CSSNode | str, ...]) -> str:
+    parts: list[str] = []
+    for node in nodes:
+        parts.append(node.render() if isinstance(node, CSSNode) else str(node))
+    return "\n".join(parts)
+
+
+@dataclass(frozen=True, init=False)
+class CSSInlineStyle(CSSNode):
+    """Render a sequence of declarations for use in a style attribute."""
+
+    declarations: tuple[CSSDeclaration | tuple[str, Any] | Mapping[str, Any], ...] = ()
+
+    def __init__(self, *declarations: CSSDeclaration | tuple[str, Any] | Mapping[str, Any]) -> None:
+        object.__setattr__(self, "declarations", declarations)
+
+    def render(self) -> str:
+        return _render_declarations(self.declarations)
+
+
+@dataclass(frozen=True)
+class CSSLink(CSSNode):
+    """Render a stylesheet link element."""
+
+    href: str
+    rel: str = "stylesheet"
+    attributes: Mapping[str, Any] = field(default_factory=dict)
+
+    def render(self) -> str:
+        return element("link", void=True, rel=self.rel, href=self.href, **self.attributes).render()
+
+
+@dataclass(frozen=True, init=False)
+class CSSRule(CSSNode):
+    """Render a CSS selector rule."""
+
+    selector: str
+    declarations: tuple[CSSDeclaration | tuple[str, Any] | Mapping[str, Any], ...] = ()
+
+    def __init__(self, selector: str, *declarations: CSSDeclaration | tuple[str, Any] | Mapping[str, Any]) -> None:
+        object.__setattr__(self, "selector", selector)
+        object.__setattr__(self, "declarations", declarations)
+
+    def render(self) -> str:
+        body = _render_declarations(self.declarations)
+        return f"{self.selector} {{ {body} }}" if body else f"{self.selector} {{}}"
+
+
+@dataclass(frozen=True)
+class CSSAtRule(CSSNode):
+    """Render a generic CSS at-rule."""
+
+    name: str
+    prelude: str = ""
+    body: tuple[CSSNode | str, ...] = ()
+    block: bool = True
+
+    def render(self) -> str:
+        name = _normalize_at_rule_name(self.name)
+        prelude = f" {self.prelude}" if self.prelude else ""
+        if not self.block:
+            return f"@{name}{prelude};"
+        body = _render_nodes(self.body)
+        return f"@{name}{prelude} {{ {body} }}" if body else f"@{name}{prelude} {{}}"
+
+
+@dataclass(frozen=True, init=False)
+class CSSImportRule(CSSAtRule):
+    """Render a CSS @import rule."""
+
+    def __init__(self, url: str, media: str = "") -> None:
+        prelude = f'url("{url}")'
+        if media:
+            prelude = f"{prelude} {media}"
+        object.__setattr__(self, "name", "import")
+        object.__setattr__(self, "prelude", prelude)
+        object.__setattr__(self, "body", ())
+        object.__setattr__(self, "block", False)
+
+
+@dataclass(frozen=True, init=False)
+class CSSMediaRule(CSSAtRule):
+    """Render a CSS @media block."""
+
+    def __init__(self, query: str, *rules: CSSNode | str) -> None:
+        object.__setattr__(self, "name", "media")
+        object.__setattr__(self, "prelude", query)
+        object.__setattr__(self, "body", rules)
+        object.__setattr__(self, "block", True)
+
+
+@dataclass(frozen=True, init=False)
+class CSSSupportsRule(CSSAtRule):
+    """Render a CSS @supports block."""
+
+    def __init__(self, condition: str, *rules: CSSNode | str) -> None:
+        object.__setattr__(self, "name", "supports")
+        object.__setattr__(self, "prelude", condition)
+        object.__setattr__(self, "body", rules)
+        object.__setattr__(self, "block", True)
+
+
+@dataclass(frozen=True, init=False)
+class CSSLayerRule(CSSAtRule):
+    """Render a CSS @layer block."""
+
+    def __init__(self, layer: str = "", *rules: CSSNode | str) -> None:
+        object.__setattr__(self, "name", "layer")
+        object.__setattr__(self, "prelude", layer)
+        object.__setattr__(self, "body", rules)
+        object.__setattr__(self, "block", True)
+
+
+@dataclass(frozen=True, init=False)
+class CSSKeyframe(CSSNode):
+    """Render a single frame inside a CSS keyframes rule."""
+
+    selector: str
+    declarations: tuple[CSSDeclaration | tuple[str, Any] | Mapping[str, Any], ...] = ()
+
+    def __init__(self, selector: str, *declarations: CSSDeclaration | tuple[str, Any] | Mapping[str, Any]) -> None:
+        object.__setattr__(self, "selector", selector)
+        object.__setattr__(self, "declarations", declarations)
+
+    def render(self) -> str:
+        body = _render_declarations(self.declarations)
+        return f"{self.selector} {{ {body} }}" if body else f"{self.selector} {{}}"
+
+
+@dataclass(frozen=True)
+class CSSKeyframesRule(CSSNode):
+    """Render a CSS @keyframes rule."""
+
+    name: str
+    frames: tuple[CSSKeyframe, ...] = ()
+
+    def render(self) -> str:
+        body = " ".join(frame.render() for frame in self.frames)
+        return f"@keyframes {self.name} {{ {body} }}" if body else f"@keyframes {self.name} {{}}"
+
+
+@dataclass(frozen=True)
+class CSSStyleElement(CSSNode):
+    """Render a complete <style> element."""
+
+    stylesheet: CSSNode | str
+
+    def render(self) -> str:
+        css = self.stylesheet.render() if isinstance(self.stylesheet, CSSNode) else self.stylesheet
+        return f"<style>{css}</style>"
+
+
+BOOTSTRAP5_CSS_URL = "https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/css/bootstrap.min.css"
+TAILWIND_PLAY_CDN_URL = "https://cdn.tailwindcss.com"
+GOOGLE_FONTS_PRECONNECT_URL = "https://fonts.googleapis.com"
+GOOGLE_FONTS_STATIC_URL = "https://fonts.gstatic.com"
+
+
+def bootstrap5_stylesheet(version: str = "5.3.3") -> CSSLink:
+    """Return the Bootstrap 5 stylesheet link tag."""
+
+    href = f"https://cdn.jsdelivr.net/npm/bootstrap@{version}/dist/css/bootstrap.min.css"
+    return CSSLink(href=href)
+
+
+def tailwind_script() -> JSScript:
+    """Return the Tailwind Play CDN script tag."""
+
+    return JSScript(src=TAILWIND_PLAY_CDN_URL)
+
+
+def google_fonts_url(
+    *families: str,
+    weights: Sequence[int] = (400, 500, 700),
+    display: str = "swap",
+    text: str | None = None,
+) -> str:
+    """Build a Google Fonts CSS2 URL for the requested families and weights."""
+
+    if not families:
+        raise ValueError("At least one Google Fonts family is required")
+
+    family_parts: list[str] = []
+    weight_part = ";".join(str(weight) for weight in weights)
+    for family in families:
+        family_parts.append(f"family={quote_plus(family)}:wght@{weight_part}")
+
+    params = [*family_parts, f"display={quote_plus(display)}"]
+    if text is not None:
+        params.append(f"text={quote_plus(text)}")
+    return "https://fonts.googleapis.com/css2?" + "&".join(params)
+
+
+def google_fonts_assets(
+    *families: str,
+    weights: Sequence[int] = (400, 500, 700),
+    display: str = "swap",
+    text: str | None = None,
+) -> tuple[CSSLink, CSSLink, CSSLink]:
+    """Return preconnect and stylesheet links for Google Fonts."""
+
+    href = google_fonts_url(*families, weights=weights, display=display, text=text)
+    return (
+        CSSLink(href=GOOGLE_FONTS_PRECONNECT_URL, rel="preconnect"),
+        CSSLink(href=GOOGLE_FONTS_STATIC_URL, rel="preconnect", attributes={"crossorigin": "anonymous"}),
+        CSSLink(href=href),
+    )
+
+
+@dataclass
+class CSSStyleSheet(CSSNode):
+    rules: list[CSSNode | str] = field(default_factory=list)
+
+    def add(self, *items: CSSNode | str) -> "CSSStyleSheet":
+        self.rules.extend(items)
+        return self
+
+    def add_comment(self, value: str) -> "CSSStyleSheet":
+        self.rules.append(CSSComment(value))
+        return self
+
+    def add_rule(
+        self,
+        selector: str,
+        *declarations: CSSDeclaration | tuple[str, Any] | Mapping[str, Any],
+        **keyword_declarations: Any,
+    ) -> "CSSStyleSheet":
+        combined_declarations = declarations + tuple(keyword_declarations.items())
+        self.rules.append(CSSRule(selector, *combined_declarations))
+        return self
+
+    def add_import(self, url: str, media: str = "") -> "CSSStyleSheet":
+        self.rules.append(CSSImportRule(url=url, media=media))
+        return self
+
+    def add_media(self, query: str, *rules: CSSNode | str) -> "CSSStyleSheet":
+        self.rules.append(CSSMediaRule(query, *rules))
+        return self
+
+    def add_supports(self, condition: str, *rules: CSSNode | str) -> "CSSStyleSheet":
+        self.rules.append(CSSSupportsRule(condition, *rules))
+        return self
+
+    def add_layer(self, layer: str = "", *rules: CSSNode | str) -> "CSSStyleSheet":
+        self.rules.append(CSSLayerRule(layer, *rules))
+        return self
+
+    def add_keyframes(self, name: str, *frames: CSSKeyframe) -> "CSSStyleSheet":
+        self.rules.append(CSSKeyframesRule(name=name, frames=frames))
+        return self
+
+    def add_raw(self, css: str) -> "CSSStyleSheet":
+        self.rules.append(css)
+        return self
+
+    def render(self) -> str:
+        parts: list[str] = []
+        for rule in self.rules:
+            parts.append(rule.render() if isinstance(rule, CSSNode) else rule)
+        return "\n".join(parts)
+
+
+def style_tag(stylesheet: CSSNode | str) -> Raw:
+    """Render a stylesheet or CSS node into a raw <style> tag.
+
+    If *stylesheet* is already a :class:`CSSStyleElement` (which renders its
+    own ``<style>`` wrapper), return it as-is to avoid double-wrapping.
+    """
+
+    if isinstance(stylesheet, CSSStyleElement):
+        return raw(stylesheet.render())
+    css = stylesheet.render() if isinstance(stylesheet, CSSNode) else stylesheet
+    return raw(f"<style>{css}</style>")
+
+
+def inline_style(
+    *declarations: CSSDeclaration | tuple[str, Any] | Mapping[str, Any],
+    **keyword_declarations: Any,
+) -> str:
+    """Render declarations for a style attribute."""
+
+    return CSSInlineStyle(*(declarations + tuple(keyword_declarations.items()))).render()
+
+
+__all__ = [
+    "CSSAtRule",
+    "CSSComment",
+    "CSSDeclaration",
+    "CSSLink",
+    "CSSImportRule",
+    "CSSInlineStyle",
+    "CSSKeyframe",
+    "CSSKeyframesRule",
+    "CSSLayerRule",
+    "CSSMediaRule",
+    "CSSNode",
+    "CSSRule",
+    "CSSStyleElement",
+    "CSSStyleSheet",
+    "CSSSupportsRule",
+    "BOOTSTRAP5_CSS_URL",
+    "GOOGLE_FONTS_PRECONNECT_URL",
+    "GOOGLE_FONTS_STATIC_URL",
+    "TAILWIND_PLAY_CDN_URL",
+    "bootstrap5_stylesheet",
+    "google_fonts_assets",
+    "google_fonts_url",
+    "inline_style",
+    "tailwind_script",
+    "style_tag",
+]

html5/document.py

@@ -0,0 +1,166 @@
+"""HTML5 document primitives."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from html import escape
+from typing import Any, Mapping
+
+
+def doctype() -> str:
+    """Return the HTML5 doctype string."""
+
+    return "<!doctype html>"
+
+
+def _normalize_attr_name(name: str) -> str:
+    if name.endswith("_"):
+        name = name[:-1]
+    return name.replace("_", "-")
+
+
+def _render_attributes(attributes: Mapping[str, Any]) -> str:
+    rendered: list[str] = []
+    for key, value in attributes.items():
+        if value is None or value is False:
+            continue
+        attribute_name = _normalize_attr_name(key)
+        if value is True:
+            rendered.append(attribute_name)
+        else:
+            rendered.append(f'{attribute_name}="{escape(str(value), quote=True)}"')
+    return (" " + " ".join(rendered)) if rendered else ""
+
+
+class Node:
+    """Base class for HTML document nodes."""
+
+    def render(self) -> str:
+        raise NotImplementedError
+
+
+@dataclass(frozen=True)
+class Text(Node):
+    """Render escaped text content."""
+
+    value: str
+
+    def render(self) -> str:
+        return escape(self.value)
+
+
+@dataclass(frozen=True)
+class Raw(Node):
+    """Render raw HTML content without escaping."""
+
+    value: str
+
+    def render(self) -> str:
+        return self.value
+
+
+@dataclass(frozen=True)
+class Comment(Node):
+    """Render an HTML comment."""
+
+    value: str
+
+    def render(self) -> str:
+        return f"<!--{self.value}-->"
+
+
+@dataclass(frozen=True)
+class Doctype(Node):
+    """Render a doctype node."""
+
+    value: str = "html"
+
+    def render(self) -> str:
+        return f"<!doctype {self.value}>"
+
+
+@dataclass(frozen=True)
+class Element(Node):
+    """Render an HTML element with children and attributes."""
+
+    tag: str
+    children: tuple[Node | str, ...] = ()
+    attributes: Mapping[str, Any] = field(default_factory=dict)
+    void: bool = False
+
+    def render(self) -> str:
+        attributes = _render_attributes(self.attributes)
+        if self.void:
+            return f"<{self.tag}{attributes}>"
+
+        inner_html = "".join(_coerce_node(child).render() for child in self.children)
+        return f"<{self.tag}{attributes}>{inner_html}</{self.tag}>"
+
+
+def _coerce_node(value: Node | str) -> Node:
+    return value if isinstance(value, Node) else Text(str(value))
+
+
+def text(value: str) -> Text:
+    """Create an escaped text node."""
+
+    return Text(value)
+
+
+def raw(value: str) -> Raw:
+    """Create a raw HTML node."""
+
+    return Raw(value)
+
+
+def comment(value: str) -> Comment:
+    """Create an HTML comment node."""
+
+    return Comment(value)
+
+
+def doctype_node(value: str = "html") -> Doctype:
+    """Create a doctype node."""
+
+    return Doctype(value)
+
+
+def element(tag: str, *children: Node | str, void: bool = False, **attributes: Any) -> Element:
+    """Create an HTML element node."""
+
+    return Element(tag=tag, children=children, attributes=attributes, void=void)
+
+
+@dataclass
+class HtmlDocument:
+    """Represent a complete HTML document."""
+
+    title: str = ""
+    lang: str = "en"
+    head_nodes: list[Node | str] = field(default_factory=list)
+    body_nodes: list[Node | str] = field(default_factory=list)
+
+    def add_head(self, *nodes: Node | str) -> "HtmlDocument":
+        """Append nodes to the document head."""
+
+        self.head_nodes.extend(nodes)
+        return self
+
+    def add_body(self, *nodes: Node | str) -> "HtmlDocument":
+        """Append nodes to the document body."""
+
+        self.body_nodes.extend(nodes)
+        return self
+
+    def render(self) -> str:
+        """Render the full HTML document."""
+
+        head_children: list[Node | str] = [element("meta", charset="utf-8", void=True)]
+        if self.title:
+            head_children.append(element("title", self.title))
+        head_children.extend(self.head_nodes)
+
+        body = element("body", *self.body_nodes)
+        head = element("head", *head_children)
+        html = element("html", head, body, lang=self.lang)
+        return "\n".join([doctype(), html.render()])

html5/elements.py

@@ -0,0 +1,397 @@
+"""Generated HTML5 element classes."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .document import Element, Node
+
+
+VOID_ELEMENTS = {
+    "area",
+    "base",
+    "br",
+    "col",
+    "embed",
+    "hr",
+    "img",
+    "input",
+    "link",
+    "meta",
+    "param",
+    "source",
+    "track",
+    "wbr",
+}
+
+HTML5_ELEMENTS = (
+    "a",
+    "abbr",
+    "address",
+    "area",
+    "article",
+    "aside",
+    "audio",
+    "b",
+    "base",
+    "bdi",
+    "bdo",
+    "blockquote",
+    "body",
+    "br",
+    "button",
+    "canvas",
+    "caption",
+    "cite",
+    "code",
+    "col",
+    "colgroup",
+    "data",
+    "datalist",
+    "dd",
+    "del",
+    "details",
+    "dfn",
+    "dialog",
+    "div",
+    "dl",
+    "dt",
+    "em",
+    "embed",
+    "fieldset",
+    "figcaption",
+    "figure",
+    "footer",
+    "form",
+    "h1",
+    "h2",
+    "h3",
+    "h4",
+    "h5",
+    "h6",
+    "head",
+    "header",
+    "hgroup",
+    "hr",
+    "html",
+    "i",
+    "iframe",
+    "img",
+    "input",
+    "ins",
+    "kbd",
+    "label",
+    "legend",
+    "li",
+    "link",
+    "main",
+    "map",
+    "mark",
+    "menu",
+    "meta",
+    "meter",
+    "nav",
+    "noscript",
+    "object",
+    "ol",
+    "optgroup",
+    "option",
+    "output",
+    "p",
+    "param",
+    "picture",
+    "pre",
+    "progress",
+    "q",
+    "rp",
+    "rt",
+    "ruby",
+    "s",
+    "samp",
+    "script",
+    "section",
+    "select",
+    "slot",
+    "small",
+    "source",
+    "span",
+    "strong",
+    "style",
+    "sub",
+    "summary",
+    "sup",
+    "table",
+    "tbody",
+    "td",
+    "template",
+    "textarea",
+    "tfoot",
+    "th",
+    "thead",
+    "time",
+    "title",
+    "tr",
+    "track",
+    "u",
+    "ul",
+    "var",
+    "video",
+    "wbr",
+)
+
+
+def _class_name(tag: str) -> str:
+    return tag.replace("-", " ").title().replace(" ", "")
+
+
+def _build_init(tag: str, *, void: bool) -> Any:
+    def __init__(self, *children: Node | str, **attributes: Any) -> None:
+        if void and children:
+            raise ValueError(f"{tag} is a void HTML element and cannot have children")
+        Element.__init__(self, tag=tag, children=children, attributes=attributes, void=void)
+
+    return __init__
+
+
+def _create_tag_class(tag: str) -> type[Element]:
+    cls = type(
+        _class_name(tag),
+        (Element,),
+        {
+            "__module__": __name__,
+            "__init__": _build_init(tag, void=tag in VOID_ELEMENTS),
+        },
+    )
+    cls.__doc__ = f"Render a <{tag}> HTML element."
+    return cls
+
+
+A = _create_tag_class("a")
+Abbr = _create_tag_class("abbr")
+Address = _create_tag_class("address")
+Area = _create_tag_class("area")
+Article = _create_tag_class("article")
+Aside = _create_tag_class("aside")
+Audio = _create_tag_class("audio")
+B = _create_tag_class("b")
+Base = _create_tag_class("base")
+Bdi = _create_tag_class("bdi")
+Bdo = _create_tag_class("bdo")
+Blockquote = _create_tag_class("blockquote")
+Body = _create_tag_class("body")
+Br = _create_tag_class("br")
+Button = _create_tag_class("button")
+Canvas = _create_tag_class("canvas")
+Caption = _create_tag_class("caption")
+Cite = _create_tag_class("cite")
+Code = _create_tag_class("code")
+Col = _create_tag_class("col")
+Colgroup = _create_tag_class("colgroup")
+Data = _create_tag_class("data")
+Datalist = _create_tag_class("datalist")
+Dd = _create_tag_class("dd")
+Del = _create_tag_class("del")
+Details = _create_tag_class("details")
+Dfn = _create_tag_class("dfn")
+Dialog = _create_tag_class("dialog")
+Div = _create_tag_class("div")
+Dl = _create_tag_class("dl")
+Dt = _create_tag_class("dt")
+Em = _create_tag_class("em")
+Embed = _create_tag_class("embed")
+Fieldset = _create_tag_class("fieldset")
+Figcaption = _create_tag_class("figcaption")
+Figure = _create_tag_class("figure")
+Footer = _create_tag_class("footer")
+Form = _create_tag_class("form")
+H1 = _create_tag_class("h1")
+H2 = _create_tag_class("h2")
+H3 = _create_tag_class("h3")
+H4 = _create_tag_class("h4")
+H5 = _create_tag_class("h5")
+H6 = _create_tag_class("h6")
+Head = _create_tag_class("head")
+Header = _create_tag_class("header")
+Hgroup = _create_tag_class("hgroup")
+Hr = _create_tag_class("hr")
+Html = _create_tag_class("html")
+I = _create_tag_class("i")
+Iframe = _create_tag_class("iframe")
+Img = _create_tag_class("img")
+Input = _create_tag_class("input")
+Ins = _create_tag_class("ins")
+Kbd = _create_tag_class("kbd")
+Label = _create_tag_class("label")
+Legend = _create_tag_class("legend")
+Li = _create_tag_class("li")
+Link = _create_tag_class("link")
+Main = _create_tag_class("main")
+Map = _create_tag_class("map")
+Mark = _create_tag_class("mark")
+Menu = _create_tag_class("menu")
+Meta = _create_tag_class("meta")
+Meter = _create_tag_class("meter")
+Nav = _create_tag_class("nav")
+Noscript = _create_tag_class("noscript")
+Object = _create_tag_class("object")
+Ol = _create_tag_class("ol")
+Optgroup = _create_tag_class("optgroup")
+Option = _create_tag_class("option")
+Output = _create_tag_class("output")
+P = _create_tag_class("p")
+Param = _create_tag_class("param")
+Picture = _create_tag_class("picture")
+Pre = _create_tag_class("pre")
+Progress = _create_tag_class("progress")
+Q = _create_tag_class("q")
+Rp = _create_tag_class("rp")
+Rt = _create_tag_class("rt")
+Ruby = _create_tag_class("ruby")
+S = _create_tag_class("s")
+Samp = _create_tag_class("samp")
+Script = _create_tag_class("script")
+Section = _create_tag_class("section")
+Select = _create_tag_class("select")
+Slot = _create_tag_class("slot")
+Small = _create_tag_class("small")
+Source = _create_tag_class("source")
+Span = _create_tag_class("span")
+Strong = _create_tag_class("strong")
+Style = _create_tag_class("style")
+Sub = _create_tag_class("sub")
+Summary = _create_tag_class("summary")
+Sup = _create_tag_class("sup")
+Table = _create_tag_class("table")
+Tbody = _create_tag_class("tbody")
+Td = _create_tag_class("td")
+Template = _create_tag_class("template")
+Textarea = _create_tag_class("textarea")
+Tfoot = _create_tag_class("tfoot")
+Th = _create_tag_class("th")
+Thead = _create_tag_class("thead")
+Time = _create_tag_class("time")
+Title = _create_tag_class("title")
+Tr = _create_tag_class("tr")
+Track = _create_tag_class("track")
+U = _create_tag_class("u")
+Ul = _create_tag_class("ul")
+Var = _create_tag_class("var")
+Video = _create_tag_class("video")
+Wbr = _create_tag_class("wbr")
+
+__all__ = [
+    "VOID_ELEMENTS",
+    "HTML5_ELEMENTS",
+    "A",
+    "Abbr",
+    "Address",
+    "Area",
+    "Article",
+    "Aside",
+    "Audio",
+    "B",
+    "Base",
+    "Bdi",
+    "Bdo",
+    "Blockquote",
+    "Body",
+    "Br",
+    "Button",
+    "Canvas",
+    "Caption",
+    "Cite",
+    "Code",
+    "Col",
+    "Colgroup",
+    "Data",
+    "Datalist",
+    "Dd",
+    "Del",
+    "Details",
+    "Dfn",
+    "Dialog",
+    "Div",
+    "Dl",
+    "Dt",
+    "Em",
+    "Embed",
+    "Fieldset",
+    "Figcaption",
+    "Figure",
+    "Footer",
+    "Form",
+    "H1",
+    "H2",
+    "H3",
+    "H4",
+    "H5",
+    "H6",
+    "Head",
+    "Header",
+    "Hgroup",
+    "Hr",
+    "Html",
+    "I",
+    "Iframe",
+    "Img",
+    "Input",
+    "Ins",
+    "Kbd",
+    "Label",
+    "Legend",
+    "Li",
+    "Link",
+    "Main",
+    "Map",
+    "Mark",
+    "Menu",
+    "Meta",
+    "Meter",
+    "Nav",
+    "Noscript",
+    "Object",
+    "Ol",
+    "Optgroup",
+    "Option",
+    "Output",
+    "P",
+    "Param",
+    "Picture",
+    "Pre",
+    "Progress",
+    "Q",
+    "Rp",
+    "Rt",
+    "Ruby",
+    "S",
+    "Samp",
+    "Script",
+    "Section",
+    "Select",
+    "Slot",
+    "Small",
+    "Source",
+    "Span",
+    "Strong",
+    "Style",
+    "Sub",
+    "Summary",
+    "Sup",
+    "Table",
+    "Tbody",
+    "Td",
+    "Template",
+    "Textarea",
+    "Tfoot",
+    "Th",
+    "Thead",
+    "Time",
+    "Title",
+    "Tr",
+    "Track",
+    "U",
+    "Ul",
+    "Var",
+    "Video",
+    "Wbr",
+]

html5/js.py

@@ -0,0 +1,85 @@
+"""JavaScript helpers for HTML documents."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Sequence
+
+from .document import raw, element
+
+
+class JSNode:
+    """Base class for JavaScript document nodes."""
+
+    def render(self) -> str:
+        raise NotImplementedError
+
+
+@dataclass(frozen=True)
+class JSScript(JSNode):
+    """Render an inline or external JavaScript script tag.
+
+    Set *src* for an external script, or *code* for an inline script.
+    Setting both raises :exc:`ValueError`.
+    """
+
+    src: str | None = None
+    code: str = ""
+    attributes: dict[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        if self.src is not None and self.code:
+            raise ValueError(
+                "JSScript cannot set both 'src' and 'code'; use one or the other"
+            )
+
+    def render(self) -> str:
+        if self.src is not None:
+            return element("script", src=self.src, **self.attributes).render()
+        return element("script", raw(self.code), **self.attributes).render()
+
+
+def javascript_script(code: str, **attributes: Any) -> JSScript:
+    """Create an inline script node."""
+    return JSScript(code=code, attributes=attributes)
+
+
+def javascript_link(src: str, **attributes: Any) -> JSScript:
+    """Create an external script node."""
+    return JSScript(src=src, attributes=attributes)
+
+
+def bootstrap5_bundle_script(version: str = "5.3.3") -> JSScript:
+    """Return the Bootstrap 5 bundle script tag."""
+    href = f"https://cdn.jsdelivr.net/npm/bootstrap@{version}/dist/js/bootstrap.bundle.min.js"
+    return javascript_link(href)
+
+
+def google_charts_loader(version: str = "51") -> JSScript:
+    """Return the Google Charts loader script tag."""
+    src = f"https://www.gstatic.com/charts/loader.js?ver={version}"
+    return javascript_link(src)
+
+
+def google_charts_package_loader(packages: Sequence[str], callback: str | None = None) -> JSScript:
+    """Return an inline Google Charts package loader snippet."""
+    package_list = ", ".join(f'"{package}"' for package in packages)
+    callback_line = f"google.charts.setOnLoadCallback({callback});" if callback else ""
+    code = (
+        "google.charts.load('current', {packages: ["
+        f"{package_list}"
+        "]});\n"
+        f"{callback_line}"
+    )
+    return javascript_script(code.strip())
+
+
+__all__ = [
+    "JSNode",
+    "JSScript",
+    "bootstrap5_bundle_script",
+    "google_charts_loader",
+    "google_charts_package_loader",
+    "javascript_link",
+    "javascript_script",
+]

html5/version.py

@@ -0,0 +1,3 @@
+"""Package version information."""
+
+__version__ = "0.3.0"

html5/writer.py

@@ -0,0 +1,48 @@
+"""Utilities for writing rendered HTML and CSS to disk."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Protocol
+
+
+class Renderable(Protocol):
+    def render(self) -> str:
+        raise NotImplementedError
+
+
+@dataclass(slots=True)
+class MarkupWriter:
+    """Write rendered HTML and CSS content beneath a fixed root directory."""
+
+    root: Path = Path(".")
+    encoding: str = "utf-8"
+
+    def write_text(self, path: str | Path, content: str) -> Path:
+        """Write text content to a file below the configured root directory."""
+
+        root = self.root.resolve()
+        relative_path = Path(path)
+        if relative_path.is_absolute():
+            raise ValueError("path must be relative to the writer root")
+
+        destination = (root / relative_path).resolve()
+        if destination == root or root not in destination.parents:
+            raise ValueError("path must be a file inside the writer root, not the root itself")
+
+        destination.parent.mkdir(parents=True, exist_ok=True)
+        destination.write_text(content, encoding=self.encoding)
+        return destination
+
+    def write_html(self, path: str | Path, document: Renderable | str) -> Path:
+        """Write rendered HTML to disk."""
+
+        content = document if isinstance(document, str) else document.render()
+        return self.write_text(path, content)
+
+    def write_css(self, path: str | Path, stylesheet: Renderable | str) -> Path:
+        """Write rendered CSS to disk."""
+
+        content = stylesheet if isinstance(stylesheet, str) else stylesheet.render()
+        return self.write_text(path, content)

html5cc-0.3.0.dist-info/METADATA

@@ -0,0 +1,148 @@
+Metadata-Version: 2.4
+Name: html5cc
+Version: 0.3.0
+Summary: A small Python module for building HTML5 documents and CSS3 stylesheets.
+Author: Jason Miller
+License: MIT
+Project-URL: Homepage, https://jasonmiller-cc.github.io/html5/
+Project-URL: Documentation, https://jasonmiller-cc.github.io/html5/
+Project-URL: Source, https://github.com/jasonmiller-cc/html5
+Project-URL: Changelog, https://github.com/jasonmiller-cc/html5/blob/main/CHANGELOG.md
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == "test"
+Requires-Dist: pytest-cov>=5.0; extra == "test"
+Provides-Extra: docs
+Requires-Dist: furo>=2024.8.6; extra == "docs"
+Requires-Dist: myst-parser>=4.0; extra == "docs"
+Requires-Dist: sphinx>=7.4; extra == "docs"
+Dynamic: license-file
+
+# html5
+
+Small Python helpers for building HTML5 documents, CSS, and JavaScript assets from Python.
+
+Documentation is published on GitHub Pages at [jasonmiller-cc.github.io/html5](https://jasonmiller-cc.github.io/html5/).
+
+The package ships with HTML5 element classes, CSS node classes, JavaScript helpers, CDN helpers for Bootstrap 5 and Tailwind, optimized Google Fonts helpers, a disk writer, and semantic version metadata.
+
+## Installation
+
+`html5cc` is published to [PyPI](https://pypi.org/project/html5cc/).
+The import name is still `html5`.
+
+```bash
+pip install html5cc
+```
+
+**requirements.txt**
+
+```text
+html5cc==0.3.0
+```
+
+**pyproject.toml (uv)**
+
+```toml
+[project]
+dependencies = ["html5cc>=0.3.0"]
+```
+
+See the [Installation docs](https://jasonmiller-cc.github.io/html5/installation.html) for Poetry and other options.
+
+## Example
+
+```python
+from html5 import (
+    CSSDeclaration,
+    CSSKeyframe,
+    CSSStyleSheet,
+    Div,
+    H1,
+    HtmlDocument,
+    Img,
+    MarkupWriter,
+    bootstrap5_bundle_script,
+    bootstrap5_stylesheet,
+    google_charts_loader,
+    google_charts_package_loader,
+    google_fonts_assets,
+    inline_style,
+    tailwind_script,
+)
+
+styles = CSSStyleSheet()
+styles.add_comment("base styles")
+styles.add_import("reset.css")
+styles.add_rule("body", margin="0", font_family="system-ui")
+styles.add_rule("h1", color="#1f2937")
+styles.add_media("screen and (min-width: 40rem)", CSSDeclaration("color", "black"))
+styles.add_keyframes("fade", CSSKeyframe("from", ("opacity", 0)), CSSKeyframe("to", ("opacity", 1)))
+
+doc = (
+    HtmlDocument(title="Hello HTML5")
+    .add_head(*google_fonts_assets("Inter"))
+    .add_head(bootstrap5_stylesheet())
+    .add_head(tailwind_script())
+    .add_head(bootstrap5_bundle_script())
+    .add_head(google_charts_loader())
+    .add_body(Div(H1("Hello, world!"), Img(src="hero.png", style=inline_style(("border_radius", "8px")))))
+)
+
+print(doc.render())
+
+chart_loader = google_charts_package_loader(["corechart", "table"], callback="drawChart")
+writer = MarkupWriter()
+writer.write_html("dist/index.html", doc)
+writer.write_css("dist/site.css", styles)
+writer.write_html("dist/charts.html", HtmlDocument(title="Charts").add_head(chart_loader))
+```
+
+## JavaScript Helpers
+
+Use `javascript_link()` and `javascript_script()` for arbitrary script tags and inline code. The library also exposes `bootstrap5_bundle_script()` and Google Charts helpers so you can wire up common browser libraries without hand-building script tags.
+
+## Asset Helpers
+
+Tailwind is injected with the official Play CDN script because that is the fastest supported browser-side setup for this library. Bootstrap 5 is injected as a CSS stylesheet from jsDelivr. Google Fonts are emitted as a preconnect pair plus a CSS2 stylesheet link so browsers can establish connections early and only download the fonts you ask for.
+
+Common Tailwind class families that pair well with the helpers:
+
+- Layout: `container`, `mx-auto`, `flex`, `grid`, `gap-*`, `items-center`, `justify-between`
+- Spacing: `p-*`, `px-*`, `py-*`, `m-*`, `space-x-*`, `space-y-*`
+- Typography: `text-*`, `font-*`, `leading-*`, `tracking-*`
+- Surface: `bg-*`, `text-*`, `border-*`, `rounded-*`, `shadow-*`
+- Responsive prefixes: `sm:`, `md:`, `lg:`, `xl:`, `2xl:`
+
+Common Bootstrap 5 class families that pair well with the helpers:
+
+- Layout and grid: `container`, `container-fluid`, `row`, `col`, `g-*`, `row-cols-*`
+- Spacing and display: `m-*`, `p-*`, `d-flex`, `d-grid`, `gap-*`, `justify-content-*`, `align-items-*`
+- Typography: `lead`, `fw-bold`, `fst-italic`, `text-muted`, `text-center`, `text-nowrap`
+- Components: `btn`, `btn-primary`, `card`, `badge`, `alert`, `navbar`, `modal`
+- Responsive prefixes: `sm`, `md`, `lg`, `xl`, `xxl`
+
+Google Fonts examples:
+
+- `google_fonts_assets("Inter")`
+- `google_fonts_assets("Inter", "Open Sans")`
+- `google_fonts_assets("Roboto", weights=(400, 700), text="Hello world")`
+
+## Layout
+
+- `src/html5/document.py` contains the HTML5 document and element primitives.
+- `src/html5/elements.py` contains generated classes for standard HTML5 tags.
+- `src/html5/css.py` contains CSS node classes for comments, declarations, rules, at-rules, keyframes, inline styles, and `<style>` generation.
+- `src/html5/js.py` contains JavaScript helpers for inline scripts, external scripts, Bootstrap 5, and Google Charts.
+- `src/html5/writer.py` contains a disk writer for rendered HTML and CSS outputs.
+- `src/html5/version.py` stores the semantic version string used by packaging.
+
+## Versioning
+
+This project uses semantic versioning. The current package version is `0.3.0`, and the release history is documented in [CHANGELOG.md](CHANGELOG.md).

html5cc-0.3.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+html5/__init__.py,sha256=5JPvAKio0VdXclTdSd6gGJh9krj_yfK-fomdVMzV5YQ,967
+html5/css.py,sha256=Awd05kzIkg9wzibrwUWEPHRrpd44UTzGYvuZ_G6Nw6g,12206
+html5/document.py,sha256=U0zuXlgQobg1nmjOemEsiarpchbV6zgjNYBMRW1sutw,4057
+html5/elements.py,sha256=qq1hvTGm7UIKoGeSatGacEkbrpRtd5kMNzZA4x-FhDo,7697
+html5/js.py,sha256=MFd6DPT1UsPwyy15zwg-V5gPSkt3WI0Hl_Qwq_pcDzo,2574
+html5/version.py,sha256=ARHt_V5W60rkhA4dNqWOMwN6UASxrGycgPN13sngWbQ,58
+html5/writer.py,sha256=Ul2e3A_3cfCsREnQcg_wtc1bXCMj6t24smscabyb3r0,1665
+html5cc-0.3.0.dist-info/licenses/LICENSE,sha256=AcJ45gbn44D2lI-RgrcLGCkiDjy2XpC8JhGHH-id07k,1073
+html5cc-0.3.0.dist-info/METADATA,sha256=G5JMlAx_WaD6bkk1VLUw1OGr4-T7bIehSntgdOOPRW4,5715
+html5cc-0.3.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+html5cc-0.3.0.dist-info/top_level.txt,sha256=wGjDApZ61gkSmsTfbb0jalPII1ajGD__R7w7Ba5PAlw,6
+html5cc-0.3.0.dist-info/RECORD,,

html5cc-0.3.0.dist-info/WHEEL

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

html5cc-0.3.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jason Lee Miller
+
+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.

html5cc-0.3.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+html5