Source code for collective.html2blocks.services.html
"""
HTML and Markdown conversion service for ``collective.html2blocks``.
Provides API endpoints for converting HTML or Markdown content to Volto blocks and
block layout information. Includes endpoints for both simple block conversion and
full Volto layout.
Example:
.. code-block:: console
POST /html
POST /markdown
POST /volto
"""
from collective.html2blocks import _types as t
from collective.html2blocks.converter import html_to_blocks
from collective.html2blocks.converter import markdown_to_blocks
from collective.html2blocks.converter import volto_blocks
from fastapi import APIRouter
from fastapi import HTTPException
from pydantic import BaseModel
from typing import Any
from typing import Literal
router = APIRouter()
# The ``blocks`` setting of a request, see
# :func:`~collective.html2blocks.registry.resolve_blocks`.
BlocksField = dict[str, bool | dict[str, Any]] | None
def _bad_request(exc: ValueError) -> HTTPException:
"""Return the 400 response for an invalid ``blocks`` setting."""
return HTTPException(status_code=400, detail=str(exc))
[docs]
class HtmlBody(BaseModel):
"""
Request body model for HTML to blocks conversion.
Attributes:
html (str): The HTML content to convert.
converter (str): The type of conversion to perform (default is ``slate``).
blocks (dict, optional): Enables, disables and configures block types.
"""
html: str
converter: str = "slate"
blocks: BlocksField = None
[docs]
@router.post("/html")
async def convert_html(body: HtmlBody) -> list[t.VoltoBlock]:
"""
Convert HTML to blocks.
Converts the provided HTML content to a list of Volto blocks using the specified
converter.
Args:
body (HtmlBody): Request body containing HTML and converter type.
Returns:
list[VoltoBlock]: The converted blocks.
Raises:
HTTPException: If an unsupported converter is specified.
Example:
.. code-block:: shell
curl -X POST /html -d '{"html": "<p>Hello</p>", "converter": "slate"}'
"""
converter = body.converter
html = body.html
if converter not in ["slate"]:
raise HTTPException(
status_code=400, detail=f"Unsupported converter: {converter}"
)
try:
return html_to_blocks(html, blocks=body.blocks)
except ValueError as exc:
raise _bad_request(exc) from None
[docs]
class MarkdownBody(BaseModel):
"""
Request body model for Markdown to blocks conversion.
:ivar markdown: The Markdown content to convert.
:ivar converter: The type of conversion to perform (default is ``slate``).
:ivar blocks: Enables, disables and configures block types.
"""
markdown: str
converter: str = "slate"
blocks: BlocksField = None
[docs]
@router.post("/markdown")
async def convert_markdown(body: MarkdownBody) -> list[t.VoltoBlock]:
"""
Convert Markdown to blocks.
Converts the provided Markdown content to a list of Volto blocks using the
specified converter.
:param body: Request body containing Markdown and converter type.
:returns: The converted blocks.
:raises HTTPException: If an unsupported converter is specified.
Example:
.. code-block:: shell
curl -X POST /markdown -d '{"markdown": "# Hello", "converter": "slate"}'
"""
converter = body.converter
markdown = body.markdown
if converter not in ["slate"]:
raise HTTPException(
status_code=400, detail=f"Unsupported converter: {converter}"
)
try:
return markdown_to_blocks(markdown, blocks=body.blocks)
except ValueError as exc:
raise _bad_request(exc) from None
[docs]
class VoltoBody(BaseModel):
"""
Request body model for HTML or Markdown to Volto blocks conversion with layout.
:ivar html: The HTML or Markdown content to convert.
:ivar format: The format of ``html``, either ``html`` (default) or ``markdown``.
:ivar default_blocks: Default blocks to include.
:ivar additional_blocks: Additional blocks to include.
:ivar blocks: Enables, disables and configures block types, keyed by
their Volto ``@type``: ``true`` or an object of options enables a
block, ``false`` disables it.
"""
html: str
format: Literal["html", "markdown"] = "html"
default_blocks: list[t.VoltoBlock] | None = None
additional_blocks: list[t.VoltoBlock] | None = None
blocks: BlocksField = None
[docs]
@router.post("/volto")
def convert_to_volto(body: VoltoBody) -> t.VoltoBlocksInfo:
"""
Convert HTML or Markdown to Volto blocks and return blocks information.
Converts the provided content to a Volto blocks structure, including block
layout. The ``format`` field tells whether the content is HTML or Markdown.
:param body: Request body containing the content, its format and block lists.
:returns: Information about the converted Volto blocks and layout.
Example:
.. code-block:: shell
curl -X POST /volto -d '{"html": "<p>Hello</p>"}'
curl -X POST /volto -d '{"html": "# Hello", "format": "markdown"}'
curl -X POST /volto -d '{"html": "<pre>ls</pre>",
"blocks": {"codeBlock": true}}'
"""
html = body.html
default_blocks = body.default_blocks or []
additional_blocks = body.additional_blocks or []
try:
return volto_blocks(
html,
default_blocks,
additional_blocks,
source_format=body.format,
blocks=body.blocks,
)
except ValueError as exc:
raise _bad_request(exc) from None