draftjs_exporter 5.2.0__py3-none-any.whl

draftjs_exporter/engines/string_compat.py

@@ -0,0 +1,62 @@
+from html import escape
+from typing import Sequence, Union
+
+from draftjs_exporter.engines.base import Attr
+from draftjs_exporter.engines.string import VOID_ELEMENTS, DOMString, Elt
+from draftjs_exporter.types import HTML
+
+
+class DOMStringCompat(DOMString):
+    """
+    The same as DOMString, but with as much backwards-compatibility as possible.
+    """
+
+    @staticmethod
+    def render_attrs(attr: Attr) -> str:
+        attrs = [f' {k}="{escape(v)}"' for k, v in attr.items()]
+        # Compat: reverts "Remove HTML attributes alphabetical sorting of default string engine ([#129](https://github.com/springload/draftjs_exporter/pull/129))"
+        attrs.sort()
+        return "".join(attrs)
+
+    @staticmethod
+    def render_children(children: Sequence[Union[HTML, Elt]]) -> HTML:
+        return "".join(
+            [
+                DOMStringCompat.render(c)
+                if isinstance(c, Elt)
+                # Compat: reverts "Disable single and double quotes escaping outside of attributes for string engine ([#129](https://github.com/springload/draftjs_exporter/pull/129))"
+                else escape(c, quote=True)
+                for c in children
+            ]
+        )
+
+    @staticmethod
+    def render(elt: Elt) -> HTML:
+        type_ = elt.type
+        attr = DOMStringCompat.render_attrs(elt.attr) if elt.attr else ""
+        children = DOMStringCompat.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 = DOMStringCompat.render_attrs(elt.attr) if elt.attr else ""
+        children = DOMStringCompat.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_}>"

draftjs_exporter/entity_state.py

@@ -0,0 +1,108 @@
+from typing import List, Optional, Sequence
+
+from draftjs_exporter.command import Command
+from draftjs_exporter.constants import ENTITY_TYPES
+from draftjs_exporter.dom import DOM
+from draftjs_exporter.error import ExporterException
+from draftjs_exporter.options import Options, OptionsMap
+from draftjs_exporter.types import (
+    Block,
+    Element,
+    EntityDetails,
+    EntityKey,
+    EntityMap,
+)
+
+
+class EntityException(ExporterException):
+    pass
+
+
+class EntityState:
+    __slots__ = (
+        "entity_options",
+        "entity_map",
+        "entity_stack",
+        "completed_entity",
+        "element_stack",
+    )
+
+    def __init__(self, entity_options: OptionsMap, entity_map: EntityMap) -> None:
+        self.entity_options = entity_options
+        self.entity_map = entity_map
+
+        self.entity_stack: List[EntityKey] = []
+        self.completed_entity: Optional[EntityKey] = None
+        self.element_stack: List[Element] = []
+
+    def apply(self, command: Command) -> None:
+        if command.name == "start_entity":
+            self.entity_stack.append(command.data)
+        elif command.name == "stop_entity":
+            expected_entity = self.entity_stack[-1]
+
+            if command.data != expected_entity:
+                raise EntityException(f"Expected {expected_entity}, got {command.data}")
+
+            self.completed_entity = self.entity_stack.pop()
+
+    def has_entity(self) -> List[EntityKey]:
+        return self.entity_stack
+
+    def has_no_entity(self) -> bool:
+        return not self.entity_stack
+
+    def get_entity_details(self, entity_key: EntityKey) -> EntityDetails:
+        details = self.entity_map.get(entity_key)
+
+        if details is None:
+            raise EntityException(
+                f'Entity "{entity_key}" does not exist in the entityMap'
+            )
+
+        return details
+
+    def render_entities(
+        self, style_node: Element, block: Block, blocks: Sequence[Block]
+    ) -> Element:
+        # We have a complete (start, stop) entity to render.
+        if self.completed_entity is not None:
+            entity_details = self.get_entity_details(self.completed_entity)
+            options = Options.get(
+                self.entity_options,
+                entity_details["type"],
+                ENTITY_TYPES.FALLBACK,
+            )
+            props = entity_details["data"].copy()
+            props["entity"] = {
+                "type": entity_details["type"],
+                "mutability": entity_details["mutability"]
+                if "mutability" in entity_details
+                else None,
+                "block": block,
+                "blocks": blocks,
+                "entity_range": {"key": self.completed_entity},
+            }
+
+            if len(self.element_stack) == 1:
+                children = self.element_stack[0]
+            else:
+                children = DOM.create_element()
+
+                for n in self.element_stack:
+                    DOM.append_child(children, n)
+
+            self.completed_entity = None
+            self.element_stack = []
+
+            # Is there still another entity? (adjacent) if so add the current style_node for it.
+            if self.has_entity():
+                self.element_stack.append(style_node)
+
+            return DOM.create_element(options.element, props, children)
+
+        if self.has_entity():
+            self.element_stack.append(style_node)
+            return None
+
+        return style_node

