notionary 0.2.27__py3-none-any.whl → 0.3.0__py3-none-any.whl

notionary/blocks/markdown/markdown_builder.py

@@ -1,525 +0,0 @@
-"""
-Clean Fluent Markdown Builder
-============================
-
-A direct, chainable builder for all MarkdownNode types without overengineering.
-Maps 1:1 to the available blocks with clear, expressive method names.
-"""
-
-from __future__ import annotations
-
-from typing import Callable, Optional, Self
-
-from notionary.blocks.bookmark import BookmarkMarkdownNode
-from notionary.blocks.breadcrumbs import BreadcrumbMarkdownNode
-from notionary.blocks.bulleted_list import BulletedListMarkdownNode
-from notionary.blocks.callout import CalloutMarkdownNode
-from notionary.blocks.code import CodeLanguage, CodeMarkdownNode
-from notionary.blocks.column import ColumnListMarkdownNode, ColumnMarkdownNode
-from notionary.blocks.divider import DividerMarkdownNode
-from notionary.blocks.embed import EmbedMarkdownNode
-from notionary.blocks.equation import EquationMarkdownNode
-from notionary.blocks.file import FileMarkdownNode
-from notionary.blocks.heading import HeadingMarkdownNode
-from notionary.blocks.image_block import ImageMarkdownNode
-from notionary.blocks.numbered_list import NumberedListMarkdownNode
-from notionary.blocks.paragraph import ParagraphMarkdownNode
-from notionary.blocks.pdf import PdfMarkdownNode
-from notionary.blocks.quote import QuoteMarkdownNode
-from notionary.blocks.table import TableMarkdownNode
-from notionary.blocks.table_of_contents import TableOfContentsMarkdownNode
-from notionary.blocks.todo import TodoMarkdownNode
-from notionary.blocks.toggle import ToggleMarkdownNode
-from notionary.blocks.toggleable_heading import ToggleableHeadingMarkdownNode
-from notionary.blocks.video import VideoMarkdownNode
-from notionary.blocks.audio import AudioMarkdownNode
-
-from notionary.blocks.markdown.markdown_node import MarkdownNode
-
-
-class MarkdownBuilder:
-    """
-    Fluent interface builder for creating Notion content with clean, direct methods.
-
-    Focuses on the developer API for programmatic content creation.
-    Model processing is handled by MarkdownModelProcessor.
-    """
-
-    def __init__(self) -> None:
-        """Initialize builder with empty children list."""
-        self.children: list[MarkdownNode] = []
-
-    def h1(self, text: str) -> Self:
-        """
-        Add an H1 heading.
-
-        Args:
-            text: The heading text content
-        """
-        self.children.append(HeadingMarkdownNode(text=text, level=1))
-        return self
-
-    def h2(self, text: str) -> Self:
-        """
-        Add an H2 heading.
-
-        Args:
-            text: The heading text content
-        """
-        self.children.append(HeadingMarkdownNode(text=text, level=2))
-        return self
-
-    def h3(self, text: str) -> Self:
-        """
-        Add an H3 heading.
-
-        Args:
-            text: The heading text content
-        """
-        self.children.append(HeadingMarkdownNode(text=text, level=3))
-        return self
-
-    def heading(self, text: str, level: int = 2) -> Self:
-        """
-        Add a heading with specified level.
-
-        Args:
-            text: The heading text content
-            level: Heading level (1-3), defaults to 2
-        """
-        self.children.append(HeadingMarkdownNode(text=text, level=level))
-        return self
-
-    def paragraph(self, text: str) -> Self:
-        """
-        Add a paragraph block.
-
-        Args:
-            text: The paragraph text content
-        """
-        self.children.append(ParagraphMarkdownNode(text=text))
-        return self
-
-    def text(self, content: str) -> Self:
-        """
-        Add a text paragraph (alias for paragraph).
-
-        Args:
-            content: The text content
-        """
-        return self.paragraph(content)
-
-    def quote(self, text: str) -> Self:
-        """
-        Add a blockquote.
-
-        Args:
-            text: Quote text content
-            author: Optional quote author/attribution
-        """
-        self.children.append(QuoteMarkdownNode(text=text))
-        return self
-
-    def divider(self) -> Self:
-        """Add a horizontal divider."""
-        self.children.append(DividerMarkdownNode())
-        return self
-
-    def numbered_list(self, items: list[str]) -> Self:
-        """
-        Add a numbered list.
-
-        Args:
-            items: List of text items for the numbered list
-        """
-        self.children.append(NumberedListMarkdownNode(texts=items))
-        return self
-
-    def bulleted_list(self, items: list[str]) -> Self:
-        """
-        Add a bulleted list.
-
-        Args:
-            items: List of text items for the bulleted list
-        """
-        self.children.append(BulletedListMarkdownNode(texts=items))
-        return self
-
-    def todo(self, text: str, checked: bool = False) -> Self:
-        """
-        Add a single todo item.
-
-        Args:
-            text: The todo item text
-            checked: Whether the todo item is completed, defaults to False
-        """
-        self.children.append(TodoMarkdownNode(text=text, checked=checked))
-        return self
-
-    def todo_list(
-        self, items: list[str], completed: Optional[list[bool]] = None
-    ) -> Self:
-        """
-        Add multiple todo items.
-
-        Args:
-            items: List of todo item texts
-            completed: List of completion states for each item, defaults to all False
-        """
-        if completed is None:
-            completed = [False] * len(items)
-
-        for i, item in enumerate(items):
-            is_done = completed[i] if i < len(completed) else False
-            self.children.append(TodoMarkdownNode(text=item, checked=is_done))
-        return self
-
-    def callout(self, text: str, emoji: Optional[str] = None) -> Self:
-        """
-        Add a callout block.
-
-        Args:
-            text: The callout text content
-            emoji: Optional emoji for the callout icon
-        """
-        self.children.append(CalloutMarkdownNode(text=text, emoji=emoji))
-        return self
-
-    def toggle(
-        self, title: str, builder_func: Callable[["MarkdownBuilder"], "MarkdownBuilder"]
-    ) -> Self:
-        """
-        Add a toggle block with content built using the builder API.
-
-        Args:
-            title: The toggle title/header text
-            builder_func: Function that receives a MarkdownBuilder and returns it configured
-
-        Example:
-            builder.toggle("Advanced Settings", lambda t:
-                t.h3("Configuration")
-                .paragraph("Settings description")
-                .table(["Setting", "Value"], [["Debug", "True"]])
-                .callout("Important note", "⚠️")
-            )
-        """
-        toggle_builder = MarkdownBuilder()
-        builder_func(toggle_builder)
-        self.children.append(
-            ToggleMarkdownNode(title=title, children=toggle_builder.children)
-        )
-        return self
-
-    def toggleable_heading(
-        self,
-        text: str,
-        level: int,
-        builder_func: Callable[["MarkdownBuilder"], "MarkdownBuilder"],
-    ) -> Self:
-        """
-        Add a toggleable heading with content built using the builder API.
-
-        Args:
-            text: The heading text content
-            level: Heading level (1-3)
-            builder_func: Function that receives a MarkdownBuilder and returns it configured
-
-        Example:
-            builder.toggleable_heading("Advanced Section", 2, lambda t:
-                t.paragraph("Introduction to this section")
-                .numbered_list(["Step 1", "Step 2", "Step 3"])
-                .code("example_code()", "python")
-                .table(["Feature", "Status"], [["API", "Ready"]])
-            )
-        """
-        toggle_builder = MarkdownBuilder()
-        builder_func(toggle_builder)
-        self.children.append(
-            ToggleableHeadingMarkdownNode(
-                text=text, level=level, children=toggle_builder.children
-            )
-        )
-        return self
-
-    def image(
-        self, url: str, caption: Optional[str] = None, alt: Optional[str] = None
-    ) -> Self:
-        """
-        Add an image.
-
-        Args:
-            url: Image URL or file path
-            caption: Optional image caption text
-            alt: Optional alternative text for accessibility
-        """
-        self.children.append(ImageMarkdownNode(url=url, caption=caption, alt=alt))
-        return self
-
-    def video(self, url: str, caption: Optional[str] = None) -> Self:
-        """
-        Add a video.
-
-        Args:
-            url: Video URL or file path
-            caption: Optional video caption text
-        """
-        self.children.append(VideoMarkdownNode(url=url, caption=caption))
-        return self
-
-    def audio(self, url: str, caption: Optional[str] = None) -> Self:
-        """
-        Add audio content.
-
-        Args:
-            url: Audio file URL or path
-            caption: Optional audio caption text
-        """
-        self.children.append(AudioMarkdownNode(url=url, caption=caption))
-        return self
-
-    def file(self, url: str, caption: Optional[str] = None) -> Self:
-        """
-        Add a file.
-
-        Args:
-            url: File URL or path
-            caption: Optional file caption text
-        """
-        self.children.append(FileMarkdownNode(url=url, caption=caption))
-        return self
-
-    def pdf(self, url: str, caption: Optional[str] = None) -> Self:
-        """
-        Add a PDF document.
-
-        Args:
-            url: PDF URL or file path
-            caption: Optional PDF caption text
-        """
-        self.children.append(PdfMarkdownNode(url=url, caption=caption))
-        return self
-
-    def bookmark(
-        self, url: str, title: Optional[str] = None, caption: Optional[str] = None
-    ) -> Self:
-        """
-        Add a bookmark.
-
-        Args:
-            url: Bookmark URL
-            title: Optional bookmark title
-            description: Optional bookmark description text
-        """
-        self.children.append(
-            BookmarkMarkdownNode(url=url, title=title, caption=caption)
-        )
-        return self
-
-    def embed(self, url: str, caption: Optional[str] = None) -> Self:
-        """
-        Add an embed.
-
-        Args:
-            url: URL to embed (e.g., YouTube, Twitter, etc.)
-            caption: Optional embed caption text
-        """
-        self.children.append(EmbedMarkdownNode(url=url, caption=caption))
-        return self
-
-    def code(
-        self, code: str, language: Optional[str] = None, caption: Optional[str] = None
-    ) -> Self:
-        """
-        Add a code block.
-
-        Args:
-            code: The source code content
-            language: Optional programming language for syntax highlighting
-            caption: Optional code block caption text
-        """
-        self.children.append(
-            CodeMarkdownNode(code=code, language=language, caption=caption)
-        )
-        return self
-
-    def mermaid(self, diagram: str, caption: Optional[str] = None) -> Self:
-        """
-        Add a Mermaid diagram block.
-
-        Args:
-            diagram: The Mermaid diagram source code
-            caption: Optional diagram caption text
-        """
-        self.children.append(
-            CodeMarkdownNode(
-                code=diagram, language=CodeLanguage.MERMAID.value, caption=caption
-            )
-        )
-        return self
-
-    def table(self, headers: list[str], rows: list[list[str]]) -> Self:
-        """
-        Add a table.
-
-        Args:
-            headers: List of column header texts
-            rows: List of rows, where each row is a list of cell texts
-        """
-        self.children.append(TableMarkdownNode(headers=headers, rows=rows))
-        return self
-
-    def add_custom(self, node: MarkdownNode) -> Self:
-        """
-        Add a custom MarkdownNode.
-
-        Args:
-            node: A custom MarkdownNode instance
-        """
-        self.children.append(node)
-        return self
-
-    def breadcrumb(self) -> Self:
-        """Add a breadcrumb navigation block."""
-        self.children.append(BreadcrumbMarkdownNode())
-        return self
-
-    def equation(self, expression: str) -> Self:
-        """
-        Add a LaTeX equation block.
-
-        Args:
-            expression: LaTeX mathematical expression
-
-        Example:
-            builder.equation("E = mc^2")
-            builder.equation("f(x) = \\sin(x) + \\cos(x)")
-            builder.equation("x = \\frac{-b \\pm \\sqrt{b^2-4ac}}{2a}")
-        """
-        self.children.append(EquationMarkdownNode(expression=expression))
-        return self
-
-    def table_of_contents(self, color: Optional[str] = None) -> Self:
-        """
-        Add a table of contents.
-
-        Args:
-            color: Optional color for the table of contents (e.g., "blue", "blue_background")
-        """
-        self.children.append(TableOfContentsMarkdownNode(color=color))
-        return self
-
-    def columns(
-        self,
-        *builder_funcs: Callable[["MarkdownBuilder"], "MarkdownBuilder"],
-        width_ratios: Optional[list[float]] = None,
-    ) -> Self:
-        """
-        Add multiple columns in a layout.
-
-        Args:
-            *builder_funcs: Multiple functions, each building one column
-            width_ratios: Optional list of width ratios (0.0 to 1.0).
-                        If None, columns have equal width.
-                        Length must match number of builder_funcs.
-
-        Examples:
-            # Equal width (original API unchanged):
-            builder.columns(
-                lambda col: col.h2("Left").paragraph("Left content"),
-                lambda col: col.h2("Right").paragraph("Right content")
-            )
-
-            # Custom ratios:
-            builder.columns(
-                lambda col: col.h2("Main").paragraph("70% width"),
-                lambda col: col.h2("Sidebar").paragraph("30% width"),
-                width_ratios=[0.7, 0.3]
-            )
-
-            # Three columns with custom ratios:
-            builder.columns(
-                lambda col: col.h3("Nav").paragraph("Navigation"),
-                lambda col: col.h2("Main").paragraph("Main content"),
-                lambda col: col.h3("Ads").paragraph("Advertisement"),
-                width_ratios=[0.2, 0.6, 0.2]
-            )
-        """
-        if len(builder_funcs) < 2:
-            raise ValueError("Column layout requires at least 2 columns")
-
-        if width_ratios is not None:
-            if len(width_ratios) != len(builder_funcs):
-                raise ValueError(
-                    f"width_ratios length ({len(width_ratios)}) must match number of columns ({len(builder_funcs)})"
-                )
-
-            ratio_sum = sum(width_ratios)
-            if not (0.9 <= ratio_sum <= 1.1):  # Allow small floating point errors
-                raise ValueError(f"width_ratios should sum to 1.0, got {ratio_sum}")
-
-        # Create all columns
-        columns = []
-        for i, builder_func in enumerate(builder_funcs):
-            width_ratio = width_ratios[i] if width_ratios else None
-
-            col_builder = MarkdownBuilder()
-            builder_func(col_builder)
-
-            column_node = ColumnMarkdownNode(
-                children=col_builder.children, width_ratio=width_ratio
-            )
-            columns.append(column_node)
-
-        self.children.append(ColumnListMarkdownNode(columns=columns))
-        return self
-
-    def column_with_nodes(
-        self, *nodes: MarkdownNode, width_ratio: Optional[float] = None
-    ) -> Self:
-        """
-        Add a column with pre-built MarkdownNode objects.
-
-        Args:
-            *nodes: MarkdownNode objects to include in the column
-            width_ratio: Optional width ratio (0.0 to 1.0)
-
-        Examples:
-            # Original API (unchanged):
-            builder.column_with_nodes(
-                HeadingMarkdownNode(text="Title", level=2),
-                ParagraphMarkdownNode(text="Content")
-            )
-
-            # New API with ratio:
-            builder.column_with_nodes(
-                HeadingMarkdownNode(text="Sidebar", level=2),
-                ParagraphMarkdownNode(text="Narrow content"),
-                width_ratio=0.25
-            )
-        """
-        from notionary.blocks.column.column_markdown_node import ColumnMarkdownNode
-
-        column_node = ColumnMarkdownNode(children=list(nodes), width_ratio=width_ratio)
-        self.children.append(column_node)
-        return self
-
-    def _column(
-        self, builder_func: Callable[[MarkdownBuilder], MarkdownBuilder]
-    ) -> ColumnMarkdownNode:
-        """
-        Internal helper to create a single column.
-        Use columns() instead for public API.
-        """
-        col_builder = MarkdownBuilder()
-        builder_func(col_builder)
-        return ColumnMarkdownNode(children=col_builder.children)
-
-    def space(self) -> Self:
-        """Add vertical spacing."""
-        return self.paragraph("")
-
-    def build(self) -> str:
-        """Build and return the final markdown string."""
-        return "\n\n".join(
-            child.to_markdown() for child in self.children if child is not None
-        )

