notionary 0.2.6__tar.gz → 0.2.7__tar.gz

notionary-0.2.7/PKG-INFO

@@ -0,0 +1,245 @@
+Metadata-Version: 2.4
+Name: notionary
+Version: 0.2.7
+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()
+```
+
+### 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_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
+ark
+# 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!

notionary-0.2.7/README.md

@@ -0,0 +1,219 @@
+# 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()
+```
+
+### 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_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
+ark
+# 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!

{notionary-0.2.6 → notionary-0.2.7}/notionary/database/database_discovery.py

@@ -26,29 +26,7 @@ class DatabaseDiscovery(LoggingMixin):
         self._client = client if client else NotionClient()
         self.logger.info("DatabaseDiscovery initialized")
 
-    async def discover(self, page_size: int = 100) -> List[Tuple[str, str]]:
-        """
-        Discover all accessible databases and return their titles and IDs.
-
-        Args:
-            page_size: The number of databases to fetch per request
-
-        Returns:
-            List of tuples containing (database_title, database_id)
-        """
-        databases = []
-
-        async for database in self._iter_databases(page_size):
-            db_id = database.get("id")
-            if not db_id:
-                continue
-
-            title = self._extract_database_title(database)
-            databases.append((title, db_id))
-
-        return databases
-
-    async def discover_and_print(self, page_size: int = 100) -> List[Tuple[str, str]]:
+    async def __call__(self, page_size: int = 100) -> List[Tuple[str, str]]:
         """
         Discover databases and print the results in a nicely formatted way.
 
@@ -61,7 +39,7 @@ class DatabaseDiscovery(LoggingMixin):
         Returns:
             The same list of databases as discover() for further processing
         """
-        databases = await self.discover(page_size)
+        databases = await self._discover(page_size)
 
         if not databases:
             print("\n⚠️ No databases found!")
@@ -78,6 +56,28 @@ class DatabaseDiscovery(LoggingMixin):
 
         return databases
 
+    async def _discover(self, page_size: int = 100) -> List[Tuple[str, str]]:
+        """
+        Discover all accessible databases and return their titles and IDs.
+
+        Args:
+            page_size: The number of databases to fetch per request
+
+        Returns:
+            List of tuples containing (database_title, database_id)
+        """
+        databases = []
+
+        async for database in self._iter_databases(page_size):
+            db_id = database.get("id")
+            if not db_id:
+                continue
+
+            title = self._extract_database_title(database)
+            databases.append((title, db_id))
+
+        return databases
+
     async def _iter_databases(
         self, page_size: int = 100
     ) -> AsyncGenerator[Dict[str, Any], None]:

{notionary-0.2.6 → notionary-0.2.7}/notionary/elements/code_block_element.py

@@ -15,13 +15,17 @@ class CodeBlockElement(NotionBlockElement):
     ```language
     code content
     ```
+    Caption: optional caption text
 
     Where:
     - language is optional and specifies the programming language
     - code content is the code to be displayed
