notionary 0.3.1__py3-none-any.whl → 0.4.1__py3-none-any.whl

notionary/__init__.py

@@ -1,14 +1,62 @@
 from .data_source.service import NotionDataSource
 from .database.service import NotionDatabase
+from .file_upload import FileUploadQuery, FileUploadQueryBuilder, NotionFileUpload
+from .page.content import SyntaxPromptRegistry
 from .page.content.markdown.builder import MarkdownBuilder
+from .page.content.markdown.structured_output import (
+    MarkdownDocumentSchema,
+    StructuredOutputMarkdownConverter,
+)
 from .page.service import NotionPage
-from .workspace import NotionWorkspace, NotionWorkspaceQueryConfigBuilder
+from .workspace import (
+    NotionWorkspace,
+    NotionWorkspaceQueryConfigBuilder,
+    WorkspaceQueryConfig,
+)
 
 __all__ = [
+    "AudioSchema",
+    "BookmarkSchema",
+    "BreadcrumbSchema",
+    "BulletedListItemSchema",
+    "BulletedListSchema",
+    "CalloutSchema",
+    "CodeSchema",
+    "ColumnSchema",
+    "ColumnsSchema",
+    "DividerSchema",
+    "EmbedSchema",
+    "EquationSchema",
+    "FileSchema",
+    "FileUploadQuery",
+    "FileUploadQueryBuilder",
+    "Heading1Schema",
+    "Heading2Schema",
+    "Heading3Schema",
+    "ImageSchema",
     "MarkdownBuilder",
+    "MarkdownDocumentSchema",
+    "MarkdownNodeSchema",
+    "MermaidSchema",
     "NotionDataSource",
     "NotionDatabase",
+    "NotionFileUpload",
     "NotionPage",
     "NotionWorkspace",
     "NotionWorkspaceQueryConfigBuilder",
+    "NumberedListItemSchema",
+    "NumberedListSchema",
+    "ParagraphSchema",
+    "PdfSchema",
+    "QuoteSchema",
+    "SpaceSchema",
+    "StructuredOutputMarkdownConverter",
+    "SyntaxPromptRegistry",
+    "TableOfContentsSchema",
+    "TableSchema",
+    "TodoListSchema",
+    "TodoSchema",
+    "ToggleSchema",
+    "VideoSchema",
+    "WorkspaceQueryConfig",
 ]

notionary/blocks/client.py

@@ -31,9 +31,13 @@ class NotionBlockHttpClient(NotionHttpClient):
     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)
+        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)
+        self.logger.debug(
+            "Retrieved %d total children for block %s", len(all_blocks), parent_block_id
+        )
         return all_blocks
 
     async def get_block_children(
@@ -64,11 +68,17 @@ class NotionBlockHttpClient(NotionHttpClient):
 
         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_append_request(
+                block_id, children_dicts, insert_after_block_id
+            )
 
-        return await self._send_batched_append_requests(block_id, batches, 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]]:
+    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]
@@ -89,19 +99,31 @@ class NotionBlockHttpClient(NotionHttpClient):
         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
+        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))
+        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))
+            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)
+            response = await self._send_append_request(
+                block_id, children_dicts, after_block_id
+            )
             all_responses.append(response)
 
             if response.results:
@@ -112,9 +134,13 @@ class NotionBlockHttpClient(NotionHttpClient):
         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:
+    def _merge_responses(
+        self, responses: list[BlockChildrenResponse]
+    ) -> BlockChildrenResponse:
         if not responses:
-            raise ValueError("Cannot merge empty response list - this should never happen")
+            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]

notionary/blocks/enums.py

@@ -62,12 +62,6 @@ class BlockType(StrEnum):
     VIDEO = "video"
 
 
-class FileType(StrEnum):
-    EXTERNAL = "external"
-    FILE = "file"
-    FILE_UPLOAD = "file_upload"
-
-
 class CodingLanguage(StrEnum):
     ABAP = "abap"
     ARDUINO = "arduino"

