collective.html2blocks 1.0.0a1__tar.gz

collective.html2blocks-1.0.0a1/.gitignore

@@ -0,0 +1,18 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+.mypy_cache
+.pytest_cache
+.ruff_cache
+.coverage
+
+# Test files
+tmp.json
+tmp.html
+
+# Virtual environments
+.venv

collective.html2blocks-1.0.0a1/PKG-INFO

@@ -0,0 +1,47 @@
+Metadata-Version: 2.4
+Name: collective.html2blocks
+Version: 1.0.0a1
+Summary: Convert html to blocks to be used by Volto
+Project-URL: Homepage, https://github.com/collective/collective.html2blocks#readme
+Project-URL: Changelog, https://github.com/collective/collective.html2blocks/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/collective/collective.html2blocks/issues
+Project-URL: Source, https://github.com/collective/collective.html2blocks
+Project-URL: Repository, https://github.com/collective/collective.html2blocks
+Author-email: Érico Andrei <ericof@plone.org>
+Keywords: Plone,Python,Volto
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Web Environment
+Classifier: Framework :: Plone
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: GNU General Public License v2 (GPLv2)
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.12
+Requires-Dist: beautifulsoup4>=4.13.3
+Requires-Dist: fastapi[standard]>=0.116.1
+Requires-Dist: python-slugify>=8.0.4
+Requires-Dist: typer>=0.15.1
+Description-Content-Type: text/markdown
+
+<h1 align="center">collective.html2blocks</h1>
+
+<div align="center">
+
+[![PyPI](https://img.shields.io/pypi/v/collective.html2blocks)](https://pypi.org/project/collective.html2blocks/)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/collective.html2blocks)](https://pypi.org/project/collective.html2blocks/)
+[![PyPI - Wheel](https://img.shields.io/pypi/wheel/collective.html2blocks)](https://pypi.org/project/collective.html2blocks/)
+[![PyPI - License](https://img.shields.io/pypi/l/collective.html2blocks)](https://pypi.org/project/collective.html2blocks/)
+[![PyPI - Status](https://img.shields.io/pypi/status/collective.html2blocks)](https://pypi.org/project/collective.html2blocks/)
+
+
+[![Code Quality](https://github.com/collective/collective.html2blocks/actions/workflows/qa.yml/badge.svg)](https://github.com/collective/collective.html2blocks/actions/workflows/qa.yml)
+[![Tests](https://github.com/collective/collective.html2blocks/actions/workflows/test.yml/badge.svg)](https://github.com/collective/collective.html2blocks/actions/workflows/test.yml)
+
+[![GitHub contributors](https://img.shields.io/github/contributors/collective/collective.html2blocks)](https://github.com/collective/collective.html2blocks)
+[![GitHub Repo stars](https://img.shields.io/github/stars/collective/collective.html2blocks?style=social)](https://github.com/collective/collective.html2blocks)
+
+</div>
+
+**collective.html2blocks** helps with migrations from old Plone versions -- and other CMS -- to Volto.

collective.html2blocks-1.0.0a1/README.md

@@ -0,0 +1,20 @@
+<h1 align="center">collective.html2blocks</h1>
+
+<div align="center">
+
+[![PyPI](https://img.shields.io/pypi/v/collective.html2blocks)](https://pypi.org/project/collective.html2blocks/)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/collective.html2blocks)](https://pypi.org/project/collective.html2blocks/)
+[![PyPI - Wheel](https://img.shields.io/pypi/wheel/collective.html2blocks)](https://pypi.org/project/collective.html2blocks/)
+[![PyPI - License](https://img.shields.io/pypi/l/collective.html2blocks)](https://pypi.org/project/collective.html2blocks/)
+[![PyPI - Status](https://img.shields.io/pypi/status/collective.html2blocks)](https://pypi.org/project/collective.html2blocks/)
+
+
+[![Code Quality](https://github.com/collective/collective.html2blocks/actions/workflows/qa.yml/badge.svg)](https://github.com/collective/collective.html2blocks/actions/workflows/qa.yml)
+[![Tests](https://github.com/collective/collective.html2blocks/actions/workflows/test.yml/badge.svg)](https://github.com/collective/collective.html2blocks/actions/workflows/test.yml)
+
+[![GitHub contributors](https://img.shields.io/github/contributors/collective/collective.html2blocks)](https://github.com/collective/collective.html2blocks)
+[![GitHub Repo stars](https://img.shields.io/github/stars/collective/collective.html2blocks?style=social)](https://github.com/collective/collective.html2blocks)
+
+</div>
+
+**collective.html2blocks** helps with migrations from old Plone versions -- and other CMS -- to Volto.

collective.html2blocks-1.0.0a1/collective/html2blocks/__init__.py

@@ -0,0 +1,2 @@
+__version__ = "1.0.0a1"
+PACKAGE_NAME = "collective.html2blocks"

collective.html2blocks-1.0.0a1/collective/html2blocks/_types.py

@@ -0,0 +1,119 @@
+from bs4 import Tag
+from collections.abc import Callable
+from collections.abc import Generator
+from collections.abc import Sequence
+from dataclasses import dataclass
+from typing import NotRequired
+from typing import Protocol
+from typing import TypedDict
+
+import re
+
+
+BaseVoltoBlock = TypedDict("BaseVoltoBlock", {"@type": str})
+
+
+class VoltoBlock(BaseVoltoBlock, total=False):
+    """Volto Block type with optional fields."""
+
+    value: NotRequired[list]
+    align: NotRequired[str]
+    size: NotRequired[str]
+    url: NotRequired[str]
+    plaintext: NotRequired[str]
+
+
+class SlateBlockItem(TypedDict, total=False):
+    """A child in an Slate Block."""
+
+    type: NotRequired[str]
+    text: NotRequired[str]
+    key: NotRequired[str]
+    cells: NotRequired[Sequence["SlateBlockItem"]]
+    children: NotRequired[list["SlateBlockItem"]]
+    value: NotRequired["SlateBlockItem | str"]
+
+
+class BlocksLayout(TypedDict):
+    """Blocks layout information."""
+
+    items: Sequence[str]
+
+
+class VoltoBlocksInfo(TypedDict):
+    """Volto Blocks information."""
+
+    blocks: dict[str, VoltoBlock]
+    blocks_layout: BlocksLayout
+
+
+class BlockConverter(Protocol):
+    """Protocol for block converters."""
+
+    __name__: str
+    __orig_mod__: str
+
+    def __call__(self, element: Tag) -> Generator[VoltoBlock, None, None]: ...
+
+
+class ElementConverterFunc(Protocol):
+    """Protocol for element converters."""
+
+    __name__: str
+    __module__: str
+
+    def __call__(
+        self, element: Tag, tag_name: str
+    ) -> Generator[VoltoBlock, None, SlateBlockItem]: ...
+
+
+class ElementConverter(ElementConverterFunc):
+    """Protocol for element converters."""
+
+    __name__: str
+    __orig_mod__: str
+
+
+SlateItemsGenerator = Generator[VoltoBlock | None, None, list[SlateBlockItem]]
+
+SlateItemGenerator = Generator[VoltoBlock | None, None, SlateBlockItem | None]
+
+
+@dataclass
+class IFrameConverter:
+    url_pattern: str
+    provider: str
+    converter: Callable
+
+
+@dataclass
+class Registry:
+    block_converters: dict[str, BlockConverter]
+    element_converters: dict[str, ElementConverter]
+    iframe_converters: dict[re.Pattern | str, IFrameConverter]
+    default: BlockConverter | None = None
+
+
+@dataclass
+class EmbedInfo:
+    url: str
+    provider_id: str
+    converter: Callable
+
+
+class ReportRegistrations(TypedDict):
+    """Report registrations type."""
+
+    block: dict[str, str]
+    element: dict[str, str]
+    iframe: dict[str, str]
+
+
+__all__ = [
+    "EmbedInfo",
+    "Registry",
+    "ReportRegistrations",
+    "Tag",
+    "VoltoBlock",
+    "VoltoBlocksInfo",
+]

collective.html2blocks-1.0.0a1/collective/html2blocks/blocks/__init__.py

@@ -0,0 +1,56 @@
+"""
+Block converters for collective.html2blocks.
+
+This module imports and exposes the main block converter functions for HTML elements
+such as iframe, image, slate (rich text), table, and video. These converters are
+registered with the html2blocks registry and are used to transform HTML elements
+into Volto blocks for use in Plone/Volto content management systems.
+
+Each converter implements a specific strategy for handling its corresponding HTML tag:
+
+- `iframe_block`: Converts <iframe> elements to Volto embed blocks,
+  handling provider-specific logic.
+- `image_block`: Converts <img> elements to Volto image blocks,
+  extracting src, alt, and other attributes.
+- `slate_block`: Converts rich text elements (paragraphs, headings,
+  lists, etc.) to Volto Slate blocks, supporting nested and inline content.
+- `table_block`: Converts <table> elements to Volto table blocks,
+  handling headers, rows, and cell types.
+- `video_block`: Converts <video> elements to Volto video blocks,
+  extracting sources and metadata.
+
+These converters are registered using decorators and can be extended or referenced
+by other developers to implement custom block conversion logic. See the implementation
+of each block in its respective module for details on parsing, normalization, and
+Volto block structure.
+
+Example usage::
+
+    from collective.html2blocks.blocks import slate_block
+    blocks = slate_block(element)
+
+For custom converters, use the registry decorators:
+
+    from collective.html2blocks.registry import block_converter
+
+    @block_converter('custom')
+    def custom_block(element):
+        ...
+
+__all__ lists the available block converters for import and reference.
+"""
+
+from .iframe import iframe_block
+from .image import image_block
+from .slate import slate_block
+from .table import table_block
+from .video import video_block
+
+
+__all__ = [
+    "iframe_block",
+    "image_block",
+    "slate_block",
+    "table_block",
+    "video_block",
+]

collective.html2blocks-1.0.0a1/collective/html2blocks/blocks/iframe/__init__.py

@@ -0,0 +1,31 @@
+from .soundcloud import soundcloud_block
+from .youtube import youtube_block
+from collections.abc import Generator
+from collective.html2blocks import _types as t
+from collective.html2blocks import registry
+from collective.html2blocks.utils.markup import url_from_iframe
+
+
+__all__ = [
+    "iframe_block",
+    "iframe_default_block",
+    "soundcloud_block",
+    "youtube_block",
+]
+
+
+@registry.iframe_converter("iframe")
+def iframe_default_block(
+    element: t.Tag, src: str, provider_id: str
+) -> Generator[t.VoltoBlock, None, None]:
+    """Implemented by @kitconcept/volto-iframe-block."""
+    height = element.get("height", "200px")
+    yield {"@type": "iframe", "src": src, "width": "full", "height": height}
+
+
+@registry.block_converter("iframe")
+def iframe_block(element: t.Tag) -> Generator[t.VoltoBlock, None, None]:
+    """Variations of the iframe block."""
+    src = url_from_iframe(element)
+    embed_info = registry.get_iframe_converter(src)
+    yield from embed_info.converter(element, embed_info.url, embed_info.provider_id)

collective.html2blocks-1.0.0a1/collective/html2blocks/blocks/iframe/soundcloud.py

@@ -0,0 +1,25 @@
+from collective.html2blocks import _types as t
+from collective.html2blocks import registry
+
+import re
+
+
+SOUNDCLOUD_REGEX = re.compile(
+    r"https://w\.soundcloud.com/player/\?url=https(%3A|:)//api.soundcloud.com/tracks/(?P<provider_id>\d+)(.*)$"
+)
+
+
+@registry.iframe_converter(
+    "soundcloud",
+    src_pattern=SOUNDCLOUD_REGEX,
+    url_pattern=r"https://api.soundcloud.com/tracks/\g<provider_id>\2",
+)
+def soundcloud_block(element: t.Tag, src: str, provider_id: str) -> list[t.VoltoBlock]:
+    """Implemented by @kitconcept/volto-social-blocks."""
+    block: t.VoltoBlock = {
+        "@type": "soundcloudBlock",
+        "soundcloudId": provider_id,
+        "align": "center",
+        "size": "l",
+    }
+    return [block]

collective.html2blocks-1.0.0a1/collective/html2blocks/blocks/iframe/youtube.py

@@ -0,0 +1,32 @@
+from collective.html2blocks import _types as t
+from collective.html2blocks import registry
+
+import re
+
+
+YOUTUBE_REGEX = re.compile(
+    r"^(http:|https:|)\/\/(m.|www.)?(youtu(be\.com|\.be|be\.googleapis\.com|be-nocookie\.com))\/(embed\/|watch\?v=|v\/)?(?P<provider_id>[A-Za-z0-9._%-]*)(\?\S+|\&\S+)?$"
+)
+
+
+def get_youtube_video_id(url: str) -> str:
+    video_id = ""
+    if match := re.match(YOUTUBE_REGEX, url):
+        video_id = match.group("provider_id")
+    return video_id
+
+
+def _youtube_block(src: str) -> list[t.VoltoBlock]:
+    """Return a block to display youtube videos."""
+    block: t.VoltoBlock = {"@type": "video", "url": src}
+    return [block]
+
+
+@registry.iframe_converter(
+    "youtube",
+    src_pattern=YOUTUBE_REGEX,
+    url_pattern=r"https://youtu.be/\g<provider_id>",
+)
+def youtube_block(element: t.Tag, src: str, provider_id: str) -> list[t.VoltoBlock]:
+    """Implemented by @plone/volto."""
+    return _youtube_block(src)

collective.html2blocks-1.0.0a1/collective/html2blocks/blocks/image.py

@@ -0,0 +1,112 @@
+"""
+Image block converter for collective.html2blocks.
+
+This module provides the block converter for <img> elements, transforming them
+into Volto image blocks. It extracts image attributes, alignment, size, and
+custom data attributes, supporting Plone/Volto conventions for image handling.
+
+Implementation details:
+- Alignment and size are inferred from CSS classes and image src patterns.
+- Custom data attributes are added to the block for extensibility.
+- The converter yields a Volto image block with all relevant metadata.
+
+Example usage::
+
+    from collective.html2blocks.blocks.image import image_block
+    blocks = list(image_block(element))
+"""
+
+from collections.abc import Generator
+from collective.html2blocks import _types as t
+from collective.html2blocks import registry
+from collective.html2blocks.logger import logger
+
+import re
+
+
+def _align_from_classes(css_classes: list[str]) -> str:
+    align = "center"
+    if "image-left" in css_classes:
+        align = "left"
+    elif "image-right" in css_classes:
+        align = "right"
+    elif "image-inline" in css_classes:
+        align = "center"
+    return align
+
+
+def _add_align_to_block(block: t.VoltoBlock, css_classes: list[str]) -> None:
+    size: str = "l"
+    match align := _align_from_classes(css_classes):
+        case "left":
+            size = "m"
+        case "right":
+            size = "m"
+    block["align"] = align
+    block["size"] = size
+
+
+def _add_size_to_block(block: t.VoltoBlock, src: str) -> None:
+    size: str = block.get("size", "m")
+    match _scale_from_src(src):
+        case "large":
+            size = "l"
+        case "preview":
+            size = "l"
+        case "thumb":
+            size = "s"
+        case "tile":
+            size = "s"
+    block["size"] = size
+
+
+def _add_data_attrs_to_block(block: t.VoltoBlock, attrs: dict) -> None:
+    data_attrs: dict = {k: v for k, v in attrs.items() if k.startswith("data-")}
+    for raw_key, value in data_attrs.items():
+        key = raw_key.replace("data-", "")
+        block[key] = value
+
+
+def _scale_from_src(src: str) -> str:
+    scale = ""
+    if (match := re.search("/@@images/(?P<field>[^/]*)/(?P<scale>.+)", src)) or (
+        match := re.search("/image_(?P<scale>.+)", src)
+    ):
+        scale = match.group("scale")
+    elif match := re.search("/image$", src):
+        scale = "original"
+    return scale
+
+
+@registry.block_converter("img")
+def image_block(element: t.Tag) -> Generator[t.VoltoBlock, None, None]:
+    """
+    Convert an <img> element to a Volto image block.
+
+    This converter extracts src, alt, title, alignment, size, and custom data
+    attributes from the image element and yields a Volto image block.
+
+    Args:
+        element (Tag): The <img> element to convert.
+
+    Yields:
+        VoltoBlock: The converted image block.
+
+    Example::
+
+        blocks = list(image_block(element))
+        # [{'@type': 'image', 'url': ..., 'alt': ..., ...}]
+    """
+    src: str = element.get("src")
+    if src is None:
+        logger.debug(f"Dropping element {element}")
+        return None
+    url: str = src.split("/@@images")[0]
+    css_classes: list[str] = element.get("class", [])
+    alt: str = element.get("alt", "")
+    title: str = element.get("title", "")
+    block: t.VoltoBlock = {"@type": "image", "url": url, "alt": alt, "title": title}
+    _add_align_to_block(block, css_classes)
+    _add_size_to_block(block, src)
+    _add_data_attrs_to_block(block, element.attrs)
+    yield block

collective.html2blocks-1.0.0a1/collective/html2blocks/blocks/slate/__init__.py

@@ -0,0 +1,69 @@
+"""
+Slate block converter for collective.html2blocks.
+
+This module provides the default block converter for rich text elements,
+transforming paragraphs, headings, lists, and other inline/nested content into
+Volto Slate blocks. It uses the parser to deserialize HTML elements and
+normalizes the result for Volto consumption.
+
+Implementation details:
+- Handles plain text extraction and normalization.
+- Supports nested and inline content, grouping and flattening as needed.
+- Yields Volto Slate blocks and any additional blocks found during parsing.
+
+Example usage::
+
+    from collective.html2blocks.blocks.slate import slate_block
+    blocks = list(slate_block(element))
+"""
+
+from . import parser
+from collections.abc import Generator
+from collective.html2blocks import _types as t
+from collective.html2blocks import registry
+from collective.html2blocks.utils import markup
+from collective.html2blocks.utils import slate as utils
+
+
+@registry.default_converter
+def slate_block(
+    element: t.Tag,
+) -> Generator[t.VoltoBlock, None, t.VoltoBlock | None]:
+    """
+    Convert rich text HTML elements to Volto Slate blocks.
+
+    This converter deserializes paragraphs, headings, lists, and other content
+    into Volto Slate blocks, handling nested and inline elements, and normalizing
+    the result for Volto. Additional blocks found during parsing are also yielded.
+
+    Args:
+        element (Tag): The HTML element to convert.
+
+    Yields:
+        VoltoBlock: The converted Slate block and any additional blocks.
+
+    Example::
+
+        blocks = list(slate_block(element))
+        # [{'@type': 'slate', 'plaintext': ..., 'value': [...]}]
+    """
+    plaintext = markup.extract_plaintext(element)
+    value = yield from parser.deserialize(element)
+    blocks: list[t.VoltoBlock] = []
+    additional_blocks: list[t.VoltoBlock] = []
+    if value is None:
+        value = []
+    elif isinstance(value, list):
+        value = yield from parser.extract_blocks(value)
+    elif isinstance(value, dict) and (children := value.get("children", [])):
+        children = yield from parser.extract_blocks(children)
+        value["children"] = children
+    if value and not blocks:
+        value = [value] if not isinstance(value, list) else value
+        value = utils.process_top_level_items(value)
+        block = {"@type": "slate", "plaintext": plaintext, "value": value}
+        block = yield from parser.finalize_slate(block)
+        blocks = [block]
+    yield from blocks
+    yield from additional_blocks
+    return None