+    - Caption line is optional and must appear immediately after the closing ```
     """
 
-    PATTERN = re.compile(r"```(\w*)\n([\s\S]+?)```", re.MULTILINE)
+    PATTERN = re.compile(
+        r"```(\w*)\n([\s\S]+?)```(?:\n(?:Caption|caption):\s*(.+))?", re.MULTILINE
+    )
 
     @classmethod
     def match_markdown(cls, text: str) -> bool:
@@ -42,25 +46,18 @@ class CodeBlockElement(NotionBlockElement):
 
         language = match.group(1) or "plain text"
         content = match.group(2)
+        caption = match.group(3)
 
         if content.endswith("\n"):
             content = content[:-1]
 
-        return {
+        block = {
             "type": "code",
             "code": {
                 "rich_text": [
                     {
                         "type": "text",
                         "text": {"content": content},
-                        "annotations": {
-                            "bold": False,
-                            "italic": False,
-                            "strikethrough": False,
-                            "underline": False,
-                            "code": False,
-                            "color": "default",
-                        },
                         "plain_text": content,
                     }
                 ],
@@ -68,6 +65,18 @@ class CodeBlockElement(NotionBlockElement):
             },
         }
 
+        # Add caption if provided
+        if caption and caption.strip():
+            block["code"]["caption"] = [
+                {
+                    "type": "text",
+                    "text": {"content": caption.strip()},
+                    "plain_text": caption.strip(),
+                }
+            ]
+
+        return block
+
     @classmethod
     def notion_to_markdown(cls, block: Dict[str, Any]) -> Optional[str]:
         """Convert Notion code block to markdown code block."""
@@ -84,8 +93,20 @@ class CodeBlockElement(NotionBlockElement):
 
         language = code_data.get("language", "")
 
+        # Extract caption if present
+        caption_text = ""
+        caption_data = code_data.get("caption", [])
+        for caption_block in caption_data:
+            caption_text += caption_block.get("plain_text", "")
+
         # Format as a markdown code block
-        return f"```{language}\n{content}\n```"
+        result = f"```{language}\n{content}\n```"
+
+        # Add caption if present
+        if caption_text.strip():
+            result += f"\nCaption: {caption_text}"
+
+        return result
 
     @classmethod
     def find_matches(cls, text: str) -> List[Tuple[int, int, Dict[str, Any]]]:
@@ -102,6 +123,7 @@ class CodeBlockElement(NotionBlockElement):
         for match in CodeBlockElement.PATTERN.finditer(text):
             language = match.group(1) or "plain text"
             content = match.group(2)
+            caption = match.group(3)
 
             # Remove trailing newline if present
             if content.endswith("\n"):
@@ -121,6 +143,16 @@ class CodeBlockElement(NotionBlockElement):
                 },
             }
 
+            # Add caption if provided
+            if caption and caption.strip():
+                block["code"]["caption"] = [
+                    {
+                        "type": "text",
+                        "text": {"content": caption.strip()},
+                        "plain_text": caption.strip(),
+                    }
+                ]
+
             matches.append((match.start(), match.end(), block))
 
         return matches
@@ -139,25 +171,34 @@ class CodeBlockElement(NotionBlockElement):
             .with_description(
                 "Use fenced code blocks to format content as code. Supports language annotations like "
                 "'python', 'json', or 'mermaid'. Useful for displaying code, configurations, command-line "
-                "examples, or diagram syntax. Also suitable for explaining or visualizing systems with diagram languages."
+                "examples, or diagram syntax. Also suitable for explaining or visualizing systems with diagram languages. "
+                "Code blocks can include optional captions for better documentation."
             )
             .with_usage_guidelines(
                 "Use code blocks when you want to present technical content like code snippets, terminal commands, "
-                "JSON structures, or system diagrams. Especially helpful when structure and formatting are essential."
+                "JSON structures, or system diagrams. Especially helpful when structure and formatting are essential. "
+                "Add captions to provide context, explanations, or titles for your code blocks."
+            )
+            .with_syntax(
+                "```language\ncode content\n```\nCaption: optional caption text\n\n"
+                "OR\n\n"
+                "```language\ncode content\n```"
             )
-            .with_syntax("```language\ncode content\n```")
             .with_examples(
                 [
-                    "```python\nprint('Hello, world!')\n```",
-                    '```json\n{"name": "Alice", "age": 30}\n```',
-                    "```mermaid\nflowchart TD\n  A --> B\n```",
+                    "```python\nprint('Hello, world!')\n```\nCaption: Basic Python greeting example",
+                    '```json\n{"name": "Alice", "age": 30}\n```\nCaption: User data structure',
+                    "```mermaid\nflowchart TD\n  A --> B\n```\nCaption: Simple flow diagram",
+                    '```bash\ngit commit -m "Initial commit"\n```',  # Without caption
                 ]
             )
             .with_avoidance_guidelines(
                 "NEVER EVER wrap markdown content with ```markdown. Markdown should be written directly without code block formatting. "
                 "NEVER use ```markdown under any circumstances. "
                 "For Mermaid diagrams, use ONLY the default styling without colors, backgrounds, or custom styling attributes. "
-                "Keep Mermaid diagrams simple and minimal without any styling or color modifications."
+                "Keep Mermaid diagrams simple and minimal without any styling or color modifications. "
+                "Captions must appear immediately after the closing ``` on a new line starting with 'Caption:' - "
+                "no empty lines between the code block and the caption."
             )
             .build()
         )