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

notionary/file_upload/validation/models.py

@@ -0,0 +1,124 @@
+from enum import StrEnum
+
+
+class AudioExtension(StrEnum):
+    AAC = ".aac"
+    ADTS = ".adts"
+    MID = ".mid"
+    MIDI = ".midi"
+    MP3 = ".mp3"
+    MPGA = ".mpga"
+    M4A = ".m4a"
+    M4B = ".m4b"
+    MP4 = ".mp4"
+    OGA = ".oga"
+    OGG = ".ogg"
+    WAV = ".wav"
+    WMA = ".wma"
+
+
+class AudioMimeType(StrEnum):
+    AAC = "audio/aac"
+    MIDI = "audio/midi"
+    MPEG = "audio/mpeg"
+    MP4 = "audio/mp4"
+    OGG = "audio/ogg"
+    WAV = "audio/wav"
+    WMA = "audio/x-ms-wma"
+
+
+class DocumentExtension(StrEnum):
+    PDF = ".pdf"
+    TXT = ".txt"
+    JSON = ".json"
+    DOC = ".doc"
+    DOT = ".dot"
+    DOCX = ".docx"
+    DOTX = ".dotx"
+    XLS = ".xls"
+    XLT = ".xlt"
+    XLA = ".xla"
+    XLSX = ".xlsx"
+    XLTX = ".xltx"
+    PPT = ".ppt"
+    POT = ".pot"
+    PPS = ".pps"
+    PPA = ".ppa"
+    PPTX = ".pptx"
+    POTX = ".potx"
+
+
+class DocumentMimeType(StrEnum):
+    PDF = "application/pdf"
+    PLAIN_TEXT = "text/plain"
+    JSON = "application/json"
+    MSWORD = "application/msword"
+    WORD_DOCUMENT = "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
+    WORD_TEMPLATE = "application/vnd.openxmlformats-officedocument.wordprocessingml.template"
+    EXCEL = "application/vnd.ms-excel"
+    EXCEL_SHEET = "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
+    EXCEL_TEMPLATE = "application/vnd.openxmlformats-officedocument.spreadsheetml.template"
+    POWERPOINT = "application/vnd.ms-powerpoint"
+    POWERPOINT_PRESENTATION = "application/vnd.openxmlformats-officedocument.presentationml.presentation"
+    POWERPOINT_TEMPLATE = "application/vnd.openxmlformats-officedocument.presentationml.template"
+
+
+class ImageExtension(StrEnum):
+    GIF = ".gif"
+    HEIC = ".heic"
+    JPEG = ".jpeg"
+    JPG = ".jpg"
+    PNG = ".png"
+    SVG = ".svg"
+    TIF = ".tif"
+    TIFF = ".tiff"
+    WEBP = ".webp"
+    ICO = ".ico"
+
+
+class ImageMimeType(StrEnum):
+    GIF = "image/gif"
+    HEIC = "image/heic"
+    JPEG = "image/jpeg"
+    PNG = "image/png"
+    SVG = "image/svg+xml"
+    TIFF = "image/tiff"
+    WEBP = "image/webp"
+    ICON = "image/vnd.microsoft.icon"
+
+
+class VideoExtension(StrEnum):
+    AMV = ".amv"
+    ASF = ".asf"
+    WMV = ".wmv"
+    AVI = ".avi"
+    F4V = ".f4v"
+    FLV = ".flv"
+    GIFV = ".gifv"
+    M4V = ".m4v"
+    MP4 = ".mp4"
+    MKV = ".mkv"
+    WEBM = ".webm"
+    MOV = ".mov"
+    QT = ".qt"
+    MPEG = ".mpeg"
+
+
+class VideoMimeType(StrEnum):
+    AMV = "video/x-amv"
+    ASF = "video/x-ms-asf"
+    AVI = "video/x-msvideo"
+    F4V = "video/x-f4v"
+    FLV = "video/x-flv"
+    MP4 = "video/mp4"
+    MKV = "video/x-matroska"
+    WEBM = "video/webm"
+    QUICKTIME = "video/quicktime"
+    MPEG = "video/mpeg"
+
+
+class FileCategory(StrEnum):
+    AUDIO = "audio"
+    DOCUMENT = "document"
+    IMAGE = "image"
+    VIDEO = "video"

