notionary 0.2.6__py3-none-any.whl → 0.2.8__py3-none-any.whl

notionary/page/content/page_content_writer.py

@@ -37,7 +37,6 @@ class PageContentWriter(LoggingMixin):
     async def append_markdown(self, markdown_text: str, append_divider=False) -> bool:
         """
         Append markdown text to a Notion page, automatically handling content length limits.
-
         """
         if append_divider and not self.block_registry.contains(DividerElement):
             self.logger.warning(
@@ -45,9 +44,11 @@ class PageContentWriter(LoggingMixin):
             )
             append_divider = False
 
-        # Append divider in markdonw format as it will be converted to a Notion divider block
+        # Append divider in markdown format as it will be converted to a Notion divider block
         if append_divider:
-            markdown_text = markdown_text + "\n\n---\n\n"
+            markdown_text = markdown_text + "\n---"
+
+        markdown_text = self._process_markdown_whitespace(markdown_text)
 
         try:
             blocks = self._markdown_to_notion_converter.convert(markdown_text)
@@ -101,3 +102,102 @@ class PageContentWriter(LoggingMixin):
         except Exception as e:
             self.logger.error("Failed to delete block: %s", str(e))
             return False
+
+    def _process_markdown_whitespace(self, markdown_text: str) -> str:
+        """
+        Process markdown text to preserve code structure while removing unnecessary indentation.
+        Strips all leading whitespace from regular lines, but preserves relative indentation
+        within code blocks.
+
+        Args:
+            markdown_text: Original markdown text with potential leading whitespace
+
+        Returns:
+            Processed markdown text with corrected whitespace
+        """
+        lines = markdown_text.split("\n")
+        if not lines:
+            return ""
+
+        processed_lines = []
+        in_code_block = False
+        current_code_block = []
+
+        for line in lines:
+            # Handle code block markers
+            if self._is_code_block_marker(line):
+                if not in_code_block:
+                    # Starting a new code block
+                    in_code_block = True
+                    processed_lines.append(self._process_code_block_start(line))
+                    current_code_block = []
+                    continue
+
+                # Ending a code block
+                processed_lines.extend(
+                    self._process_code_block_content(current_code_block)
+                )
+                processed_lines.append("```")
+                in_code_block = False
+                continue
+
+            # Handle code block content
+            if in_code_block:
+                current_code_block.append(line)
+                continue
+
+            # Handle regular text
+            processed_lines.append(line.lstrip())
+
+        # Handle unclosed code block
+        if in_code_block and current_code_block:
+            processed_lines.extend(self._process_code_block_content(current_code_block))
+            processed_lines.append("```")
+
+        return "\n".join(processed_lines)
+
+    def _is_code_block_marker(self, line: str) -> bool:
+        """Check if a line is a code block marker."""
+        return line.lstrip().startswith("```")
+
+    def _process_code_block_start(self, line: str) -> str:
+        """Extract and normalize the code block opening marker."""
+        language = line.lstrip().replace("```", "", 1).strip()
+        return "```" + language
+
+    def _process_code_block_content(self, code_lines: list) -> list:
+        """
+        Normalize code block indentation by removing the minimum common indentation.
+
+        Args:
+            code_lines: List of code block content lines
+
+        Returns:
+            List of processed code lines with normalized indentation
+        """
+        if not code_lines:
+            return []
+
+        # Find non-empty lines to determine minimum indentation
+        non_empty_code_lines = [line for line in code_lines if line.strip()]
+        if not non_empty_code_lines:
+            return [""] * len(code_lines)  # All empty lines stay empty
+
+        # Calculate minimum indentation
+        min_indent = min(
+            len(line) - len(line.lstrip()) for line in non_empty_code_lines
+        )
+        if min_indent == 0:
+            return code_lines  # No common indentation to remove
+
+        # Process each line
+        processed_code_lines = []
+        for line in code_lines:
+            if not line.strip():
+                processed_code_lines.append("")  # Keep empty lines empty
+                continue
+
+            # Remove exactly the minimum indentation
+            processed_code_lines.append(line[min_indent:])
+
+        return processed_code_lines