draftjs_exporter/error.py

@@ -0,0 +1,6 @@
+class ExporterException(Exception):
+    pass
+
+
+class ConfigException(ExporterException):
+    pass

draftjs_exporter/html.py

@@ -0,0 +1,180 @@
+from itertools import groupby
+from operator import attrgetter
+from typing import List, Optional, Tuple
+
+from draftjs_exporter.command import Command
+from draftjs_exporter.composite_decorators import (
+    render_decorators,
+    should_render_decorators,
+)
+from draftjs_exporter.defaults import BLOCK_MAP, STYLE_MAP
+from draftjs_exporter.dom import DOM
+from draftjs_exporter.entity_state import EntityState
+from draftjs_exporter.options import Options
+from draftjs_exporter.style_state import StyleState
+from draftjs_exporter.types import (
+    Block,
+    Config,
+    ContentState,
+    Element,
+    EntityMap,
+)
+from draftjs_exporter.wrapper_state import WrapperState
+
+
+class HTML:
+    """
+    Entry point of the exporter. Combines entity, wrapper and style state
+    to generate the right HTML nodes.
+    """
+
+    __slots__ = (
+        "composite_decorators",
+        "entity_options",
+        "block_options",
+        "style_options",
+    )
+
+    def __init__(self, config: Optional[Config] = None) -> None:
+        if config is None:
+            config = {}
+
+        self.composite_decorators = config.get("composite_decorators", [])
+
+        self.entity_options = Options.map_entities(config.get("entity_decorators", {}))
+        self.block_options = Options.map_blocks(config.get("block_map", BLOCK_MAP))
+        self.style_options = Options.map_styles(config.get("style_map", STYLE_MAP))
+
+        DOM.use(config.get("engine", DOM.STRING))
+
+    def render(self, content_state: Optional[ContentState] = None) -> str:
+        """
+        Starts the export process on a given piece of content state.
+        """
+        if content_state is None:
+            content_state = {}
+
+        blocks = content_state.get("blocks", [])
+        wrapper_state = WrapperState(self.block_options, blocks)
+        document = DOM.create_element()
+        entity_map = content_state.get("entityMap", {})
+        min_depth = 0
+
+        for block in blocks:
+            # Assume a depth of 0 if it's not specified, like Draft.js would.
+            depth = block["depth"] if "depth" in block else 0
+            elt = self.render_block(block, entity_map, wrapper_state)
+
+            if depth > min_depth:
+                min_depth = depth
+
+            # At level 0, append the element to the document.
+            if depth == 0:
+                DOM.append_child(document, elt)
+
+        # If there is no block at depth 0, we need to add the wrapper that contains the whole tree to the document.
+        if min_depth > 0 and wrapper_state.stack.length() != 0:
+            DOM.append_child(document, wrapper_state.stack.tail().elt)
+
+        return DOM.render(document)
+
+    def render_block(
+        self, block: Block, entity_map: EntityMap, wrapper_state: WrapperState
+    ) -> Element:
+        has_styles = "inlineStyleRanges" in block and block["inlineStyleRanges"]
+        has_entities = "entityRanges" in block and block["entityRanges"]
+        has_decorators = should_render_decorators(
+            self.composite_decorators, block["text"]
+        )
+
+        if has_styles or has_entities:
+            content = DOM.create_element()
+            entity_state = EntityState(self.entity_options, entity_map)
+            style_state = StyleState(self.style_options) if has_styles else None
+
+            for text, commands in self.build_command_groups(block):
+                for command in commands:
+                    entity_state.apply(command)
+                    if style_state:
+                        style_state.apply(command)
+
+                # Decorators are not rendered inside entities.
+                if has_decorators and entity_state.has_no_entity():
+                    decorated_node = render_decorators(
+                        self.composite_decorators,
+                        text,
+                        block,
+                        wrapper_state.blocks,
+                    )
+                else:
+                    decorated_node = text
+
+                if style_state:
+                    styled_node = style_state.render_styles(
+                        decorated_node, block, wrapper_state.blocks
+                    )
+                else:
+                    styled_node = decorated_node
+                entity_node = entity_state.render_entities(
+                    styled_node, block, wrapper_state.blocks
+                )
+
+                if entity_node is not None:
+                    DOM.append_child(content, entity_node)
+
+                    # Check whether there actually are two different nodes, confirming we are not inserting an upcoming entity.
+                    if styled_node != entity_node and entity_state.has_no_entity():
+                        DOM.append_child(content, styled_node)
+        # Fast track for blocks which do not contain styles nor entities, which is very common.
+        elif has_decorators:
+            content = render_decorators(
+                self.composite_decorators,
+                block["text"],
+                block,
+                wrapper_state.blocks,
+            )
+        else:
+            content = block["text"]
+
+        return wrapper_state.element_for(block, content)
+
+    def build_command_groups(self, block: Block) -> List[Tuple[str, List[Command]]]:
+        """
+        Creates block modification commands, grouped by start index,
+        with the text to apply them on.
+        """
+        text = block["text"]
+
+        commands = self.build_commands(block)
+        grouped = groupby(commands, attrgetter("index"))
+        listed = list(groupby(commands, attrgetter("index")))
+        sliced = []
+
+        i = 0
+        for start_index, comms in grouped:
+            if i < len(listed) - 1:
+                stop_index = listed[i + 1][0]
+                sliced.append((text[start_index:stop_index], list(comms)))
+            else:
+                sliced.append(("", list(comms)))
+            i += 1
+
+        return sliced
+
+    def build_commands(self, block: Block) -> List[Command]:
+        """
+        Build all of the manipulation commands for a given block.
+        - One pair to set the text.
+        - Multiple pairs for styles.
+        - Multiple pairs for entities.
+        """
+        style_commands = Command.from_style_ranges(block)
+        entity_commands = Command.from_entity_ranges(block)
+        styles_and_entities = style_commands + entity_commands
+        styles_and_entities.sort(key=attrgetter("index"))
+
+        return (
+            [Command("start_text", 0)]
+            + styles_and_entities
+            + [Command("stop_text", len(block["text"]))]
+        )

