notionary 0.2.27__tar.gz → 0.3.0__tar.gz

notionary-0.3.0/.gitignore

@@ -0,0 +1,94 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+temp/
+
+# Virtual environments
+venv/
+env/
+.venv/
+.env/
+
+# Mkdocs
+site/
+
+# Distribution / packaging
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Jupyter Notebook checkpoints
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre
+.pyre/
+
+# Pytype
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# VS Code
+.vscode/
+
+# JetBrains IDEs (PyCharm, etc.)
+.idea/
+
+# MacOS
+.DS_Store
+
+# Windows
+Thumbs.db
+ehthumbs.db
+desktop.ini
+
+# dotenv files
+.env
+
+docs/node_modules/
+
+.ruff_cache/
+bandit-report.json

{notionary-0.2.27 → notionary-0.3.0}/LICENSE

@@ -4,18 +4,18 @@ Copyright (c) 2025 Mathis Kristoffer Arends
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights  
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell  
-copies of the Software, and to permit persons to whom the Software is  
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
 furnished to do so, subject to the following conditions:
 
-The above copyright notice and this permission notice shall be included in  
+The above copyright notice and this permission notice shall be included in
 all copies or substantial portions of the Software.
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR  
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,  
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE  
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER  
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN  
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 THE SOFTWARE.

notionary-0.3.0/PKG-INFO

@@ -0,0 +1,201 @@
+Metadata-Version: 2.4
+Name: notionary
+Version: 0.3.0
+Summary: Python library for programmatic Notion workspace management - databases, pages, and content with advanced Markdown support
+Project-URL: Homepage, https://github.com/mathisarends/notionary
+Author-email: Mathis Arends <mathisarends27@gmail.com>
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: aiofiles<25.0.0,>=24.1.0
+Requires-Dist: httpx>=0.28.0
+Requires-Dist: pydantic>=2.11.4
+Requires-Dist: python-dotenv<2.0.0,>=1.0.1
+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
+
+https://github.com/user-attachments/assets/da8b4691-bee4-4b0f-801e-dccacb630398
+
+_Create rich database entries with properties, content, and beautiful formatting_
+
+---
+
+## Quick Start
+
+### Find → Create → Update Flow
+
+```python
+from notionary import NotionPage
+
+# Find pages by name with fuzzy matching
+page = await NotionPage.from_title("Meeting Notes")
+
+# Define rich content with extended markdown
+content = """
+## Action Items
+- [x] Review proposal
+- [ ] Schedule meeting
+
+[callout](Key decision made! "💡")
+
+| Task | Owner | Deadline |
+|------|-------|----------|
+| Design Review | Alice | 2024-03-15 |
+| Implementation | Bob | 2024-03-22 |
+
++++ Budget Details
+See attached spreadsheet...
++++
+"""
+
+await page.append_markdown(content)
+```
+
+### Complete Block Support
+
+Every Notion block type with extended syntax:
+
+| Block Type    | Markdown Syntax                              | Use Case                     |
+| ------------- | -------------------------------------------- | ---------------------------- |
+| **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]`                     | Auto-generated navigation    |
+
+---
+
+## 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
+
+---
+
+## 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>

notionary-0.3.0/README.md

@@ -0,0 +1,186 @@
+<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
+
+https://github.com/user-attachments/assets/da8b4691-bee4-4b0f-801e-dccacb630398
+
+_Create rich database entries with properties, content, and beautiful formatting_
+
+---
+
+## Quick Start
+
+### Find → Create → Update Flow
+
+```python
+from notionary import NotionPage
+
+# Find pages by name with fuzzy matching
+page = await NotionPage.from_title("Meeting Notes")
+
+# Define rich content with extended markdown
+content = """
+## Action Items
+- [x] Review proposal
+- [ ] Schedule meeting
+
+[callout](Key decision made! "💡")
+
+| Task | Owner | Deadline |
+|------|-------|----------|
+| Design Review | Alice | 2024-03-15 |
+| Implementation | Bob | 2024-03-22 |
+
++++ Budget Details
+See attached spreadsheet...
++++
+"""
+
+await page.append_markdown(content)
+```
+
+### Complete Block Support
+
+Every Notion block type with extended syntax:
+
+| Block Type    | Markdown Syntax                              | Use Case                     |
+| ------------- | -------------------------------------------- | ---------------------------- |
+| **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]`                     | Auto-generated navigation    |
+
+---
+
+## 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
+
+---
+
+## 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>

notionary-0.3.0/notionary/__init__.py

@@ -0,0 +1,7 @@
+from .data_source.service import NotionDataSource
+from .database.service import NotionDatabase
+from .page.content.markdown.builder import MarkdownBuilder
+from .page.service import NotionPage
+from .workspace import NotionWorkspace
+
+__all__ = ["MarkdownBuilder", "NotionDataSource", "NotionDatabase", "NotionPage", "NotionWorkspace", "NotionWorkspace"]

notionary-0.3.0/notionary/blocks/__init__.py

@@ -0,0 +1,5 @@
+from .enums import CodingLanguage
+
+# Import from schemas aswell
+
+__all__ = ["CodingLanguage"]

notionary-0.3.0/notionary/blocks/client.py