notionary/blocks/rich_text/markdown_rich_text_converter.py

@@ -4,7 +4,12 @@ from dataclasses import dataclass
 from re import Match
 from typing import ClassVar
 
-from notionary.blocks.rich_text.models import MentionType, RichText, RichTextType, TextAnnotations
+from notionary.blocks.rich_text.models import (
+    MentionType,
+    RichText,
+    RichTextType,
+    TextAnnotations,
+)
 from notionary.blocks.rich_text.name_id_resolver import (
     DatabaseNameIdResolver,
     DataSourceNameIdResolver,
@@ -58,17 +63,32 @@ class MarkdownRichTextConverter:
         return [
             PatternHandler(RichTextPatterns.BOLD, self._handle_bold_pattern),
             PatternHandler(RichTextPatterns.ITALIC, self._handle_italic_pattern),
-            PatternHandler(RichTextPatterns.ITALIC_UNDERSCORE, self._handle_italic_pattern),
+            PatternHandler(
+                RichTextPatterns.ITALIC_UNDERSCORE, self._handle_italic_pattern
+            ),
             PatternHandler(RichTextPatterns.UNDERLINE, self._handle_underline_pattern),
-            PatternHandler(RichTextPatterns.STRIKETHROUGH, self._handle_strikethrough_pattern),
+            PatternHandler(
+                RichTextPatterns.STRIKETHROUGH, self._handle_strikethrough_pattern
+            ),
             PatternHandler(RichTextPatterns.CODE, self._handle_code_pattern),
             PatternHandler(RichTextPatterns.LINK, self._handle_link_pattern),
-            PatternHandler(RichTextPatterns.INLINE_EQUATION, self._handle_equation_pattern),
+            PatternHandler(
+                RichTextPatterns.INLINE_EQUATION, self._handle_equation_pattern
+            ),
             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),
+            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
+            ),
         ]
 
     async def to_rich_text(self, text: str) -> list[RichText]:
@@ -106,12 +126,16 @@ class MarkdownRichTextConverter:
         for pattern_handler in self.format_handlers:
             match = re.search(pattern_handler.pattern, text)
             if match and match.start() < earliest_position:
-                earliest_match = PatternMatch(match=match, handler=pattern_handler.handler, position=match.start())
+                earliest_match = PatternMatch(
+                    match=match, handler=pattern_handler.handler, position=match.start()
+                )
                 earliest_position = match.start()
 
         return earliest_match
 
-    async def _process_pattern_match(self, pattern_match: PatternMatch) -> RichText | list[RichText]:
+    async def _process_pattern_match(
+        self, pattern_match: PatternMatch
+    ) -> RichText | list[RichText]:
         handler_method = pattern_match.handler
 
         if self._is_async_handler(handler_method):
@@ -169,9 +193,13 @@ class MarkdownRichTextConverter:
     def _apply_color_to_link_segment(self, segment: RichText, color: str) -> RichText:
         formatting = self._extract_formatting_attributes(segment.annotations)
 
-        return RichText.for_link(segment.plain_text, segment.text.link.url, color=color, **formatting)
+        return RichText.for_link(
+            segment.plain_text, segment.text.link.url, color=color, **formatting
+        )
 
-    def _apply_color_to_plain_text_segment(self, segment: RichText, color: str) -> RichText:
+    def _apply_color_to_plain_text_segment(
+        self, segment: RichText, color: str
+    ) -> RichText:
         if segment.type != RichTextType.TEXT:
             return segment
 
@@ -179,7 +207,9 @@ class MarkdownRichTextConverter:
 
         return RichText.from_plain_text(segment.plain_text, color=color, **formatting)
 
