edwh-editorjs 2.0.0__tar.gz → 2.0.0b1__tar.gz

edwh_editorjs-2.0.0b1/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+<!--next-version-placeholder-->
+
+## v2.0.0-beta.1 (2024-11-06)
+
+
+
+## v1.1.0 (2024-10-31)
+
+### Feature
+
+* Expose _sanitize via EditorJSBlock.sanitize for external usage ([`7daa67c`](https://github.com/educationwarehouse/edwh-editorjs/commit/7daa67c90440510c83b573c22edf377cc2fd801f))
+
+### Documentation
+
+* Added section on defining new custom blocks ([`51d7720`](https://github.com/educationwarehouse/edwh-editorjs/commit/51d77208d4f8156e895de914f41bdeb882a508c0))
+
+## v1.0.1 (2024-10-31)
+
+### Documentation
+
+* Updated README ([`18d0216`](https://github.com/educationwarehouse/edwh-editorjs/commit/18d021629bcb223b89a9731e9ad8c574248f75c7))
+
+## v1.0.0 (2024-10-31)
+
+### Feature
+
+* Implemented more blocks (raw, warning, code, table, quote) ([`fb93bd9`](https://github.com/educationwarehouse/edwh-editorjs/commit/fb93bd959f06fa86bc23c9bfc51a8b7fddfc65f2))
+* Refactor to Registry Pattern so new block can be easily added ([`b06c86d`](https://github.com/educationwarehouse/edwh-editorjs/commit/b06c86da623dd2a2d92f7c48353a1f3208fb5749))

{edwh_editorjs-2.0.0 → edwh_editorjs-2.0.0b1}/LICENSE

@@ -1,7 +1,6 @@
 MIT License
 
 Copyright (c) 2021 SKevo
-Copyright (c) 2024 Education Warehouse
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

edwh_editorjs-2.0.0b1/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.3
+Name: edwh-editorjs
+Version: 2.0.0b1
+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
+
+# edwh-editorjs
+
+A minimal, fast Python 3.10+ package for parsing [Editor.js](https://editorjs.io) content.
+This package is a fork of [pyEditorJS by SKevo](https://github.com/SKevo18/pyEditorJS) with additional capabilities.
+
+## New Features
+
+- Expanded support for additional block types: Quote, Table, Code, Warning, and Raw blocks
+- Issues a warning if an unknown block type is encountered, rather than ignoring it
+- Adds a `strict` mode, raising an `EditorJSUnsupportedBlock` exception for unknown block types when `strict=True`
+- Allows adding new blocks by decorating a subclass of `EditorJsParser` with `@block("name")`
+
+## Installation
+
+```bash
+pip install edwh-editorjs
+```
+
+## 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` uses the included `bleach` dependency
+print(html)  # your clean HTML
+```
+
+### Enforcing Strict Block Types
+
+```python
+from pyeditorjs import EditorJsParser, EditorJSUnsupportedBlock
+
+editor_js_data: dict = ...
+parser = EditorJsParser(editor_js_data)
+
+try:
+    html = parser.html(strict=True)
+except EditorJSUnsupportedBlock as e:
+    print(f"Unsupported block type encountered: {e}")
+```
+
+### Adding a Custom Block
+
+To add a custom block type, create a new class that subclasses `EditorJsBlock` and decorates it with `@block("name")`,
+where `"name"` is the custom block type. Implement an `html` method to define how the block’s content should be
+rendered. This method should accept a `sanitize` parameter and can access block data via `self.data`.
+
+```python
+from pyeditorjs import EditorJsParser, EditorJsBlock, block
+
+@block("custom")
+class CustomBlock(EditorJsBlock):
+    def html(self, sanitize: bool = False) -> str:
+        # Access data with self.data and return the rendered HTML
+        content = self.data.get("something", "")
+        if sanitize:
+            content = self.sanitize(content)
+        
+        return f"<div class='custom-block'>{content}</div>"
+
+# Usage
+class CustomEditorJsParser(EditorJsParser):
+    pass  # Custom blocks are automatically detected
+
+editor_js_data = ...  # Editor.js JSON data with a "customBlock" type
+parser = CustomEditorJsParser(editor_js_data)
+html = parser.html()
+print(html)  # Includes rendered custom blocks
+```
+
+## Disclaimer
+
+This is a community-provided project and is not affiliated with the Editor.js team. 
+Contributions, bug reports, and suggestions are welcome!

edwh_editorjs-2.0.0b1/README.md

@@ -0,0 +1,79 @@
+# edwh-editorjs
+
+A minimal, fast Python 3.10+ package for parsing [Editor.js](https://editorjs.io) content.
+This package is a fork of [pyEditorJS by SKevo](https://github.com/SKevo18/pyEditorJS) with additional capabilities.
+
+## New Features
+
+- Expanded support for additional block types: Quote, Table, Code, Warning, and Raw blocks
+- Issues a warning if an unknown block type is encountered, rather than ignoring it
+- Adds a `strict` mode, raising an `EditorJSUnsupportedBlock` exception for unknown block types when `strict=True`
+- Allows adding new blocks by decorating a subclass of `EditorJsParser` with `@block("name")`
+
+## Installation
+
+```bash
+pip install edwh-editorjs
+```
+
+## 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` uses the included `bleach` dependency
+print(html)  # your clean HTML
+```
+
+### Enforcing Strict Block Types
+
+```python
+from pyeditorjs import EditorJsParser, EditorJSUnsupportedBlock
+
+editor_js_data: dict = ...
+parser = EditorJsParser(editor_js_data)
+
+try:
+    html = parser.html(strict=True)
+except EditorJSUnsupportedBlock as e:
+    print(f"Unsupported block type encountered: {e}")
+```
+
+### Adding a Custom Block
+
+To add a custom block type, create a new class that subclasses `EditorJsBlock` and decorates it with `@block("name")`,
+where `"name"` is the custom block type. Implement an `html` method to define how the block’s content should be
+rendered. This method should accept a `sanitize` parameter and can access block data via `self.data`.
+
+```python
+from pyeditorjs import EditorJsParser, EditorJsBlock, block
+
+@block("custom")
+class CustomBlock(EditorJsBlock):
+    def html(self, sanitize: bool = False) -> str:
+        # Access data with self.data and return the rendered HTML
+        content = self.data.get("something", "")
+        if sanitize:
+            content = self.sanitize(content)
+        
+        return f"<div class='custom-block'>{content}</div>"
+
+# Usage
+class CustomEditorJsParser(EditorJsParser):
+    pass  # Custom blocks are automatically detected
+
+editor_js_data = ...  # Editor.js JSON data with a "customBlock" type
+parser = CustomEditorJsParser(editor_js_data)
+html = parser.html()
+print(html)  # Includes rendered custom blocks
+```
+
+## Disclaimer
+
+This is a community-provided project and is not affiliated with the Editor.js team. 
+Contributions, bug reports, and suggestions are welcome!

edwh_editorjs-2.0.0b1/pyeditorjs/__about__.py

@@ -0,0 +1 @@
+__version__ = "2.0.0-beta.1"

edwh_editorjs-2.0.0b1/pyeditorjs/__init__.py

@@ -0,0 +1,30 @@
+from pathlib import Path
+
+from .blocks import BLOCKS_MAP, EditorJsBlock, block
+from .exceptions import EditorJsException, EditorJsParseError, EditorJSUnsupportedBlock
+from .parser import EditorJsParser
+
+__all__ = [
+    "EditorJsParser",
+    "EditorJsParseError",
+    "EditorJsException",
+    "EditorJSUnsupportedBlock",
+    "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]

edwh_editorjs-2.0.0b1/pyeditorjs/blocks.py

@@ -0,0 +1,313 @@
+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"""
+
+    @classmethod
+    def sanitize(cls, html: str) -> str:
+        return _sanitize(html)
+
+    @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

edwh_editorjs-2.0.0b1/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."""

edwh_editorjs-2.0.0b1/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)]
+        )