notionary/blocks/markdown/markdown_node.py

@@ -1,25 +0,0 @@
-from abc import ABC, abstractmethod
-from pydantic import BaseModel
-
-
-class MarkdownNode(BaseModel, ABC):
-    """
-    Enhanced base class for all Markdown nodes with Pydantic integration.
-
-    This class serves dual purposes:
-    1. Runtime representation for markdown generation
-    2. Serializable model for structured output (LLM/API)
-
-    The 'type' field acts as a discriminator for Union types and processing.
-    """
-
-    @abstractmethod
-    def to_markdown(self) -> str:
-        """
-        Returns the Markdown representation of the block.
-        Must be implemented by subclasses.
-        """
-        pass
-
-    def __str__(self):
-        return self.to_markdown()

notionary/blocks/mixins/captions/__init__.py

@@ -1,4 +0,0 @@
-from .caption_mixin import CaptionMixin
-from .caption_markdown_node_mixin import CaptionMarkdownNodeMixin
-
-__all__ = ["CaptionMixin", "CaptionMarkdownNodeMixin"]

notionary/blocks/mixins/captions/caption_markdown_node_mixin.py

@@ -1,31 +0,0 @@
-from typing import Optional
-
-
-class CaptionMarkdownNodeMixin:
-    """Mixin to add caption functionality to MarkdownNode classes."""
-
-    @classmethod
-    def append_caption_to_markdown(
-        cls, base_markdown: str, caption: Optional[str]
-    ) -> str:
-        """
-        Append caption to existing markdown if caption is present.
-        Returns: base_markdown + "(caption:...)" or just base_markdown
-        """
-        if not caption:
-            return base_markdown
-        return f"{base_markdown}(caption:{caption})"
-
-    @classmethod
-    def format_caption_for_markdown(cls, caption: Optional[str]) -> str:
-        """
-        Format caption text for markdown output.
-        Returns: "(caption:...)" or empty string
-        """
-        if not caption:
-            return ""
-        return f"(caption:{caption})"
-
-    def has_caption(self) -> bool:
-        """Check if this node has a caption."""
-        return hasattr(self, "caption") and bool(getattr(self, "caption", None))

