notionary 0.2.23__py3-none-any.whl → 0.2.25__py3-none-any.whl

notionary/page/writer/handler/toggleable_heading_handler.py

@@ -19,8 +19,9 @@ class ToggleableHeadingHandler(LineHandler):
 
     def __init__(self):
         super().__init__()
+        # Updated: Support both "+++# title" and "+++#title"
         self._start_pattern = re.compile(
-            r"^[+]{3}(?P<level>#{1,3})\s+(.+)$", re.IGNORECASE
+            r"^[+]{3}\s*(?P<level>#{1,3})\s*(.+)$", re.IGNORECASE
         )
         # +++
         self._end_pattern = re.compile(r"^[+]{3}\s*$")
@@ -49,7 +50,7 @@ class ToggleableHeadingHandler(LineHandler):
             return await _handle(self._add_toggleable_heading_content)
 
     def _is_toggleable_heading_start(self, context: LineProcessingContext) -> bool:
-        """Check if line starts a toggleable heading (+++# "Title")."""
+        """Check if line starts a toggleable heading (+++# "Title" or +++#"Title")."""
         return self._start_pattern.match(context.line.strip()) is not None
 
     def _is_toggleable_heading_end(self, context: LineProcessingContext) -> bool:

notionary/page/writer/markdown_to_notion_converter.py

@@ -12,54 +12,32 @@ from notionary.page.writer.handler import (
     ToggleableHeadingHandler,
     ToggleHandler,
 )
-from notionary.page.writer.markdown_to_notion_formatting_post_processor import (
-    MarkdownToNotionFormattingPostProcessor,
-)
 from notionary.page.writer.notion_text_length_processor import (
     NotionTextLengthProcessor,
 )
+from notionary.util.logging_mixin import LoggingMixin
+
+
+class HandlerOrderValidationError(RuntimeError):
+    """Raised when handler chain order is incorrect."""
 
+    pass
 
-class MarkdownToNotionConverter:
+
+class MarkdownToNotionConverter(LoggingMixin):
     """Converts Markdown text to Notion API block format with unified stack-based processing."""
 
     def __init__(self, block_registry: BlockRegistry) -> None:
         self._block_registry = block_registry
-        self._formatting_post_processor = MarkdownToNotionFormattingPostProcessor()
         self._text_length_post_processor = NotionTextLengthProcessor()
-
         self._setup_handler_chain()
 
-    def _setup_handler_chain(self) -> None:
-        code_handler = CodeHandler()
-        equation_handler = EquationHandler()
-        table_handler = TableHandler()
-        column_list_handler = ColumnListHandler()
-        column_handler = ColumnHandler()
-        toggle_handler = ToggleHandler()
-        toggleable_heading_handler = ToggleableHeadingHandler()
-        regular_handler = RegularLineHandler()
-
-        # register more specific elements first
-        code_handler.set_next(equation_handler).set_next(table_handler).set_next(
-            column_list_handler
-        ).set_next(column_handler).set_next(toggleable_heading_handler).set_next(
-            toggle_handler
-        ).set_next(
-            regular_handler
-        )
-
-        self._handler_chain = code_handler
-
     async def convert(self, markdown_text: str) -> list[BlockCreateRequest]:
         if not markdown_text.strip():
             return []
 
         all_blocks = await self.process_lines(markdown_text)
 
-        # Apply formatting post-processing (empty paragraphs)
-        all_blocks = self._formatting_post_processor.process(all_blocks)
-
         # Apply text length post-processing (truncation)
         all_blocks = self._text_length_post_processor.process(all_blocks)
 
@@ -93,3 +71,69 @@ class MarkdownToNotionConverter:
                 continue
 
         return result_blocks
