draftjs_exporter 5.2.0__tar.gz → 7.1.0__tar.gz

draftjs_exporter-7.1.0/PKG-INFO

@@ -0,0 +1,75 @@
+Metadata-Version: 2.4
+Name: draftjs_exporter
+Version: 7.1.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-7.1.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-7.1.0/draftjs_exporter/__init__.py

@@ -0,0 +1,178 @@
+"""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__ = "7.1.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.contentstate_filter import (
+    ContentStateFilter as ContentStateFilter,
+)
+from draftjs_exporter.contentstate_filter import FilterRule as FilterRule
+from draftjs_exporter.defaults import BLOCK_MAP as BLOCK_MAP
+from draftjs_exporter.defaults import STYLE_MAP as STYLE_MAP
+from draftjs_exporter.defaults import code_block as code_block
+from draftjs_exporter.defaults import render_children as render_children
+from draftjs_exporter.dom import DOM as DOM
+from draftjs_exporter.error import MarkdownParseError as MarkdownParseError
+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.markdown.blocks import md_list_wrapper as md_list_wrapper
+from draftjs_exporter.markdown.blocks import md_make_ol as md_make_ol
+from draftjs_exporter.markdown.blocks import md_make_ul as md_make_ul
+from draftjs_exporter.markdown.blocks import md_ol as md_ol
+from draftjs_exporter.markdown.blocks import md_prefixed_block as md_prefixed_block
+from draftjs_exporter.markdown.blocks import md_ul as md_ul
+from draftjs_exporter.markdown.code import md_code_element as md_code_element
+from draftjs_exporter.markdown.code import md_code_wrapper as md_code_wrapper
+from draftjs_exporter.markdown.code import md_make_code_element as md_make_code_element
+from draftjs_exporter.markdown.code import md_make_code_wrapper as md_make_code_wrapper
+from draftjs_exporter.markdown.entities import md_horizontal_rule as md_horizontal_rule
+from draftjs_exporter.markdown.entities import md_image as md_image
+from draftjs_exporter.markdown.entities import md_link as md_link
+from draftjs_exporter.markdown.entities import (
+    md_make_horizontal_rule as md_make_horizontal_rule,
+)
+from draftjs_exporter.markdown.fallbacks import md_block_fallback as md_block_fallback
+from draftjs_exporter.markdown.fallbacks import md_entity_fallback as md_entity_fallback
+from draftjs_exporter.markdown.fallbacks import md_style_fallback as md_style_fallback
+from draftjs_exporter.markdown.helpers import md_block as md_block
+from draftjs_exporter.markdown.helpers import md_inline as md_inline
+from draftjs_exporter.markdown.helpers import md_link_destination as md_link_destination
+from draftjs_exporter.markdown.helpers import md_mark_safe as md_mark_safe
+from draftjs_exporter.markdown.styles import md_code_span as md_code_span
+from draftjs_exporter.markdown.styles import md_inline_style as md_inline_style
+from draftjs_exporter.markdown_importer import ImporterConfig as ImporterConfig
+from draftjs_exporter.markdown_importer import MarkdownImporter as MarkdownImporter
+from draftjs_exporter.markdown_parser import EntityResolution as EntityResolution
+from draftjs_exporter.markdown_parser import EntityResolver as EntityResolver
+from draftjs_exporter.markdown_parser import MarkdownParser as MarkdownParser
+from draftjs_exporter.markdown_parser import ParserConfig as ParserConfig
+from draftjs_exporter.markdown_parser import scheme_resolver as scheme_resolver
+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",
+    "HTMLExporter",
+    "ExporterConfig",
+    "ContentState",
+    "DOM",
+    # Configs
+    "HTML_CONFIG",
+    "MARKDOWN_CONFIG",
+    "MarkdownOptions",
+    "build_markdown_config",
+    # Markdown helpers
+    "md_block",
+    "md_block_fallback",
+    "md_code_element",
+    "md_code_span",
+    "md_code_wrapper",
+    "md_entity_fallback",
+    "md_horizontal_rule",
+    "md_image",
+    "md_inline",
+    "md_inline_style",
+    "md_link",
+    "md_link_destination",
+    "md_list_wrapper",
+    "md_make_code_element",
+    "md_make_code_wrapper",
+    "md_make_horizontal_rule",
+    "md_make_ol",
+    "md_make_ul",
+    "md_mark_safe",
+    "md_ol",
+    "md_prefixed_block",
+    "md_style_fallback",
+    "md_ul",
+    # Importer
+    "MarkdownImporter",
+    "ImporterConfig",
+    "MarkdownParser",
+    "ParserConfig",
+    "ContentStateFilter",
+    "FilterRule",
+    "MarkdownParseError",
+    "EntityResolution",
+    "EntityResolver",
+    "scheme_resolver",
+    # Constants
+    "BLOCK_TYPES",
+    "ENTITY_TYPES",
+    "INLINE_STYLES",
+    # Defaults
+    "BLOCK_MAP",
+    "STYLE_MAP",
+    "code_block",
+    "render_children",
+    # 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."""
+
+HTMLExporter = 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-7.1.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-7.1.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: list[tuple[int, int, Any, Decorator]] = []
+
+    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-7.1.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."""