-    def _extract_formatting_attributes(self, annotations: TextAnnotations) -> dict[str, bool]:
+    def _extract_formatting_attributes(
+        self, annotations: TextAnnotations
+    ) -> dict[str, bool]:
         if not annotations:
             return {
                 "bold": False,
@@ -246,13 +276,17 @@ class MarkdownRichTextConverter:
             if resolved_id:
                 return create_mention_func(resolved_id)
             else:
-                return self._create_unresolved_mention_fallback(identifier, mention_type)
+                return self._create_unresolved_mention_fallback(
+                    identifier, mention_type
+                )
 
         except Exception:
             # If resolution throws an error, fallback to plain text
             return self._create_unresolved_mention_fallback(identifier, mention_type)
 
-    def _create_unresolved_mention_fallback(self, identifier: str, mention_type: MentionType) -> RichText:
+    def _create_unresolved_mention_fallback(
+        self, identifier: str, mention_type: MentionType
+    ) -> RichText:
         fallback_text = f"@{mention_type.value}[{identifier}]"
         return RichText.for_caption(fallback_text)
 

notionary/blocks/rich_text/models.py

@@ -140,7 +140,9 @@ class RichText(BaseModel):
     def mention_user(cls, user_id: str) -> Self:
         return cls(
             type=RichTextType.MENTION,
-            mention=MentionObject(type=MentionType.USER, user=MentionUserRef(id=user_id)),
+            mention=MentionObject(
+                type=MentionType.USER, user=MentionUserRef(id=user_id)
+            ),
             annotations=TextAnnotations(),
         )
 
@@ -148,7 +150,9 @@ class RichText(BaseModel):
     def mention_page(cls, page_id: str) -> Self:
         return cls(
             type=RichTextType.MENTION,
-            mention=MentionObject(type=MentionType.PAGE, page=MentionPageRef(id=page_id)),
+            mention=MentionObject(
+                type=MentionType.PAGE, page=MentionPageRef(id=page_id)
+            ),
             annotations=TextAnnotations(),
         )
 
@@ -156,7 +160,9 @@ class RichText(BaseModel):
     def mention_database(cls, database_id: str) -> Self:
         return cls(
             type=RichTextType.MENTION,
-            mention=MentionObject(type=MentionType.DATABASE, database=MentionDatabaseRef(id=database_id)),
+            mention=MentionObject(
+                type=MentionType.DATABASE, database=MentionDatabaseRef(id=database_id)
+            ),
             annotations=TextAnnotations(),
         )
 
@@ -164,7 +170,10 @@ class RichText(BaseModel):
     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)),
+            mention=MentionObject(
+                type=MentionType.DATASOURCE,
+                data_source=MentionDataSourceRef(id=data_source_id),
+            ),
             annotations=TextAnnotations(),
         )
 

notionary/blocks/rich_text/name_id_resolver/data_source.py

@@ -6,8 +6,12 @@ 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()
+    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:
@@ -15,7 +19,9 @@ class DataSourceNameIdResolver(NameIdResolver):
             return None
 
         cleaned_name = name.strip()
-        data_source = await self._workspace_query_service.find_data_source(query=cleaned_name)
+        data_source = await self._workspace_query_service.find_data_source(
+            query=cleaned_name
+        )
         return data_source.id if data_source else None
 
     @override

notionary/blocks/rich_text/name_id_resolver/person.py

@@ -6,7 +6,9 @@ from notionary.user.person import PersonUser
 
 
 class PersonNameIdResolver(NameIdResolver):
-    def __init__(self, person_user_factory=None, http_client: UserHttpClient | None = None) -> None:
+    def __init__(
+        self, person_user_factory=None, http_client: UserHttpClient | None = None
+    ) -> None:
         if person_user_factory is None:
             person_user_factory = PersonUser
         self.person_user_factory = person_user_factory
@@ -31,7 +33,9 @@ class PersonNameIdResolver(NameIdResolver):
             return None
 
         try:
-            user = await self.person_user_factory.from_id(user_id.strip(), self.http_client)
+            user = await self.person_user_factory.from_id(
+                user_id.strip(), self.http_client
+            )
             return user.name if user else None
         except Exception:
             return None

notionary/blocks/rich_text/rich_text_markdown_converter.py

@@ -69,7 +69,9 @@ class RichTextToMarkdownConverter:
             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)
