draftjs_exporter 5.2.0__tar.gz → 6.0.0__tar.gz

draftjs_exporter-6.0.0/PKG-INFO

@@ -0,0 +1,75 @@
+Metadata-Version: 2.4
+Name: draftjs_exporter
+Version: 6.0.0
+Summary: Library to convert rich text from Draft.js raw ContentState to HTML
+License-Expression: MIT
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Classifier: Topic :: Internet :: WWW/HTTP :: Site Management
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Text Editors :: Word Processors
+Classifier: Typing :: Typed
+Requires-Dist: beautifulsoup4>=4.4.1,<5 ; extra == 'html5lib'
+Requires-Dist: html5lib>=0.999,<2 ; extra == 'html5lib'
+Requires-Dist: lxml>=4.6.5,<7 ; extra == 'lxml'
+Requires-Python: >=3.10
+Project-URL: Documentation, https://wagtail.github.io/draftjs_exporter/
+Project-URL: Source, https://github.com/wagtail/draftjs_exporter
+Project-URL: Tracker, https://github.com/wagtail/draftjs_exporter/issues
+Project-URL: Changelog, https://github.com/wagtail/draftjs_exporter/blob/main/CHANGELOG.md
+Project-URL: llms.txt, https://wagtail.github.io/draftjs_exporter/llms.txt
+Provides-Extra: html5lib
+Provides-Extra: lxml
+Description-Content-Type: text/markdown
+
+# [Draft.js exporter](https://pypi.org/project/draftjs_exporter/)
+
+> Library to convert rich text from Draft.js raw ContentState to HTML.
+
+## Features
+
+This project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html), and [measures performance](https://thib.me/python-memory-profiling-for-the-draft-js-exporter) and [code coverage](https://coveralls.io/github/wagtail/draftjs_exporter). Code is checked with [mypy](https://mypy.readthedocs.io/en/latest/index.html).
+
+- Extensive configuration of the generated HTML.
+- Default, extensible block & inline style maps for common HTML elements.
+- Convert line breaks to `<br>` elements with decorators.
+- Define any attribute in the block map – custom class names for elements.
+- React-like API to create custom components.
+- Automatic conversion of entity data to HTML attributes (int & boolean to string, style object to style string).
+- Nested lists (`<li>` elements go inside `<ul>` or `<ol>`, with multiple levels).
+- Output inline styles as inline elements (`<em>`, `<strong>`, pick and choose, with any attribute).
+- Overlapping inline style and entity ranges.
+- Static type annotations.
+
+It is developed alongside the [Draftail](https://www.draftail.org/) rich text editor, for [Wagtail](https://github.com/wagtail/wagtail). Check out the [online demo](http://playground.draftail.org/), and our [introductory blog post](https://www.draftail.org/blog/2018/03/13/rethinking-rich-text-pipelines-with-draft-js).
+
+## When to use the exporter
+
+[Draft.js](https://draftjs.org/) is a rich text editor framework for [React](https://reactjs.org/). Its approach is different from most rich text editors because it does not store data as HTML, but rather in its own representation called ContentState. This exporter is useful when the ContentState to HTML conversion has to be done in a Python ecosystem.
+
+The initial use case was to gain more control over the content managed by rich text editors in a Wagtail/Django site. If you want to read the full story, have a look at our blog post: [Rethinking rich text pipelines with Draft.js](https://www.draftail.org/blog/2018/03/13/rethinking-rich-text-pipelines-with-draft-js).
+
+## Documentation
+
+The full documentation is available at [on the docs website](https://wagtail.github.io/draftjs_exporter/). For LLM-assisted tooling, there is also a concise [`llms.txt`](https://wagtail.github.io/draftjs_exporter/llms.txt) and a complete [`llms-full.txt`](https://wagtail.github.io/draftjs_exporter/llms-full.txt).
+
+## Contributing
+
+See anything you like in here? Anything missing? We welcome all support, whether on bug reports, feature requests, code, design, reviews, tests, documentation, and more. Please have a look at our [contribution guidelines](docs/CONTRIBUTING.md).
+
+## Credits
+
+Draftail was created by [Springload](https://github.com/springload/), and is now maintained by Wagtail contributors. View the full list of [contributors](https://github.com/wagtail/draftjs_exporter/graphs/contributors). MIT licensed.

draftjs_exporter-6.0.0/README.md

@@ -0,0 +1,38 @@
+# [Draft.js exporter](https://pypi.org/project/draftjs_exporter/)
+
+> Library to convert rich text from Draft.js raw ContentState to HTML.
+
+## Features
+
+This project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html), and [measures performance](https://thib.me/python-memory-profiling-for-the-draft-js-exporter) and [code coverage](https://coveralls.io/github/wagtail/draftjs_exporter). Code is checked with [mypy](https://mypy.readthedocs.io/en/latest/index.html).
+
+- Extensive configuration of the generated HTML.
+- Default, extensible block & inline style maps for common HTML elements.
+- Convert line breaks to `<br>` elements with decorators.
+- Define any attribute in the block map – custom class names for elements.
+- React-like API to create custom components.
+- Automatic conversion of entity data to HTML attributes (int & boolean to string, style object to style string).
+- Nested lists (`<li>` elements go inside `<ul>` or `<ol>`, with multiple levels).
+- Output inline styles as inline elements (`<em>`, `<strong>`, pick and choose, with any attribute).
+- Overlapping inline style and entity ranges.
+- Static type annotations.
+
+It is developed alongside the [Draftail](https://www.draftail.org/) rich text editor, for [Wagtail](https://github.com/wagtail/wagtail). Check out the [online demo](http://playground.draftail.org/), and our [introductory blog post](https://www.draftail.org/blog/2018/03/13/rethinking-rich-text-pipelines-with-draft-js).
+
+## When to use the exporter
+
+[Draft.js](https://draftjs.org/) is a rich text editor framework for [React](https://reactjs.org/). Its approach is different from most rich text editors because it does not store data as HTML, but rather in its own representation called ContentState. This exporter is useful when the ContentState to HTML conversion has to be done in a Python ecosystem.
+
+The initial use case was to gain more control over the content managed by rich text editors in a Wagtail/Django site. If you want to read the full story, have a look at our blog post: [Rethinking rich text pipelines with Draft.js](https://www.draftail.org/blog/2018/03/13/rethinking-rich-text-pipelines-with-draft-js).
+
+## Documentation
+
+The full documentation is available at [on the docs website](https://wagtail.github.io/draftjs_exporter/). For LLM-assisted tooling, there is also a concise [`llms.txt`](https://wagtail.github.io/draftjs_exporter/llms.txt) and a complete [`llms-full.txt`](https://wagtail.github.io/draftjs_exporter/llms-full.txt).
+
+## Contributing
+
+See anything you like in here? Anything missing? We welcome all support, whether on bug reports, feature requests, code, design, reviews, tests, documentation, and more. Please have a look at our [contribution guidelines](docs/CONTRIBUTING.md).
+
+## Credits
+
+Draftail was created by [Springload](https://github.com/springload/), and is now maintained by Wagtail contributors. View the full list of [contributors](https://github.com/wagtail/draftjs_exporter/graphs/contributors). MIT licensed.

draftjs_exporter-6.0.0/draftjs_exporter/__init__.py

@@ -0,0 +1,98 @@
+"""Public API and metadata of draftjs_exporter.
+
+This module gathers metadata, core classes, default configuration maps,
+type aliases, and helpers so callers can import everything from
+``draftjs_exporter`` directly.
+"""
+
+__title__ = "draftjs_exporter"
+__version__ = "6.0.0"
+__uri__ = "https://wagtail.github.io/draftjs_exporter/"
+__author__ = "Springload and Contributors"
+__license__ = "MIT"
+__copyright__ = "Copyright 2016-present Springload and Contributors"
+
+from draftjs_exporter.constants import BLOCK_TYPES as BLOCK_TYPES
+from draftjs_exporter.constants import ENTITY_TYPES as ENTITY_TYPES
+from draftjs_exporter.constants import INLINE_STYLES as INLINE_STYLES
+from draftjs_exporter.defaults import BLOCK_MAP as BLOCK_MAP
+from draftjs_exporter.defaults import STYLE_MAP as STYLE_MAP
+from draftjs_exporter.dom import DOM as DOM
+from draftjs_exporter.html import HTML as HTML
+from draftjs_exporter.html import ExporterConfig as ExporterConfig
+from draftjs_exporter.markdown import CONFIG as MARKDOWN_CONFIG
+from draftjs_exporter.markdown import MarkdownOptions as MarkdownOptions
+from draftjs_exporter.markdown import build_markdown_config as build_markdown_config
+from draftjs_exporter.types import Block as Block
+from draftjs_exporter.types import Component as Component
+from draftjs_exporter.types import CompositeDecorators as CompositeDecorators
+from draftjs_exporter.types import ConfigMap as ConfigMap
+from draftjs_exporter.types import ContentState as ContentState
+from draftjs_exporter.types import Decorator as Decorator
+from draftjs_exporter.types import Element as Element
+from draftjs_exporter.types import Entity as Entity
+from draftjs_exporter.types import EntityKey as EntityKey
+from draftjs_exporter.types import EntityMap as EntityMap
+from draftjs_exporter.types import EntityRange as EntityRange
+from draftjs_exporter.types import InlineStyleRange as InlineStyleRange
+from draftjs_exporter.types import Mutability as Mutability
+from draftjs_exporter.types import Props as Props
+from draftjs_exporter.types import RenderableConfig as RenderableConfig
+from draftjs_exporter.types import RenderableType as RenderableType
+from draftjs_exporter.types import Tag as Tag
+
+__all__ = [
+    # Metadata
+    "__title__",
+    "__version__",
+    "__uri__",
+    "__author__",
+    "__license__",
+    "__copyright__",
+    # Core
+    "Exporter",
+    "HTML",
+    "ExporterConfig",
+    "ContentState",
+    "DOM",
+    # Configs
+    "HTML_CONFIG",
+    "MARKDOWN_CONFIG",
+    "MarkdownOptions",
+    "build_markdown_config",
+    # Constants
+    "BLOCK_TYPES",
+    "ENTITY_TYPES",
+    "INLINE_STYLES",
+    # Default maps
+    "BLOCK_MAP",
+    "STYLE_MAP",
+    # Types
+    "Block",
+    "Component",
+    "CompositeDecorators",
+    "ConfigMap",
+    "ContentState",
+    "Decorator",
+    "Element",
+    "Entity",
+    "EntityKey",
+    "EntityMap",
+    "EntityRange",
+    "InlineStyleRange",
+    "Mutability",
+    "Props",
+    "RenderableConfig",
+    "RenderableType",
+    "Tag",
+]
+
+Exporter = HTML
+"""Compatibility alias for the HTML exporter."""
+
+HTML_CONFIG: ExporterConfig = {
+    "block_map": BLOCK_MAP,
+    "style_map": STYLE_MAP,
+    "engine": DOM.STRING,
+}
+"""Default exporter configuration using the built-in maps and string engine."""

draftjs_exporter-6.0.0/draftjs_exporter/command.py

@@ -0,0 +1,69 @@
+"""Represent and build rendering commands derived from Draft.js ranges."""
+
+from draftjs_exporter.types import Block
+
+
+class Command:
+    """Represent an operation applied while converting a block to HTML nodes."""
+
+    __slots__ = ("name", "index", "data")
+
+    def __init__(self, name: str, index: int, data: str = "") -> None:
+        """Initialize a command.
+
+        Parameters:
+            name: The operation name, such as ``start_entity`` or ``stop_inline_style``.
+            index: The character offset at which the command applies.
+            data: The payload for the command, such as an entity key or style name.
+        """
+        self.name = name
+        self.index = index
+        self.data = data
+
+    def __str__(self) -> str:
+        """Return a human-readable representation of the command."""
+        return f"<Command {self.name} {self.index} {self.data}>"
+
+    def __repr__(self) -> str:
+        """Return the same representation as ``__str__`` for debugging."""
+        return str(self)
+
+    @staticmethod
+    def from_entity_ranges(block: Block) -> list["Command"]:
+        """Create start and stop commands from a block's entity ranges.
+
+        Parameters:
+            block: The block containing ``entityRanges``.
+
+        Returns:
+            A list of start_entity and stop_entity commands.
+        """
+        commands: list["Command"] = []
+        for r in block.get("entityRanges", []):
+            # Entity key is an integer in entity ranges, while a string in the entity map.
+            data = str(r["key"])
+            start = r["offset"]
+            stop = start + r["length"]
+            commands.append(Command("start_entity", start, data))
+            commands.append(Command("stop_entity", stop, data))
+
+        return commands
+
+    @staticmethod
+    def from_style_ranges(block: Block) -> list["Command"]:
+        """Create start and stop commands from a block's inline style ranges.
+
+        Parameters:
+            block: The block containing ``inlineStyleRanges``.
+
+        Returns:
+            A list of start_inline_style and stop_inline_style commands.
+        """
+        commands: list["Command"] = []
+        for r in block.get("inlineStyleRanges", []):
+            data = r["style"]
+            start = r["offset"]
+            stop = start + r["length"]
+            commands.append(Command("start_inline_style", start, data))
+            commands.append(Command("stop_inline_style", stop, data))
+        return commands

draftjs_exporter-6.0.0/draftjs_exporter/composite_decorators.py

@@ -0,0 +1,137 @@
+"""Apply regex-based composite decorators to text while rendering blocks."""
+
+import re
+from collections.abc import Generator
+from operator import itemgetter
+from typing import Any
+
+from draftjs_exporter.dom import DOM
+from draftjs_exporter.engines.base import DOMEngine
+from draftjs_exporter.types import Block, CompositeDecorators, Decorator, Element
+
+br = "\n"
+"""Line-break character handled by the default decorator strategy."""
+
+br_strategy = re.compile(r"\n")
+"""Default decorator strategy matching single line breaks."""
+
+
+def get_decorations(
+    decorators: CompositeDecorators, text: str
+) -> list[tuple[int, int, Any, Decorator]]:
+    """Collect non-overlapping decorator matches for the given text.
+
+    Parameters:
+        decorators: Composite decorator definitions.
+        text: The block text to decorate.
+
+    Returns:
+        A sorted list of decorations as ``(start, end, match, decorator)`` tuples.
+    """
+    occupied: dict[int, int] = {}
+    decorations = []
+
+    for decorator in decorators:
+        for match in decorator["strategy"].finditer(text):
+            begin, end = match.span()
+            if not any(occupied.get(i) for i in range(begin, end)):
+                for i in range(begin, end):
+                    occupied[i] = 1
+                decorations.append((begin, end, match, decorator))
+
+    decorations.sort(key=itemgetter(0))
+
+    return decorations
+
+
+def apply_decorators(
+    decorators: CompositeDecorators,
+    text: str,
+    block: Block,
+    blocks: list[Block],
+) -> Generator[str, None, None]:
+    """Yield decorated text segments and decorator elements for a block.
+
+    Parameters:
+        decorators: Composite decorator definitions.
+        text: The block text to decorate.
+        block: The block currently being rendered.
+        blocks: All blocks in the content state.
+
+    Yields:
+        Plain text or decorator element nodes covering the full block text.
+    """
+    decorations = get_decorations(decorators, text)
+
+    pointer = 0
+    for begin, end, match, decorator in decorations:
+        if pointer < begin:
+            yield text[pointer:begin]
+
+        yield DOM.create_element(
+            decorator["component"],
+            {"match": match, "block": block, "blocks": blocks},
+            match.group(0),
+        )
+        pointer = end
+
+    if pointer < len(text):
+        yield text[pointer:]
+
+
+def render_decorators(
+    decorators: CompositeDecorators,
+    text: str,
+    block: Block,
+    blocks: list[Block],
+    dom: type[DOMEngine],
+) -> Element:
+    """Render all decorator output for a block into a single element.
+
+    Parameters:
+        decorators: Composite decorator definitions.
+        text: The block text to decorate.
+        block: The block currently being rendered.
+        blocks: All blocks in the content state.
+        dom: The active DOM engine.
+
+    Returns:
+        A single element containing all decorated text, or the text itself.
+    """
+    decorated_children = list(apply_decorators(decorators, text, block, blocks))
+
+    if len(decorated_children) == 1:
+        decorated_node = decorated_children[0]
+    else:
+        decorated_node = DOM.create_element()
+        for decorated_child in decorated_children:
+            dom.append_child(decorated_node, decorated_child)
+
+    return decorated_node
+
+
+def should_render_decorators(
+    decorators: CompositeDecorators,
+    text: str,
+) -> bool:
+    """Return whether decorators need to be processed for the given text.
+
+    Parameters:
+        decorators: Composite decorator definitions.
+        text: The block text to check.
+
+    Returns:
+        True when there are decorators and the default newline-only optimization does not apply.
+    """
+    nb_decorators = len(decorators)
+
+    if nb_decorators == 0:
+        return False
+
+    is_skippable_br = (
+        nb_decorators == 1
+        and decorators[0]["strategy"] == br_strategy
+        and br not in text
+    )
+
+    return not is_skippable_br

{draftjs_exporter-5.2.0 → draftjs_exporter-6.0.0}/draftjs_exporter/constants.py

@@ -1,11 +1,36 @@
+"""Draft.js-compatible constants used by the exporter.
+
+Defines the block types, inline styles, and entity categories supported
+by Draft.js, plus a small enum helper.
+"""
+
+
 # http://stackoverflow.com/a/22723724/1798491
 class Enum:
+    """Minimal enum-like container exposing a fixed set of string attributes.
+
+    Accessing a registered attribute returns its name. Accessing any other
+    attribute raises ``AttributeError``.
+    """
+
     __slots__ = "elements"
 
     def __init__(self, *elements: str) -> None:
+        """Store the allowed attribute names for the enum."""
         self.elements = tuple(elements)
 
     def __getattr__(self, name: str) -> str:
+        """Return the attribute name if it is a registered enum element.
+
+        Parameters:
+            name: Attribute name being accessed.
+
+        Returns:
+            The requested attribute name.
+
+        Raises:
+            AttributeError: If the name is not a registered element.
+        """
         if name not in self.elements:
             raise AttributeError(f"'Enum' has no attribute '{name}'")
 
@@ -14,6 +39,8 @@ class Enum:
 
 # https://github.com/facebook/draft-js/blob/master/src/model/constants/DraftBlockType.js
 class BLOCK_TYPES:
+    """Draft.js block types mapped to HTML elements."""
+
     UNSTYLED = "unstyled"
     HEADER_ONE = "header-one"
     HEADER_TWO = "header-two"
@@ -40,6 +67,7 @@ ENTITY_TYPES = Enum(
     # Special type to configure handling of missing components.
     "FALLBACK",
 )
+"""Draft.js entity categories."""
 
 INLINE_STYLES = Enum(
     "BOLD",
@@ -59,3 +87,4 @@ INLINE_STYLES = Enum(
     # Special type to configure handling of missing components.
     "FALLBACK",
 )
+"""Draft.js inline style names."""

{draftjs_exporter-5.2.0 → draftjs_exporter-6.0.0}/draftjs_exporter/defaults.py

@@ -1,24 +1,28 @@
+"""Default block and style maps for the exporter.
+
+The mappings connect Draft.js block types and inline styles to HTML
+tags or component functions.
+"""
+
 from draftjs_exporter.constants import BLOCK_TYPES, INLINE_STYLES
 from draftjs_exporter.dom import DOM
-from draftjs_exporter.types import Element, Props
+from draftjs_exporter.types import ConfigMap, Element, Props
 
 
 def render_children(props: Props) -> Element:
-    """
-    Renders the children of a component without any specific
-    markup for the component itself.
-    """
+    """Return the children of a component without wrapping markup."""
     return props["children"]
 
 
 def code_block(props: Props) -> Element:
+    """Render a code block inside a ``pre`` > ``code`` element tree."""
     return DOM.create_element(
         "pre", {}, DOM.create_element("code", {}, props["children"])
     )
 
 
 # Default block map to extend.
-BLOCK_MAP = {
+BLOCK_MAP: ConfigMap = {
     BLOCK_TYPES.UNSTYLED: "p",
     BLOCK_TYPES.HEADER_ONE: "h1",
     BLOCK_TYPES.HEADER_TWO: "h2",
@@ -33,12 +37,14 @@ BLOCK_MAP = {
     BLOCK_TYPES.CODE: code_block,
     BLOCK_TYPES.ATOMIC: render_children,
 }
+"""Default mapping from block types to renderable tags or components."""
+
 
 # Default style map to extend.
 # Tags come from https://developer.mozilla.org/en-US/docs/Web/HTML/Element.
 # and are loosely aligned with https://github.com/jpuri/draftjs-to-html.
 # Only styles that map to HTML elements are allowed as defaults.
-STYLE_MAP = {
+STYLE_MAP: ConfigMap = {
     INLINE_STYLES.BOLD: "strong",
     INLINE_STYLES.CODE: "code",
     INLINE_STYLES.ITALIC: "em",
@@ -54,3 +60,4 @@ STYLE_MAP = {
     INLINE_STYLES.DELETE: "del",
     INLINE_STYLES.KEYBOARD: "kbd",
 }
+"""Default mapping from inline styles to HTML tags."""