notionary/file_upload/validation/port.py

@@ -0,0 +1,7 @@
+from abc import ABC, abstractmethod
+
+
+class FileUploadValidator(ABC):
+    @abstractmethod
+    async def validate(self) -> None:
+        pass

notionary/file_upload/validation/service.py

@@ -0,0 +1,17 @@
+from notionary.file_upload.validation.port import FileUploadValidator
+from notionary.utils.decorators import time_execution_async
+from notionary.utils.mixins.logging import LoggingMixin
+
+
+class FileUploadValidationService(LoggingMixin):
+    def __init__(self) -> None:
+        self._validators: list[FileUploadValidator] = []
+
+    def register(self, validator: FileUploadValidator) -> None:
+        self._validators.append(validator)
+
+    @time_execution_async()
+    async def validate(self) -> None:
+        for validator in self._validators:
+            self.logger.info("Validating with %s", validator.__class__.__name__)
+            await validator.validate()

notionary/file_upload/validation/validators/__init__.py

@@ -0,0 +1,11 @@
+from .file_exists import FileExistsValidator
+from .file_extension import FileExtensionValidator
+from .file_name_length import FileNameLengthValidator
+from .upload_limit import FileUploadLimitValidator
+
+__all__ = [
+    "FileExistsValidator",
+    "FileExtensionValidator",
+    "FileNameLengthValidator",
+    "FileUploadLimitValidator",
+]

notionary/file_upload/validation/validators/file_exists.py

@@ -0,0 +1,15 @@
+from pathlib import Path
+from typing import override
+
+from notionary.exceptions.file_upload import FileNotFoundError
+from notionary.file_upload.validation.port import FileUploadValidator
+
+
+class FileExistsValidator(FileUploadValidator):
+    def __init__(self, file_path: Path) -> None:
+        self.file_path = file_path
+
+    @override
+    async def validate(self) -> None:
+        if not self.file_path.exists():
+            raise FileNotFoundError(str(self.file_path))

notionary/file_upload/validation/validators/file_extension.py

