draftjs_exporter 5.2.0__py3-none-any.whl

draftjs_exporter/__init__.py

@@ -0,0 +1,5 @@
+__title__ = "draftjs_exporter"
+__version__ = "5.2.0"
+__author__ = "Springload"
+__license__ = "MIT"
+__copyright__ = "Copyright 2016-present Springload"

draftjs_exporter/command.py

@@ -0,0 +1,56 @@
+from typing import List
+
+from draftjs_exporter.types import Block
+
+
+class Command:
+    """
+    A Command represents an operation that has to be executed
+    on a block for it to be converted into an arbitrary number
+    of HTML nodes.
+    """
+
+    __slots__ = ("name", "index", "data")
+
+    def __init__(self, name: str, index: int, data: str = "") -> None:
+        self.name = name
+        self.index = index
+        self.data = data
+
+    def __str__(self) -> str:
+        return f"<Command {self.name} {self.index} {self.data}>"
+
+    def __repr__(self) -> str:
+        return str(self)
+
+    @staticmethod
+    def from_entity_ranges(block: Block) -> List["Command"]:
+        """
+        Creates a list of commands from a block’s list of entity ranges.
+        Each range is converted to two commands: a start_* and a stop_*.
+        """
+        commands: List["Command"] = []
+        for r in block["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"]:
+        """
+        Creates a list of commands from a block’s list of style ranges.
+        Each range is converted to two commands: a start_* and a stop_*.
+        """
+        commands: List["Command"] = []
+        for r in block["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/composite_decorators.py

@@ -0,0 +1,93 @@
+import re
+from operator import itemgetter
+from typing import Any, Dict, Generator, List, Sequence, Tuple
+
+from draftjs_exporter.dom import DOM
+from draftjs_exporter.types import (
+    Block,
+    CompositeDecorators,
+    Decorator,
+    Element,
+)
+
+br = "\n"
+br_strategy = re.compile(r"\n")
+
+
+def get_decorations(
+    decorators: CompositeDecorators, text: str
+) -> List[Tuple[int, int, Any, Decorator]]:
+    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: Sequence[Block],
+) -> Generator[str, None, None]:
+    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: Sequence[Block],
+) -> Element:
+    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:
+    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/constants.py

@@ -0,0 +1,61 @@
+# http://stackoverflow.com/a/22723724/1798491
+class Enum:
+    __slots__ = "elements"
+
+    def __init__(self, *elements: str) -> None:
+        self.elements = tuple(elements)
+
+    def __getattr__(self, name: str) -> str:
+        if name not in self.elements:
+            raise AttributeError(f"'Enum' has no attribute '{name}'")
+
+        return name
+
+
+# https://github.com/facebook/draft-js/blob/master/src/model/constants/DraftBlockType.js
+class BLOCK_TYPES:
+    UNSTYLED = "unstyled"
+    HEADER_ONE = "header-one"
+    HEADER_TWO = "header-two"
+    HEADER_THREE = "header-three"
+    HEADER_FOUR = "header-four"
+    HEADER_FIVE = "header-five"
+    HEADER_SIX = "header-six"
+    UNORDERED_LIST_ITEM = "unordered-list-item"
+    ORDERED_LIST_ITEM = "ordered-list-item"
+    BLOCKQUOTE = "blockquote"
+    PRE = "pre"
+    CODE = "code-block"
+    ATOMIC = "atomic"
+    # Special type to configure handling of missing components.
+    FALLBACK = "fallback"
+
+
+ENTITY_TYPES = Enum(
+    "LINK",
+    "DOCUMENT",
+    "IMAGE",
+    "EMBED",
+    "HORIZONTAL_RULE",
+    # Special type to configure handling of missing components.
+    "FALLBACK",
+)
+
+INLINE_STYLES = Enum(
+    "BOLD",
+    "CODE",
+    "ITALIC",
+    "UNDERLINE",
+    "STRIKETHROUGH",
+    "SUPERSCRIPT",
+    "SUBSCRIPT",
+    "MARK",
+    "QUOTATION",
+    "SMALL",
+    "SAMPLE",
+    "INSERT",
+    "DELETE",
+    "KEYBOARD",
+    # Special type to configure handling of missing components.
+    "FALLBACK",
+)