@@ -0,0 +1,130 @@
+from notionary.blocks.schemas import Block, BlockChildrenResponse, BlockCreatePayload
+from notionary.http.client import NotionHttpClient
+from notionary.shared.typings import JsonDict
+from notionary.utils.decorators import time_execution_async
+from notionary.utils.pagination import paginate_notion_api
+
+
+class NotionBlockHttpClient(NotionHttpClient):
+    BATCH_SIZE = 100
+
+    async def get_block(self, block_id: str) -> Block:
+        response = await self.get(f"blocks/{block_id}")
+        return Block.model_validate(response)
+
+    async def delete_block(self, block_id: str) -> None:
+        self.logger.debug("Deleting block: %s", block_id)
+        await self.delete(f"blocks/{block_id}")
+
+    @time_execution_async()
+    async def get_block_tree(self, parent_block_id: str) -> list[Block]:
+        blocks_at_this_level = await self.get_all_block_children(parent_block_id)
+
+        for block in blocks_at_this_level:
+            if block.has_children:
+                nested_children = await self.get_block_tree(parent_block_id=block.id)
+                block.children = nested_children
+
+        return blocks_at_this_level
+
+    @time_execution_async()
+    async def get_all_block_children(self, parent_block_id: str) -> list[Block]:
+        self.logger.debug("Retrieving all children for block: %s", parent_block_id)
+
+        all_blocks = await paginate_notion_api(self.get_block_children, block_id=parent_block_id)
+
+        self.logger.debug("Retrieved %d total children for block %s", len(all_blocks), parent_block_id)
+        return all_blocks
+
+    async def get_block_children(
+        self, block_id: str, start_cursor: str | None = None, page_size: int = 100
+    ) -> BlockChildrenResponse:
+        self.logger.debug("Retrieving children of block: %s", block_id)
+
+        params = {"page_size": min(page_size, 100)}
+        if start_cursor:
+            params["start_cursor"] = start_cursor
+
+        response = await self.get(f"blocks/{block_id}/children", params=params)
+        return BlockChildrenResponse.model_validate(response)
+
+    async def append_block_children(
+        self,
+        block_id: str,
+        children: list[BlockCreatePayload],
+        insert_after_block_id: str | None = None,
+    ) -> BlockChildrenResponse | None:
+        if not children:
+            self.logger.warning("No children provided to append")
+            return None
+
+        self.logger.debug("Appending %d children to block: %s", len(children), block_id)
+
+        batches = self._split_into_batches(children)
+
+        if len(batches) == 1:
+            children_dicts = self._serialize_blocks(batches[0])
+            return await self._send_append_request(block_id, children_dicts, insert_after_block_id)
+
+        return await self._send_batched_append_requests(block_id, batches, insert_after_block_id)
+
+    def _split_into_batches(self, blocks: list[BlockCreatePayload]) -> list[list[BlockCreatePayload]]:
+        batches = []
+        for i in range(0, len(blocks), self.BATCH_SIZE):
+            batch = blocks[i : i + self.BATCH_SIZE]
+            batches.append(batch)
+        return batches
+
+    def _serialize_blocks(self, blocks: list[BlockCreatePayload]) -> list[JsonDict]:
+        return [block.model_dump(exclude_none=True) for block in blocks]
+
+    async def _send_append_request(
+        self, block_id: str, children: list[JsonDict], after_block_id: str | None = None
+    ) -> BlockChildrenResponse:
+        payload = {"children": children}
+        if after_block_id:
+            payload["after"] = after_block_id
+
+        response = await self.patch(f"blocks/{block_id}/children", payload)
+        return BlockChildrenResponse.model_validate(response)
+
+    async def _send_batched_append_requests(
+        self, block_id: str, batches: list[list[BlockCreatePayload]], initial_after_block_id: str | None = None
+    ) -> BlockChildrenResponse:
+        total_blocks = sum(len(batch) for batch in batches)
+        self.logger.info("Appending %d blocks in %d batches", total_blocks, len(batches))
+
+        all_responses = []
+        after_block_id = initial_after_block_id
+
+        for batch_index, batch in enumerate(batches, start=1):
+            self.logger.debug("Processing batch %d/%d (%d blocks)", batch_index, len(batches), len(batch))
+
+            children_dicts = self._serialize_blocks(batch)
+            response = await self._send_append_request(block_id, children_dicts, after_block_id)
+            all_responses.append(response)
+
+            if response.results:
+                after_block_id = response.results[-1].id
+
+            self.logger.debug("Completed batch %d/%d", batch_index, len(batches))
+
+        self.logger.info("Successfully appended all blocks in %d batches", len(batches))
+        return self._merge_responses(all_responses)
+
+    def _merge_responses(self, responses: list[BlockChildrenResponse]) -> BlockChildrenResponse:
+        if not responses:
+            raise ValueError("Cannot merge empty response list - this should never happen")
+
+        first_response = responses[0]
+        all_results = [block for response in responses for block in response.results]
+
+        return BlockChildrenResponse(
+            object=first_response.object,
+            results=all_results,
+            next_cursor=None,
+            has_more=False,
+            type=first_response.type,
+            block=first_response.block,
+            request_id=responses[-1].request_id,
+        )