@@ -0,0 +1,122 @@
+from pathlib import Path
+from typing import ClassVar, override
+
+from notionary.exceptions.file_upload import NoFileExtensionException, UnsupportedFileTypeException
+from notionary.file_upload.validation.models import (
+    AudioExtension,
+    AudioMimeType,
+    DocumentExtension,
+    DocumentMimeType,
+    FileCategory,
+    ImageExtension,
+    ImageMimeType,
+    VideoExtension,
+    VideoMimeType,
+)
+from notionary.file_upload.validation.port import FileUploadValidator
+
+
+class FileExtensionValidator(FileUploadValidator):
+    EXTENSION_TO_MIME: ClassVar[dict[str, str]] = {
+        AudioExtension.AAC: AudioMimeType.AAC,
+        AudioExtension.ADTS: AudioMimeType.AAC,
+        AudioExtension.MID: AudioMimeType.MIDI,
+        AudioExtension.MIDI: AudioMimeType.MIDI,
+        AudioExtension.MP3: AudioMimeType.MPEG,
+        AudioExtension.MPGA: AudioMimeType.MPEG,
+        AudioExtension.M4A: AudioMimeType.MP4,
+        AudioExtension.M4B: AudioMimeType.MP4,
+        AudioExtension.MP4: AudioMimeType.MP4,
+        AudioExtension.OGA: AudioMimeType.OGG,
+        AudioExtension.OGG: AudioMimeType.OGG,
+        AudioExtension.WAV: AudioMimeType.WAV,
+        AudioExtension.WMA: AudioMimeType.WMA,
+        DocumentExtension.PDF: DocumentMimeType.PDF,
+        DocumentExtension.TXT: DocumentMimeType.PLAIN_TEXT,
+        DocumentExtension.JSON: DocumentMimeType.JSON,
+        DocumentExtension.DOC: DocumentMimeType.MSWORD,
+        DocumentExtension.DOT: DocumentMimeType.MSWORD,
+        DocumentExtension.DOCX: DocumentMimeType.WORD_DOCUMENT,
+        DocumentExtension.DOTX: DocumentMimeType.WORD_TEMPLATE,
+        DocumentExtension.XLS: DocumentMimeType.EXCEL,
+        DocumentExtension.XLT: DocumentMimeType.EXCEL,
+        DocumentExtension.XLA: DocumentMimeType.EXCEL,
+        DocumentExtension.XLSX: DocumentMimeType.EXCEL_SHEET,
+        DocumentExtension.XLTX: DocumentMimeType.EXCEL_TEMPLATE,
+        DocumentExtension.PPT: DocumentMimeType.POWERPOINT,
+        DocumentExtension.POT: DocumentMimeType.POWERPOINT,
+        DocumentExtension.PPS: DocumentMimeType.POWERPOINT,
+        DocumentExtension.PPA: DocumentMimeType.POWERPOINT,
+        DocumentExtension.PPTX: DocumentMimeType.POWERPOINT_PRESENTATION,
+        DocumentExtension.POTX: DocumentMimeType.POWERPOINT_TEMPLATE,
+        ImageExtension.GIF: ImageMimeType.GIF,
+        ImageExtension.HEIC: ImageMimeType.HEIC,
+        ImageExtension.JPEG: ImageMimeType.JPEG,
+        ImageExtension.JPG: ImageMimeType.JPEG,
+        ImageExtension.PNG: ImageMimeType.PNG,
+        ImageExtension.SVG: ImageMimeType.SVG,
+        ImageExtension.TIF: ImageMimeType.TIFF,
+        ImageExtension.TIFF: ImageMimeType.TIFF,
+        ImageExtension.WEBP: ImageMimeType.WEBP,
+        ImageExtension.ICO: ImageMimeType.ICON,
+        VideoExtension.AMV: VideoMimeType.AMV,
+        VideoExtension.ASF: VideoMimeType.ASF,
+        VideoExtension.WMV: VideoMimeType.ASF,
+        VideoExtension.AVI: VideoMimeType.AVI,
+        VideoExtension.F4V: VideoMimeType.F4V,
+        VideoExtension.FLV: VideoMimeType.FLV,
+        VideoExtension.GIFV: VideoMimeType.WEBM,
+        VideoExtension.M4V: VideoMimeType.MP4,
+        VideoExtension.MP4: VideoMimeType.MP4,
+        VideoExtension.MKV: VideoMimeType.MKV,
+        VideoExtension.WEBM: VideoMimeType.WEBM,
+        VideoExtension.MOV: VideoMimeType.QUICKTIME,
+        VideoExtension.QT: VideoMimeType.QUICKTIME,
+        VideoExtension.MPEG: VideoMimeType.MPEG,
+    }
+
+    EXTENSION_TO_CATEGORY: ClassVar[dict[str, FileCategory]] = {
+        **{ext.value: FileCategory.AUDIO for ext in AudioExtension},
+        **{ext.value: FileCategory.DOCUMENT for ext in DocumentExtension},
+        **{ext.value: FileCategory.IMAGE for ext in ImageExtension},
+        **{ext.value: FileCategory.VIDEO for ext in VideoExtension},
+    }
+
+    def __init__(self, filename: str | Path) -> None:
+        self.filename = Path(filename).name if isinstance(filename, Path) else filename
+
+    @override
+    async def validate(self) -> None:
+        extension = self._extract_extension(self.filename)
+
+        if not extension:
+            raise NoFileExtensionException(self.filename)
+
+        if not self._is_supported(extension):
+            supported_by_category = self._get_supported_extensions_by_category()
+            raise UnsupportedFileTypeException(extension, self.filename, supported_by_category)
+
+    @staticmethod
+    def _extract_extension(filename: str) -> str:
+        import os
+
+        _, ext = os.path.splitext(filename)
+        return ext.lower()
+
+    def _is_supported(self, extension: str) -> bool:
+        normalized = self._normalize_extension(extension)
+        return normalized in self.EXTENSION_TO_MIME
+
+    @staticmethod
+    def _normalize_extension(extension: str) -> str:
+        extension = extension.lower()
+        if not extension.startswith("."):
+            extension = f".{extension}"
+        return extension
+
+    def _get_supported_extensions_by_category(self) -> dict[str, list[str]]:
+        result = {}
+        for category in FileCategory:
+            extensions = [ext for ext, cat in self.EXTENSION_TO_CATEGORY.items() if cat == category]
+            result[category.value] = extensions
+        return result