+
+    def _setup_handler_chain(self) -> None:
+        code_handler = CodeHandler()
+        equation_handler = EquationHandler()
+        table_handler = TableHandler()
+        column_list_handler = ColumnListHandler()
+        column_handler = ColumnHandler()
+        toggle_handler = ToggleHandler()
+        toggleable_heading_handler = ToggleableHeadingHandler()
+        regular_handler = RegularLineHandler()
+
+        # Create handler chain
+        code_handler.set_next(equation_handler).set_next(table_handler).set_next(
+            column_handler
+        ).set_next(column_list_handler).set_next(toggleable_heading_handler).set_next(
+            toggle_handler
+        ).set_next(
+            regular_handler
+        )
+
+        self._handler_chain = code_handler
+
+        # Validate critical order - only log/error if something is wrong
+        self._validate_handler_order(
+            [
+                code_handler,
+                equation_handler,
+                table_handler,
+                column_handler,
+                column_list_handler,
+                toggleable_heading_handler,
+                toggle_handler,
+                regular_handler,
+            ]
+        )
+
+    def _validate_handler_order(self, handlers) -> None:
+        """Validate critical handler positioning rules - only warns/errors when needed."""
+        handler_classes = [handler.__class__ for handler in handlers]
+
+        # Critical: ColumnHandler MUST come before ColumnListHandler
+        try:
+            column_handler_pos = handler_classes.index(ColumnHandler)
+            column_list_handler_pos = handler_classes.index(ColumnListHandler)
+
+            if column_handler_pos >= column_list_handler_pos:
+                error_msg = (
+                    f"CRITICAL: ColumnHandler must come BEFORE ColumnListHandler. "
+                    f"Current order: ColumnHandler at {column_handler_pos}, ColumnListHandler at {column_list_handler_pos}. "
+                    f"Fix: Move ColumnHandler before ColumnListHandler in _setup_handler_chain()"
+                )
+                self.logger.error(error_msg)
+                raise HandlerOrderValidationError(error_msg)
+
+        except ValueError as e:
+            error_msg = f"Missing required handlers in chain: {e}"
+            self.logger.error(error_msg)
+            raise HandlerOrderValidationError(error_msg)
+
+        # Critical: RegularLineHandler should be last (fallback)
+        if handler_classes[-1] != RegularLineHandler:
+            error_msg = (
+                f"WARNING: RegularLineHandler should be last handler (fallback), "
+                f"but {handler_classes[-1].__name__} is at the end"
+            )
+            self.logger.warning(error_msg)

notionary/schemas/__init__.py

@@ -0,0 +1,3 @@
+from .base import NotionContentSchema
+
+__all__ = ["NotionContentSchema"]

notionary/schemas/base.py

@@ -0,0 +1,73 @@
+"""
+NotionContentSchema Base Class
+=============================
+
+Base class for all Notion structured output schemas with injected MarkdownBuilder
+"""
+
+from pydantic import BaseModel
+from notionary.blocks.markdown.markdown_builder import MarkdownBuilder
+
+
+class NotionContentSchema(BaseModel):
+    """
+    Base class for all Notion content schemas.
+
+    Inherit from this and implement to_notion_content() to create
+    schemas that work with LLM structured output.
+
+    Example usage:
+
+        class BlogPost(NotionContentSchema):
+            title: str = Field(description="Catchy blog post title")
+            introduction: str = Field(description="Engaging opening paragraph")
+            main_points: List[str] = Field(description="3-5 key takeaways")
+            conclusion: str = Field(description="Summary and call-to-action")
+
+            def to_notion_content(self, builder: MarkdownBuilder) -> str:
+                return (builder
+                    .h1(self.title)
+                    .paragraph(self.introduction)
+                    .h2("Key Points")
+                    .bulleted_list(self.main_points)
+                    .h2("Conclusion")
+                    .paragraph(self.conclusion)
+                    .build()
+                )
+
+        # Usage with LLM:
+        llm = ChatOpenAI(model="gpt-4o")
+        structured_llm = llm.with_structured_output(BlogPost)
+        blog = structured_llm.invoke("Write about Python async/await")
+
+        # Upload to Notion:
+        await blog.append_to_page("My Blog")
+    """
+
+    def to_notion_content(self, builder: MarkdownBuilder) -> str:
+        """
+        Build Notion content using the provided MarkdownBuilder.
+
+        Args:
+            builder: Empty MarkdownBuilder instance to build content with
+
+        Returns:
+            str: The final markdown string (user should call build() on the builder)
+        """
+        raise NotImplementedError("Subclasses must implement to_notion_content()")
+
+    async def append_to_page(self, page_name: str):
+        """
+        Upload this content directly to a Notion page.
+
+        Args:
+            page_name: Name of the target Notion page
+        """
+        from notionary import NotionPage
+
+        # Create fresh builder and let subclass build content
+        builder = MarkdownBuilder()
+        markdown = self.to_notion_content(builder)
+
+        page = await NotionPage.from_page_name(page_name)
+        await page.append_markdown(markdown)