notionary/blocks/mixins/captions/caption_mixin.py

@@ -1,92 +0,0 @@
-from typing import Optional
-import re
-from notionary.blocks.rich_text.rich_text_models import RichTextObject
-from notionary.blocks.rich_text.text_inline_formatter import TextInlineFormatter
-
-
-class CaptionMixin:
-    """Mixin to add caption parsing functionality to block elements."""
-
-    # Generic caption pattern - finds caption anywhere in text
-    CAPTION_PATTERN = re.compile(r"\(caption:([^)]*)\)")
-
-    @classmethod
-    def extract_caption(cls, text: str) -> Optional[str]:
-        """
-        Extract caption text from anywhere in the input text.
-        Returns only the caption content, preserving parentheses in content.
-        """
-        # Look for (caption: followed by content followed by )
-        # Handle cases where caption content contains parentheses
-        caption_start = text.find("(caption:")
-        if caption_start == -1:
-            return None
-
-        # Find the matching closing parenthesis
-        # Start after "(caption:"
-        content_start = caption_start + 9  # len("(caption:")
-        paren_count = 1
-        pos = content_start
-
-        while pos < len(text) and paren_count > 0:
-            if text[pos] == "(":
-                paren_count += 1
-            elif text[pos] == ")":
-                paren_count -= 1
-            pos += 1
-
-        if paren_count == 0:
-            # Found matching closing parenthesis
-            return text[content_start : pos - 1]
-
-        return None
-
-    @classmethod
-    def remove_caption(cls, text: str) -> str:
-        """
-        Remove caption from text and return clean text.
-        Uses the same balanced parentheses logic as extract_caption.
-        """
-        caption_start = text.find("(caption:")
-        if caption_start == -1:
-            return text.strip()
-
-        # Find the matching closing parenthesis
-        content_start = caption_start + 9  # len("(caption:")
-        paren_count = 1
-        pos = content_start
-
-        while pos < len(text) and paren_count > 0:
-            if text[pos] == "(":
-                paren_count += 1
-            elif text[pos] == ")":
-                paren_count -= 1
-            pos += 1
-
-        if paren_count == 0:
-            # Remove the entire caption including the outer parentheses
-            return (text[:caption_start] + text[pos:]).strip()
-
-        # Fallback to regex-based removal if balanced parsing fails
-        return cls.CAPTION_PATTERN.sub("", text).strip()
-
-    @classmethod
-    def build_caption_rich_text(cls, caption_text: str) -> list[RichTextObject]:
-        """Return caption as canonical rich text list (with annotations)."""
-        if not caption_text:
-            return []
-        # IMPORTANT: use the same formatter used elsewhere in the app
-        return [RichTextObject.for_caption(caption_text)]
-
-    @classmethod
-    async def format_caption_for_markdown(
-        cls, caption_list: list[RichTextObject]
-    ) -> str:
-        """Convert rich text caption back to markdown format."""
-        if not caption_list:
-            return ""
-        # Preserve markdown formatting (bold, italic, etc.)
-        caption_text = await TextInlineFormatter.extract_text_with_formatting(
-            caption_list
-        )
-        return f"(caption:{caption_text})" if caption_text else ""

notionary/blocks/mixins/file_upload/__init__.py

@@ -1,3 +0,0 @@
-from .file_upload_mixin import FileUploadMixin
-
-__all__ = ["FileUploadMixin"]