draftjs_exporter/defaults.py

@@ -0,0 +1,56 @@
+from draftjs_exporter.constants import BLOCK_TYPES, INLINE_STYLES
+from draftjs_exporter.dom import DOM
+from draftjs_exporter.types import Element, Props
+
+
+def render_children(props: Props) -> Element:
+    """
+    Renders the children of a component without any specific
+    markup for the component itself.
+    """
+    return props["children"]
+
+
+def code_block(props: Props) -> Element:
+    return DOM.create_element(
+        "pre", {}, DOM.create_element("code", {}, props["children"])
+    )
+
+
+# Default block map to extend.
+BLOCK_MAP = {
+    BLOCK_TYPES.UNSTYLED: "p",
+    BLOCK_TYPES.HEADER_ONE: "h1",
+    BLOCK_TYPES.HEADER_TWO: "h2",
+    BLOCK_TYPES.HEADER_THREE: "h3",
+    BLOCK_TYPES.HEADER_FOUR: "h4",
+    BLOCK_TYPES.HEADER_FIVE: "h5",
+    BLOCK_TYPES.HEADER_SIX: "h6",
+    BLOCK_TYPES.UNORDERED_LIST_ITEM: {"element": "li", "wrapper": "ul"},
+    BLOCK_TYPES.ORDERED_LIST_ITEM: {"element": "li", "wrapper": "ol"},
+    BLOCK_TYPES.BLOCKQUOTE: "blockquote",
+    BLOCK_TYPES.PRE: "pre",
+    BLOCK_TYPES.CODE: code_block,
+    BLOCK_TYPES.ATOMIC: render_children,
+}
+
+# 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 = {
+    INLINE_STYLES.BOLD: "strong",
+    INLINE_STYLES.CODE: "code",
+    INLINE_STYLES.ITALIC: "em",
+    INLINE_STYLES.UNDERLINE: "u",
+    INLINE_STYLES.STRIKETHROUGH: "s",
+    INLINE_STYLES.SUPERSCRIPT: "sup",
+    INLINE_STYLES.SUBSCRIPT: "sub",
+    INLINE_STYLES.MARK: "mark",
+    INLINE_STYLES.QUOTATION: "q",
+    INLINE_STYLES.SMALL: "small",
+    INLINE_STYLES.SAMPLE: "samp",
+    INLINE_STYLES.INSERT: "ins",
+    INLINE_STYLES.DELETE: "del",
+    INLINE_STYLES.KEYBOARD: "kbd",
+}

draftjs_exporter/dom.py