notionary/shared/__init__.py

@@ -1,5 +1,3 @@
 from .name_to_id_resolver import NameIdResolver
 
-__all__ = [
-    "NameIdResolver"
-]
+__all__ = ["NameIdResolver"]

notionary-0.2.25.dist-info/METADATA

@@ -0,0 +1,270 @@
+Metadata-Version: 2.3
+Name: notionary
+Version: 0.2.25
+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: aiofiles (>=24.1.0,<25.0.0)
+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">The Modern Notion API for Python & AI Agents</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.**  
+Perfect for developers building AI agents, automation workflows, and dynamic content systems.
+
+</div>
+
+---
+
+## Why Notionary?
+
+- **AI-Native Design** - Built specifically for AI agents with schema-driven markdown syntax
+- **Smart Discovery** - Find pages and databases by name with fuzzy matching—no more hunting for IDs
+- **Extended Markdown** - Rich syntax for toggles, columns, callouts, and media uploads
+- **Async-First** - Modern Python with full async/await support and high performance
+- **Round-Trip** - Read existing content, modify it, and write it back while preserving formatting
+- **Complete Coverage** - Every Notion block type supported with type safety
+
+---
+
+## Installation
+
+```bash
+pip install notionary
+```
+
+Set up your [Notion integration](https://www.notion.so/profile/integrations) and configure your token:
+
+```bash
+export NOTION_SECRET=your_integration_key
+```
+
+---
+
+## See It in Action
+
+### Creating Rich Database Entries
+
+https://github.com/user-attachments/assets/da8b4691-bee4-4b0f-801e-dccacb630398
+
+*Create styled project pages with properties, content, and rich formatting*
+
+### Local File Uploads (Videos & Images)
+
+https://github.com/user-attachments/assets/a079ec01-bb56-4c65-8260-7b1fca42ac68
+
+*Upload videos and images using simple markdown syntax - files are automatically uploaded to Notion*
+
+---
+
+## Quick Start
+
+### Find → Create → Update Flow
+
+```python
+import asyncio
+from notionary import NotionPage, NotionDatabase
+
+async def main():
+    # Find pages by name - fuzzy matching included!
+    page = await NotionPage.from_page_name("Meeting Notes")
+    
+    # Option 1: Direct Extended Markdown
+    await page.append_markdown("""
+    ## Action Items
+    - [x] Review project proposal
+    - [ ] Schedule team meeting  
+    - [ ] Update documentation
+
+    [callout](Meeting decisions require follow-up "💡")
+    
+    +++ Details
+    Additional context and next steps...
+    +++
+    """)
+    
+    # Option 2: Type-Safe Builder (maps to same markdown internally)
+    await page.append_markdown(lambda builder: (
+        builder
+        .h2("Project Status") 
+        .callout("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"  
+            ]),
+            width_ratios=[0.6, 0.4]
+        )
+        .toggle("Budget Details", lambda t: t
+            .table(["Item", "Cost", "Status"], [
+                ["Development", "$15,000", "Paid"],
+                ["Design", "$8,000", "Pending"]
+            ])
+        )
+    ))
+
+asyncio.run(main())
+```
+
+### Complete Block Support
+
+Every Notion block type with extended syntax:
+
+| Block Type | Markdown Syntax | Use Case |
+|------------|-----------------|----------|
+| **Callouts** | `[callout](Text "🔥")` | Highlighting key information |
+| **Toggles** | `+++ Title\nContent\n+++` | Collapsible sections |
+| **Columns** | `::: columns\n::: column\nContent\n:::\n:::` | Side-by-side layouts |
+| **Tables** | Standard markdown tables | Structured data |
+| **Media** | `[video](./file.mp4)(caption:Description)` | Auto-uploading files |
+| **Code** | Standard code fences with captions | Code snippets |
+| **Equations** | `$LaTeX$` | Mathematical expressions |
+| **TOC** | `[toc](blue_background)` | Auto-generated navigation |
+
+---
+
+## What You Can Build 💡
+
+### **AI Content Systems**
+- **Report Generation**: AI agents that create structured reports, documentation, and analysis
+- **Content Pipelines**: Automated workflows that process data and generate Notion pages
+- **Knowledge Management**: AI-powered documentation systems with smart categorization
+
+### **Workflow Automation**  
+- **Project Management**: Sync project status, update timelines, generate progress reports
+- **Data Integration**: Connect external APIs and databases to Notion workspaces
+- **Template Systems**: Dynamic page generation from templates and data sources
+
+### **Content Management**
+- **Bulk Operations**: Mass page updates, content migration, and database management  
+- **Media Handling**: Automated image/video uploads with proper organization
+- **Cross-Platform**: Sync content between Notion and other platforms
+
+---
+
+## Key Features
+
+<table>
+<tr>
+<td width="50%">
+
+### Smart Discovery
+- Find pages/databases by name
+- Fuzzy matching for approximate searches  
+- No more hunting for IDs or URLs
+
+### Extended Markdown
+- Rich syntax beyond standard markdown
+- Callouts, toggles, columns, media uploads
+- Schema provided for AI agent integration
+
+### Modern Python 
+- Full async/await support
+- Type hints throughout  
+- High-performance batch operations
+
+</td>
+<td width="50%">
+
+### Round-Trip Editing
+- Read existing content as markdown
+- Edit and modify preserving formatting
+- Write back to Notion seamlessly
+
+### AI-Ready Architecture
+- Schema-driven syntax for LLM prompts
+- Perfect for AI content generation
+- Handles complex nested structures
+
+### Complete Coverage
+- Every Notion block type supported
+- File uploads with automatic handling
+- Database operations and properties
+
+</td>
+</tr>
+</table>
+
+---
+
+## Examples & Documentation
+
+### Full Documentation
+[**mathisarends.github.io/notionary**](https://mathisarends.github.io/notionary/) - Complete API reference, guides, and tutorials
+
+### Quick Links
+- [**Getting Started**](https://mathisarends.github.io/notionary/get-started/) - Setup and first steps
+- [**Page Management**](https://mathisarends.github.io/notionary/page/) - Content and properties  
+- [**Database Operations**](https://mathisarends.github.io/notionary/database/) - Queries and management
+- [**Block Types Reference**](https://mathisarends.github.io/notionary/blocks/) - Complete syntax guide
+
+### Hands-On Examples
+
+**Core Functionality:**
+- [Page Management](examples/page_example.py) - Create, update, and manage pages
+- [Database Operations](examples/database.py) - Connect and query databases  
+- [Workspace Discovery](examples/workspace_discovery.py) - Explore your workspace
+
+**Extended Markdown:**
+- [Basic Formatting](examples/markdown/basic.py) - Text, lists, and links
+- [Callouts & Highlights](examples/markdown/callout.py) - Information boxes  
+- [Toggle Sections](examples/markdown/toggle.py) - Collapsible content
+- [Multi-Column Layouts](examples/markdown/columns.py) - Side-by-side design
+- [Tables & Data](examples/markdown/table.py) - Structured presentations
+
+---
+
+## Contributing
+
+We welcome contributions from the community! Whether you're:
+- **Fixing bugs** - Help improve stability and reliability
+- **Adding features** - Extend functionality for new use cases  
+- **Improving docs** - Make the library more accessible
+- **Sharing examples** - Show creative applications and patterns
+
+Check our [**Contributing Guide**](https://mathisarends.github.io/notionary/contributing/) to get started.
+
+---
+
+<div align="center">
+
+**Ready to revolutionize your Notion workflows?**
+
+[📖 **Read the Docs**](https://mathisarends.github.io/notionary/) • [🚀 **Getting Started**](https://mathisarends.github.io/notionary/get-started/) • [💻 **Browse Examples**](examples/)
+
+*Built with ❤️ for Python developers and AI agents*
+
+---
+
+**Transform complex Notion API interactions into simple, powerful code.**
+
+</div>
+