adf-parse 0.1.0__py3-none-any.whl

adf_parse/__init__.py

@@ -0,0 +1,18 @@
+"""adf-parse: convert Atlassian Document Format (ADF) to plain text / Markdown."""
+
+from .enums import ADFMarkType, ADFNodeType, MediaRefType
+from .models import MediaRef, NodeCollection
+from .parser import create_md_doc, parse_content, parse_doc
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "ADFMarkType",
+    "ADFNodeType",
+    "MediaRefType",
+    "MediaRef",
+    "NodeCollection",
+    "create_md_doc",
+    "parse_content",
+    "parse_doc",
+]

adf_parse/enums.py

@@ -0,0 +1,53 @@
+from enum import StrEnum
+
+class ADFNodeType(StrEnum):
+    """Node types in Atlassian Document Format.
+    Split by how the parser handles them."""
+
+    # --- Root ---
+    DOC = "doc"
+
+    # The only node with a "text" key
+    TEXT = "text"
+
+    # --- Containers you format specially ---
+    PARAGRAPH = "paragraph"       # join inner text into one line
+    HEADING = "heading"           # prefix with # based on attrs.level
+    BULLET_LIST = "bulletList"    # children are listItems, prefix with -
+    ORDERED_LIST = "orderedList"  # children are listItems, prefix with 1. 2. 3.
+    LIST_ITEM = "listItem"        # wrapper inside lists, just recurse
+    CODE_BLOCK = "codeBlock"      # grab attrs.language, wrap in ```
+    TABLE = "table"               # contains tableRows
+    TABLE_ROW = "tableRow"        # contains cells, join with |
+    TABLE_HEADER = "tableHeader"  # like a cell but bold/header
+    TABLE_CELL = "tableCell"      # grab text, separate with |
+    BLOCKQUOTE = "blockquote"     # prefix lines with >
+
+    # --- Containers you just recurse into (treat as blob) ---
+    PANEL = "panel"               # attrs.panelType = warning/info/error/success/note
+    EXPAND = "expand"             # attrs.title = collapsible section title
+    TASK_LIST = "taskList"        # contains taskItems
+    TASK_ITEM = "taskItem"        # attrs.state = TODO/DONE
+
+    # --- Leaves: no content, no text. Info in attrs ---
+    HARD_BREAK = "hardBreak"      # just insert \n
+    RULE = "rule"                 # horizontal line, insert \n---\n or skip
+    MENTION = "mention"           # attrs.text = "@John Smith"
+    STATUS = "status"             # attrs.text = "IN PROGRESS", attrs.color
+    DATE = "date"                 # attrs.timestamp (unix millis string)
+    INLINE_CARD = "inlineCard"    # attrs.url = smart link URL
+    MEDIA_SINGLE = "mediaSingle"  # container for media node
+    MEDIA = "media"               # attrs.id, attrs.type, attrs.collection
+    MEDIA_INLINE = "mediaInline"  # Inline Media
+
+
+class ADFMarkType(StrEnum):
+    """Mark types you actually care about during parsing."""
+
+    LINK = "link" 
+    CODE = "code"
+
+class MediaRefType(StrEnum):
+    URL = "url"
+    ID = "id"
+

adf_parse/models.py

@@ -0,0 +1,13 @@
+from dataclasses import dataclass ,field
+from .enums import MediaRefType
+
+@dataclass
+class MediaRef:
+    ref_type:MediaRefType
+    ref :str
+
+@dataclass
+class NodeCollection:
+    collected_text:list = field(default_factory=list)
+    links:list[tuple[str,str]] =  field(default_factory=list)
+    media_ref:list[MediaRef] = field(default_factory=list)

adf_parse/parser.py

