html5cc 0.3.0__tar.gz → 0.4.0__tar.gz

{html5cc-0.3.0 → html5cc-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: html5cc
-Version: 0.3.0
+Version: 0.4.0
 Summary: A small Python module for building HTML5 documents and CSS3 stylesheets.
 Author: Jason Miller
 License: MIT

{html5cc-0.3.0 → html5cc-0.4.0}/src/html5/__init__.py

@@ -3,6 +3,7 @@
 from .css import (
     CSSAtRule,
     CSSComment,
+    CSSCustomProperties,
     CSSDeclaration,
     CSSLink,
     CSSImportRule,
@@ -21,12 +22,14 @@ from .css import (
     GOOGLE_FONTS_STATIC_URL,
     TAILWIND_PLAY_CDN_URL,
     bootstrap5_stylesheet,
+    css_var,
     google_fonts_assets,
     google_fonts_url,
     inline_style,
     tailwind_script,
     style_tag,
 )
+from .loader import css_loader, html_loader
 from .document import Comment, Doctype, Element, HtmlDocument, Node, Raw, Text, comment, doctype, doctype_node, element, raw, text
 from .elements import *
 from .version import __version__

{html5cc-0.3.0 → html5cc-0.4.0}/src/html5/css.py

@@ -50,6 +50,38 @@ class CSSDeclaration(CSSNode):
         return f"{_normalize_property_name(self.property_name)}: {self.value}{suffix};"
 
 
+def css_var(name: str) -> str:
+    """Return a CSS var() reference for a custom property.
+
+    Example: ``css_var("--size-1")`` → ``"var(--size-1)"``
+    """
+    return f"var({name})"
+
+
+@dataclass(frozen=True, init=False)
+class CSSCustomProperties(CSSNode):
+    """Render a block of CSS custom properties (variables) on a selector.
+
+    Pass a plain ``dict`` mapping ``--name`` strings to values.  The selector
+    defaults to ``:root`` so the variables are available document-wide::
+
+        CSSCustomProperties({"--size-1": "0.25rem", "--color-brand": "#005fcc"})
+    """
+
+    selector: str
+    properties: tuple[tuple[str, Any], ...]
+
+    def __init__(self, props: Mapping[str, Any], selector: str = ":root") -> None:
+        object.__setattr__(self, "selector", selector)
+        object.__setattr__(self, "properties", tuple(props.items()))
+
+    def render(self) -> str:
+        if not self.properties:
+            return f"{self.selector} {{}}"
+        declarations = " ".join(f"{name}: {value};" for name, value in self.properties)
+        return f"{self.selector} {{ {declarations} }}"
+
+
 def _coerce_declaration(value: CSSDeclaration | tuple[str, Any] | Mapping[str, Any]) -> CSSDeclaration:
     if isinstance(value, CSSDeclaration):
         return value
@@ -322,6 +354,14 @@ class CSSStyleSheet(CSSNode):
         self.rules.append(CSSKeyframesRule(name=name, frames=frames))
         return self
 
+    def add_custom_properties(
+        self,
+        props: Mapping[str, Any],
+        selector: str = ":root",
+    ) -> "CSSStyleSheet":
+        self.rules.append(CSSCustomProperties(props, selector=selector))
+        return self
+
     def add_raw(self, css: str) -> "CSSStyleSheet":
         self.rules.append(css)
         return self
@@ -358,6 +398,7 @@ def inline_style(
 __all__ = [
     "CSSAtRule",
     "CSSComment",
+    "CSSCustomProperties",
     "CSSDeclaration",
     "CSSLink",
     "CSSImportRule",
@@ -376,6 +417,7 @@ __all__ = [
     "GOOGLE_FONTS_STATIC_URL",
     "TAILWIND_PLAY_CDN_URL",
     "bootstrap5_stylesheet",
+    "css_var",
     "google_fonts_assets",
     "google_fonts_url",
     "inline_style",

html5cc-0.4.0/src/html5/loader.py

@@ -0,0 +1,141 @@
+"""File loaders that read HTML and CSS into html5 document objects."""
+
+from __future__ import annotations
+
+from html.parser import HTMLParser
+from pathlib import Path
+
+from .css import CSSStyleSheet
+from .document import HtmlDocument, Raw
+
+_VOID_ELEMENTS = frozenset(
+    {
+        "area", "base", "br", "col", "embed", "hr", "img", "input",
+        "link", "meta", "param", "source", "track", "wbr",
+    }
+)
+
+
+class _HTMLStructureParser(HTMLParser):
+    """Extract lang, title, head content, and body content from an HTML file."""
+
+    def __init__(self) -> None:
+        super().__init__(convert_charrefs=False)
+        self.lang: str = "en"
+        self.title: str = ""
+        self._section: str = ""
+        self._in_title: bool = False
+        self._head_buf: list[str] = []
+        self._body_buf: list[str] = []
+
+    def _buf(self) -> list[str]:
+        if self._section == "head":
+            return self._head_buf
+        if self._section == "body":
+            return self._body_buf
+        return []
+
+    def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
+        attr_map = dict(attrs)
+        if tag == "html":
+            self.lang = attr_map.get("lang", "en") or "en"
+            return
+        if tag == "head":
+            self._section = "head"
+            return
+        if tag == "body":
+            self._section = "body"
+            return
+        if tag == "title" and self._section == "head":
+            self._in_title = True
+            return
+        if tag == "meta" and self._section == "head" and "charset" in attr_map:
+            return
+
+        if self._in_title:
+            return
+
+        attrs_str = "".join(
+            f" {k}" if v is None else f' {k}="{v}"'
+            for k, v in attrs
+        )
+        self._buf().append(f"<{tag}{attrs_str}>")
+
+    def handle_endtag(self, tag: str) -> None:
+        if tag in ("html", "head", "body"):
+            if tag == "head":
+                self._section = ""
+            elif tag == "body":
+                self._section = ""
+            return
+        if tag == "title" and self._in_title:
+            self._in_title = False
+            return
+        if tag in _VOID_ELEMENTS or self._in_title:
+            return
+        self._buf().append(f"</{tag}>")
+
+    def handle_data(self, data: str) -> None:
+        if self._in_title:
+            self.title += data
+        else:
+            self._buf().append(data)
+
+    def handle_comment(self, data: str) -> None:
+        self._buf().append(f"<!--{data}-->")
+
+    def handle_entityref(self, name: str) -> None:
+        self._buf().append(f"&{name};")
+
+    def handle_charref(self, name: str) -> None:
+        self._buf().append(f"&#{name};")
+
+
+def html_loader(path: str | Path) -> HtmlDocument:
+    """Read an HTML file and return an :class:`HtmlDocument`.
+
+    The document title, ``lang`` attribute, head nodes, and body content are
+    extracted from the file.  The charset ``<meta>`` tag is stripped (since
+    :meth:`HtmlDocument.render` always emits one).  All other head and body
+    content is preserved as a single :class:`Raw` node each.
+
+    Args:
+        path: Path to the HTML file to read.
+
+    Returns:
+        An :class:`HtmlDocument` populated from the file.
+    """
+    content = Path(path).read_text(encoding="utf-8")
+    parser = _HTMLStructureParser()
+    parser.feed(content)
+
+    doc = HtmlDocument(title=parser.title, lang=parser.lang)
+
+    head_html = "".join(parser._head_buf).strip()
+    if head_html:
+        doc.add_head(Raw(head_html))
+
+    body_html = "".join(parser._body_buf).strip()
+    if body_html:
+        doc.add_body(Raw(body_html))
+
+    return doc
+
+
+def css_loader(path: str | Path) -> CSSStyleSheet:
+    """Read a CSS file and return a :class:`CSSStyleSheet`.
+
+    The file content is stored as a single raw CSS block; no parsing of
+    individual rules is performed.
+
+    Args:
+        path: Path to the CSS file to read.
+
+    Returns:
+        A :class:`CSSStyleSheet` whose rendered output is the file content.
+    """
+    content = Path(path).read_text(encoding="utf-8")
+    return CSSStyleSheet().add_raw(content)
+
+
+__all__ = ["html_loader", "css_loader"]

{html5cc-0.3.0 → html5cc-0.4.0}/src/html5/version.py

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

{html5cc-0.3.0 → html5cc-0.4.0}/src/html5cc.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: html5cc
-Version: 0.3.0
+Version: 0.4.0
 Summary: A small Python module for building HTML5 documents and CSS3 stylesheets.
 Author: Jason Miller
 License: MIT

{html5cc-0.3.0 → html5cc-0.4.0}/src/html5cc.egg-info/SOURCES.txt

@@ -6,6 +6,7 @@ src/html5/css.py
 src/html5/document.py
 src/html5/elements.py
 src/html5/js.py
+src/html5/loader.py
 src/html5/version.py
 src/html5/writer.py
 src/html5cc.egg-info/PKG-INFO

{html5cc-0.3.0 → html5cc-0.4.0}/tests/test_html5.py

@@ -6,6 +6,7 @@ import pytest
 
 from html5 import (
     CSSAtRule,
+    CSSCustomProperties,
     CSSDeclaration,
     CSSKeyframe,
     CSSLayerRule,
@@ -22,10 +23,13 @@ from html5 import (
     __version__,
     bootstrap5_bundle_script,
     bootstrap5_stylesheet,
+    css_loader,
+    css_var,
     google_fonts_assets,
     google_fonts_url,
     google_charts_loader,
     google_charts_package_loader,
+    html_loader,
     javascript_link,
     javascript_script,
     inline_style,
@@ -35,7 +39,7 @@ from html5 import (
 
 
 def test_version_uses_semver() -> None:
-    assert __version__ == "0.3.0"
+    assert __version__ == "0.4.0"
     assert __version__.count(".") == 2
 
 
@@ -246,3 +250,139 @@ def test_markup_writer_rejects_dotdot_traversal(tmp_path: Path) -> None:
 def test_void_html_elements_reject_children() -> None:
     with pytest.raises(ValueError):
         Img("unexpected child", src="hero.png")
+
+
+# ---------------------------------------------------------------------------
+# CSS custom properties
+# ---------------------------------------------------------------------------
+
+def test_css_custom_properties_renders_root_block() -> None:
+    props = CSSCustomProperties({"--size-1": "0.25rem", "--size-2": "0.5rem"})
+    rendered = props.render()
+    assert rendered.startswith(":root {")
+    assert "--size-1: 0.25rem;" in rendered
+    assert "--size-2: 0.5rem;" in rendered
+
+
+def test_css_custom_properties_custom_selector() -> None:
+    props = CSSCustomProperties({"--accent": "#005fcc"}, selector=".theme-dark")
+    rendered = props.render()
+    assert rendered.startswith(".theme-dark {")
+    assert "--accent: #005fcc;" in rendered
+
+
+def test_css_custom_properties_empty_renders_empty_block() -> None:
+    rendered = CSSCustomProperties({}).render()
+    assert rendered == ":root {}"
+
+
+def test_css_var_returns_var_reference() -> None:
+    assert css_var("--size-1") == "var(--size-1)"
+    assert css_var("--color-brand") == "var(--color-brand)"
+
+
+def test_stylesheet_add_custom_properties() -> None:
+    sheet = (
+        CSSStyleSheet()
+        .add_custom_properties({"--gap": "1rem", "--radius": "4px"})
+        .add_rule("button", ("border_radius", css_var("--radius")))
+    )
+    rendered = sheet.render()
+    assert ":root { --gap: 1rem; --radius: 4px; }" in rendered
+    assert "border-radius: var(--radius);" in rendered
+
+
+def test_stylesheet_add_custom_properties_custom_selector() -> None:
+    sheet = CSSStyleSheet().add_custom_properties(
+        {"--fg": "#fff"}, selector="[data-theme='dark']"
+    )
+    rendered = sheet.render()
+    assert "[data-theme='dark'] { --fg: #fff; }" in rendered
+
+
+def test_css_declaration_custom_property_passthrough() -> None:
+    decl = CSSDeclaration("--my-color", "red")
+    assert decl.render() == "--my-color: red;"
+
+
+# ---------------------------------------------------------------------------
+# html_loader / css_loader
+# ---------------------------------------------------------------------------
+
+def test_css_loader_reads_file(tmp_path: Path) -> None:
+    css_file = tmp_path / "styles.css"
+    css_file.write_text("body { margin: 0; }\nh1 { font-size: 2rem; }", encoding="utf-8")
+    sheet = css_loader(css_file)
+    rendered = sheet.render()
+    assert "body { margin: 0; }" in rendered
+    assert "h1 { font-size: 2rem; }" in rendered
+
+
+def test_css_loader_returns_stylesheet_instance(tmp_path: Path) -> None:
+    css_file = tmp_path / "x.css"
+    css_file.write_text("p { color: blue; }", encoding="utf-8")
+    assert isinstance(css_loader(css_file), CSSStyleSheet)
+
+
+def test_html_loader_reads_title_and_lang(tmp_path: Path) -> None:
+    html_file = tmp_path / "index.html"
+    html_file.write_text(
+        '<!doctype html>\n<html lang="fr"><head><meta charset="utf-8">'
+        "<title>Bonjour</title></head><body><p>Texte</p></body></html>",
+        encoding="utf-8",
+    )
+    doc = html_loader(html_file)
+    assert doc.title == "Bonjour"
+    assert doc.lang == "fr"
+
+
+def test_html_loader_body_content_preserved(tmp_path: Path) -> None:
+    html_file = tmp_path / "page.html"
+    html_file.write_text(
+        '<!doctype html><html lang="en"><head><meta charset="utf-8">'
+        "<title>Test</title></head><body><div><h1>Hello</h1></div></body></html>",
+        encoding="utf-8",
+    )
+    doc = html_loader(html_file)
+    rendered = doc.render()
+    assert "<h1>Hello</h1>" in rendered
+    assert "<div>" in rendered
+
+
+def test_html_loader_strips_charset_meta(tmp_path: Path) -> None:
+    html_file = tmp_path / "page.html"
+    html_file.write_text(
+        '<!doctype html><html><head><meta charset="utf-8"><title>X</title>'
+        "</head><body></body></html>",
+        encoding="utf-8",
+    )
+    doc = html_loader(html_file)
+    rendered = doc.render()
+    assert rendered.count('charset="utf-8"') == 1
+
+
+def test_html_loader_returns_html_document(tmp_path: Path) -> None:
+    html_file = tmp_path / "page.html"
+    html_file.write_text(
+        "<!doctype html><html><head><meta charset=\"utf-8\"><title>Hi</title>"
+        "</head><body></body></html>",
+        encoding="utf-8",
+    )
+    assert isinstance(html_loader(html_file), HtmlDocument)
+
+
+def test_html_loader_roundtrip(tmp_path: Path) -> None:
+    sheet = CSSStyleSheet().add_custom_properties({"--size-1": "0.25rem"})
+    original = (
+        HtmlDocument(title="Round Trip", lang="en")
+        .add_head(style_tag(sheet))
+        .add_body(Div(H1("Hello")))
+    )
+    writer = MarkupWriter(root=tmp_path)
+    html_path = writer.write_html("page.html", original)
+    doc = html_loader(html_path)
+    assert doc.title == "Round Trip"
+    assert doc.lang == "en"
+    rendered = doc.render()
+    assert "--size-1: 0.25rem;" in rendered
+    assert "Hello" in rendered