djot-py 0.1.0__tar.gz

djot_py-0.1.0/PKG-INFO

@@ -0,0 +1,85 @@
+Metadata-Version: 2.4
+Name: djot-py
+Version: 0.1.0
+Summary: A pure Python implementation of the Jot markup language
+Author: Victor Nee
+Author-email: Victor Nee <neefrankie@gmail.com>
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Text Processing :: Markup
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# djot-py
+
+A Python library for parsing the light markup format [djot](https://github.com/jgm/djot).
+
+This implementation is based on and modified from [djot.js](https://github.com/jgm/djot.js).
+
+## Usage
+
+```bash
+pip install djot-py
+```
+
+## API
+
+To parse text into an AST, call `parse`:
+
+```python
+from djot import parse
+
+ast = parse("hi there\nfriend\n\nnew para")
+```
+
+To parse text into events:
+
+```python
+from djot import EventParser
+
+text = "hello *world*\n\nfoo"
+
+parser = EventParser(text)
+
+# The parse method returns an iterator of events.
+for event in parser.parse():
+    print(event)
+```
+
+There are no rendering features available currently. Will be added in the future.
+
+## Differences from Djot.js
+
+- Comment is not supported yet.
+- Multi-line attributes is not supported yet.
+
+## My personal view on the above not-yet-implemented features
+
+### Comment
+
+Comment should not be mixed with attributes.
+
+I hope there's a specific comment syntax in the future. For example, there could be two types of comments:
+
+- Line comment appeared at the end of each line, using symbols like `%%`
+- Block comment wrapped in `%%%`, similar to code block.
+
+### Multi-line attributes
+
+Djot.js current implementation to support multi-line attributes involves a lot of backtracing,
+which is in direct conflict with the philosophy of djot. To support multi-line attributes,
+there needs a fundamental change in the line-based parsing algorithm.
+
+### List
+
+This is not hard to implement. However, too much choices might introduce future ambiguity.
+I prefere simplicity rather than feature-rich. For example, Typst style simply uses `-` and `+`. Leave styling to a renderer. And block attributes could be used to convey some basic styling information.

djot_py-0.1.0/README.md

@@ -0,0 +1,64 @@
+# djot-py
+
+A Python library for parsing the light markup format [djot](https://github.com/jgm/djot).
+
+This implementation is based on and modified from [djot.js](https://github.com/jgm/djot.js).
+
+## Usage
+
+```bash
+pip install djot-py
+```
+
+## API
+
+To parse text into an AST, call `parse`:
+
+```python
+from djot import parse
+
+ast = parse("hi there\nfriend\n\nnew para")
+```
+
+To parse text into events:
+
+```python
+from djot import EventParser
+
+text = "hello *world*\n\nfoo"
+
+parser = EventParser(text)
+
+# The parse method returns an iterator of events.
+for event in parser.parse():
+    print(event)
+```
+
+There are no rendering features available currently. Will be added in the future.
+
+## Differences from Djot.js
+
+- Comment is not supported yet.
+- Multi-line attributes is not supported yet.
+
+## My personal view on the above not-yet-implemented features
+
+### Comment
+
+Comment should not be mixed with attributes.
+
+I hope there's a specific comment syntax in the future. For example, there could be two types of comments:
+
+- Line comment appeared at the end of each line, using symbols like `%%`
+- Block comment wrapped in `%%%`, similar to code block.
+
+### Multi-line attributes
+
+Djot.js current implementation to support multi-line attributes involves a lot of backtracing,
+which is in direct conflict with the philosophy of djot. To support multi-line attributes,
+there needs a fundamental change in the line-based parsing algorithm.
+
+### List
+
+This is not hard to implement. However, too much choices might introduce future ambiguity.
+I prefere simplicity rather than feature-rich. For example, Typst style simply uses `-` and `+`. Leave styling to a renderer. And block attributes could be used to convey some basic styling information.

djot_py-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[project]
+name = "djot-py"
+version = "0.1.0"
+description = "A pure Python implementation of the Jot markup language"
+readme = "README.md"
+requires-python = ">=3.12"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Text Processing :: Markup",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Typing :: Typed",
+]
+license = "MIT"
+dependencies = []
+
+[[project.authors]]
+name = "Victor Nee"
+email = "neefrankie@gmail.com"
+
+[build-system]
+requires = ["uv_build>=0.12.6,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "djot"

djot_py-0.1.0/pyproject.toml.orig

@@ -0,0 +1,31 @@
+[project]
+name = "djot-py"
+version = "0.1.0"
+description = "A pure Python implementation of the Jot markup language"
+readme = "README.md"
+authors = [
+    { name = "Victor Nee", email = "neefrankie@gmail.com" }
+]
+requires-python = ">=3.12"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Text Processing :: Markup",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Typing :: Typed",
+]
+license = "MIT"
+dependencies = []
+
+[build-system]
+requires = ["uv_build>=0.12.6,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "djot"

djot_py-0.1.0/src/djot/__init__.py

@@ -0,0 +1,81 @@
+from .parser import (
+    parse,
+    ASTBuilder,
+    render_ast,
+)
+from .block import (
+    EventParser,
+)
+from .event import (
+    Event,
+)
+
+from .common import (
+    Alignment,
+    unescape_djot,
+    Pos,
+    SourceLoc,
+)
+
+from .ast import (
+    AstNode,
+    Attributes,
+    BlockNode,
+    BlockQuote,
+    BulletList,
+    BulletListStyle,
+    Caption,
+    Cell,
+    CheckboxStatus,
+    CodeBlock,
+    Definition,
+    DefinitionList,
+    DefinitionListItem,
+    Delete,
+    DisplayMath,
+    Div,
+    Doc,
+    DoubleQuoted,
+    Email,
+    Emph,
+    Footnote,
+    FootnoteReference,
+    HardBreak,
+    HasChildren,
+    HasText,
+    Heading,
+    Image,
+    InlineNode,
+    InlineMath,
+    Insert,
+    Link,
+    ListItem,
+    Mark,
+    NonBreakingSpace,
+    OrderedList,
+    OrderedListStyle,
+    Para,
+    RawBlock,
+    RawInline,
+    Reference,
+    Row,
+    Section,
+    SingleQuoted,
+    SmartPunctuation,
+    SmartPunctType,
+    SoftBreak,
+    Span,
+    Str,
+    Strong,
+    Subscript,
+    Superscript,
+    Symb,
+    Table,
+    TaskList,
+    TaskListItem,
+    Term,
+    ThematicBreak,
+    Url,
+    Verbatim,
+    Visitor,
+)

djot_py-0.1.0/src/djot/ast/__init__.py

@@ -0,0 +1,345 @@
+from abc import ABC, abstractmethod
+from typing import TypeGuard, TypeVar
+
+from .base import (
+    AstNode,
+    Attributes,
+    merge_attributes,
+    BlockNode,
+    InlineNode,
+    HasChildren,
+    HasText,
+    ContentBlock,
+    DefinitionBlock,
+)
+from .doc import Doc
+from .block import (
+    Para,
+    Heading,
+    ThematicBreak,
+    Section,
+    Div,
+    CodeBlock,
+    RawBlock,
+    BlockQuote,
+    Footnote,
+    Reference,
+)
+from .list import (
+    OrderedList,
+    BulletList,
+    TaskList,
+    DefinitionList,
+    ListItem,
+    TaskListItem,
+    DefinitionListItem,
+    Term,
+    Definition,
+    BulletListStyle,
+    OrderedListStyle,
+    CheckboxStatus,
+)
+from .table import (
+    Table,
+    Caption,
+    Row,
+    Cell,
+)
+from .inline import (
+    Str,
+    SoftBreak,
+    HardBreak,
+    NonBreakingSpace,
+    Symb,
+    Verbatim,
+    RawInline,
+    InlineMath,
+    DisplayMath,
+    Url,
+    Email,
+    FootnoteReference,
+    SmartPunctuation,
+    SmartPunctType,
+    Emph,
+    Strong,
+    Link,
+    Image,
+    Span,
+    Mark,
+    Superscript,
+    Subscript,
+    Insert,
+    Delete,
+    DoubleQuoted,
+    SingleQuoted,
+)
+
+
+C = TypeVar('C')
+R = TypeVar('R')
+
+class Visitor[C, R](ABC):
+    @abstractmethod
+    def doc(self, node: Doc, context: C) -> R:
+        pass
+
+    @abstractmethod
+    def para(self, node: Para, context: C) -> R:
+        pass
+
+    @abstractmethod
+    def heading(self, node: Heading, context: C) -> R:
+        pass
+
+    @abstractmethod
+    def thematic_break(self, node: ThematicBreak, context: C) -> R:
+        pass
+
+    @abstractmethod
+    def section(self, node: Section, context: C) -> R:
+        pass
+
+    @abstractmethod
+    def div(self, node: Div, context: C) -> R:
+        pass
+
+    @abstractmethod
+    def code_block(self, node: CodeBlock, context: C) -> R:
+        pass
+
+    @abstractmethod
+    def raw_block(self, node: RawBlock, context: C) -> R:
+        pass
+
+    @abstractmethod
+    def block_quote(self, node: BlockQuote, context: C) -> R:
+        pass
+
+    @abstractmethod
+    def ordered_list(self, node: OrderedList, context: C) -> R:
+        pass
+
+    @abstractmethod
+    def bullet_list(self, node: BulletList, context: C) -> R:
+        pass
+
+    @abstractmethod
+    def task_list(self, node: TaskList, context: C) -> R:
+        pass
+
+    @abstractmethod
+    def definition_list(self, node: DefinitionList, context: C) -> R:
+        pass
+
+    @abstractmethod
+    def table(self, node: Table, context: C) -> R:
+        pass
+
+    @abstractmethod
+    def str(self, node: Str, context: C) -> R:
+        pass
+
+    @abstractmethod
+    def soft_break(self, node: SoftBreak, context: C) -> R:
+        pass
+
+    @abstractmethod
+    def hard_break(self, node: HardBreak, context: C) -> R:
+        pass
+
+    @abstractmethod
+    def non_breaking_space(self, node: NonBreakingSpace, context: C) -> R:
+        pass
+
+    @abstractmethod
+    def symb(self, node: Symb, context: C) -> R:
+        pass
+
+    @abstractmethod
+    def verbatim(self, node: Verbatim, context: C) -> R:
+        pass
+
+    @abstractmethod
+    def raw_inline(self, node: RawInline, context: C) -> R:
+        pass
+
+    @abstractmethod
+    def display_math(self, node: DisplayMath, context: C) -> R:
+        pass
+
+    @abstractmethod
+    def url(self, node: Url, context: C) -> R:
+        pass
+
+    @abstractmethod
+    def email(self, node: Email, context: C) -> R:
+        pass
+
+    @abstractmethod
+    def footnote_reference(self, node: FootnoteReference, context: C) -> R:
+        pass
+
+    @abstractmethod
+    def smart_punctuation(self, node: SmartPunctuation, context: C) -> R:
+        pass
+
+    @abstractmethod
+    def emph(self, node: Emph, context: C) -> R:
+        pass
+
+    @abstractmethod
+    def strong(self, node: Strong, context: C) -> R:
+        pass
+
+    @abstractmethod
+    def link(self, node: Link, context: C) -> R:
+        pass
+
+    @abstractmethod
+    def image(self, node: Image, context: C) -> R:
+        pass
+
+    @abstractmethod
+    def span(self, node: Span, context: C) -> R:
+        pass
+
+    @abstractmethod
+    def mark(self, node: Mark, context: C) -> R:
+        pass
+
+    @abstractmethod
+    def superscript(self, node: Superscript, context: C) -> R:
+        pass
+
+    @abstractmethod
+    def subscript(self, node: Subscript, context: C) -> R:
+        pass
+
+    @abstractmethod
+    def insert(self, node: Insert, context: C) -> R:
+        pass
+
+    @abstractmethod
+    def delete(self, node: Delete, context: C) -> R:
+        pass
+
+    @abstractmethod
+    def double_quoted(self, node: DoubleQuoted, context: C) -> R:
+        pass
+
+    @abstractmethod
+    def single_quoted(self, node: SingleQuoted, context: C) -> R:
+        pass
+
+    @abstractmethod
+    def list_item(self, node: ListItem, context: C) -> R:
+        pass
+
+    @abstractmethod
+    def task_list_item(self, node: TaskListItem, context: C) -> R:
+        pass
+
+    @abstractmethod
+    def definition_list_item(self, node: DefinitionListItem, context: C) -> R:
+        pass
+
+    @abstractmethod
+    def term(self, node: Term, context: C) -> R:
+        pass
+
+    @abstractmethod
+    def definition(self, node: Definition, context: C) -> R:
+        pass
+
+    @abstractmethod
+    def row(self, node: Row, context: C) -> R:
+        pass
+
+    @abstractmethod
+    def cell(self, node: Cell, context: C) -> R:
+        pass
+    
+    @abstractmethod
+    def caption(self, node: Caption, context: C) -> R:
+        pass
+
+    @abstractmethod
+    def footnote(self, node: Footnote, context: C) -> R:
+        pass
+
+    @abstractmethod
+    def reference(self, node: Reference, context: C) -> R:
+        pass
+
+def is_block(node: AstNode) -> TypeGuard[BlockNode]:
+    match node:
+        case (
+            Para()
+            | Heading()
+            | BlockQuote()
+            | ThematicBreak()
+            | Section()
+            | Div()
+            | CodeBlock()
+            | RawBlock()
+            | BulletList()
+            | OrderedList()
+            | TaskList()
+            | DefinitionList()
+            | Table()
+            | Reference()
+            | Footnote()
+        ):
+            return True
+        
+        case _:
+            return False
+
+def is_inline(node: AstNode) -> bool:
+    match node:
+        case (
+            Str()
+            | SoftBreak()
+            | HardBreak()
+            | NonBreakingSpace()
+            | Symb()
+            | Verbatim()
+            | RawInline()
+            | InlineMath()
+            | DisplayMath()
+            | Url()
+            | Email()
+            | FootnoteReference()
+            | SmartPunctuation()
+            | Emph()
+            | Strong()
+            | Link()
+            | Image()
+            | Span()
+            | Mark()
+            | Superscript()
+            | Subscript()
+            | Insert()
+            | Delete()
+            | DoubleQuoted()
+            | SingleQuoted()
+        ):
+            return True
+        
+        case _:
+            return False
+        
+
+def is_row(node: Row | Caption) -> TypeGuard[Row]:
+    match node:
+        case Row(head=_):
+            return True
+        case _:
+            return False
+
+def is_caption(node: Row | Caption) -> TypeGuard[Caption]:
+    match node:
+        case Row(head=_):
+            return False
+        case _:
+            return True

djot_py-0.1.0/src/djot/ast/base.py

@@ -0,0 +1,67 @@
+from abc import ABC, abstractmethod
+import copy
+from dataclasses import dataclass
+from typing import Dict, Generic, List, Optional, TypeVar
+
+from ..common import Pos
+
+type Attributes = Dict[str, str]
+
+def merge_attributes(
+    target: Optional[Attributes],
+    source: Attributes
+) -> Attributes:
+    if not target:
+        return source.copy()
+
+    result = target.copy()
+
+    for key, value in source.items():
+        if key == 'class' and key in result:
+            result[key] = f'{result[key]} {value}'
+        else:
+            result[key] = value
+
+    return result
+
+@dataclass(kw_only=True)
+class AstNode(ABC):
+    attributes: Attributes | None = None
+    pos: Pos | None = None
+
+    @property
+    @abstractmethod
+    def tag(self) -> str:
+        pass
+
+    def merge_attributes(self, other: Attributes):
+        self.attributes = merge_attributes(self.attributes, other)
+
+T = TypeVar("T")
+
+@dataclass(kw_only=True)
+class HasChildren(Generic[T], ABC):
+    children: List[T]
+
+@dataclass(kw_only=True)
+class HasText(ABC):
+    text: str
+
+@dataclass(kw_only=True)
+class InlineNode(AstNode):
+    pass
+
+@dataclass(kw_only=True)
+class BlockNode(AstNode, ABC):
+    pass
+
+# 区分常规内容块（Para, Heading 等）与 定义类块（Footnote, Reference）
+@dataclass(kw_only=True)
+class ContentBlock(BlockNode, ABC):
+    """能够嵌入普通 Container（如 BlockQuote, Div, Doc）的内容块"""
+    pass
+
+@dataclass(kw_only=True)
+class DefinitionBlock(BlockNode, ABC):
+    """元数据/定义类块（如 Footnote, Reference）"""
+    pass