@@ -0,0 +1,150 @@
+
+from datetime import datetime ,timezone
+from .enums import ADFMarkType,ADFNodeType,MediaRefType
+from .models import MediaRef, NodeCollection
+
+def format_list_item(prefix: str, item_text: str) -> str:
+    # first line gets the prefix, the rest (nested lists etc.) get indented under it
+    lines = item_text.split("\n")
+    pad = " " * len(prefix)
+    return "\n".join([prefix + lines[0]] + [pad + line for line in lines[1:]])
+
+
+def parse_content(content: list[dict]) -> NodeCollection:
+    collection = NodeCollection()
+
+    for node in content:
+        node_type = node["type"]
+        attrs = node.get("attrs") or {}
+
+        parts: list[str] = []
+        if node.get("content"):
+            resp = parse_content(node["content"])
+            collection.links.extend(resp.links)
+            collection.media_ref.extend(resp.media_ref)
+            parts = resp.collected_text
+
+        # text (the only node with a "text" key)
+        if node_type == ADFNodeType.TEXT:
+            text = node["text"]
+            for mark in node.get("marks", []):
+                if mark["type"] == ADFMarkType.LINK:
+                    ref = mark["attrs"]["href"]
+                    collection.links.append((text,ref))
+                    text = f"{text} ({ref})"
+                elif mark["type"] == ADFMarkType.CODE:
+                    text = f"`{text}`"
+            collection.collected_text.append(text)
+
+        # leaves: no content, info is in attrs
+        elif node_type == ADFNodeType.HARD_BREAK:
+            collection.collected_text.append("\n")
+
+        elif node_type == ADFNodeType.MENTION:
+            collection.collected_text.append(attrs.get("text") or f"@{attrs.get('id', 'unknown')}")
+
+        elif node_type == ADFNodeType.INLINE_CARD:
+            url = attrs.get("url", "")
+            if url:
+                collection.links.append((url,url))
+                collection.collected_text.append(url)
+
+        # ---- containers ----
+        elif node_type == ADFNodeType.HEADING:
+            level = int(attrs.get("level", 1))
+            collection.collected_text.append(f"{'#' * level} {''.join(parts)}")
+
+        elif node_type == ADFNodeType.PARAGRAPH:
+            collection.collected_text.append("".join(parts))  # empty paragraph -> "" -> blank line
+
+        elif node_type == ADFNodeType.LIST_ITEM:
+            collection.collected_text.append("\n".join(parts))
+
+        elif node_type == ADFNodeType.BULLET_LIST:
+            items = [format_list_item("- ", item) for item in parts]
+            collection.collected_text.append("\n".join(items))
+
+        elif node_type == ADFNodeType.ORDERED_LIST:
+            start = int(attrs.get("order", 1))
+            items = [format_list_item(f"{start + i}. ", item) for i, item in enumerate(parts)]
+            collection.collected_text.append("\n".join(items))
+
+        elif node_type == ADFNodeType.CODE_BLOCK:
+            language = attrs.get("language", "")
+            collection.collected_text.append(f"```{language}\n{''.join(parts)}\n```")
+
+        elif node_type == ADFNodeType.PANEL:
+            panel_type = attrs.get("panelType", "info")
+            collection.collected_text.append(f"[{panel_type}] " + "\n".join(parts))
+
+        
+        # leaves ----
+        elif node_type == ADFNodeType.RULE:
+            collection.collected_text.append("---")
+
+        elif node_type == ADFNodeType.STATUS:
+            if attrs.get("text"):
+                collection.collected_text.append(f"[status: {attrs['text']}]")
+
+        elif node_type == ADFNodeType.DATE:
+            try:
+                ts = int(attrs["timestamp"]) / 1000
+                collection.collected_text.append(datetime.fromtimestamp(ts, tz=timezone.utc).strftime("%Y-%m-%d"))
+            except (KeyError, ValueError, TypeError):
+                pass
+
+        # containers 
+        elif node_type == ADFNodeType.BLOCKQUOTE:
+            lines = "\n".join(parts).split("\n")
+            collection.collected_text.append("\n".join(f"> {line}" for line in lines))
+
+        elif node_type == ADFNodeType.EXPAND:
+            title = attrs.get("title") or "details"
+            collection.collected_text.append(f"[expand: {title}]\n" + "\n".join(parts))
+
+        elif node_type == ADFNodeType.TASK_ITEM:
+            box = "[x]" if attrs.get("state") == "DONE" else "[ ]"
+            collection.collected_text.append(f"- {box} {''.join(parts)}")
+
+        elif node_type == ADFNodeType.TASK_LIST:
+            collection.collected_text.append("\n".join(parts))
+
+        # media
+        elif node_type in (ADFNodeType.MEDIA, ADFNodeType.MEDIA_INLINE):
+            ref_type  =  MediaRefType.URL if attrs.get("url") else MediaRefType.ID
+            ref:str = attrs.get(ref_type.value,"")
+            if ref:
+                collection.media_ref.append(MediaRef(ref_type=ref_type,ref=ref))
+
+        # ---- table ----
+        elif node_type in (ADFNodeType.TABLE_HEADER, ADFNodeType.TABLE_CELL):
+            cell = " ".join(parts).replace("\n", " ").replace("|", "\\|")  # keep each cell on one line
+            collection.collected_text.append(cell)
+
+        elif node_type == ADFNodeType.TABLE_ROW:
+            collection.collected_text.append("| " + " | ".join(parts) + " |")
+
+        elif node_type == ADFNodeType.TABLE:
+            rows = list(parts)
+            first_row_cells = node["content"][0].get("content", []) if node.get("content") else []
+            is_header = bool(first_row_cells) and all(
+                c["type"] == ADFNodeType.TABLE_HEADER for c in first_row_cells
+            )
+            if is_header:
+                rows.insert(1, "| " + " | ".join(["---"] * len(first_row_cells)) + " |")
+            collection.collected_text.append("\n".join(rows))
+
+        elif parts:
+            collection.collected_text.append("\n".join(parts))
+
+    return collection
+
+
+def parse_doc(adf: dict) -> NodeCollection:
+    """Parse a full ADF document and return the collected text, links and media refs."""
+    return parse_content(adf.get("content") or [])
+
+
+def create_md_doc(adf: dict) -> str:
+    """Render a full ADF document as a Markdown string."""
+    return "\n".join(parse_doc(adf).collected_text)

