edwh-editorjs 1.0.0__py3-none-any.whl

edwh_editorjs-1.0.0.dist-info/METADATA

@@ -0,0 +1,92 @@
+Metadata-Version: 2.3
+Name: edwh-editorjs
+Version: 1.0.0
+Summary: pyEditorJS
+Project-URL: Homepage, https://github.com/educationwarehouse/edwh-EditorJS
+Author-email: SKevo <skevo.cw@gmail.com>, Robin van der Noord <robin.vdn@educationwarehouse.nl>
+License: MIT
+License-File: LICENSE
+Keywords: bleach,clean,editor,editor.js,html,javascript,json,parser,wysiwyg
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Requires-Dist: bleach
+Provides-Extra: dev
+Requires-Dist: edwh; extra == 'dev'
+Requires-Dist: hatch; extra == 'dev'
+Requires-Dist: su6[all]; extra == 'dev'
+Requires-Dist: types-bleach; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# pyEditorJS
+
+A minimal, fast, Python 3.6+ package for parsing [Editor.js](https://editorjs.io) content.
+
+## Features
+
+- Handles all out-of-the-box Editor.js elements;
+- Optional sanitization via the `bleach` library;
+- Checks whether the data is valid (e. g.: a header can't have more than 6 levels), and raises `EditorJsParseError` if data is malformed;
+- Uses Editor.js's class names for styles, so the output will be consistent with WYSIWYG (see [Editor.js's example style](https://github.com/codex-team/editor.js/blob/8ae8823dcd6877d63241fcb94694a8a18744485d/example/assets/demo.css) and [styles documentation](https://editorjs.io/styles))
+
+## Installation
+
+```bash
+    pip install pyeditorjs
+```
+
+**Optional:** install [bleach](https://pypi.org/project/bleach) for clean HTML:
+
+```bash
+    pip install bleach
+```
+
+## Usage
+
+### Quickstart
+
+```python
+from pyeditorjs import EditorJsParser
+
+editor_js_data = ... # your Editor.js JSON data
+parser = EditorJsParser(editor_js_data) # initialize the parser
+
+html = parser.html(sanitize=True) # `sanitize=True` requires `bleach` to be installed
+print(html) # your clean HTML
+```
+
+### Obtain texts only (for creating audio-only version, for example)
+
+> **WARNING:** This does not sanitize the texts! Please, call `bleach.clean(...)` directly. This also doesn't obtain text from bold texts, markers, etc... - you should use [BeautifulSoup](https://pypi.org/project/beautifulsoup4/) for this.
+
+```python
+#import bleach
+from pyeditorjs import EditorJsParser
+
+editor_js_data = ... # your Editor.js JSON data
+parser = EditorJsParser(editor_js_data) # initialize the parser
+
+all_texts = []
+
+for block in parser:
+    text = getattr(block, 'text', None)
+
+    if text:
+        all_texts.append(text) # all_texts.append(bleach.clean(text))
+
+print(all_texts)
+```
+
+## Disclaimer
+
+This is a community-provided project, and is not affiliated with the Editor.js team.
+It was created in my spare time. I cannot make sure that it will receive consistent updates.
+
+Because of this, PRs, bug reports and suggestions are welcome!
+
+<a href="https://www.buymeacoffee.com/skevo"><img src="https://img.buymeacoffee.com/button-api/?text=Support me&emoji=🐣&slug=skevo&button_colour=ffa200&font_colour=000000&font_family=Poppins&outline_colour=000000&coffee_colour=FFDD00" /></a>

edwh_editorjs-1.0.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+pyeditorjs/__about__.py,sha256=J-j-u0itpEFT6irdmWmixQqYMadNl1X91TxUmoiLHMI,22
+pyeditorjs/__init__.py,sha256=Z0jH2OV2NkieVFU_URtWWhVsIMihIc4IGbUvCW_2Tm0,705
+pyeditorjs/blocks.py,sha256=qksJTNfKShzxinWVIk9DiCGRCJ5C7lp5jLG4Hbl1enk,8214
+pyeditorjs/exceptions.py,sha256=Uni8r3FwJ-6xQIdSmBsHLs_htWLHD0Arp1KJEvjGU1U,439
+pyeditorjs/parser.py,sha256=6DCqqi-FuXDFxn9xb-dgQ19alvVu7Pjx6x3rTAx9IsI,2154
+edwh_editorjs-1.0.0.dist-info/METADATA,sha256=CIRh9bLb2wwbKecMPayxr8TyY4z3GkYlr2L7FJIjCxI,3269
+edwh_editorjs-1.0.0.dist-info/WHEEL,sha256=1yFddiXMmvYK7QYTqtRNtX66WJ0Mz8PYEiEUoOUUxRY,87
+edwh_editorjs-1.0.0.dist-info/licenses/LICENSE,sha256=bY9MhHLeuW8w1aAl-i1O1uSNP5IMOGaL6AWvHcdnt0k,1062
+edwh_editorjs-1.0.0.dist-info/RECORD,,

edwh_editorjs-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.25.0
+Root-Is-Purelib: true
+Tag: py3-none-any

edwh_editorjs-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 SKevo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pyeditorjs/__about__.py

@@ -0,0 +1 @@
+__version__ = "1.0.0"

pyeditorjs/__init__.py

@@ -0,0 +1,28 @@
+from pathlib import Path
+
+from .blocks import BLOCKS_MAP, EditorJsBlock, block
+from .exceptions import EditorJsParseError
+from .parser import EditorJsParser
+
+__all__ = [
+    "EditorJsParser",
+    "EditorJsParseError",
+    "EditorJsBlock",
+    "block",
+    "BLOCKS_MAP",
+]
+
+
+# Overwrite __doc__ with README, so that pdoc can render it:
+README_PATH = Path(__file__).parent.parent.absolute() / Path("README.md")
+try:
+    with open(README_PATH, "r", encoding="UTF-8") as readme:
+        __readme__ = readme.read()
+except Exception:
+    __readme__ = "Failed to read README.md!"  # fallback message, for example when there's no README
+
+__doc__ = __readme__
+
+
+if __name__ == "__main__":
+    _ = [EditorJsParser]

pyeditorjs/blocks.py

@@ -0,0 +1,309 @@
+import abc
+import typing as t
+from dataclasses import dataclass
+
+import bleach
+
+from .exceptions import EditorJsParseError
+
+__all__ = [
+    "block",
+    "BLOCKS_MAP",
+    "EditorJsBlock",
+]
+
+
+def _sanitize(html: str) -> str:
+    return bleach.clean(
+        html,
+        tags=["b", "i", "u", "a", "mark", "code"],
+        attributes=["class", "data-placeholder", "href"],
+    )
+
+
+BLOCKS_MAP: t.Dict[str, t.Type["EditorJsBlock"]] = {
+    # 'header': HeaderBlock,
+    # 'paragraph': ParagraphBlock,
+    # 'list': ListBlock,
+    # 'delimiter': DelimiterBlock,
+    # 'image': ImageBlock,
+}
+
+
+def block(_type: str):
+    def wrapper(cls: t.Type["EditorJsBlock"]):
+        BLOCKS_MAP[_type] = cls
+        return cls
+
+    return wrapper
+
+
+@dataclass
+class EditorJsBlock(abc.ABC):
+    """
+    A generic parsed Editor.js block
+    """
+
+    _data: dict
+    """The raw JSON data of the entire block"""
+
+    @property
+    def id(self) -> t.Optional[str]:
+        """
+        Returns ID of the block, generated client-side.
+        """
+
+        return self._data.get("id", None)
+
+    @property
+    def type(self) -> t.Optional[str]:
+        """
+        Returns the type of the block.
+        """
+
+        return self._data.get("type", None)
+
+    @property
+    def data(self) -> dict:
+        """
+        Returns the actual block data.
+        """
+
+        return self._data.get("data", {})
+
+    @abc.abstractmethod
+    def html(self, sanitize: bool = False) -> str:
+        """
+        Returns the HTML representation of the block.
+
+        ### Parameters:
+        - `sanitize` - if `True`, then the block's text/contents will be sanitized.
+        """
+
+        raise NotImplementedError()
+
+
+@block("header")
+class HeaderBlock(EditorJsBlock):
+    VALID_HEADER_LEVEL_RANGE = range(1, 7)
+    """Valid range for header levels. Default is `range(1, 7)` - so, `0` - `6`."""
+
+    @property
+    def text(self) -> str:
+        """
+        Returns the header's text.
+        """
+
+        return self.data.get("text", "")
+
+    @property
+    def level(self) -> int:
+        """
+        Returns the header's level (`0` - `6`).
+        """
+
+        _level = self.data.get("level", 1)
+
+        if not isinstance(_level, int) or _level not in self.VALID_HEADER_LEVEL_RANGE:
+            raise EditorJsParseError(f"`{_level}` is not a valid header level.")
+
+        return _level
+
+    def html(self, sanitize: bool = False) -> str:
+        text = self.text
+        if sanitize:
+            text = _sanitize(text)
+        return rf'<h{self.level} class="cdx-block ce-header">{text}</h{self.level}>'
+
+
+@block("paragraph")
+class ParagraphBlock(EditorJsBlock):
+    @property
+    def text(self) -> str:
+        """
+        The text content of the paragraph.
+        """
+
+        return self.data.get("text", "")
+
+    def html(self, sanitize: bool = False) -> str:
+        return rf'<p class="cdx-block ce-paragraph">{_sanitize(self.text) if sanitize else self.text}</p>'
+
+
+@block("list")
+class ListBlock(EditorJsBlock):
+    VALID_STYLES = ("unordered", "ordered")
+    """Valid list order styles."""
+
+    @property
+    def style(self) -> t.Optional[str]:
+        """
+        The style of the list. Can be `ordered` or `unordered`.
+        """
+
+        return self.data.get("style", None)
+
+    @property
+    def items(self) -> t.List[str]:
+        """
+        Returns the list's items, in raw format.
+        """
+
+        return self.data.get("items", [])
+
+    def html(self, sanitize: bool = False) -> str:
+        if self.style not in self.VALID_STYLES:
+            raise EditorJsParseError(f"`{self.style}` is not a valid list style.")
+
+        _items = [
+            f"<li>{_sanitize(item) if sanitize else item}</li>" for item in self.items
+        ]
+        _type = "ul" if self.style == "unordered" else "ol"
+        _items_html = "".join(_items)
+
+        return rf'<{_type} class="cdx-block cdx-list cdx-list--{self.style}">{_items_html}</{_type}>'
+
+
+@block("delimiter")
+class DelimiterBlock(EditorJsBlock):
+    def html(self, sanitize: bool = False) -> str:
+        return r'<div class="cdx-block ce-delimiter"></div>'
+
+
+@block("image")
+class ImageBlock(EditorJsBlock):
+    @property
+    def file_url(self) -> str:
+        """
+        URL of the image file.
+        """
+
+        return self.data.get("file", {}).get("url", "")
+
+    @property
+    def caption(self) -> str:
+        """
+        The image's caption.
+        """
+
+        return self.data.get("caption", "")
+
+    @property
+    def with_border(self) -> bool:
+        """
+        Whether the image has a border.
+        """
+
+        return self.data.get("withBorder", False)
+
+    @property
+    def stretched(self) -> bool:
+        """
+        Whether the image is stretched.
+        """
+
+        return self.data.get("stretched", False)
+
+    @property
+    def with_background(self) -> bool:
+        """
+        Whether the image has a background.
+        """
+
+        return self.data.get("withBackground", False)
+
+    def html(self, sanitize: bool = False) -> str:
+        if self.file_url.startswith("data:image/"):
+            _img = self.file_url
+        else:
+            _img = _sanitize(self.file_url) if sanitize else self.file_url
+
+        parts = [
+            rf'<div class="cdx-block image-tool image-tool--filled {"image-tool--stretched" if self.stretched else ""} {"image-tool--withBorder" if self.with_border else ""} {"image-tool--withBackground" if self.with_background else ""}">'
+            r'<div class="image-tool__image">',
+            r'<div class="image-tool__image-preloader"></div>',
+            rf'<img class="image-tool__image-picture" src="{_img}"/>',
+            r"</div>"
+            rf'<div class="image-tool__caption" data-placeholder="{_sanitize(self.caption) if sanitize else self.caption}"></div>'
+            r"</div>"
+            r"</div>",
+        ]
+
+        return "".join(parts)
+
+
+@block("quote")
+class QuoteBlock(EditorJsBlock):
+    def html(self, sanitize: bool = False) -> str:
+        quote = self.data.get("text", "")
+        caption = self.data.get("caption", "")
+        if sanitize:
+            quote = _sanitize(quote)
+            caption = _sanitize(caption)
+        _alignment = self.data.get("alignment", "left")  # todo
+        return f"""
+        <blockquote class="cdx-block cdx-quote">
+            <div class="cdx-input cdx-quote__text">{quote}</div>
+            <cite class="cdx-input cdx-quote__caption">{caption}</cite>
+        </blockquote>
+        """
+
+
+@block("table")
+class TableBlock(EditorJsBlock):
+    def html(self, sanitize: bool = False) -> str:
+        content = self.data.get("content", [])
+        _stretched = self.data.get("stretched", False)  # todo
+        _with_headings = self.data.get("withHeadings", False)  # todo
+
+        html_table = '<table class="tc-table">'
+
+        # Add content rows
+        for row in content:
+            html_table += '<tr class="tc-row">'
+            for cell in row:
+                html_table += (
+                    f'<td class="tc-cell">{_sanitize(cell) if sanitize else cell}</td>'
+                )
+            html_table += "</tr>"
+
+        html_table += "</table>"
+        return html_table
+
+
+@block("code")
+class CodeBlock(EditorJsBlock):
+    def html(self, sanitize: bool = False) -> str:
+        code = self.data.get("code", "")
+        if sanitize:
+            code = _sanitize(code)
+        return f"""
+        <code class="ce-code__textarea cdx-input" data-empty="false">{code}</code>
+        """
+
+
+@block("warning")
+class WarningBlock(EditorJsBlock):
+    def html(self, sanitize: bool = False) -> str:
+        title = self.data.get("title", "")
+        message = self.data.get("message", "")
+
+        if sanitize:
+            title = _sanitize(title)
+            message = _sanitize(message)
+
+        return f"""
+            <div class="cdx-block cdx-warning">
+                <div class="cdx-input cdx-warning__title">{title}</div>
+                <div class="cdx-input cdx-warning__message">{message}</div>
+            </div>
+        """
+
+
+@block("raw")
+class RawBlock(EditorJsBlock):
+    def html(self, sanitize: bool = False) -> str:
+        html = self.data.get("html", "")
+        if sanitize:
+            html = _sanitize(html)
+        return html

pyeditorjs/exceptions.py

@@ -0,0 +1,19 @@
+__all__ = [
+    "EditorJsException",
+    "EditorJsParseError",
+    "EditorJSUnsupportedBlock",
+]
+
+
+class EditorJsException(Exception):
+    """
+    Base exception
+    """
+
+
+class EditorJsParseError(EditorJsException):
+    """Raised when a parse error occurs (example: the JSON data has invalid or malformed content)."""
+
+
+class EditorJSUnsupportedBlock(EditorJsException):
+    """Raised when strict=True and using an unknown block type."""

pyeditorjs/parser.py

@@ -0,0 +1,75 @@
+import typing as t
+import warnings
+from dataclasses import dataclass
+
+from .blocks import BLOCKS_MAP, EditorJsBlock
+from .exceptions import EditorJsParseError, EditorJSUnsupportedBlock
+
+
+@dataclass
+class EditorJsParser:
+    """
+    An Editor.js parser.
+    """
+
+    content: dict
+    """The JSON data of Editor.js content."""
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.content, dict):
+            raise EditorJsParseError(
+                f"Content must be `dict`, not {type(self.content).__name__}"
+            )
+
+    @staticmethod
+    def _get_block(data: dict, strict: bool = False) -> t.Optional[EditorJsBlock]:
+        """
+        Obtains block instance from block data.
+        """
+
+        _type = data.get("type", None)
+
+        if _type not in BLOCKS_MAP:
+            if strict:
+                raise EditorJSUnsupportedBlock(_type)
+            else:
+                warnings.warn(f"Unsupported block: {_type}", category=RuntimeWarning)
+                return None
+
+        return BLOCKS_MAP[_type](_data=data)
+
+    def blocks(self, strict: bool = False) -> list[EditorJsBlock]:
+        """
+        Obtains a list of all available blocks from the editor's JSON data.
+        """
+
+        all_blocks: list[EditorJsBlock] = []
+        blocks = self.content.get("blocks", [])
+
+        if not isinstance(blocks, list):
+            raise EditorJsParseError(
+                f"Blocks is not `list`, but `{type(blocks).__name__}`"
+            )
+
+        for block_data in blocks:
+            if block := self._get_block(data=block_data, strict=strict):
+                all_blocks.append(block)
+
+        return all_blocks
+
+    def __iter__(self) -> t.Iterator[EditorJsBlock]:
+        """Returns `iter(self.blocks())`"""
+
+        return iter(self.blocks())
+
+    def html(self, sanitize: bool = False, strict: bool = False) -> str:
+        """
+        Renders the editor's JSON content as HTML.
+
+        ### Parameters:
+        - `sanitize` - whether to also sanitize the blocks' texts/contents.
+        """
+
+        return "\n".join(
+            [block.html(sanitize=sanitize) for block in self.blocks(strict=strict)]
+        )