notionary 0.2.18__tar.gz → 0.2.21__tar.gz

{notionary-0.2.18 → notionary-0.2.21}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: notionary
-Version: 0.2.18
+Version: 0.2.21
 Summary: Python library for programmatic Notion workspace management - databases, pages, and content with advanced Markdown support
 License: MIT
 Author: Mathis Arends
@@ -15,6 +15,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Requires-Dist: aiofiles (>=24.1.0,<25.0.0)
 Requires-Dist: httpx (>=0.28.0)
+Requires-Dist: isort (>=6.0.1,<7.0.0)
 Requires-Dist: posthog (>=6.3.1,<7.0.0)
 Requires-Dist: pydantic (>=2.11.4)
 Requires-Dist: python-dotenv (>=1.1.0)
@@ -36,11 +37,11 @@ Description-Content-Type: text/markdown
 - **Rich Markdown to Notion**: Convert extended Markdown (callouts, toggles, columns) directly into beautiful Notion blocks
 - **Smart Discovery**: Find pages and databases by name with fuzzy matching - no more hunting for URLs
 - **Async-First Architecture**: Built for modern Python with full async/await support and high performance
-- **AI-Ready Integration**: Generate LLM system prompts and let AI agents create Notion content seamlessly
 
 ---
 
 # Quick start
+
 ```bash
 pip install notionary
 ```
@@ -53,29 +54,30 @@ NOTION_SECRET=YOUR_INTEGRATION_KEY
 ```
 
 ### Creating and Managing Pages 🚀
+
 ```python
 from notionary import NotionPage
 
 async def main():
     # Simpy find an existing page by its title
     page = await NotionPage.from_page_name("My Test Page")
-    
+
     # Add rich content with custom Markdown
     content = """
     # 🚀 Generated with Notionary
-    
+
     !> [💡] This page was created programmatically!
-    
+
     ## Features
     - **Rich** Markdown support
     - Database integration
     - AI-ready content generation
-    
+
     +++ Click to see more details
     | Notionary makes it easy to create beautiful Notion pages
     | directly from Python code with intuitive Markdown syntax.
     """
-    
+
     await page.replace_content(content)
     print(f"✅ Page updated: {page.url}")
 
@@ -99,7 +101,7 @@ async def main():
   await page.set_title("🆕 New Project Entry")
   await page.set_property_value_by_name("Status", "In Progress")
   await page.set_property_value_by_name("Priority", "High")
