notionary 0.2.28__tar.gz → 0.3.1__tar.gz

{notionary-0.2.28 → notionary-0.3.1}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: notionary
-Version: 0.2.28
+Version: 0.3.1
 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-Python: >=3.12
 Requires-Dist: aiofiles<25.0.0,>=24.1.0
 Requires-Dist: httpx>=0.28.0
 Requires-Dist: pydantic>=2.11.4
@@ -23,9 +23,13 @@ Description-Content-Type: text/markdown
 
 <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/)
+[![PyPI version](https://badge.fury.io/py/notionary.svg)](https://badge.fury.io/py/notionary)
+[![Python Version](https://img.shields.io/badge/python-3.12%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Coverage](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/mathisarends/fc0568b66a20fbbaa5018205861c0da9/raw/notionary-coverage.json)](https://github.com/mathisarends/notionary)
+[![Downloads](https://img.shields.io/pypi/dm/notionary?color=blue)](https://pypi.org/project/notionary/)
+[![Documentation](https://img.shields.io/badge/docs-notionary-blue?style=flat&logo=readthedocs)](https://mathisarends.github.io/notionary/)
+[![Notion API](https://img.shields.io/badge/Notion%20API-Official-000000?logo=notion&logoColor=white)](https://developers.notion.com/)
 
 **Transform complex Notion API interactions into simple, Pythonic code.**
 Perfect for developers building AI agents, automation workflows, and dynamic content systems.
@@ -61,17 +65,9 @@ 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_
+_Create rich database entries with properties, content, and beautiful formatting_
 
 ---
 
@@ -80,50 +76,30 @@ _Upload videos and images using simple markdown syntax - files are automatically
 ### 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_title("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())
+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
@@ -132,36 +108,13 @@ 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
+| **TOC**       | `[toc]`                     | Auto-generated navigation    |
 
 ---
 
@@ -222,29 +175,6 @@ Every Notion block type with extended syntax:
 
 [**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

notionary-0.3.1/README.md

@@ -0,0 +1,190 @@
+<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">
+
+[![PyPI version](https://badge.fury.io/py/notionary.svg)](https://badge.fury.io/py/notionary)
+[![Python Version](https://img.shields.io/badge/python-3.12%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Coverage](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/mathisarends/fc0568b66a20fbbaa5018205861c0da9/raw/notionary-coverage.json)](https://github.com/mathisarends/notionary)
+[![Downloads](https://img.shields.io/pypi/dm/notionary?color=blue)](https://pypi.org/project/notionary/)
+[![Documentation](https://img.shields.io/badge/docs-notionary-blue?style=flat&logo=readthedocs)](https://mathisarends.github.io/notionary/)
+[![Notion API](https://img.shields.io/badge/Notion%20API-Official-000000?logo=notion&logoColor=white)](https://developers.notion.com/)
+
+**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.1/notionary/__init__.py

@@ -0,0 +1,14 @@
+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, NotionWorkspaceQueryConfigBuilder
+
+__all__ = [
+    "MarkdownBuilder",
+    "NotionDataSource",
+    "NotionDatabase",
+    "NotionPage",
+    "NotionWorkspace",
+    "NotionWorkspaceQueryConfigBuilder",
+]

notionary-0.3.1/notionary/blocks/__init__.py

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

{notionary-0.2.28 → notionary-0.3.1}/notionary/blocks/client.py

@@ -1,7 +1,7 @@
-from typing import Any
-
 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
 
 
@@ -16,6 +16,7 @@ class NotionBlockHttpClient(NotionHttpClient):
         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)
 
@@ -26,6 +27,7 @@ class NotionBlockHttpClient(NotionHttpClient):
 
         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)
 
@@ -73,11 +75,11 @@ class NotionBlockHttpClient(NotionHttpClient):
             batches.append(batch)
         return batches
 
-    def _serialize_blocks(self, blocks: list[BlockCreatePayload]) -> list[dict[str, Any]]:
+    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[dict[str, Any]], after_block_id: str | None = None
+        self, block_id: str, children: list[JsonDict], after_block_id: str | None = None
     ) -> BlockChildrenResponse:
         payload = {"children": children}
         if after_block_id:

{notionary-0.2.28 → notionary-0.3.1}/notionary/blocks/enums.py

@@ -68,7 +68,7 @@ class FileType(StrEnum):
     FILE_UPLOAD = "file_upload"
 
 
-class CodeLanguage(StrEnum):
+class CodingLanguage(StrEnum):
     ABAP = "abap"
     ARDUINO = "arduino"
     BASH = "bash"
@@ -165,3 +165,30 @@ class CodeLanguage(StrEnum):
                 return member
 
         return default if default is not None else cls.PLAIN_TEXT
+
+
+class VideoFileType(StrEnum):
+    AMV = ".amv"
+    ASF = ".asf"
+    AVI = ".avi"
+    F4V = ".f4v"
+    FLV = ".flv"
+    GIFV = ".gifv"
+    MKV = ".mkv"
+    MOV = ".mov"
+    MPG = ".mpg"
+    MPEG = ".mpeg"
+    MPV = ".mpv"
+    MP4 = ".mp4"
+    M4V = ".m4v"
+    QT = ".qt"
+    WMV = ".wmv"
+
+    @classmethod
+    def get_all_extensions(cls) -> set[str]:
+        return {ext.value for ext in cls}
+
+    @classmethod
+    def is_valid_extension(cls, filename: str) -> bool:
+        lower_filename = filename.lower()
+        return any(lower_filename.endswith(ext.value) for ext in cls)

{notionary-0.2.28 → notionary-0.3.1}/notionary/blocks/rich_text/markdown_rich_text_converter.py

@@ -7,6 +7,7 @@ from typing import ClassVar
 from notionary.blocks.rich_text.models import MentionType, RichText, RichTextType, TextAnnotations
 from notionary.blocks.rich_text.name_id_resolver import (
     DatabaseNameIdResolver,
+    DataSourceNameIdResolver,
     NameIdResolver,
     PageNameIdResolver,
     PersonNameIdResolver,
@@ -44,10 +45,12 @@ class MarkdownRichTextConverter:
         *,
         page_resolver: NameIdResolver | None = None,
         database_resolver: NameIdResolver | None = None,
+        data_source_resolver: NameIdResolver | None = None,
         person_resolver: NameIdResolver | None = None,
     ):
         self.page_resolver = page_resolver or PageNameIdResolver()
         self.database_resolver = database_resolver or DatabaseNameIdResolver()
+        self.data_source_resolver = data_source_resolver or DataSourceNameIdResolver()
         self.person_resolver = person_resolver or PersonNameIdResolver()
         self.format_handlers = self._setup_format_handlers()
 
@@ -64,6 +67,7 @@ class MarkdownRichTextConverter:
             PatternHandler(RichTextPatterns.COLOR, self._handle_color_pattern),
             PatternHandler(RichTextPatterns.PAGE_MENTION, self._handle_page_mention_pattern),
             PatternHandler(RichTextPatterns.DATABASE_MENTION, self._handle_database_mention_pattern),
+            PatternHandler(RichTextPatterns.DATASOURCE_MENTION, self._handle_data_source_mention_pattern),
             PatternHandler(RichTextPatterns.USER_MENTION, self._handle_user_mention_pattern),
         ]
 
@@ -119,6 +123,7 @@ class MarkdownRichTextConverter:
         async_handlers = {
             self._handle_page_mention_pattern,
             self._handle_database_mention_pattern,
+            self._handle_data_source_mention_pattern,
             self._handle_color_pattern,  # Color pattern needs async for recursive parsing
             self._handle_user_mention_pattern,
         }
@@ -210,6 +215,15 @@ class MarkdownRichTextConverter:
             mention_type=MentionType.DATABASE,
         )
 
+    async def _handle_data_source_mention_pattern(self, match: Match) -> RichText:
+        identifier = match.group(1)
+        return await self._create_mention_or_fallback(
+            identifier=identifier,
+            resolve_func=self.data_source_resolver.resolve_name_to_id,
+            create_mention_func=RichText.mention_data_source,
+            mention_type=MentionType.DATASOURCE,
+        )
+
     async def _handle_user_mention_pattern(self, match: Match) -> RichText:
         identifier = match.group(1)
         return await self._create_mention_or_fallback(

{notionary-0.2.28 → notionary-0.3.1}/notionary/blocks/rich_text/models.py

@@ -16,6 +16,7 @@ class MentionType(StrEnum):
     USER = "user"
     PAGE = "page"
     DATABASE = "database"
+    DATASOURCE = "data_source"
     DATE = "date"
     LINK_PREVIEW = "link_preview"
     TEMPLATE_MENTION = "template_mention"
@@ -60,6 +61,10 @@ class MentionDatabaseRef(BaseModel):
     id: str
 
 
+class MentionDataSourceRef(BaseModel):
+    id: str
+
+
 class MentionLinkPreview(BaseModel):
     url: str
 
@@ -81,6 +86,7 @@ class MentionObject(BaseModel):
     user: MentionUserRef | None = None
     page: MentionPageRef | None = None
     database: MentionDatabaseRef | None = None
+    data_source: MentionDataSourceRef | None = None
     date: MentionDate | None = None
     link_preview: MentionLinkPreview | None = None
     template_mention: MentionTemplateMention | None = None
@@ -154,6 +160,14 @@ class RichText(BaseModel):
             annotations=TextAnnotations(),
         )
 
+    @classmethod
+    def mention_data_source(cls, data_source_id: str) -> Self:
+        return cls(
+            type=RichTextType.MENTION,
+            mention=MentionObject(type=MentionType.DATASOURCE, data_source=MentionDataSourceRef(id=data_source_id)),
+            annotations=TextAnnotations(),
+        )
+
     @classmethod
     def equation_inline(cls, expression: str) -> Self:
         return cls(

{notionary-0.2.28 → notionary-0.3.1}/notionary/blocks/rich_text/name_id_resolver/__init__.py

@@ -1,9 +1,11 @@
+from .data_source import DataSourceNameIdResolver
 from .database import DatabaseNameIdResolver
 from .page import PageNameIdResolver
 from .person import PersonNameIdResolver
 from .port import NameIdResolver
 
 __all__ = [
+    "DataSourceNameIdResolver",
     "DatabaseNameIdResolver",
     "NameIdResolver",
     "PageNameIdResolver",

notionary-0.3.1/notionary/blocks/rich_text/name_id_resolver/data_source.py

@@ -0,0 +1,32 @@
+from typing import override
+
+from notionary.blocks.rich_text.name_id_resolver.port import NameIdResolver
+from notionary.workspace.query.service import WorkspaceQueryService
+
+
+# !!! in the notion api mentions that reference datasources are not provided yet (it's a limiation of the API as of now)
+class DataSourceNameIdResolver(NameIdResolver):
+    def __init__(self, workspace_query_service: WorkspaceQueryService | None = None) -> None:
+        self._workspace_query_service = workspace_query_service or WorkspaceQueryService()
+
+    @override
+    async def resolve_name_to_id(self, name: str) -> str | None:
+        if not name:
+            return None
+
+        cleaned_name = name.strip()
+        data_source = await self._workspace_query_service.find_data_source(query=cleaned_name)
+        return data_source.id if data_source else None
+
+    @override
+    async def resolve_id_to_name(self, data_source_id: str) -> str | None:
+        if not data_source_id:
+            return None
+
+        try:
+            from notionary import NotionDataSource
+
+            data_source = await NotionDataSource.from_id(data_source_id)
+            return data_source.title if data_source else None
+        except Exception:
+            return None

{notionary-0.2.28 → notionary-0.3.1}/notionary/blocks/rich_text/rich_text_markdown_converter.py

@@ -8,6 +8,7 @@ from notionary.blocks.rich_text.models import (
 )
 from notionary.blocks.rich_text.name_id_resolver import (
     DatabaseNameIdResolver,
+    DataSourceNameIdResolver,
     NameIdResolver,
     PageNameIdResolver,
     PersonNameIdResolver,
@@ -23,10 +24,12 @@ class RichTextToMarkdownConverter:
         *,
         page_resolver: NameIdResolver | None = None,
         database_resolver: NameIdResolver | None = None,
+        data_source_resolver: NameIdResolver | None = None,
         person_resolver: NameIdResolver | None = None,
     ) -> None:
         self.page_resolver = page_resolver or PageNameIdResolver()
         self.database_resolver = database_resolver or DatabaseNameIdResolver()
+        self.data_source_resolver = data_source_resolver or DataSourceNameIdResolver()
         self.person_resolver = person_resolver or PersonNameIdResolver()
 
     async def to_markdown(self, rich_text: list[RichText]) -> str:
@@ -65,6 +68,9 @@ class RichTextToMarkdownConverter:
         elif mention.type == MentionType.DATABASE and mention.database:
             return await self._extract_database_mention_markdown(mention.database.id)
 
+        elif mention.type == MentionType.DATASOURCE and mention.data_source:
+            return await self._extract_data_source_mention_markdown(mention.data_source.id)
+
         elif mention.type == MentionType.USER and mention.user:
             return await self._extract_user_mention_markdown(mention.user.id)
 
@@ -81,6 +87,10 @@ class RichTextToMarkdownConverter:
         database_name = await self.database_resolver.resolve_id_to_name(database_id)
         return f"@database[{database_name or database_id}]"
 
+    async def _extract_data_source_mention_markdown(self, data_source_id: str) -> str:
+        data_source_name = await self.data_source_resolver.resolve_id_to_name(data_source_id)
+        return f"@datasource[{data_source_name or data_source_id}]"
+
     async def _extract_user_mention_markdown(self, user_id: str) -> str:
         user_name = await self.person_resolver.resolve_id_to_name(user_id)
         return f"@user[{user_name or user_id}]"
@@ -122,11 +132,13 @@ async def convert_rich_text_to_markdown(
     *,
     page_resolver: NameIdResolver | None = None,
     database_resolver: NameIdResolver | None = None,
+    data_source_resolver: NameIdResolver | None = None,
     person_resolver: NameIdResolver | None = None,
 ) -> str:
     converter = RichTextToMarkdownConverter(
         page_resolver=page_resolver,
         database_resolver=database_resolver,
+        data_source_resolver=data_source_resolver,
         person_resolver=person_resolver,
     )
     return await converter.to_markdown(rich_text)