@@ -0,0 +1,129 @@
+import re
+from typing import Any, Optional
+
+from draftjs_exporter.engines.base import DOMEngine
+from draftjs_exporter.types import HTML, Element, Props, RenderableType
+from draftjs_exporter.utils.module_loading import import_string
+
+# https://gist.github.com/yahyaKacem/8170675
+_first_cap_re = re.compile(r"(.)([A-Z][a-z]+)")
+_all_cap_re = re.compile("([a-z0-9])([A-Z])")
+
+
+class DOM:
+    """
+    Component building API, abstracting the DOM implementation.
+    """
+
+    HTML5LIB = "draftjs_exporter.engines.html5lib.DOM_HTML5LIB"
+    LXML = "draftjs_exporter.engines.lxml.DOM_LXML"
+    STRING = "draftjs_exporter.engines.string.DOMString"
+    STRING_COMPAT = "draftjs_exporter.engines.string_compat.DOMStringCompat"
+
+    dom: DOMEngine = None  # type: ignore
+
+    @staticmethod
+    def camel_to_dash(camel_cased_str: str) -> str:
+        sub2 = _first_cap_re.sub(r"\1-\2", camel_cased_str)
+        dashed_case_str = _all_cap_re.sub(r"\1-\2", sub2).lower()
+        return dashed_case_str.replace("--", "-")
+
+    @classmethod
+    def use(cls, engine: str) -> None:
+        """
+        Choose which DOM implementation to use.
+        """
+        cls.dom = import_string(engine)
+
+    @classmethod
+    def create_element(
+        cls,
+        type_: RenderableType = None,
+        props: Optional[Props] = None,
+        *elt_children: Optional[Element],
+    ) -> Element:
+        """
+        Signature inspired by React.createElement.
+        createElement(
+          string/Component type,
+          [dict props],
+          [children ...]
+        )
+        https://facebook.github.io/react/docs/top-level-api.html#react.createelement
+        """
+        # Create an empty document fragment.
+        if not type_:
+            return cls.dom.create_tag("fragment")
+
+        if props is None:
+            props = {}
+
+        # If the first element of children is a list, we use it as the list.
+        if len(elt_children) and isinstance(elt_children[0], (list, tuple)):
+            children = elt_children[0]
+        else:
+            children = elt_children
+
+        # The children prop is the first child if there is only one.
+        props["children"] = children[0] if len(children) == 1 else children
+
+        if callable(type_):
+            # Function component, via def or lambda.
+            elt = type_(props)
+        else:
+            # Raw tag, as a string.
+            attributes = {}
+
+            # Never render those attributes on a raw tag.
+            props.pop("children", None)
+            props.pop("block", None)
+            props.pop("blocks", None)
+            props.pop("entity", None)
+            props.pop("inline_style_range", None)
+
+            # Convert style object to style string, like the DOM would do.
+            if "style" in props and isinstance(props["style"], dict):
+                rules = [
+                    f"{DOM.camel_to_dash(s)}: {v};" for s, v in props["style"].items()
+                ]
+                props["style"] = "".join(rules)
+
+            # Convert props to HTML attributes.
+            for key in props:
+                if props[key] is False:
+                    props[key] = "false"
+
+                if props[key] is True:
+                    props[key] = "true"
+
+                if props[key] is not None:
+                    attributes[key] = str(props[key])
+
+            elt = cls.dom.create_tag(type_, attributes)
+
+            # Append the children inside the element.
+            for child in children:
+                if child not in (None, ""):
+                    cls.append_child(elt, child)
+
+        # If elt is "empty", create a fragment anyway to add children.
+        if elt in (None, ""):
+            elt = cls.dom.create_tag("fragment")
+
+        return elt
+
+    @classmethod
+    def parse_html(cls, markup: HTML) -> Element:
+        return cls.dom.parse_html(markup)
+
+    @classmethod
+    def append_child(cls, elt: Element, child: Element) -> Any:
+        return cls.dom.append_child(elt, child)
+
+    @classmethod
+    def render(cls, elt: Element) -> HTML:
+        return cls.dom.render(elt)
+
+    @classmethod
+    def render_debug(cls, elt: Element) -> HTML:
+        return cls.dom.render_debug(elt)

draftjs_exporter/engines/base.py