+            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)
@@ -88,7 +90,9 @@ class RichTextToMarkdownConverter:
         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)
+        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:
@@ -121,7 +125,10 @@ class RichTextToMarkdownConverter:
         if annotations.bold:
             content = f"**{content}**"
 
-        if annotations.color != BlockColor.DEFAULT and annotations.color in self.VALID_COLORS:
+        if (
+            annotations.color != BlockColor.DEFAULT
+            and annotations.color in self.VALID_COLORS
+        ):
             content = f"({annotations.color}:{content})"
 
         return content

notionary/blocks/schemas.py

@@ -4,41 +4,39 @@ from typing import Annotated, Literal
 
 from pydantic import BaseModel, ConfigDict, Field
 
-from notionary.blocks.enums import BlockColor, BlockType, CodingLanguage, FileType
+from notionary.blocks.enums import BlockColor, BlockType, CodingLanguage
 from notionary.blocks.rich_text.models import RichText
+from notionary.shared.models.file import ExternalFile, FileUploadFile, NotionHostedFile
 from notionary.shared.models.icon import Icon
 from notionary.shared.models.parent import Parent
 from notionary.user.schemas import PartialUserDto
 
 # ============================================================================
-# File-related models
+# File Data wrapper with caption
 # ============================================================================
 
 
-class ExternalFile(BaseModel):
-    model_config = ConfigDict(from_attributes=True)
-    url: str
+class CaptionMixin(BaseModel):
+    caption: list[RichText] = Field(default_factory=list)
+    name: str | None = None
 
 
-class NotionHostedFile(BaseModel):
-    model_config = ConfigDict(from_attributes=True)
-    url: str
-    expiry_time: str
+class ExternalFileWithCaption(CaptionMixin, ExternalFile):
+    pass
 
 
-class FileUploadFile(BaseModel):
-    model_config = ConfigDict(from_attributes=True)
-    id: str
+class NotionHostedFileWithCaption(CaptionMixin, NotionHostedFile):
+    pass
 
 
-class FileData(BaseModel):
-    model_config = ConfigDict(from_attributes=True)
-    caption: list[RichText] = Field(default_factory=list)
-    type: FileType
-    external: ExternalFile | None = None
-    file: NotionHostedFile | None = None
-    file_upload: FileUploadFile | None = None
-    name: str | None = None
+class FileUploadFileWithCaption(CaptionMixin, FileUploadFile):
+    pass
+
+
+type FileWithCaption = Annotated[
+    ExternalFileWithCaption | NotionHostedFileWithCaption | FileUploadFileWithCaption,
+    Field(discriminator="type"),
+]
 
 
 # ============================================================================
@@ -65,24 +63,14 @@ class BaseBlock(BaseModel):
 # ============================================================================
 
 
-class AudioData(BaseModel):
-    model_config = ConfigDict(from_attributes=True)
-    caption: list[RichText] = Field(default_factory=list)
-    type: FileType
-    external: ExternalFile | None = None
-    file: NotionHostedFile | None = None
-    file_upload: FileUploadFile | None = None
-    name: str | None = None
-
-
 class AudioBlock(BaseBlock):
     type: Literal[BlockType.AUDIO] = BlockType.AUDIO
-    audio: AudioData
+    audio: FileWithCaption
 
 
 class CreateAudioBlock(BaseModel):
     type: Literal[BlockType.AUDIO] = BlockType.AUDIO
-    audio: AudioData
+    audio: FileWithCaption
 
 
 # ============================================================================
@@ -90,8 +78,7 @@ class CreateAudioBlock(BaseModel):
 # ============================================================================
 
 
-class BookmarkData(BaseModel):
-    caption: list[RichText] = Field(default_factory=list)
+class BookmarkData(CaptionMixin):
     url: str
 
 
@@ -224,8 +211,7 @@ class CreateChildDatabaseBlock(BaseModel):
 # ============================================================================
 
 
