notionary 0.2.21__tar.gz → 0.2.23__tar.gz

notionary-0.2.23/PKG-INFO

@@ -0,0 +1,235 @@
+Metadata-Version: 2.3
+Name: notionary
+Version: 0.2.23
+Summary: Python library for programmatic Notion workspace management - databases, pages, and content with advanced Markdown support
+License: MIT
+Author: Mathis Arends
+Author-email: mathisarends27@gmail.com
+Requires-Python: >=3.9
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+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-Dist: httpx (>=0.28.0)
+Requires-Dist: posthog (>=6.3.1,<7.0.0)
+Requires-Dist: pydantic (>=2.11.4)
+Requires-Dist: python-dotenv (>=1.1.0)
+Project-URL: Homepage, https://github.com/mathisarends/notionary
+Description-Content-Type: text/markdown
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="./static/notionary-dark.png">
+  <source media="(prefers-color-scheme: light)" srcset="./static/notionary-light.png">
+  <img alt="Notionary logo: dark mode shows a white logo, light mode shows a black logo." src="./static/browser-use.png"  width="full">
+</picture>
+
+<h1 align="center">Notion API simplified for Python developers 🐍</h1>
+
+<div align="center">
+
+[![Python Version](https://img.shields.io/badge/python-3.8%2B-blue.svg)](https://www.python.org/downloads/)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![Documentation](https://img.shields.io/badge/docs-mathisarends.github.io-blue.svg)](https://mathisarends.github.io/notionary/)
+
+Transform complex Notion API interactions into simple, Pythonic code. Build AI agents, automate workflows, and create dynamic content with ease.
+
+</div>
+
+---
+
+## Why Notionary?
+
+- **Smart Discovery**: Find pages and databases by name—no more hunting for URLs or IDs
+- **Rich Markdown**: Convert extended Markdown (callouts, toggles, columns) directly into beautiful Notion blocks
+- **Async-First**: Built for modern Python with full async/await support and high performance
+- **AI-Ready**: Perfect foundation for AI agents that generate and manage Notion content
+- **Round-Trip**: Read existing content, modify it, and write it back while preserving formatting
+
+---
+
+## Quick Start
+
+```bash
+pip install notionary
+```
+
+Set up your [Notion integration](https://www.notion.so/profile/integrations) and add your token:
+
+```bash
+NOTION_SECRET=your_integration_key
+```
+
+### Simple Flow: Find → Create → Update
+
+```python
+import asyncio
+from notionary import NotionPage, NotionDatabase
+
+async def main():
+    # Work with pages - find by name, no exact match needed!
+    page = await NotionPage.from_page_name("Meeting Notes")
+
+    # Direct Markdown - quick & intuitive
+    await page.append_markdown("""
+    ## Action Items
+    - Review project proposal
+    - Schedule team meeting
+    - Update documentation
+
+    [callout](Important meeting decisions require follow-up "💡")
+    """)
+
+    # Builder Pattern - type-safe & powerful for complex layouts
+    await page.append_markdown(lambda builder: (
+        builder
+        .h2("Project Status")
+        .callout("Project milestone reached!", "🎉")
+        .columns(
+            lambda col: (col
+                .h3("Completed")
+                .bulleted_list(["API design", "Database setup", "Authentication"])
+            ),
+            lambda col: (col
+                .h3("In Progress")
+                .bulleted_list(["Frontend UI", "Testing", "Documentation"])
+            )
+        )
+        .table(
+            headers=["Task", "Owner", "Due Date"],
+            rows=[
+                ["Launch prep", "Alice", "2024-03-15"],
+                ["Marketing", "Bob", "2024-03-20"]
+            ]
+        )
+    ))
+
+asyncio.run(main())
+```
+
+### Create Rich Database Entries
+
+```python
+# Work with databases - connect and create styled entries
+db = await NotionDatabase.from_database_name("Projects")
+
+# Create new project with full styling
+project = await db.create_blank_page()
+await project.set_title("New Marketing Campaign")
+await project.set_emoji_icon("🚀")
+await project.set_random_gradient_cover()
+
+# Set database properties
+await project.set_property_value_by_name("Status", "Planning")
+await project.set_property_value_by_name("Priority", "High")
+await project.set_property_value_by_name("Team Lead", "sarah@company.com")
+
+# Add rich content to the new page
+await project.replace_content(lambda builder: (
+    builder
+    .h1("Campaign Overview")
+    .callout("New marketing initiative targeting Q2 growth", "🎯")
+    .h2("Goals & Objectives")
+    .numbered_list([
+        "Increase brand awareness by 25%",
+        "Generate 500 qualified leads",
+        "Launch in 3 target markets"
+    ])
+    .h2("Budget Breakdown")
+    .table(
+        headers=["Category", "Allocated", "Spent", "Remaining"],
+        rows=[
+            ["Digital Ads", "$15,000", "$3,200", "$11,800"],
+            ["Content Creation", "$8,000", "$1,500", "$6,500"],
+            ["Events", "$12,000", "$0", "$12,000"]
+        ]
+    )
+    .divider()
+    .toggle("Technical Requirements", lambda toggle: (
+        toggle
+        .paragraph("Platform specifications and integration details.")
+        .bulleted_list([
+            "CRM integration with Salesforce",
+            "Analytics tracking setup",
+            "Landing page development"
+        ])
+    ))
+))
+
+print(f"✅ Created styled project: {project.url}")
+```
+
+### Extended Markdown Syntax
+
+Notionary supports rich formatting with callouts, toggles, multi-column layouts, tables, media embeds, and more. Use either direct markdown syntax or the type-safe builder pattern.
+
+See the complete [Block Types documentation](https://mathisarends.github.io/notionary/blocks/) for all available formatting options and syntax examples.
+
+## What You Can Build
+
+- **AI Content Generation** - Perfect for AI agents that create structured reports and documentation
+- **Workflow Automation** - Update project status, sync data between databases, generate reports
+- **Dynamic Documentation** - Auto-generate team docs, API references, and knowledge bases
+- **Content Management** - Bulk page updates, template generation, and content migration
+
+## Core Features
+
+| Feature              | Description                                            |
+| -------------------- | ------------------------------------------------------ |
+| **Smart Discovery**  | Find pages/databases by name with fuzzy matching       |
+| **Rich Markdown**    | Extended syntax for callouts, toggles, columns, tables |
+| **Async-First**      | Modern Python with full async/await support            |
+| **Round-Trip**       | Read content as markdown, edit, and write back         |
+| **AI-Ready**         | Generate system prompts for AI content creation        |
+| **All Block Types**  | Support for every Notion block type                    |
+| **Type Safety**      | Full type hints for better IDE support                 |
+| **High Performance** | Efficient batch operations and caching                 |
+
+## Examples & Documentation
+
+Explore comprehensive guides and real-world examples:
+
+- **[📖 Full Documentation](https://mathisarends.github.io/notionary/)** - Complete API reference and guides
+- **[Getting Started](https://mathisarends.github.io/notionary/get-started/)** - Quick setup and first steps
+- **[Page Management](https://mathisarends.github.io/notionary/page/)** - Work with page content and properties
+- **[Database Operations](https://mathisarends.github.io/notionary/database/)** - Query and manage databases
+- **[Block Types](https://mathisarends.github.io/notionary/blocks/)** - Complete formatting reference
+
+Check out the `examples/` directory for hands-on tutorials:
+
+### Core Examples
+
+- **[Page Management](examples/page_example.py)** - Create, update, and manage pages
+- **[Database Operations](examples/database.py)** - Connect to and query databases
+- **[Workspace Discovery](examples/workspace_discovery.py)** - Explore your workspace
+
+### Markdown Examples
+
+- **[Basic Formatting](examples/markdown/basic.py)** - Text, lists, and links
+- **[Callouts](examples/markdown/callout.py)** - Eye-catching information boxes
+- **[Toggles](examples/markdown/toggle.py)** - Collapsible content sections
+- **[Multi-Column](examples/markdown/columns.py)** - Side-by-side layouts
+- **[Tables](examples/markdown/table.py)** - Structured data presentation
+
+## Contributing
+
+We'd love your help making Notionary even better!
+
+Whether it's fixing bugs, adding features, improving docs, or sharing examples - all contributions are welcome.
+
+See our [Contributing Guide](https://mathisarends.github.io/notionary/contributing/) to get started.
+
+---
+
+<div align="center">
+
+**Ready to transform your Notion workflow?**
+
+[📖 Read the Docs](https://mathisarends.github.io/notionary/) • [Getting Started](https://mathisarends.github.io/notionary/get-started/) • [Examples](examples/)
+
+Built with ❤️ for the Python community
+
+</div>
+

notionary-0.2.23/README.md

@@ -0,0 +1,212 @@
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="./static/notionary-dark.png">
+  <source media="(prefers-color-scheme: light)" srcset="./static/notionary-light.png">
+  <img alt="Notionary logo: dark mode shows a white logo, light mode shows a black logo." src="./static/browser-use.png"  width="full">
+</picture>
+
+<h1 align="center">Notion API simplified for Python developers 🐍</h1>
+
+<div align="center">
+
+[![Python Version](https://img.shields.io/badge/python-3.8%2B-blue.svg)](https://www.python.org/downloads/)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![Documentation](https://img.shields.io/badge/docs-mathisarends.github.io-blue.svg)](https://mathisarends.github.io/notionary/)
+
+Transform complex Notion API interactions into simple, Pythonic code. Build AI agents, automate workflows, and create dynamic content with ease.
+
+</div>
+
+---
+
+## Why Notionary?
+
+- **Smart Discovery**: Find pages and databases by name—no more hunting for URLs or IDs
+- **Rich Markdown**: Convert extended Markdown (callouts, toggles, columns) directly into beautiful Notion blocks
+- **Async-First**: Built for modern Python with full async/await support and high performance
+- **AI-Ready**: Perfect foundation for AI agents that generate and manage Notion content
+- **Round-Trip**: Read existing content, modify it, and write it back while preserving formatting
+
+---
+
+## Quick Start
+
+```bash
+pip install notionary
+```
+
+Set up your [Notion integration](https://www.notion.so/profile/integrations) and add your token:
+
+```bash
+NOTION_SECRET=your_integration_key
+```
+
+### Simple Flow: Find → Create → Update
+
+```python
+import asyncio
+from notionary import NotionPage, NotionDatabase
+
+async def main():
+    # Work with pages - find by name, no exact match needed!
+    page = await NotionPage.from_page_name("Meeting Notes")
+
+    # Direct Markdown - quick & intuitive
+    await page.append_markdown("""
+    ## Action Items
+    - Review project proposal
+    - Schedule team meeting
+    - Update documentation
+
+    [callout](Important meeting decisions require follow-up "💡")
+    """)
+
+    # Builder Pattern - type-safe & powerful for complex layouts
+    await page.append_markdown(lambda builder: (
+        builder
+        .h2("Project Status")
+        .callout("Project milestone reached!", "🎉")
+        .columns(
+            lambda col: (col
+                .h3("Completed")
+                .bulleted_list(["API design", "Database setup", "Authentication"])
+            ),
+            lambda col: (col
+                .h3("In Progress")
+                .bulleted_list(["Frontend UI", "Testing", "Documentation"])
+            )
+        )
+        .table(
+            headers=["Task", "Owner", "Due Date"],
+            rows=[
+                ["Launch prep", "Alice", "2024-03-15"],
+                ["Marketing", "Bob", "2024-03-20"]
+            ]
+        )
+    ))
+
+asyncio.run(main())
+```
+
+### Create Rich Database Entries
+
+```python
+# Work with databases - connect and create styled entries
+db = await NotionDatabase.from_database_name("Projects")
+
+# Create new project with full styling
+project = await db.create_blank_page()
+await project.set_title("New Marketing Campaign")
+await project.set_emoji_icon("🚀")
+await project.set_random_gradient_cover()
+
+# Set database properties
+await project.set_property_value_by_name("Status", "Planning")
+await project.set_property_value_by_name("Priority", "High")
+await project.set_property_value_by_name("Team Lead", "sarah@company.com")
+
+# Add rich content to the new page
+await project.replace_content(lambda builder: (
+    builder
+    .h1("Campaign Overview")
+    .callout("New marketing initiative targeting Q2 growth", "🎯")
+    .h2("Goals & Objectives")
+    .numbered_list([
+        "Increase brand awareness by 25%",
+        "Generate 500 qualified leads",
+        "Launch in 3 target markets"
+    ])
+    .h2("Budget Breakdown")
+    .table(
+        headers=["Category", "Allocated", "Spent", "Remaining"],
+        rows=[
+            ["Digital Ads", "$15,000", "$3,200", "$11,800"],
+            ["Content Creation", "$8,000", "$1,500", "$6,500"],
+            ["Events", "$12,000", "$0", "$12,000"]
+        ]
+    )
+    .divider()
+    .toggle("Technical Requirements", lambda toggle: (
+        toggle
+        .paragraph("Platform specifications and integration details.")
+        .bulleted_list([
+            "CRM integration with Salesforce",
+            "Analytics tracking setup",
+            "Landing page development"
+        ])
+    ))
+))
+
+print(f"✅ Created styled project: {project.url}")
+```
+
+### Extended Markdown Syntax
+
+Notionary supports rich formatting with callouts, toggles, multi-column layouts, tables, media embeds, and more. Use either direct markdown syntax or the type-safe builder pattern.
+
+See the complete [Block Types documentation](https://mathisarends.github.io/notionary/blocks/) for all available formatting options and syntax examples.
+
+## What You Can Build
+
+- **AI Content Generation** - Perfect for AI agents that create structured reports and documentation
+- **Workflow Automation** - Update project status, sync data between databases, generate reports
+- **Dynamic Documentation** - Auto-generate team docs, API references, and knowledge bases
+- **Content Management** - Bulk page updates, template generation, and content migration
+
+## Core Features
+
+| Feature              | Description                                            |
+| -------------------- | ------------------------------------------------------ |
+| **Smart Discovery**  | Find pages/databases by name with fuzzy matching       |
+| **Rich Markdown**    | Extended syntax for callouts, toggles, columns, tables |
+| **Async-First**      | Modern Python with full async/await support            |
+| **Round-Trip**       | Read content as markdown, edit, and write back         |
+| **AI-Ready**         | Generate system prompts for AI content creation        |
+| **All Block Types**  | Support for every Notion block type                    |
+| **Type Safety**      | Full type hints for better IDE support                 |
+| **High Performance** | Efficient batch operations and caching                 |
+
+## Examples & Documentation
+
+Explore comprehensive guides and real-world examples:
+
+- **[📖 Full Documentation](https://mathisarends.github.io/notionary/)** - Complete API reference and guides
+- **[Getting Started](https://mathisarends.github.io/notionary/get-started/)** - Quick setup and first steps
+- **[Page Management](https://mathisarends.github.io/notionary/page/)** - Work with page content and properties
+- **[Database Operations](https://mathisarends.github.io/notionary/database/)** - Query and manage databases
+- **[Block Types](https://mathisarends.github.io/notionary/blocks/)** - Complete formatting reference
+
+Check out the `examples/` directory for hands-on tutorials:
+
+### Core Examples
+
+- **[Page Management](examples/page_example.py)** - Create, update, and manage pages
+- **[Database Operations](examples/database.py)** - Connect to and query databases
+- **[Workspace Discovery](examples/workspace_discovery.py)** - Explore your workspace
+
+### Markdown Examples
+
+- **[Basic Formatting](examples/markdown/basic.py)** - Text, lists, and links
+- **[Callouts](examples/markdown/callout.py)** - Eye-catching information boxes
+- **[Toggles](examples/markdown/toggle.py)** - Collapsible content sections
+- **[Multi-Column](examples/markdown/columns.py)** - Side-by-side layouts
+- **[Tables](examples/markdown/table.py)** - Structured data presentation
+
+## Contributing
+
+We'd love your help making Notionary even better!
+
+Whether it's fixing bugs, adding features, improving docs, or sharing examples - all contributions are welcome.
+
+See our [Contributing Guide](https://mathisarends.github.io/notionary/contributing/) to get started.
+
+---
+
+<div align="center">
+
+**Ready to transform your Notion workflow?**
+
+[📖 Read the Docs](https://mathisarends.github.io/notionary/) • [Getting Started](https://mathisarends.github.io/notionary/get-started/) • [Examples](examples/)
+
+Built with ❤️ for the Python community
+
+</div>

{notionary-0.2.21 → notionary-0.2.23}/notionary/blocks/_bootstrap.py

@@ -34,6 +34,7 @@ def bootstrap_blocks() -> None:
         toggle,
         toggleable_heading,
         video,
+        child_database,
     )
 
     # Collect all exports from modules
@@ -61,6 +62,7 @@ def bootstrap_blocks() -> None:
         video,
         toggleable_heading,
         table_of_contents,
+        child_database,
     ):
         ns.update(vars(m))
 
@@ -123,6 +125,10 @@ def bootstrap_blocks() -> None:
     from notionary.blocks.toggle.toggle_models import CreateToggleBlock, ToggleBlock
     from notionary.blocks.types import BlockType
     from notionary.blocks.video.video_element_models import CreateVideoBlock
+    from notionary.blocks.child_database.child_database_models import (
+        CreateChildDatabaseBlock,
+        ChildDatabaseBlock,
+    )
 
     # Define the Union types that are needed for model rebuilding
     BlockCreateRequest = Union[
@@ -150,9 +156,10 @@ def bootstrap_blocks() -> None:
         CreateVideoBlock,
         CreateTableOfContentsBlock,
         CreatePdfBlock,
+        CreateChildDatabaseBlock,
     ]
 
-    BlockCreateResult = Optional[Union[list[BlockCreateRequest], BlockCreateRequest]]
+    BlockCreateResult = Optional[BlockCreateRequest]
 
     # Add all block types to namespace
     ns.update(
@@ -202,6 +209,7 @@ def bootstrap_blocks() -> None:
             "CreateVideoBlock": CreateVideoBlock,
             "TableOfContentsBlock": TableOfContentsBlock,
             "CreateTableOfContentsBlock": CreateTableOfContentsBlock,
+            "ChildDatabaseBlock": ChildDatabaseBlock,
             # Add the Union types
             "BlockCreateRequest": BlockCreateRequest,
             "BlockCreateResult": BlockCreateResult,

notionary-0.2.23/notionary/blocks/audio/audio_element.py

@@ -0,0 +1,115 @@
+from __future__ import annotations
+
+import re
+from typing import Optional
+
+from notionary.blocks.audio.audio_models import CreateAudioBlock
+from notionary.blocks.base_block_element import BaseBlockElement
+from notionary.blocks.file.file_element_models import ExternalFile, FileBlock, FileType
+from notionary.blocks.mixins.captions import CaptionMixin
+from notionary.blocks.syntax_prompt_builder import BlockElementMarkdownInformation
+from notionary.blocks.models import Block, BlockCreateResult, BlockType
+
+
+class AudioElement(BaseBlockElement, CaptionMixin):
+    """
+    Handles conversion between Markdown audio embeds and Notion audio blocks.
+
+    Markdown audio syntax:
+    - [audio](https://example.com/audio.mp3) - Simple audio embed
+    - [audio](https://example.com/audio.mp3)(caption:Episode 1) - Audio with caption
+    - (caption:Background music)[audio](https://example.com/song.mp3) - caption before URL
+
+    Where:
+    - URL is the required audio file URL
+    - Caption supports rich text formatting and is optional
+    """
+
+    # Simple pattern that matches just the audio link, CaptionMixin handles caption separately
+    AUDIO_PATTERN = re.compile(r"\[audio\]\((https?://[^\s\"]+)\)")
+
+    @classmethod
+    def _extract_audio_url(cls, text: str) -> Optional[str]:
+        """Extract audio URL from text, handling caption patterns."""
+        # First remove any captions to get clean text for URL extraction
+        clean_text = cls.remove_caption(text)
+
+        # Now extract the URL from clean text
+        match = cls.AUDIO_PATTERN.search(clean_text)
+        if match:
+            return match.group(1)
+
+        return None
+
+    SUPPORTED_EXTENSIONS = {".mp3", ".wav", ".ogg", ".oga", ".m4a"}
+
+    @classmethod
+    def match_notion(cls, block: Block) -> bool:
+        """Check if this element can handle the given Notion block."""
+        return block.type == BlockType.AUDIO
+
+    @classmethod
+    async def markdown_to_notion(cls, text: str) -> BlockCreateResult:
+        """Convert markdown audio embed to Notion audio block."""
+        # Use our helper method to extract the URL
+        url = cls._extract_audio_url(text.strip())
+        if not url:
+            return None
+
+        if not cls._is_likely_audio_url(url):
+            return None
+
+        # Use mixin to extract caption (if present anywhere in text)
+        caption_text = cls.extract_caption(text.strip())
+        caption_rich_text = cls.build_caption_rich_text(caption_text or "")
+
+        audio_content = FileBlock(
+            type=FileType.EXTERNAL,
+            external=ExternalFile(url=url),
+            caption=caption_rich_text,
+        )
+
+        return CreateAudioBlock(audio=audio_content)
+
+    @classmethod
+    async def notion_to_markdown(cls, block: Block) -> Optional[str]:
+        """Convert Notion audio block to markdown audio embed."""
+        if block.type != BlockType.AUDIO or block.audio is None:
+            return None
+
+        audio = block.audio
+
+        # Only handle external audio
+        if audio.type != FileType.EXTERNAL or audio.external is None:
+            return None
+        url = audio.external.url
+        if not url:
+            return None
+
+        result = f"[audio]({url})"
+
+        # Add caption if present
+        caption_markdown = await cls.format_caption_for_markdown(audio.caption or [])
+        if caption_markdown:
+            result += caption_markdown
+
+        return result
+
+    @classmethod
+    def get_system_prompt_information(cls) -> Optional[BlockElementMarkdownInformation]:
+        """Get system prompt information for audio blocks."""
+        return BlockElementMarkdownInformation(
+            block_type=cls.__name__,
+            description="Audio blocks embed audio files from external URLs with optional captions",
+            syntax_examples=[
+                "[audio](https://example.com/song.mp3)",
+                "[audio](https://example.com/podcast.wav)(caption:Episode 1)",
+                "(caption:Background music)[audio](https://soundcloud.com/track/123)",
+                "[audio](https://example.com/interview.mp3)(caption:**Live** interview)",
+            ],
+            usage_guidelines="Use for embedding audio files like music, podcasts, or sound effects. Supports common audio formats (mp3, wav, ogg, m4a). Caption supports rich text formatting and is optional.",
+        )
+
+    @classmethod
+    def _is_likely_audio_url(cls, url: str) -> bool:
+        return any(url.lower().endswith(ext) for ext in cls.SUPPORTED_EXTENSIONS)

{notionary-0.2.21 → notionary-0.2.23}/notionary/blocks/audio/audio_markdown_node.py

@@ -5,6 +5,7 @@ from typing import Optional
 from pydantic import BaseModel
 
 from notionary.markdown.markdown_node import MarkdownNode
+from notionary.blocks.mixins.captions import CaptionMarkdownNodeMixin
 
 
 class AudioMarkdownBlockParams(BaseModel):
@@ -12,7 +13,7 @@ class AudioMarkdownBlockParams(BaseModel):
     caption: Optional[str] = None
 
 
-class AudioMarkdownNode(MarkdownNode):
+class AudioMarkdownNode(MarkdownNode, CaptionMarkdownNodeMixin):
     """
     Programmatic interface for creating Notion-style audio blocks.
     """
@@ -26,6 +27,11 @@ class AudioMarkdownNode(MarkdownNode):
         return cls(url=params.url, caption=params.caption)
 
     def to_markdown(self) -> str:
-        if self.caption:
-            return f'[audio]({self.url} "{self.caption}")'
-        return f"[audio]({self.url})"
+        """Return the Markdown representation.
+
+        Examples:
+        - [audio](https://example.com/song.mp3)
+        - [audio](https://example.com/song.mp3)(caption:Background music)
+        """
+        base_markdown = f"[audio]({self.url})"
+        return self.append_caption_to_markdown(base_markdown, self.caption)

notionary-0.2.23/notionary/blocks/base_block_element.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+from abc import ABC
+from typing import Optional
+
+from notionary.blocks.syntax_prompt_builder import BlockElementMarkdownInformation
+from notionary.blocks.models import Block, BlockCreateResult
+
+
+class BaseBlockElement(ABC):
+    """Base class for elements that can be converted between Markdown and Notion."""
+
+    @classmethod
+    async def markdown_to_notion(cls, text: str) -> BlockCreateResult:
+        """
+        Convert markdown to Notion block content.
+
+        Returns:
+            - BlockContent: Single block content (e.g., ToDoBlock, ParagraphBlock)
+            - list[BlockContent]: Multiple block contents
+            - None: Cannot convert this markdown
+        """
+
+    @classmethod
+    async def notion_to_markdown(cls, block: Block) -> Optional[str]:
+        """Convert Notion block to markdown."""
+
+    @classmethod
+    def match_notion(cls, block: Block) -> bool:
+        """Check if this element can handle the given Notion block."""
+        # Default implementation - subclasses should override this method
+        # Cannot call async notion_to_markdown here
+        return False
+
+    @classmethod
+    def get_system_prompt_information(cls) -> Optional[BlockElementMarkdownInformation]:
+        """Get system prompt information for this block element.
+
+        Subclasses should override this method to provide their specific information.
+        Return None if the element should not be included in documentation.
+        """
+        return None