@@ -0,0 +1,50 @@
+from typing import Any, Dict, Optional
+
+from draftjs_exporter.types import HTML, Element, Tag
+
+Attr = Dict[str, str]
+
+
+class DOMEngine:
+    """
+    Parent class of all DOM implementations.
+    """
+
+    @staticmethod
+    def create_tag(type_: Tag, attr: Optional[Attr] = None) -> Any:
+        """
+        Creates and returns a tree node of the given type and attributes.
+        """
+        raise NotImplementedError
+
+    @staticmethod
+    def parse_html(markup: HTML) -> Element:
+        """
+        Creates nodes based on the input html.
+        Note: this method is used in component implementations only, and
+        is not required for the exporter to operate.
+        """
+        raise NotImplementedError
+
+    @staticmethod
+    def append_child(elt: Element, child: Element) -> Any:
+        """
+        Appends the given child node in the children of elt.
+        """
+        raise NotImplementedError
+
+    @staticmethod
+    def render(elt: Element) -> HTML:
+        """
+        Renders a given element to HTML.
+        """
+        raise NotImplementedError
+
+    @staticmethod
+    def render_debug(elt: Element) -> HTML:
+        """
+        Renders a given element to HTML.
+        Note: this method is only used for draftjs_exporter's tests, and
+        is not required for the exporter to operate.
+        """
+        raise NotImplementedError

draftjs_exporter/engines/html5lib.py

@@ -0,0 +1,45 @@
+import re
+from typing import Optional
+
+from draftjs_exporter.engines.base import Attr, DOMEngine
+from draftjs_exporter.types import HTML, Element, Tag
+
+try:
+    from bs4 import BeautifulSoup
+
+    # Cache empty soup so we can create tags in isolation without the performance overhead.
+    soup = BeautifulSoup("", "html5lib")
+except ImportError:
+    pass
+
+RENDER_RE = re.compile(r"</?(fragment|body|html|head)>")
+RENDER_DEBUG_RE = re.compile(r"</?(body|html|head)>")
+
+
+class DOM_HTML5LIB(DOMEngine):
+    """
+    html5lib implementation of the DOM API.
+    """
+
+    @staticmethod
+    def create_tag(type_: Tag, attr: Optional[Attr] = None) -> Element:
+        if not attr:
+            attr = {}
+
+        return soup.new_tag(type_, **attr)
+
+    @staticmethod
+    def parse_html(markup: HTML) -> Element:
+        return BeautifulSoup(markup, "html5lib")
+
+    @staticmethod
+    def append_child(elt: Element, child: Element) -> None:
+        elt.append(child)
+
+    @staticmethod
+    def render(elt: Element) -> HTML:
+        return RENDER_RE.sub("", str(elt))
+
+    @staticmethod
+    def render_debug(elt: Element) -> HTML:
+        return RENDER_DEBUG_RE.sub("", str(elt))

draftjs_exporter/engines/lxml.py

@@ -0,0 +1,49 @@
+import re
+from typing import Optional
+
+from lxml import etree, html
+
+from draftjs_exporter.engines.base import Attr, DOMEngine
+from draftjs_exporter.types import HTML, Tag
+
+NSMAP = {"xlink": "http://www.w3.org/1999/xlink"}
+
+RENDER_RE = re.compile(r"</?fragment>")
+
+
+class DOM_LXML(DOMEngine):
+    """
+    lxml implementation of the DOM API.
+    """
+
+    @staticmethod
+    def create_tag(type_: Tag, attr: Optional[Attr] = None) -> etree.Element:
+        nsmap = None
+
+        if attr:
+            if "xlink:href" in attr:
+                attr[f"{{{NSMAP['xlink']}}}href"] = attr.pop("xlink:href")
+                nsmap = NSMAP
+
+        return etree.Element(type_, attrib=attr, nsmap=nsmap)
+
+    @staticmethod
+    def parse_html(markup: HTML) -> etree.Element:
+        return html.fromstring(markup)
+
+    @staticmethod
+    def append_child(elt: etree.Element, child: etree.Element) -> None:
+        if hasattr(child, "tag"):
+            elt.append(child)
+        else:
+            c = etree.Element("fragment")
+            c.text = child
+            elt.append(c)
+
+    @staticmethod
+    def render(elt: etree.Element) -> HTML:
+        return RENDER_RE.sub("", etree.tostring(elt, method="html", encoding="unicode"))
+
+    @staticmethod
+    def render_debug(elt: etree.Element) -> HTML:
+        return etree.tostring(elt, method="html", encoding="unicode")