-class CodeData(BaseModel):
-    caption: list[RichText] = Field(default_factory=list)
+class CodeData(CaptionMixin):
     rich_text: list[RichText]
     language: CodingLanguage = CodingLanguage.PLAIN_TEXT
 
@@ -311,9 +297,8 @@ class CreateDividerBlock(BaseModel):
 # ============================================================================
 
 
-class EmbedData(BaseModel):
+class EmbedData(CaptionMixin):
     url: str
-    caption: list[RichText] = Field(default_factory=list)
 
 
 class EmbedBlock(BaseBlock):
@@ -352,12 +337,12 @@ class CreateEquationBlock(BaseModel):
 
 class FileBlock(BaseBlock):
     type: Literal[BlockType.FILE] = BlockType.FILE
-    file: FileData
+    file: FileWithCaption
 
 
 class CreateFileBlock(BaseModel):
     type: Literal[BlockType.FILE] = BlockType.FILE
-    file: FileData
+    file: FileWithCaption
 
 
 # ============================================================================
@@ -416,24 +401,14 @@ CreateHeadingBlock = CreateHeading1Block | CreateHeading2Block | CreateHeading3B
 # ============================================================================
 
 
-class ImageData(BaseModel):
-    model_config = ConfigDict(from_attributes=True)
-    caption: list[RichText] = Field(default_factory=list)
-    type: FileType
-    external: ExternalFile | None = None
-    file: NotionHostedFile | None = None
-    file_upload: FileUploadFile | None = None
-    name: str | None = None
-
-
 class ImageBlock(BaseBlock):
     type: Literal[BlockType.IMAGE] = BlockType.IMAGE
-    image: ImageData
+    image: FileWithCaption
 
 
 class CreateImageBlock(BaseModel):
     type: Literal[BlockType.IMAGE] = BlockType.IMAGE
-    image: ImageData
+    image: FileWithCaption
 
 
 # ============================================================================
@@ -497,24 +472,14 @@ class CreateParagraphBlock(BaseModel):
 # ============================================================================
 
 
-class PdfData(BaseModel):
-    model_config = ConfigDict(from_attributes=True)
-    caption: list[RichText] = Field(default_factory=list)
-    type: FileType
-    external: ExternalFile | None = None
-    file: NotionHostedFile | None = None
-    file_upload: FileUploadFile | None = None
-    name: str | None = None
-
-
 class PdfBlock(BaseBlock):
     type: Literal[BlockType.PDF] = BlockType.PDF
-    pdf: PdfData
+    pdf: FileWithCaption
 
 
 class CreatePdfBlock(BaseModel):
     type: Literal[BlockType.PDF] = BlockType.PDF
-    pdf: PdfData
+    pdf: FileWithCaption
 
 
 # ============================================================================
@@ -669,31 +634,21 @@ class CreateToggleBlock(BaseModel):
 # ============================================================================
 
 
-class VideoData(BaseModel):
-    model_config = ConfigDict(from_attributes=True)
-    caption: list[RichText] = Field(default_factory=list)
-    type: FileType
-    external: ExternalFile | None = None
-    file: NotionHostedFile | None = None
-    file_upload: FileUploadFile | None = None
-    name: str | None = None
-
-
 class VideoBlock(BaseBlock):
     type: Literal[BlockType.VIDEO] = BlockType.VIDEO
-    video: VideoData
+    video: FileWithCaption
 
 
 class CreateVideoBlock(BaseModel):
     type: Literal[BlockType.VIDEO] = BlockType.VIDEO
-    video: VideoData
+    video: FileWithCaption
 
 
 # ============================================================================
 # Block Union Type
 # ============================================================================
 
-Block = Annotated[
+type Block = Annotated[
     (
         AudioBlock
         | BookmarkBlock
@@ -743,7 +698,7 @@ class BlockChildrenResponse(BaseModel):
     request_id: str
 
 
-BlockCreatePayload = Annotated[
+type BlockCreatePayload = Annotated[
     (
         CreateAudioBlock
         | CreateBookmarkBlock