adf_parse-0.1.0.dist-info/METADATA

@@ -0,0 +1,68 @@
+Metadata-Version: 2.4
+Name: adf-parse
+Version: 0.1.0
+Summary: Convert Atlassian Document Format (ADF) from Jira/Confluence into plain text or Markdown
+Keywords: adf,atlassian,jira,confluence,markdown,parser
+Author: Abhishek Hazra
+License-Expression: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/hazra1991/adf-parse
+Project-URL: Repository, https://github.com/hazra1991/adf-parse
+Description-Content-Type: text/markdown
+
+# adf-parse
+
+Convert [Atlassian Document Format (ADF)](https://developer.atlassian.com/cloud/jira/platform/apis/document/structure/) — the JSON format used by Jira and Confluence — into plain text / Markdown.
+
+Zero dependencies. Supports paragraphs, headings, bullet/ordered lists (with nesting), code blocks, tables (with header detection), blockquotes, panels, expands, task lists, mentions, dates, statuses, inline cards, hard breaks, rules, and media references.
+
+## Installation
+
+```bash
+pip install adf-parse
+```
+
+Requires Python 3.11+.
+
+## Usage
+
+```python
+from adf_parse import create_md_doc, parse_doc
+
+adf = {
+    "type": "doc",
+    "version": 1,
+    "content": [
+        {"type": "heading", "attrs": {"level": 2},
+         "content": [{"type": "text", "text": "Release notes"}]},
+        {"type": "paragraph",
+         "content": [{"type": "text", "text": "See the docs",
+                      "marks": [{"type": "link", "attrs": {"href": "https://example.com"}}]}]},
+    ],
+}
+
+print(create_md_doc(adf))
+# ## Release notes
+# See the docs (https://example.com)
+```
+
+To also get the extracted links and media references, use `parse_doc`:
+
+```python
+result = parse_doc(adf)
+result.collected_text  # list of rendered blocks
+result.links           # list of (text, href) tuples
+result.media_ref       # list of MediaRef(ref_type, ref)
+```
+
+## License
+
+MIT

adf_parse-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+adf_parse/__init__.py,sha256=64Tg1WZiQ0q5D8pXUI7t_W36fL6gWqLyghntORfWhwI,440
+adf_parse/enums.py,sha256=8PxFno0LDOTZ7_CnaisN7AMIcwptIneU8Bncehstu1A,2197
+adf_parse/models.py,sha256=be_254oCZ3Cd2EIChxW0TElXDZK3VVBF3SarHpjE47I,348
+adf_parse/parser.py,sha256=f8sGPxlHSwwat23pRzsgdlxmiYUkxXzea4hrU11iq4k,6140
+adf_parse-0.1.0.dist-info/WHEEL,sha256=Sb1dMJuf3wy6TqB8bzcqZpk8WSKCV8HbGz39HaP5dwE,81
+adf_parse-0.1.0.dist-info/METADATA,sha256=akTgGAJzosGEEBspc0xPuuy8ruKCNLjqrJH_I8UCNF8,2209
+adf_parse-0.1.0.dist-info/RECORD,,

adf_parse-0.1.0.dist-info/WHEEL

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