draftjs_exporter/engines/string.py

@@ -0,0 +1,116 @@
+from html import escape
+from typing import List, Optional, Sequence, Union
+
+from draftjs_exporter.engines.base import Attr, DOMEngine
+from draftjs_exporter.types import HTML, Tag
+
+# http://w3c.github.io/html/single-page.html#void-elements
+# https://github.com/html5lib/html5lib-python/blob/0cae52b2073e3f2220db93a7650901f2200f2a13/html5lib/constants.py#L560
+VOID_ELEMENTS = (
+    "area",
+    "base",
+    "br",
+    "col",
+    "embed",
+    "hr",
+    "img",
+    "input",
+    "link",
+    "meta",
+    "param",
+    "source",
+    "track",
+    "wbr",
+)
+
+
+class Elt:
+    """
+    A DOM element that the string engine manipulates.
+    This class doesn't do much, but the exporter relies on
+    comparing elements by reference so it's useful nonetheless.
+    """
+
+    __slots__ = ("type", "attr", "children", "markup")
+
+    def __init__(self, type_: Tag, attr: Optional[Attr], markup: HTML = ""):
+        self.type = type_
+        self.attr = attr
+        self.children: List["Elt"] = []
+        self.markup = markup
+
+    @staticmethod
+    def from_html(markup: HTML) -> "Elt":
+        return Elt("escaped_html", None, markup)
+
+
+class DOMString(DOMEngine):
+    """
+    String concatenation implementation of the DOM API.
+    """
+
+    @staticmethod
+    def create_tag(type_: Tag, attr: Optional[Attr] = None) -> Elt:
+        return Elt(type_, attr)
+
+    @staticmethod
+    def parse_html(markup: HTML) -> Elt:
+        """
+        Allows inserting arbitrary HTML into the exporter output.
+        Treats the HTML as if it had been escaped and was safe already.
+        """
+        return Elt.from_html(markup)
+
+    @staticmethod
+    def append_child(elt: Elt, child: Elt) -> None:
+        # This check is necessary because the current wrapper_state implementation
+        # has an issue where it inserts elements multiple times.
+        # This must be skipped for text, which can be duplicated.
+        is_existing_ref = child in elt.children and isinstance(child, Elt)
+        if not is_existing_ref:
+            elt.children.append(child)
+
+    @staticmethod
+    def render_attrs(attr: Attr) -> str:
+        attrs = [f' {k}="{escape(v)}"' for k, v in attr.items()]
+        return "".join(attrs)
+
+    @staticmethod
+    def render_children(children: Sequence[Union[HTML, Elt]]) -> HTML:
+        return "".join(
+            [
+                DOMString.render(c) if isinstance(c, Elt) else escape(c, quote=False)
+                for c in children
+            ]
+        )
+
+    @staticmethod
+    def render(elt: Elt) -> HTML:
+        type_ = elt.type
+        attr = DOMString.render_attrs(elt.attr) if elt.attr else ""
+        children = DOMString.render_children(elt.children) if elt.children else ""
+
+        if type_ == "fragment":
+            return children
+
+        if type_ in VOID_ELEMENTS:
+            return f"<{type_}{attr}/>"
+
+        if type_ == "escaped_html":
+            return elt.markup
+
+        return f"<{type_}{attr}>{children}</{type_}>"
+
+    @staticmethod
+    def render_debug(elt: Elt) -> HTML:
+        type_ = elt.type
+        attr = DOMString.render_attrs(elt.attr) if elt.attr else ""
+        children = DOMString.render_children(elt.children) if elt.children else ""
+
+        if type_ in VOID_ELEMENTS:
+            return f"<{type_}{attr}/>"
+
+        if type_ == "escaped_html":
+            return elt.markup
+
+        return f"<{type_}{attr}>{children}</{type_}>"