draftjs_exporter/options.py

@@ -0,0 +1,105 @@
+from typing import Any, Dict, Optional
+
+from draftjs_exporter.constants import BLOCK_TYPES, ENTITY_TYPES, INLINE_STYLES
+from draftjs_exporter.error import ConfigException
+from draftjs_exporter.types import ConfigMap, Props, RenderableType
+
+# Internal equivalent of a ConfigMap.
+OptionsMap = Dict[str, "Options"]
+
+
+class Options:
+    """
+    Facilitates querying configuration from a config map.
+    """
+
+    __slots__ = ("type", "element", "props", "wrapper", "wrapper_props")
+
+    def __init__(
+        self,
+        type_: str,
+        element: RenderableType,
+        props: Optional[Props] = None,
+        wrapper: RenderableType = None,
+        wrapper_props: Optional[Props] = None,
+    ) -> None:
+        self.type = type_
+        self.element = element
+        self.props = props if props else {}
+        self.wrapper = wrapper
+        self.wrapper_props = wrapper_props
+
+    def __str__(self) -> str:
+        return f"<Options {self.type} {self.element} {self.props} {self.wrapper} {self.wrapper_props}>"
+
+    def __repr__(self) -> str:
+        return str(self)
+
+    def __eq__(self, other: Any) -> bool:
+        """
+        Equality used in test code only, not to be relied on for the exporter.
+        """
+        return str(self) == str(other)
+
+    def __ne__(self, other: Any) -> bool:
+        return not self == other
+
+    def __hash__(self) -> int:
+        return hash(str(self))
+
+    @staticmethod
+    def create(kind_map: ConfigMap, type_: str, fallback_key: str) -> "Options":
+        """
+        Create an Options object from any mapping.
+        """
+        if type_ not in kind_map:
+            if fallback_key not in kind_map:
+                raise ConfigException(
+                    f'"{type_}" is not in the config and has no fallback'
+                )
+
+            config = kind_map[fallback_key]
+        else:
+            config = kind_map[type_]
+
+        if isinstance(config, dict):
+            if "element" not in config:
+                raise ConfigException(f'"{type_}" does not define an element')
+
+            opts = Options(type_, **config)
+        else:
+            opts = Options(type_, config)
+
+        return opts
+
+    @staticmethod
+    def map(kind_map: ConfigMap, fallback_key: str) -> OptionsMap:
+        options = {}
+        for type_ in kind_map:
+            options[type_] = Options.create(kind_map, type_, fallback_key)
+
+        return options
+
+    @staticmethod
+    def map_blocks(block_map: ConfigMap) -> OptionsMap:
+        return Options.map(block_map, BLOCK_TYPES.FALLBACK)
+
+    @staticmethod
+    def map_styles(style_map: ConfigMap) -> OptionsMap:
+        return Options.map(style_map, INLINE_STYLES.FALLBACK)
+
+    @staticmethod
+    def map_entities(entity_map: ConfigMap) -> OptionsMap:
+        return Options.map(entity_map, ENTITY_TYPES.FALLBACK)
+
+    @staticmethod
+    def get(options: OptionsMap, type_: str, fallback_key: str) -> "Options":
+        try:
+            return options[type_]
+        except KeyError:
+            try:
+                return options[fallback_key]
+            except KeyError:
+                raise ConfigException(
+                    f'"{type_}" is not in the config and has no fallback'
+                )