notionary/file_upload/validation/validators/file_name_length.py

@@ -0,0 +1,21 @@
+from typing import override
+
+from notionary.exceptions.file_upload import FilenameTooLongError
+from notionary.file_upload.config.constants import NOTION_MAX_FILENAME_BYTES
+from notionary.file_upload.validation.port import FileUploadValidator
+
+
+class FileNameLengthValidator(FileUploadValidator):
+    def __init__(self, filename: str) -> None:
+        self._filename = filename
+        self._max_filename_bytes = NOTION_MAX_FILENAME_BYTES
+
+    @override
+    async def validate(self) -> None:
+        filename_bytes = len(self._filename.encode("utf-8"))
+        if filename_bytes > self._max_filename_bytes:
+            raise FilenameTooLongError(
+                filename=self._filename,
+                filename_bytes=filename_bytes,
+                max_filename_bytes=self._max_filename_bytes,
+            )

notionary/file_upload/validation/validators/upload_limit.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING, override
+
+from notionary.exceptions.file_upload import FileSizeException
+from notionary.file_upload.validation.port import FileUploadValidator
+
+if TYPE_CHECKING:
+    from notionary.user import BotUser
+
+
+class FileUploadLimitValidator(FileUploadValidator):
+    def __init__(self, filename: str | Path, file_size_bytes: int) -> None:
+        self.filename = Path(filename).name if isinstance(filename, Path) else filename
+        self.file_size_bytes = file_size_bytes
+
+    @override
+    async def validate(self, integration: BotUser | None = None) -> None:
+        from notionary.user import BotUser
+
+        integration = integration or await BotUser.from_current_integration()
+
+        max_file_size_in_bytes = integration.workspace_file_upload_limit_in_bytes
+
+        if self.file_size_bytes > max_file_size_in_bytes:
+            raise FileSizeException(
+                filename=self.filename,
+                file_size_bytes=self.file_size_bytes,
+                max_size_bytes=max_file_size_in_bytes,
+            )

notionary/http/client.py

@@ -18,7 +18,7 @@ from notionary.http.models import HttpMethod
 from notionary.shared.typings import JsonDict
 from notionary.utils.mixins.logging import LoggingMixin
 
-load_dotenv()
+load_dotenv(override=True)
 
 
 class NotionHttpClient(LoggingMixin):
@@ -44,7 +44,6 @@ class NotionHttpClient(LoggingMixin):
         self._is_initialized = False
 
     def __del__(self):
-        """Auto-cleanup when client is destroyed."""
         if not hasattr(self, "client") or not self.client:
             return
 
@@ -60,18 +59,13 @@ class NotionHttpClient(LoggingMixin):
             self.logger.warning("No event loop available for auto-closing NotionHttpClient")
 
     async def __aenter__(self):
-        """Async context manager entry."""
         await self._ensure_initialized()
         return self
 
     async def __aexit__(self, exc_type, exc_val, exc_tb):
-        """Async context manager exit."""
         await self.close()
 
     async def close(self) -> None:
-        """
-        Closes the HTTP client and releases resources.
-        """
         if not hasattr(self, "client") or not self.client:
             return
 
@@ -81,33 +75,24 @@ class NotionHttpClient(LoggingMixin):
         self.logger.debug("NotionHttpClient closed")
 
     async def get(self, endpoint: str, params: JsonDict | None = None) -> JsonDict | None:
-        return await self.make_request(HttpMethod.GET, endpoint, params=params)
+        return await self._make_request(HttpMethod.GET, endpoint, params=params)
 
     async def post(self, endpoint: str, data: JsonDict | None = None) -> JsonDict | None:
-        return await self.make_request(HttpMethod.POST, endpoint, data)
+        return await self._make_request(HttpMethod.POST, endpoint, data)
 
     async def patch(self, endpoint: str, data: JsonDict | None = None) -> JsonDict | None:
-        return await self.make_request(HttpMethod.PATCH, endpoint, data)
+        return await self._make_request(HttpMethod.PATCH, endpoint, data)
 
     async def delete(self, endpoint: str) -> JsonDict | None:
-        return await self.make_request(HttpMethod.DELETE, endpoint)
+        return await self._make_request(HttpMethod.DELETE, endpoint)
 
-    async def make_request(
+    async def _make_request(
         self,
         method: HttpMethod,
         endpoint: str,
         data: JsonDict | None = None,
         params: JsonDict | None = None,
     ) -> JsonDict | None:
-        """
-        Executes an HTTP request and returns the data or None on error.
-
-        Args:
-            method: HTTP method to use
-            endpoint: API endpoint
-            data: Request body data (for POST/PATCH)
-            params: Query parameters (for GET requests)
-        """
         await self._ensure_initialized()
 
         url = f"{self.BASE_URL}/{endpoint.lstrip('/')}"
@@ -141,7 +126,6 @@ class NotionHttpClient(LoggingMixin):
         status_code = e.response.status_code
         response_text = e.response.text
 
-        # Map HTTP status codes to specific business exceptions
         if status_code == 401:
             raise NotionAuthenticationError(
                 "Invalid or missing API key. Please check your Notion integration token.",

notionary/page/content/parser/factory.py

@@ -1,6 +1,7 @@
 from notionary.blocks.rich_text.markdown_rich_text_converter import (
     MarkdownRichTextConverter,
 )
+from notionary.file_upload.service import NotionFileUpload
 from notionary.page.content.parser.parsers import (
     AudioParser,
     BookmarkParser,
@@ -37,9 +38,11 @@ class ConverterChainFactory:
         self,
         rich_text_converter: MarkdownRichTextConverter | None = None,
         syntax_registry: SyntaxRegistry | None = None,
+        file_upload_service: NotionFileUpload | None = None,
     ) -> None:
         self._rich_text_converter = rich_text_converter or MarkdownRichTextConverter()
         self._syntax_registry = syntax_registry or SyntaxRegistry()
+        self._file_upload_service = file_upload_service
 
     def create(self) -> LineParser:
         # multi-line (structural) blocks
@@ -186,19 +189,19 @@ class ConverterChainFactory:
         return EmbedParser(syntax_registry=self._syntax_registry)
 
     def _create_image_parser(self) -> ImageParser:
-        return ImageParser(syntax_registry=self._syntax_registry)
+        return ImageParser(syntax_registry=self._syntax_registry, file_upload_service=self._file_upload_service)
 
     def _create_video_parser(self) -> VideoParser:
-        return VideoParser(syntax_registry=self._syntax_registry)
+        return VideoParser(syntax_registry=self._syntax_registry, file_upload_service=self._file_upload_service)
 
     def _create_audio_parser(self) -> AudioParser:
-        return AudioParser(syntax_registry=self._syntax_registry)
+        return AudioParser(syntax_registry=self._syntax_registry, file_upload_service=self._file_upload_service)
 
     def _create_file_parser(self) -> FileParser:
-        return FileParser(syntax_registry=self._syntax_registry)
+        return FileParser(syntax_registry=self._syntax_registry, file_upload_service=self._file_upload_service)
 
     def _create_pdf_parser(self) -> PdfParser:
-        return PdfParser(syntax_registry=self._syntax_registry)
+        return PdfParser(syntax_registry=self._syntax_registry, file_upload_service=self._file_upload_service)
 
     def _create_caption_parser(self) -> CaptionParser:
         return CaptionParser(

notionary/page/content/parser/parsers/audio.py

@@ -1,40 +1,15 @@
 from typing import override
 
-from notionary.blocks.schemas import (
-    CreateAudioBlock,
-    ExternalFile,
-    FileData,
-    FileType,
-)
-from notionary.page.content.parser.parsers.base import BlockParsingContext, LineParser
-from notionary.page.content.syntax import SyntaxRegistry
+from notionary.blocks.schemas import CreateAudioBlock, ExternalFileWithCaption
+from notionary.page.content.parser.parsers.file_like_block import FileLikeBlockParser
+from notionary.page.content.syntax import SyntaxDefinition, SyntaxRegistry
 
 
-class AudioParser(LineParser):
-    def __init__(self, syntax_registry: SyntaxRegistry) -> None:
-        super().__init__(syntax_registry)
-        self._syntax = syntax_registry.get_audio_syntax()
-
+class AudioParser(FileLikeBlockParser[CreateAudioBlock]):
     @override
-    def _can_handle(self, context: BlockParsingContext) -> bool:
-        if context.is_inside_parent_context():
-            return False
-        return self._syntax.regex_pattern.search(context.line) is not None
+    def _get_syntax(self, syntax_registry: SyntaxRegistry) -> SyntaxDefinition:
+        return syntax_registry.get_audio_syntax()
 
     @override
-    async def _process(self, context: BlockParsingContext) -> None:
-        url = self._extract_url(context.line)
-        if url is None:
-            return
-
-        audio_data = FileData(
-            type=FileType.EXTERNAL,
-            external=ExternalFile(url=url),
-            caption=[],
-        )
-        block = CreateAudioBlock(audio=audio_data)
-        context.result_blocks.append(block)
-
-    def _extract_url(self, line: str) -> str | None:
-        match = self._syntax.regex_pattern.search(line)
-        return match.group(1).strip() if match else None
+    def _create_block(self, file_data: ExternalFileWithCaption) -> CreateAudioBlock:
+        return CreateAudioBlock(audio=file_data)

notionary/page/content/parser/parsers/embed.py

@@ -1,5 +1,3 @@
-"""Parser for embed blocks."""
-
 from typing import override
 
 from notionary.blocks.schemas import CreateEmbedBlock, EmbedData

notionary/page/content/parser/parsers/file.py

@@ -1,42 +1,15 @@
-"""Parser for file blocks."""
-
 from typing import override
 
-from notionary.blocks.schemas import (
-    CreateFileBlock,
-    ExternalFile,
-    FileData,
-    FileType,
-)
-from notionary.page.content.parser.parsers.base import BlockParsingContext, LineParser
-from notionary.page.content.syntax import SyntaxRegistry
-
+from notionary.blocks.schemas import CreateFileBlock, ExternalFileWithCaption
+from notionary.page.content.parser.parsers.file_like_block import FileLikeBlockParser
+from notionary.page.content.syntax import SyntaxDefinition, SyntaxRegistry
 
-class FileParser(LineParser):
-    def __init__(self, syntax_registry: SyntaxRegistry) -> None:
-        super().__init__(syntax_registry)
-        self._syntax = syntax_registry.get_file_syntax()
 
+class FileParser(FileLikeBlockParser[CreateFileBlock]):
     @override
-    def _can_handle(self, context: BlockParsingContext) -> bool:
-        if context.is_inside_parent_context():
-            return False
-        return self._syntax.regex_pattern.search(context.line) is not None
+    def _get_syntax(self, syntax_registry: SyntaxRegistry) -> SyntaxDefinition:
+        return syntax_registry.get_file_syntax()
 
     @override
-    async def _process(self, context: BlockParsingContext) -> None:
-        url = self._extract_url(context.line)
-        if not url:
-            return
-
-        file_data = FileData(
-            type=FileType.EXTERNAL,
-            external=ExternalFile(url=url),
-            caption=[],
-        )
-        block = CreateFileBlock(file=file_data)
-        context.result_blocks.append(block)
-
-    def _extract_url(self, line: str) -> str | None:
-        match = self._syntax.regex_pattern.search(line)
-        return match.group(1).strip() if match else None
+    def _create_block(self, file_data: ExternalFileWithCaption) -> CreateFileBlock:
+        return CreateFileBlock(file=file_data)

notionary/page/content/parser/parsers/file_like_block.py

@@ -0,0 +1,89 @@
+from abc import abstractmethod
+from pathlib import Path
+from typing import Generic, TypeVar, override
+
+from notionary.blocks.schemas import (
+    ExternalFileWithCaption,
+    FileUploadFileWithCaption,
+    FileWithCaption,
+)
+from notionary.exceptions.file_upload import UploadFailedError, UploadTimeoutError
+from notionary.file_upload.service import NotionFileUpload
+from notionary.page.content.parser.parsers.base import BlockParsingContext, LineParser
+from notionary.page.content.syntax import SyntaxRegistry
+from notionary.page.content.syntax.models import SyntaxDefinition
+from notionary.shared.models.file import ExternalFileData, FileUploadedFileData
+from notionary.utils.mixins.logging import LoggingMixin
+
+_TBlock = TypeVar("_TBlock")
+
+
+class FileLikeBlockParser(LineParser, LoggingMixin, Generic[_TBlock]):
+    def __init__(self, syntax_registry: SyntaxRegistry, file_upload_service: NotionFileUpload | None = None) -> None:
+        super().__init__(syntax_registry)
+        self._syntax = self._get_syntax(syntax_registry)
+        self._file_upload_service = file_upload_service or NotionFileUpload()
+
+    @abstractmethod
+    def _get_syntax(self, syntax_registry: SyntaxRegistry) -> SyntaxDefinition:
+        pass
+
+    @abstractmethod
+    def _create_block(self, file_data: FileWithCaption) -> _TBlock:
+        pass
+
+    @override
+    def _can_handle(self, context: BlockParsingContext) -> bool:
+        if context.is_inside_parent_context():
+            return False
+        return self._syntax.regex_pattern.search(context.line) is not None
+
+    @override
+    async def _process(self, context: BlockParsingContext) -> None:
+        path_or_url = self._extract_path_or_url(context.line)
+        if not path_or_url:
+            return
+
+        try:
+            if self._is_external_url(path_or_url):
+                file_data = ExternalFileWithCaption(external=ExternalFileData(url=path_or_url))
+            else:
+                file_data = await self._upload_local_file(path_or_url)
+
+            block = self._create_block(file_data)
+            context.result_blocks.append(block)
+
+        except FileNotFoundError:
+            self.logger.warning("File not found: '%s' - skipping block", path_or_url)
+        except PermissionError:
+            self.logger.warning("No permission to read file: '%s' - skipping block", path_or_url)
+        except IsADirectoryError:
+            self.logger.warning("Path is a directory, not a file: '%s' - skipping block", path_or_url)
+        except (UploadFailedError, UploadTimeoutError) as e:
+            self.logger.warning("Upload failed for '%s': %s - skipping block", path_or_url, e)
+        except OSError as e:
+            self.logger.warning("IO error reading file '%s': %s - skipping block", path_or_url, e)
+        except Exception as e:
+            self.logger.warning("Unexpected error processing file '%s': %s - skipping block", path_or_url, e)
+
+    def _extract_path_or_url(self, line: str) -> str | None:
+        match = self._syntax.regex_pattern.search(line)
+        return match.group(1).strip() if match else None
+
+    def _is_external_url(self, path_or_url: str) -> bool:
+        if path_or_url.startswith("http://") or path_or_url.startswith("https://"):
+            return True
+
+        if path_or_url.startswith("data:"):
+            return True
+
+        return path_or_url.startswith("/")
+
+    async def _upload_local_file(self, file_path: str) -> FileUploadFileWithCaption:
+        path = Path(file_path)
+        self.logger.debug("Uploading local file: '%s'", path)
+        upload_response = await self._file_upload_service.upload_file(path)
+
+        return FileUploadFileWithCaption(
+            file_upload=FileUploadedFileData(id=upload_response.id),
+        )