-  
+
   # find pages created in the last 7 days
   count = 0
   async for page in db.iter_pages_with_filter(
@@ -201,6 +203,7 @@ def hello_world():
 Explore the `examples/` directory for comprehensive guides:
 
 ### 🚀 Core Examples
+
 - [**Page Management**](examples/page_example.py) - Create, update, and manage Notion pages
 - [**Page Operations**](examples/page.py) - Advanced page manipulation and content handling
 - [**Database Operations**](examples/database.py) - Connect to and manage Notion databases
@@ -208,6 +211,7 @@ Explore the `examples/` directory for comprehensive guides:
 - [**Workspace Discovery**](examples/workspace_discovery.py) - Explore and discover your Notion workspace
 
 ### 📝 Markdown Examples
+
 - [**Basic Formatting**](examples/markdown/basic.py) - Text formatting, lists, and basic elements
 - [**Callouts**](examples/markdown/callout.py) - Create beautiful callout blocks with icons
 - [**Toggles**](examples/markdown/toggle.py) - Collapsible content sections

{notionary-0.2.18 → notionary-0.2.21}/README.md

@@ -13,11 +13,11 @@
 - **Rich Markdown to Notion**: Convert extended Markdown (callouts, toggles, columns) directly into beautiful Notion blocks
 - **Smart Discovery**: Find pages and databases by name with fuzzy matching - no more hunting for URLs
 - **Async-First Architecture**: Built for modern Python with full async/await support and high performance
-- **AI-Ready Integration**: Generate LLM system prompts and let AI agents create Notion content seamlessly
 
 ---
 
 # Quick start
+
 ```bash
 pip install notionary
 ```
@@ -30,29 +30,30 @@ NOTION_SECRET=YOUR_INTEGRATION_KEY
 ```
 
 ### Creating and Managing Pages 🚀
+
 ```python
 from notionary import NotionPage
 
 async def main():
     # Simpy find an existing page by its title
     page = await NotionPage.from_page_name("My Test Page")
-    
+
     # Add rich content with custom Markdown
     content = """
     # 🚀 Generated with Notionary
-    
+
     !> [💡] This page was created programmatically!
-    
+
     ## Features
     - **Rich** Markdown support
     - Database integration
     - AI-ready content generation
-    
+
     +++ Click to see more details
     | Notionary makes it easy to create beautiful Notion pages
     | directly from Python code with intuitive Markdown syntax.
     """
-    
+
     await page.replace_content(content)
     print(f"✅ Page updated: {page.url}")
 
@@ -76,7 +77,7 @@ async def main():
   await page.set_title("🆕 New Project Entry")
   await page.set_property_value_by_name("Status", "In Progress")
   await page.set_property_value_by_name("Priority", "High")
-  
+
   # find pages created in the last 7 days
   count = 0
   async for page in db.iter_pages_with_filter(
@@ -178,6 +179,7 @@ def hello_world():
 Explore the `examples/` directory for comprehensive guides:
 
 ### 🚀 Core Examples
+
 - [**Page Management**](examples/page_example.py) - Create, update, and manage Notion pages
 - [**Page Operations**](examples/page.py) - Advanced page manipulation and content handling
 - [**Database Operations**](examples/database.py) - Connect to and manage Notion databases
@@ -185,6 +187,7 @@ Explore the `examples/` directory for comprehensive guides:
 - [**Workspace Discovery**](examples/workspace_discovery.py) - Explore and discover your Notion workspace
 
 ### 📝 Markdown Examples
+
 - [**Basic Formatting**](examples/markdown/basic.py) - Text formatting, lists, and basic elements
 - [**Callouts**](examples/markdown/callout.py) - Create beautiful callout blocks with icons
 - [**Toggles**](examples/markdown/toggle.py) - Collapsible content sections

{notionary-0.2.18 → notionary-0.2.21}/notionary/__init__.py

@@ -1,9 +1,13 @@
-from .database import NotionDatabase, DatabaseFilterBuilder
+from notionary.blocks import bootstrap_blocks
+
+bootstrap_blocks()
+
+from .database import DatabaseFilterBuilder, NotionDatabase
+from .file_upload import NotionFileUpload
+from .markdown.markdown_builder import MarkdownBuilder
 from .page.notion_page import NotionPage
+from .user import NotionBotUser, NotionUser, NotionUserManager
 from .workspace import NotionWorkspace
-from .user import NotionUser, NotionUserManager, NotionBotUser
-from .file_upload import NotionFileUpload
-from .blocks.markdown_builder import MarkdownBuilder
 
 __all__ = [
     "NotionDatabase",

{notionary-0.2.18 → notionary-0.2.21}/notionary/base_notion_client.py

@@ -2,9 +2,11 @@ import asyncio
 import os
 from abc import ABC
 from enum import Enum
-from typing import Dict, Any, Optional, Union
+from typing import Any, Dict, Optional, Union
+
 import httpx
 from dotenv import load_dotenv
+
 from notionary.util import LoggingMixin
 
 load_dotenv()

notionary-0.2.21/notionary/blocks/__init__.py

@@ -0,0 +1,3 @@
+from ._bootstrap import bootstrap_blocks
+
+__all__ = ["bootstrap_blocks"]

notionary-0.2.21/notionary/blocks/_bootstrap.py

@@ -0,0 +1,263 @@
+from __future__ import annotations
+
+from typing import Optional, Union
+
+_bootstrapped = False
+
+
+def bootstrap_blocks() -> None:
+    global _bootstrapped
+    if _bootstrapped:
+        return
+
+    from notionary.blocks import (
+        bookmark,
+        breadcrumbs,
+        bulleted_list,
+        callout,
+        child_page,
+        code,
+        column,
+        divider,
+        embed,
+        equation,
+        file,
+        heading,
+        image_block,
+        models,
+        numbered_list,
+        paragraph,
+        quote,
+        table,
+        table_of_contents,
+        todo,
+        toggle,
+        toggleable_heading,
+        video,
+    )
+
+    # Collect all exports from modules
+    ns = {}
+    for m in (
+        bookmark,
+        breadcrumbs,
+        bulleted_list,
+        callout,
+        child_page,
+        code,
+        column,
+        divider,
+        embed,
+        equation,
+        file,
+        heading,
+        image_block,
+        numbered_list,
+        paragraph,
+        quote,
+        table,
+        todo,
+        toggle,
+        video,
+        toggleable_heading,
+        table_of_contents,
+    ):
+        ns.update(vars(m))
+
+    # Add missing types that are needed for model rebuilding
+    # These are the types that are only defined in TYPE_CHECKING in block_models
+    from notionary.blocks.bookmark.bookmark_models import (
+        BookmarkBlock,
+        CreateBookmarkBlock,
+    )
+    from notionary.blocks.breadcrumbs.breadcrumb_models import (
+        BreadcrumbBlock,
+        CreateBreadcrumbBlock,
+    )
+    from notionary.blocks.bulleted_list.bulleted_list_models import (
+        BulletedListItemBlock,
+        CreateBulletedListItemBlock,
+    )
+    from notionary.blocks.callout.callout_models import CalloutBlock, CreateCalloutBlock
+    from notionary.blocks.child_page.child_page_models import (
+        ChildPageBlock,
+        CreateChildPageBlock,
+    )
+    from notionary.blocks.code.code_models import CodeBlock, CreateCodeBlock
+    from notionary.blocks.column.column_models import (
+        ColumnBlock,
+        ColumnListBlock,
+        CreateColumnBlock,
+        CreateColumnListBlock,
+    )
+    from notionary.blocks.divider.divider_models import CreateDividerBlock, DividerBlock
+    from notionary.blocks.embed.embed_models import CreateEmbedBlock, EmbedBlock
+    from notionary.blocks.equation.equation_models import (
+        CreateEquationBlock,
+        EquationBlock,
+    )
+    from notionary.blocks.file.file_element_models import CreateFileBlock, FileBlock
+    from notionary.blocks.heading.heading_models import (
+        CreateHeading1Block,
+        CreateHeading2Block,
+        CreateHeading3Block,
+        HeadingBlock,
+    )
+    from notionary.blocks.image_block.image_models import CreateImageBlock
+    from notionary.blocks.numbered_list.numbered_list_models import (
+        CreateNumberedListItemBlock,
+        NumberedListItemBlock,
+    )
+    from notionary.blocks.paragraph.paragraph_models import (
+        CreateParagraphBlock,
+        ParagraphBlock,
+    )
+    from notionary.blocks.pdf.pdf_models import CreatePdfBlock
+    from notionary.blocks.quote.quote_models import CreateQuoteBlock, QuoteBlock
+    from notionary.blocks.table.table_models import TableBlock, TableRowBlock
+    from notionary.blocks.table_of_contents.table_of_contents_models import (
+        CreateTableOfContentsBlock,
+        TableOfContentsBlock,
+    )
+    from notionary.blocks.todo.todo_models import CreateToDoBlock, ToDoBlock
+    from notionary.blocks.toggle.toggle_models import CreateToggleBlock, ToggleBlock
+    from notionary.blocks.types import BlockType
+    from notionary.blocks.video.video_element_models import CreateVideoBlock
+
+    # Define the Union types that are needed for model rebuilding
+    BlockCreateRequest = Union[
+        CreateBookmarkBlock,
+        CreateBreadcrumbBlock,
+        CreateBulletedListItemBlock,
+        CreateCalloutBlock,
+        CreateChildPageBlock,
+        CreateCodeBlock,
+        CreateColumnListBlock,
+        CreateColumnBlock,
+        CreateDividerBlock,
+        CreateEmbedBlock,
+        CreateEquationBlock,
+        CreateFileBlock,
+        CreateHeading1Block,
+        CreateHeading2Block,
+        CreateHeading3Block,
+        CreateImageBlock,
+        CreateNumberedListItemBlock,
+        CreateParagraphBlock,
+        CreateQuoteBlock,
+        CreateToDoBlock,
+        CreateToggleBlock,
+        CreateVideoBlock,
+        CreateTableOfContentsBlock,
+        CreatePdfBlock,
+    ]
+
+    BlockCreateResult = Optional[Union[list[BlockCreateRequest], BlockCreateRequest]]
+
+    # Add all block types to namespace
+    ns.update(
+        {
+            "BlockType": BlockType,
+            "BookmarkBlock": BookmarkBlock,
+            "CreateBookmarkBlock": CreateBookmarkBlock,
+            "BreadcrumbBlock": BreadcrumbBlock,
+            "CreateBreadcrumbBlock": CreateBreadcrumbBlock,
+            "BulletedListItemBlock": BulletedListItemBlock,
+            "CreateBulletedListItemBlock": CreateBulletedListItemBlock,
+            "CalloutBlock": CalloutBlock,
+            "CreateCalloutBlock": CreateCalloutBlock,
+            "ChildPageBlock": ChildPageBlock,
+            "CreateChildPageBlock": CreateChildPageBlock,
+            "CodeBlock": CodeBlock,
+            "CreateCodeBlock": CreateCodeBlock,
+            "ColumnBlock": ColumnBlock,
+            "ColumnListBlock": ColumnListBlock,
+            "CreateColumnBlock": CreateColumnBlock,
+            "CreateColumnListBlock": CreateColumnListBlock,
+            "DividerBlock": DividerBlock,
+            "CreateDividerBlock": CreateDividerBlock,
+            "EmbedBlock": EmbedBlock,
+            "CreateEmbedBlock": CreateEmbedBlock,
+            "EquationBlock": EquationBlock,
+            "CreateEquationBlock": CreateEquationBlock,
+            "FileBlock": FileBlock,
+            "CreateFileBlock": CreateFileBlock,
+            "HeadingBlock": HeadingBlock,
+            "CreateHeading1Block": CreateHeading1Block,
+            "CreateHeading2Block": CreateHeading2Block,
+            "CreateHeading3Block": CreateHeading3Block,
+            "CreateImageBlock": CreateImageBlock,
+            "NumberedListItemBlock": NumberedListItemBlock,
+            "CreateNumberedListItemBlock": CreateNumberedListItemBlock,
+            "ParagraphBlock": ParagraphBlock,
+            "CreateParagraphBlock": CreateParagraphBlock,
+            "QuoteBlock": QuoteBlock,
+            "CreateQuoteBlock": CreateQuoteBlock,
+            "TableBlock": TableBlock,
+            "TableRowBlock": TableRowBlock,
+            "ToDoBlock": ToDoBlock,
+            "CreateToDoBlock": CreateToDoBlock,
+            "ToggleBlock": ToggleBlock,
+            "CreateToggleBlock": CreateToggleBlock,
+            "CreateVideoBlock": CreateVideoBlock,
+            "TableOfContentsBlock": TableOfContentsBlock,
+            "CreateTableOfContentsBlock": CreateTableOfContentsBlock,
+            # Add the Union types
+            "BlockCreateRequest": BlockCreateRequest,
+            "BlockCreateResult": BlockCreateResult,
+        }
+    )
+
+    # Now rebuild with complete namespace
+    models.Block.model_rebuild(_types_namespace=ns)
+    models.BlockChildrenResponse.model_rebuild(_types_namespace=ns)
+
+    # Rebuild all individual block models
+    BookmarkBlock.model_rebuild()
+    BreadcrumbBlock.model_rebuild()
+    BulletedListItemBlock.model_rebuild()
+    CalloutBlock.model_rebuild()
+    ChildPageBlock.model_rebuild()
+    CodeBlock.model_rebuild()
+    ColumnBlock.model_rebuild()
+    ColumnListBlock.model_rebuild()
+    DividerBlock.model_rebuild()
+    EmbedBlock.model_rebuild()
+    EquationBlock.model_rebuild()
+    FileBlock.model_rebuild()
+    HeadingBlock.model_rebuild()
+    NumberedListItemBlock.model_rebuild()
+    ParagraphBlock.model_rebuild()
+    QuoteBlock.model_rebuild()
+    TableBlock.model_rebuild()
+    TableRowBlock.model_rebuild()
+    ToDoBlock.model_rebuild()
+    ToggleBlock.model_rebuild()
+    TableOfContentsBlock.model_rebuild()
+
+    # Rebuild create models
+    CreateBookmarkBlock.model_rebuild()
+    CreateBreadcrumbBlock.model_rebuild()
+    CreateBulletedListItemBlock.model_rebuild()
+    CreateCalloutBlock.model_rebuild()
+    CreateChildPageBlock.model_rebuild()
+    CreateCodeBlock.model_rebuild()
+    CreateColumnListBlock.model_rebuild()
+    CreateColumnBlock.model_rebuild()
+    CreateDividerBlock.model_rebuild()
+    CreateEmbedBlock.model_rebuild()
+    CreateEquationBlock.model_rebuild()
+    CreateFileBlock.model_rebuild()
+    CreateHeading1Block.model_rebuild()
+    CreateHeading2Block.model_rebuild()
+    CreateHeading3Block.model_rebuild()
+    CreateImageBlock.model_rebuild()
+    CreateNumberedListItemBlock.model_rebuild()
+    CreateParagraphBlock.model_rebuild()
+    CreateQuoteBlock.model_rebuild()
+    CreateToDoBlock.model_rebuild()
+    CreateToggleBlock.model_rebuild()
+    CreateVideoBlock.model_rebuild()
+    CreateTableOfContentsBlock.model_rebuild()
+
+    _bootstrapped = True

notionary-0.2.21/notionary/blocks/audio/__init__.py

@@ -0,0 +1,13 @@
+from notionary.blocks.audio.audio_element import AudioElement
+from notionary.blocks.audio.audio_markdown_node import (
+    AudioMarkdownBlockParams,
+    AudioMarkdownNode,
+)
+from notionary.blocks.audio.audio_models import CreateAudioBlock
+
+__all__ = [
+    "AudioElement",
+    "CreateAudioBlock",
+    "AudioMarkdownNode",
+    "AudioMarkdownBlockParams",
+]

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

@@ -0,0 +1,90 @@
+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.models import Block, BlockCreateResult, BlockType
+from notionary.blocks.rich_text.rich_text_models import RichTextObject
+from notionary.blocks.rich_text.text_inline_formatter import TextInlineFormatter
+
+
+class AudioElement(BaseBlockElement):
+    """
+    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 text") - Audio with optional caption
+
+    Where:
+    - URL is the required audio file URL
+    - Caption is optional descriptive text (enclosed in quotes)
+    """
+
+    URL_PATTERN = r"(https?://[^\s\"]+)"
+    CAPTION_PATTERN = r'(?:\s+"([^"]+)")?'
+    PATTERN = re.compile(r"^\[audio\]\(" + URL_PATTERN + CAPTION_PATTERN + r"\)$")
+
+    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
+    def markdown_to_notion(cls, text: str) -> BlockCreateResult:
+        """Convert markdown audio embed to Notion audio block (or return None if not matching)."""
+        match = cls.PATTERN.match(text.strip())
+        if not match:
+            return None
+        url = match.group(1)
+
+        if not cls._is_likely_audio_url(url):
+            return None
+        caption_text = match.group(2)
+
+        # Create caption rich text objects
+        caption_objects = []
+        if caption_text:
+            caption_rt = RichTextObject.from_plain_text(caption_text)
+            caption_objects = [caption_rt]
+
+        audio_content = FileBlock(
+            type=FileType.EXTERNAL,
+            external=ExternalFile(url=url),
+            caption=caption_objects,
+        )
+
+        return CreateAudioBlock(audio=audio_content)
+
+    @classmethod
+    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
+
+        # Extract caption
+        captions = audio.caption or []
+        if captions:
+            # use TextInlineFormatter instead of manual extraction
+            caption_text = TextInlineFormatter.extract_text_with_formatting(captions)
+            return f'[audio]({url} "{caption_text}")'
+
+        return f"[audio]({url})"
+
+    @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.18 → notionary-0.2.21}/notionary/blocks/audio/audio_markdown_node.py

@@ -1,8 +1,10 @@
 from __future__ import annotations
+
 from typing import Optional
+
 from pydantic import BaseModel
 
-from notionary.blocks.markdown_node import MarkdownNode
+from notionary.markdown.markdown_node import MarkdownNode
 
 
 class AudioMarkdownBlockParams(BaseModel):

notionary-0.2.21/notionary/blocks/audio/audio_models.py

@@ -0,0 +1,10 @@
+from typing import Literal
+
+from pydantic import BaseModel
+
+from notionary.blocks.file.file_element_models import FileBlock
+
+
+class CreateAudioBlock(BaseModel):
+    type: Literal["audio"] = "audio"
+    audio: FileBlock

notionary-0.2.21/notionary/blocks/base_block_element.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from abc import ABC
+from typing import Optional
+
+from notionary.blocks.models import Block, BlockCreateResult
+
+
+class BaseBlockElement(ABC):
+    """Base class for elements that can be converted between Markdown and Notion."""
+
+    @classmethod
+    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
+    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."""
+        return bool(cls.notion_to_markdown(block))  # Now calls the class's version

notionary-0.2.21/notionary/blocks/bookmark/__init__.py

@@ -0,0 +1,14 @@
+from notionary.blocks.bookmark.bookmark_element import BookmarkElement
+from notionary.blocks.bookmark.bookmark_markdown_node import (
+    BookmarkMarkdownBlockParams,
+    BookmarkMarkdownNode,
+)
+from notionary.blocks.bookmark.bookmark_models import BookmarkBlock, CreateBookmarkBlock
+
+__all__ = [
+    "BookmarkElement",
+    "BookmarkBlock",
+    "CreateBookmarkBlock",
+    "BookmarkMarkdownNode",
+    "BookmarkMarkdownBlockParams",
+]