draftjs_exporter/style_state.py

@@ -0,0 +1,49 @@
+from typing import List, Sequence
+
+from draftjs_exporter.command import Command
+from draftjs_exporter.constants import INLINE_STYLES
+from draftjs_exporter.dom import DOM
+from draftjs_exporter.options import Options, OptionsMap
+from draftjs_exporter.types import Block, Element
+
+
+class StyleState:
+    """
+    Handles the creation of inline styles on elements.
+    Receives inline_style commands, and generates the element's `style`
+    attribute from those.
+    """
+
+    __slots__ = ("styles", "style_options")
+
+    def __init__(self, style_options: OptionsMap) -> None:
+        self.styles: List[str] = []
+        self.style_options = style_options
+
+    def apply(self, command: Command) -> None:
+        if command.name == "start_inline_style":
+            self.styles.append(command.data)
+        elif command.name == "stop_inline_style":
+            self.styles.remove(command.data)
+
+    def is_empty(self) -> bool:
+        return not self.styles
+
+    def render_styles(
+        self, decorated_node: Element, block: Block, blocks: Sequence[Block]
+    ) -> Element:
+        node = decorated_node
+        if not self.is_empty():
+            # This will mutate self.styles, but it’s going to be reset after rendering anyway.
+            self.styles.sort(reverse=True)
+
+            # Nest the tags.
+            for style in self.styles:
+                options = Options.get(self.style_options, style, INLINE_STYLES.FALLBACK)
+                props = dict(options.props)
+                props["block"] = block
+                props["blocks"] = blocks
+                props["inline_style_range"] = {"style": style}
+                node = DOM.create_element(options.element, props, node)
+
+        return node

draftjs_exporter/types.py

@@ -0,0 +1,35 @@
+from typing import Any, Callable, Dict, List, Mapping, Union
+
+# Element represents an instance of a RenderableType. It’s engine-specific so very hard to type.
+Element = Any
+# Props are always a dictionary with string keys and arbitrary values.
+# TODO Other types than string for keys.
+Props = Dict[str, Any]
+
+# A DOM tag name.
+Tag = str
+# A component function, taking props as a parameter and returning an Element by calling DOM.create_element.
+Component = Callable[[Props], Element]
+# What can be rendered: None, DOM tag name, Component.
+RenderableType = Union[None, Tag, Component]
+# The output of the exporter.
+HTML = str
+
+# The whole config object.
+Config = Dict[str, Any]
+# block_map, style_map, entity_decorators.
+# The dict could be limited to a fixed set of keys, but this would require TypedDict.
+ConfigMap = Mapping[str, Union[Dict[str, Any], RenderableType]]
+# composite_decorators.
+Decorator = Dict[str, Any]
+CompositeDecorators = List[Decorator]
+
+# The whole content state. blocks and entity_map.
+ContentState = Mapping[str, Any]
+# Blocks have a predetermined set of keys and values, but let’s be permissive without TypedDict.
+Block = Mapping[str, Any]
+# Entity key is int in blocks, str in Entity map.
+EntityKey = str
+# Entities have fixed keys.
+EntityDetails = Mapping[str, Any]
+EntityMap = Mapping[EntityKey, EntityDetails]

draftjs_exporter/utils/module_loading.py

@@ -0,0 +1,25 @@
+from importlib import import_module
+from typing import Any
+
+
+def import_string(dotted_path: str) -> Any:
+    """
+    Import a dotted module path and return the attribute/class designated by the
+    last name in the path. Raise ImportError if the import failed.
+
+    Taken from Django:
+    https://github.com/django/django/blob/f6bd00131e687aedf2719ad31e84b097562ca5f2/django/utils/module_loading.py#L7-L24
+    """
+    try:
+        module_path, class_name = dotted_path.rsplit(".", 1)
+    except ValueError:
+        raise ImportError(f"{dotted_path} doesn't look like a module path")
+
+    module = import_module(module_path)
+
+    try:
+        return getattr(module, class_name)
+    except AttributeError:
+        raise ImportError(
+            f'Module "{module_path}" does not define a "{class_name}" attribute/class'
+        )