notionary 0.2.28__tar.gz → 0.3.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: notionary
-Version: 0.2.28
+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>
@@ -61,17 +61,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 +72,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 +104,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 +171,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.2.28 → notionary-0.3.0}/README.md

@@ -46,17 +46,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_
 
 ---
 
@@ -65,50 +57,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
@@ -117,36 +89,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    |
 
 ---
 
@@ -207,29 +156,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.0/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.0}/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.0}/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"

{notionary-0.2.28 → notionary-0.3.0}/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.0}/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.0}/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.0/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.0}/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)

{notionary-0.2.28 → notionary-0.3.0}/notionary/blocks/rich_text/rich_text_patterns.py

@@ -35,5 +35,8 @@ class RichTextPatterns(StrEnum):
     DATABASE_MENTION = r"@database\[([^\]]+)\]"
     """Matches a Notion database mention by name or ID. Example: `@database[Tasks]`."""
 
+    DATASOURCE_MENTION = r"@datasource\[([^\]]+)\]"
+    """Matches a Notion data source mention by name or ID. Example: `@datasource[My Data]`."""
+
     USER_MENTION = r"@user\[([^\]]+)\]"
     """Matches a Notion user mention by name or ID. Example: `@user[Some Person]`."""