notionary/page/markdown_to_notion_converter.py

@@ -1,5 +1,7 @@
 from typing import Dict, Any, List, Optional, Tuple
+import re
 
+from notionary.elements.column_element import ColumnElement
 from notionary.elements.registry.block_registry import BlockRegistry
 from notionary.elements.registry.block_registry_builder import (
     BlockRegistryBuilder,
@@ -9,9 +11,11 @@ from notionary.elements.registry.block_registry_builder import (
 class MarkdownToNotionConverter:
     """Converts Markdown text to Notion API block format with support for pipe syntax for nested structures."""
 
-    SPACER_MARKER = "<!-- spacer -->"
+    SPACER_MARKER = "---spacer---"
     TOGGLE_ELEMENT_TYPES = ["ToggleElement", "ToggleableHeadingElement"]
     PIPE_CONTENT_PATTERN = r"^\|\s?(.*)$"
+    HEADING_PATTERN = r"^(#{1,6})\s+(.+)$"
+    DIVIDER_PATTERN = r"^-{3,}$"
 
     def __init__(self, block_registry: Optional[BlockRegistry] = None):
         """Initialize the converter with an optional custom block registry."""
@@ -19,14 +23,21 @@ class MarkdownToNotionConverter:
             block_registry or BlockRegistryBuilder().create_full_registry()
         )
 
+        if self._block_registry.contains(ColumnElement):
+            ColumnElement.set_converter_callback(self.convert)
+
     def convert(self, markdown_text: str) -> List[Dict[str, Any]]:
         """Convert markdown text to Notion API block format."""
         if not markdown_text:
             return []
 
+        # Preprocess markdown to add spacers before headings and dividers
+        processed_markdown = self._add_spacers_before_elements(markdown_text)
+        print("Processed Markdown:", processed_markdown)
+
         # Collect all blocks with their positions in the text
         all_blocks_with_positions = self._collect_all_blocks_with_positions(
-            markdown_text
+            processed_markdown
         )
 
         # Sort all blocks by their position in the text
@@ -38,6 +49,135 @@ class MarkdownToNotionConverter:
         # Process spacing between blocks
         return self._process_block_spacing(blocks)
 
+    def _add_spacers_before_elements(self, markdown_text: str) -> str:
+        """Add spacer markers before every heading (except the first one) and before every divider,
+        but ignore content inside code blocks and consecutive headings."""
+        lines = markdown_text.split("\n")
+        processed_lines = []
+        found_first_heading = False
+        in_code_block = False
+        last_line_was_spacer = False
+        last_non_empty_was_heading = False
+
+        i = 0
+        while i < len(lines):
+            line = lines[i]
+
+            # Check for code block boundaries and handle accordingly
+            if self._is_code_block_marker(line):
+                in_code_block = not in_code_block
+                processed_lines.append(line)
+                if line.strip():  # If not empty
+                    last_non_empty_was_heading = False
+                last_line_was_spacer = False
+                i += 1
+                continue
+
+            # Skip processing markdown inside code blocks
+            if in_code_block:
+                processed_lines.append(line)
+                if line.strip():  # If not empty
+                    last_non_empty_was_heading = False
+                last_line_was_spacer = False
+                i += 1
+                continue
+
+            # Process line with context about consecutive headings
+            result = self._process_line_for_spacers(
+                line,
+                processed_lines,
+                found_first_heading,
+                last_line_was_spacer,
+                last_non_empty_was_heading,
+            )
+
+            last_line_was_spacer = result["added_spacer"]
+
+            # Update tracking of consecutive headings and first heading
+            if line.strip():  # Not empty line
+                is_heading = re.match(self.HEADING_PATTERN, line) is not None
+                if is_heading:
+                    if not found_first_heading:
+                        found_first_heading = True
+                    last_non_empty_was_heading = True
+                elif line.strip() != self.SPACER_MARKER:  # Not a spacer or heading
+                    last_non_empty_was_heading = False
+
+            i += 1
+
+        return "\n".join(processed_lines)
+
+    def _is_code_block_marker(self, line: str) -> bool:
+        """Check if a line is a code block marker (start or end)."""
+        return line.strip().startswith("```")
+
+    def _process_line_for_spacers(
+        self,
+        line: str,
+        processed_lines: List[str],
+        found_first_heading: bool,
+        last_line_was_spacer: bool,
+        last_non_empty_was_heading: bool,
+    ) -> Dict[str, bool]:
+        """
+        Process a single line to add spacers before headings and dividers if needed.
+
+        Args:
+            line: The line to process
+            processed_lines: List of already processed lines to append to
+            found_first_heading: Whether the first heading has been found
+            last_line_was_spacer: Whether the last added line was a spacer
+            last_non_empty_was_heading: Whether the last non-empty line was a heading
+
+        Returns:
+            Dictionary with processing results
+        """
+        added_spacer = False
+        line_stripped = line.strip()
+        is_empty = not line_stripped
+
+        # Skip empty lines
+        if is_empty:
+            processed_lines.append(line)
+            return {"added_spacer": False}
+
+        # Check if line is a heading
+        if re.match(self.HEADING_PATTERN, line):
+            if (
+                found_first_heading
+                and not last_line_was_spacer
+                and not last_non_empty_was_heading
+            ):
+                # Add spacer only if:
+                # 1. Not the first heading
+                # 2. Last non-empty line was not a heading
+                # 3. Last line was not already a spacer
+                processed_lines.append(self.SPACER_MARKER)
+                added_spacer = True
+
+            processed_lines.append(line)
+
+        # Check if line is a divider
+        elif re.match(self.DIVIDER_PATTERN, line):
+            if not last_line_was_spacer:
+                # Only add a single spacer line before dividers (no extra line breaks)
+                processed_lines.append(self.SPACER_MARKER)
+                added_spacer = True
+
+            processed_lines.append(line)
+
+        # Check if this line itself is a spacer
+        elif line_stripped == self.SPACER_MARKER:
+            # Never add consecutive spacers
+            if not last_line_was_spacer:
+                processed_lines.append(line)
+                added_spacer = True
+
+        else:
+            processed_lines.append(line)
+
+        return {"added_spacer": added_spacer}
+
     def _collect_all_blocks_with_positions(
         self, markdown_text: str
     ) -> List[Tuple[int, int, Dict[str, Any]]]:
@@ -75,13 +215,10 @@ class MarkdownToNotionConverter:
         if not toggleable_elements:
             return []
 
-        # Process each toggleable element type
         for element in toggleable_elements:
-            if hasattr(element, "find_matches"):
-                # Find matches with context awareness
-                matches = element.find_matches(text, self.convert, context_aware=True)
-                if matches:
-                    toggleable_blocks.extend(matches)
+            matches = element.find_matches(text, self.convert, context_aware=True)
+            if matches:
+                toggleable_blocks.extend(matches)
 
         return toggleable_blocks
 
@@ -112,9 +249,6 @@ class MarkdownToNotionConverter:
 
         multiline_blocks = []
         for element in multiline_elements:
-            if not hasattr(element, "find_matches"):
-                continue
-
             matches = element.find_matches(text)
 
             if not matches:
@@ -202,8 +336,6 @@ class MarkdownToNotionConverter:
 
     def _is_pipe_syntax_line(self, line: str) -> bool:
         """Check if a line uses pipe syntax (for nested content)."""
-        import re
-
         return bool(re.match(self.PIPE_CONTENT_PATTERN, line))
 
     def _process_line(

notionary/prompting/markdown_syntax_prompt_generator.py

@@ -1,6 +1,6 @@
-from textwrap import dedent
 from typing import Type, List
 from notionary.elements.notion_block_element import NotionBlockElement
+from notionary.elements.text_inline_formatter import TextInlineFormatter
 
 
 class MarkdownSyntaxPromptGenerator:
@@ -11,10 +11,8 @@ class MarkdownSyntaxPromptGenerator:
     and formats them optimally for LLMs.
     """
 
-    SYSTEM_PROMPT_TEMPLATE = dedent(
-        """
-    You are a knowledgeable assistant that helps users create content for Notion pages.
-    Notion supports standard Markdown with some special extensions for creating rich content.
+    SYSTEM_PROMPT_TEMPLATE = """
+    You create content for Notion pages using Markdown syntax with special Notion extensions.
 
     # Understanding Notion Blocks
 
@@ -27,30 +25,36 @@ class MarkdownSyntaxPromptGenerator:
 
     1. Do NOT start content with a level 1 heading (# Heading). In Notion, the page title is already displayed in the metadata, so starting with an H1 heading is redundant. Begin with H2 (## Heading) or lower for section headings.
 
-    2. INLINE FORMATTING - VERY IMPORTANT:
-    ✅ You can use inline formatting within almost any block type.
-    ✅ Combine **bold**, _italic_, `code`, and other formatting as needed.
-    ✅ Format text to create visual hierarchy and emphasize important points.
-    ❌ DO NOT overuse formatting - be strategic with formatting for best readability.
-
-    3. BACKTICK HANDLING - EXTREMELY IMPORTANT:
-    ❌ NEVER wrap entire content or responses in triple backticks (```).
-    ❌ DO NOT use triple backticks (```) for anything except CODE BLOCKS or DIAGRAMS.
-    ❌ DO NOT use triple backticks to mark or highlight regular text or examples.
-    ✅ USE triple backticks ONLY for actual programming code, pseudocode, or specialized notation.
-    ✅ For inline code, use single backticks (`code`).
-    ✅ When showing Markdown syntax examples, use inline code formatting with single backticks.
-
-    4. BLOCK SEPARATION - IMPORTANT:
-    ✅ Use empty lines between different blocks to ensure proper rendering in Notion.
-    ✅ For major logical sections, use the spacer element (see documentation below).
-    ⚠️ While headings can sometimes work without an empty line before the following paragraph, including empty lines between all block types ensures consistent rendering.
-
-    5. CONTENT FORMATTING - CRITICAL:
-    ❌ DO NOT include introductory phrases like "I understand that..." or "Here's the content...".
-    ✅ Provide ONLY the requested content directly without any prefacing text or meta-commentary.
-    ✅ Generate just the content itself, formatted according to these guidelines."""
-    )
+    2. BACKTICK HANDLING - EXTREMELY IMPORTANT:
+    - NEVER wrap entire content or responses in triple backticks (```).
+    - DO NOT use triple backticks (```) for anything except CODE BLOCKS or DIAGRAMS.
+    - DO NOT use triple backticks to mark or highlight regular text or examples.
+    - USE triple backticks ONLY for actual programming code, pseudocode, or specialized notation.
+    - For inline code, use single backticks (`code`).
+    - When showing Markdown syntax examples, use inline code formatting with single backticks.
+
+    3. CONTENT FORMATTING - CRITICAL:
+    - DO NOT include introductory phrases like "I understand that..." or "Here's the content...".
+    - Provide ONLY the requested content directly without any prefacing text or meta-commentary.
+    - Generate just the content itself, formatted according to these guidelines.
+    - USE INLINE FORMATTING to enhance readability:
+        - Use *italic* for emphasis, terminology, and definitions
+        - Use `code` for technical terms, file paths, variables, and commands
+        - Use **bold** sparingly for truly important information
+        - Use appropriate inline formatting naturally throughout the content, but don't overuse it
+
+    4. USER INSTRUCTIONS - VERY IMPORTANT:
+    - Follow the user's formatting instructions EXACTLY and in the specified order
+    - When the user requests specific elements (e.g., "first a callout, then 4 bullet points"), create them in that precise sequence
+    - Adhere strictly to any structural requirements provided by the user
+    - Do not deviate from or reinterpret the user's formatting requests
+
+   5. ADD EMOJIS TO HEADINGS - REQUIRED UNLESS EXPLICITLY TOLD NOT TO:
+   - ALWAYS add appropriate emojis at the beginning of headings to improve structure and readability
+   - Choose emojis that represent the content or theme of each section
+   - Format as: ## 🚀 Heading Text (with space after emoji)
+   - Only omit emojis if the user explicitly instructs you not to use them
+    """
 
     @staticmethod
     def generate_element_doc(element_class: Type[NotionBlockElement]) -> str:

notionary-0.2.8.dist-info/METADATA

@@ -0,0 +1,271 @@
+Metadata-Version: 2.4
+Name: notionary
+Version: 0.2.8
+Summary: A toolkit to convert between Markdown and Notion blocks
+Home-page: https://github.com/mathisarends/notionary
+Author: Mathis Arends
+Author-email: mathisarends27@gmail.com
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.28.0
+Requires-Dist: python-dotenv>=1.1.0
+Requires-Dist: pydantic>=2.11.4
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# Notionary 📝
+
+[![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)
+
+**Notionary** is a powerful Python library for interacting with the Notion API, making it easy to create, update, and manage Notion pages and databases programmatically with a clean, intuitive interface. It's specifically designed to be the foundation for AI-driven Notion content generation.
+
+---
+
+## Features
+
+- **Rich Markdown Support**: Create Notion pages using intuitive Markdown syntax with custom extensions
+- **Dynamic Database Operations**: Create, update, and query database entries with schema auto-detection
+- **Extensible Block Registry**: Add, customize, or remove Notion block elements with a flexible registry pattern
+- **LLM-Ready Prompts**: Generate system prompts explaining Markdown syntax for LLMs to create Notion content
+- **Async-First Design**: Built for modern Python with full async/await support
+- **Schema-Based Validation**: Automatic property validation based on database schemas
+- **Intelligent Content Conversion**: Bidirectional conversion between Markdown and Notion blocks
+
+---
+
+## Installation
+
+```bash
+pip install notionary
+```
+
+---
+
+## Quick Start
+
+### Creating and Managing Pages
+
+```python
+import asyncio
+from notionary import NotionPage
+
+async def main():
+    # Create a page from URL
+    page = NotionPage.from_url("https://www.notion.so/your-page-url")
+
+    # Or find by name
+    page = await NotionPage.from_page_name("My Project Page")
+
+    # Update page metadata
+    await page.set_title("Updated Title")
+    await page.set_emoji_icon("🚀")
+    await page.set_random_gradient_cover()
+
+    # Add markdown content
+    markdown = """
+    # Project Overview
+
+    !> [💡] This page was created programmatically using Notionary.
+
+    ## Features
+    - **Rich** Markdown support
+    - Async functionality
+    - Custom syntax extensions
+
+    +++ Implementation Details
+    | Notionary uses a custom converter to transform Markdown into Notion blocks.
+    | This makes it easy to create rich content programmatically.
+    """
+
+    await page.replace_content(markdown)
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+### Working with Databases
+
+```python
+import asyncio
+from notionary import NotionDatabase, DatabaseDiscovery
+
+async def main():
+    # Discover available databases
+    discovery = DatabaseDiscovery()
+    await discovery()
+
+    # Connect to a database by name
+    db = await NotionDatabase.from_database_name("Projects")
+
+    # Create a new page in the database
+    page = await db.create_blank_page()
+
+    # Set properties
+    await page.set_property_value_by_name("Status", "In Progress")
+    await page.set_property_value_by_name("Priority", "High")
+
+    # Query pages from database
+    async for page in db.iter_pages():
+        title = await page.get_title()
+        print(f"Page: {title}")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## Custom Markdown Syntax
+
+Notionary extends standard Markdown with special syntax to support Notion-specific features:
+
+### Text Formatting
+
+- Standard: `**bold**`, `*italic*`, `~~strikethrough~~`, `` `code` ``
+- Links: `[text](url)`
+- Quotes: `> This is a quote`
+- Divider: `---`
+
+### Callouts
+
+```markdown
+!> [💡] This is a default callout with the light bulb emoji  
+!> [🔔] This is a notification with a bell emoji  
+!> [⚠️] Warning: This is an important note
+```
+
+### Toggles
+
+```markdown
++++ How to use Notionary
+| 1. Initialize with NotionPage  
+| 2. Update metadata with set_title(), set_emoji_icon(), etc.  
+| 3. Add content with replace_content() or append_markdown()
+```
+
+### Multi-Column Layout
+
+```markdown
+::: columns
+::: column
+
+## Left Column
+
+- Item 1
+- Item 2
+- Item 3
+  :::
+  ::: column
+
+## Right Column
+
+This text appears in the second column. Multi-column layouts are perfect for:
+
+- Comparing features
+- Creating side-by-side content
+- Improving readability of wide content
+  :::
+  :::
+```
+
+### Code Blocks
+
+```python
+def hello_world():
+    print("Hello from Notionary!")
+```
+
+### To-do Lists
+
+```markdown
+- [ ] Define project scope
+- [x] Create timeline
+- [ ] Assign resources
+```
+
+### Tables
+
+```markdown
+| Feature         | Status      | Priority |
+| --------------- | ----------- | -------- |
+| API Integration | Complete    | High     |
+| Documentation   | In Progress | Medium   |
+```
+
+### More Elements
+
+```markdown
+![Caption](https://example.com/image.jpg)  
+@[Caption](https://youtube.com/watch?v=...)  
+[bookmark](https://example.com "Title" "Description")
+```
+
+## Block Registry & Customization
+
+```python
+from notionary import NotionPage, BlockRegistryBuilder
+
+# Create a custom registry with only the elements you need
+custom_registry = (
+    BlockRegistryBuilder()
+    .with_headings()
+    .with_callouts()
+    .with_toggles()
+    .with_columns()  # Include multi-column support
+    .with_code()
+    .with_todos()
+    .with_paragraphs()
+    .build()
+)
+
+# Apply this registry to a page
+page = NotionPage.from_url("https://www.notion.so/your-page-url")
+page.block_registry = custom_registry
+
+# Replace content using only supported elements
+await page.replace_content("# Custom heading with selected elements only")
+```
+
+## AI-Ready: Generate LLM Prompts
+
+```python
+from notionary import BlockRegistryBuilder
+
+# Create a registry with all standard elements
+registry = BlockRegistryBuilder.create_full_registry()
+
+# Generate the LLM system prompt
+llm_system_prompt = registry.get_notion_markdown_syntax_prompt()
+print(llm_system_prompt)
+```
+
+## Examples
+
+See the `examples/` folder for:
+
+- [Database discovery and querying](examples/database_discovery_example.py)
+- [Rich page creation with Markdown](examples/page_example.py)
+- [Database management](examples/database_management_example.py)
+- [Iterating through database entries](examples/database_iteration_example.py)
+- [Temporary usage & debugging](examples/temp.py)
+
+## Perfect for AI Agents and Automation
+
+- **LLM Integration**: Generate Notion-compatible content with any LLM using the system prompt generator
+- **Dynamic Content Generation**: AI agents can generate content in Markdown and render it directly as Notion pages
+- **Schema-Aware Operations**: Automatically validate and format properties based on database schemas
+- **Simplified API**: Clean, intuitive interface for both human developers and AI systems
+
+## Contributing
+
+Contributions welcome — feel free to submit a pull request!