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

notionary/page/service.py

@@ -11,62 +11,34 @@ from notionary.page.content.service import PageContentService
 from notionary.page.page_http_client import NotionPageHttpClient
 from notionary.page.page_metadata_update_client import PageMetadataUpdateClient
 from notionary.page.properties.factory import PagePropertyHandlerFactory
-from notionary.page.properties.models import PageTitleProperty
+from notionary.page.properties.schemas import PageTitleProperty
 from notionary.page.properties.service import PagePropertyHandler
 from notionary.page.schemas import NotionPageDto
-from notionary.shared.entity.dto_parsers import (
-    extract_cover_image_url_from_dto,
-    extract_emoji_icon_from_dto,
-    extract_external_icon_url_from_dto,
-)
 from notionary.shared.entity.service import Entity
-from notionary.user.schemas import PartialUserDto
 from notionary.workspace.query.service import WorkspaceQueryService
 
 
 class NotionPage(Entity):
     def __init__(
         self,
-        id: str,
+        dto: NotionPageDto,
         title: str,
-        created_time: str,
-        created_by: PartialUserDto,
-        last_edited_time: str,
-        last_edited_by: PartialUserDto,
-        url: str,
-        archived: bool,
-        in_trash: bool,
         page_property_handler: PagePropertyHandler,
         block_client: NotionBlockHttpClient,
         comment_service: CommentService,
         page_content_service: PageContentService,
         metadata_update_client: PageMetadataUpdateClient,
-        public_url: str | None = None,
-        emoji_icon: str | None = None,
-        external_icon_url: str | None = None,
-        cover_image_url: str | None = None,
     ) -> None:
-        super().__init__(
-            id=id,
-            created_time=created_time,
-            created_by=created_by,
-            last_edited_time=last_edited_time,
-            last_edited_by=last_edited_by,
-            in_trash=in_trash,
-            emoji_icon=emoji_icon,
-            external_icon_url=external_icon_url,
-            cover_image_url=cover_image_url,
-        )
+        super().__init__(dto=dto)
+
         self._title = title
-        self._archived = archived
-        self._url = url
-        self._public_url = public_url
+        self._archived = dto.archived
 
         self._block_client = block_client
         self._comment_service = comment_service
         self._page_content_service = page_content_service
-        self.properties = page_property_handler
         self._metadata_update_client = metadata_update_client
+        self.properties = page_property_handler
 
     @classmethod
     async def from_id(
@@ -75,8 +47,8 @@ class NotionPage(Entity):
         page_property_handler_factory: PagePropertyHandlerFactory | None = None,
     ) -> Self:
         factory = page_property_handler_factory or PagePropertyHandlerFactory()
-        response = await cls._fetch_page_dto(page_id)
-        return await cls._create_from_dto(response, factory)
+        dto = await cls._fetch_page_dto(page_id)
+        return await cls._create_from_dto(dto, factory)
 
     @classmethod
     async def from_title(
@@ -95,76 +67,43 @@ class NotionPage(Entity):
     @classmethod
     async def _create_from_dto(
         cls,
-        response: NotionPageDto,
+        dto: NotionPageDto,
         page_property_handler_factory: PagePropertyHandlerFactory,
     ) -> Self:
-        title_task = cls._extract_title_from_dto(response)
-        page_property_handler = page_property_handler_factory.create_from_page_response(response)
+        title_task = cls._extract_title_from_dto(dto)
+        page_property_handler = page_property_handler_factory.create_from_page_response(dto)
 
         title = await title_task
 
         return cls._create_with_dependencies(
-            id=response.id,
+            dto=dto,
             title=title,
-            created_time=response.created_time,
-            created_by=response.created_by,
-            last_edited_time=response.last_edited_time,
-            last_edited_by=response.last_edited_by,
-            archived=response.archived,
-            in_trash=response.in_trash,
-            url=response.url,
             page_property_handler=page_property_handler,
-            public_url=response.public_url,
-            emoji_icon=extract_emoji_icon_from_dto(response),
-            external_icon_url=extract_external_icon_url_from_dto(response),
-            cover_image_url=extract_cover_image_url_from_dto(response),
         )
 
     @classmethod
     def _create_with_dependencies(
         cls,
-        id: str,
+        dto: NotionPageDto,
         title: str,
-        created_time: str,
-        created_by: PartialUserDto,
-        last_edited_time: str,
-        last_edited_by: PartialUserDto,
-        url: str,
-        archived: bool,
-        in_trash: bool,
         page_property_handler: PagePropertyHandler,
-        public_url: str | None = None,
-        emoji_icon: str | None = None,
-        external_icon_url: str | None = None,
-        cover_image_url: str | None = None,
     ) -> Self:
         block_client = NotionBlockHttpClient()
         comment_service = CommentService()
 
         page_content_service_factory = PageContentServiceFactory()
-        page_content_service = page_content_service_factory.create(page_id=id, block_client=block_client)
+        page_content_service = page_content_service_factory.create(page_id=dto.id, block_client=block_client)
 
-        metadata_update_client = PageMetadataUpdateClient(page_id=id)
+        metadata_update_client = PageMetadataUpdateClient(page_id=dto.id)
 
         return cls(
-            id=id,
+            dto=dto,
             title=title,
-            created_time=created_time,
-            created_by=created_by,
-            last_edited_time=last_edited_time,
-            last_edited_by=last_edited_by,
-            url=url,
-            archived=archived,
-            in_trash=in_trash,
             page_property_handler=page_property_handler,
             block_client=block_client,
             comment_service=comment_service,
             page_content_service=page_content_service,
             metadata_update_client=metadata_update_client,
-            public_url=public_url,
-            emoji_icon=emoji_icon,
-            external_icon_url=external_icon_url,
-            cover_image_url=cover_image_url,
         )
 
     @staticmethod
@@ -185,8 +124,8 @@ class NotionPage(Entity):
         return self._title
 
     @property
-    def url(self) -> str:
-        return self._url
+    def archived(self) -> bool:
+        return self._archived
 
     @property
     def markdown_builder() -> MarkdownBuilder:

notionary/shared/entity/dto_parsers.py

@@ -1,40 +1,5 @@
-from typing import cast
-
 from notionary.blocks.rich_text.rich_text_markdown_converter import RichTextToMarkdownConverter
-from notionary.shared.entity.schemas import Describable, EntityResponseDto, Titled
-from notionary.shared.models.cover import CoverType
-from notionary.shared.models.icon import IconType
-from notionary.shared.models.parent import DatabaseParent, DataSourceParent, ParentType
-
-
-def extract_emoji_icon_from_dto(entity_dto: EntityResponseDto) -> str | None:
-    if not entity_dto.icon or entity_dto.icon.type != IconType.EMOJI:
-        return None
-    return entity_dto.icon.emoji
-
-
-def extract_external_icon_url_from_dto(entity_dto: EntityResponseDto) -> str | None:
-    if not entity_dto.icon or entity_dto.icon.type != IconType.EXTERNAL:
-        return None
-    return entity_dto.icon.external.url if entity_dto.icon.external else None
-
-
-def extract_cover_image_url_from_dto(entity_dto: EntityResponseDto) -> str | None:
-    if not entity_dto.cover or entity_dto.cover.type != CoverType.EXTERNAL:
-        return None
-    return entity_dto.cover.external.url if entity_dto.cover.external else None
-
-
-def extract_database_id(entity_dto: EntityResponseDto) -> str | None:
-    if entity_dto.parent.type == ParentType.DATA_SOURCE_ID:
-        data_source_parent = cast(DataSourceParent, entity_dto.parent)
-        return data_source_parent.database_id if data_source_parent else None
-
-    if entity_dto.parent.type == ParentType.DATABASE_ID:
-        database_parent = cast(DatabaseParent, entity_dto.parent)
-        return database_parent.database_id if database_parent else None
-
-    return None
+from notionary.shared.entity.schemas import Describable, Titled
 
 
 async def extract_title(

notionary/shared/entity/entity_metadata_update_client.py

@@ -1,8 +1,8 @@
 from abc import ABC, abstractmethod
 
 from notionary.shared.entity.schemas import EntityResponseDto, NotionEntityUpdateDto
-from notionary.shared.models.cover import NotionCover
-from notionary.shared.models.icon import EmojiIcon, ExternalIcon
+from notionary.shared.models.file import ExternalFile, FileUploadFile
+from notionary.shared.models.icon import EmojiIcon, Icon
 
 
 class EntityMetadataUpdateClient(ABC):
@@ -15,7 +15,14 @@ class EntityMetadataUpdateClient(ABC):
         return await self.patch_metadata(update_dto)
 
     async def patch_external_icon(self, icon_url: str) -> EntityResponseDto:
-        icon = ExternalIcon.from_url(icon_url)
+        icon = ExternalFile.from_url(icon_url)
+        return await self._patch_icon(icon)
+
+    async def patch_icon_from_file_upload(self, file_upload_id: str) -> EntityResponseDto:
+        icon = FileUploadFile.from_id(id=file_upload_id)
+        return await self._patch_icon(icon)
+
+    async def _patch_icon(self, icon: Icon) -> EntityResponseDto:
         update_dto = NotionEntityUpdateDto(icon=icon)
         return await self.patch_metadata(update_dto)
 
@@ -24,7 +31,14 @@ class EntityMetadataUpdateClient(ABC):
         return await self.patch_metadata(update_dto)
 
     async def patch_external_cover(self, cover_url: str) -> EntityResponseDto:
-        cover = NotionCover.from_url(cover_url)
+        cover = ExternalFile.from_url(cover_url)
+        return await self._patch_cover(cover)
+
+    async def patch_cover_from_file_upload(self, file_upload_id: str) -> EntityResponseDto:
+        cover = FileUploadFile.from_id(id=file_upload_id)
+        return await self._patch_cover(cover)
+
+    async def _patch_cover(self, cover: Icon) -> EntityResponseDto:
         update_dto = NotionEntityUpdateDto(cover=cover)
         return await self.patch_metadata(update_dto)
 

notionary/shared/entity/schemas.py

@@ -4,26 +4,26 @@ from typing import Protocol
 from pydantic import BaseModel
 
 from notionary.blocks.rich_text.models import RichText
-from notionary.shared.models.cover import NotionCover
+from notionary.shared.models.file import File
 from notionary.shared.models.icon import Icon
 from notionary.shared.models.parent import Parent
 from notionary.user.schemas import PartialUserDto
 
 
-class EntityWorkspaceQueryObjectType(StrEnum):
+class _EntityType(StrEnum):
     PAGE = "page"
     DATA_SOURCE = "data_source"
     DATABASE = "database"
 
 
 class EntityResponseDto(BaseModel):
-    object: EntityWorkspaceQueryObjectType
+    object: _EntityType
     id: str
     created_time: str
     created_by: PartialUserDto
     last_edited_time: str
     last_edited_by: PartialUserDto
-    cover: NotionCover | None = None
+    cover: File | None = None
     icon: Icon | None = None
     parent: Parent
     in_trash: bool
@@ -32,8 +32,8 @@ class EntityResponseDto(BaseModel):
 
 
 class NotionEntityUpdateDto(BaseModel):
-    icon: Icon | None = None
-    cover: NotionCover | None = None
+    icon: File | None = None
+    cover: File | None = None
     in_trash: bool | None = None
 
 

notionary/shared/entity/service.py

@@ -1,44 +1,82 @@
-from __future__ import annotations
-
 import random
 from abc import ABC, abstractmethod
 from collections.abc import Sequence
-from typing import TYPE_CHECKING, Self
+from pathlib import Path
+from typing import Self, cast
 
+from notionary.file_upload.service import NotionFileUpload
 from notionary.shared.entity.entity_metadata_update_client import EntityMetadataUpdateClient
-from notionary.user.schemas import PartialUserDto
+from notionary.shared.entity.schemas import EntityResponseDto
+from notionary.shared.models.file import ExternalFile, FileType, NotionHostedFile
+from notionary.shared.models.icon import EmojiIcon, IconType
+from notionary.shared.models.parent import ParentType
+from notionary.user.base import BaseUser
 from notionary.user.service import UserService
 from notionary.utils.mixins.logging import LoggingMixin
 from notionary.utils.uuid_utils import extract_uuid
 
-if TYPE_CHECKING:
-    from notionary.user.base import BaseUser
-
 
 class Entity(LoggingMixin, ABC):
     def __init__(
         self,
-        id: str,
-        created_time: str,
-        created_by: PartialUserDto,
-        last_edited_time: str,
-        last_edited_by: PartialUserDto,
-        in_trash: bool,
-        emoji_icon: str | None = None,
-        external_icon_url: str | None = None,
-        cover_image_url: str | None = None,
+        dto: EntityResponseDto,
         user_service: UserService | None = None,
+        file_upload_service: NotionFileUpload | None = None,
     ) -> None:
-        self._id = id
-        self._created_time = created_time
-        self._created_by = created_by
-        self._last_edited_time = last_edited_time
-        self._last_edited_by = last_edited_by
-        self._emoji_icon = emoji_icon
-        self._external_icon_url = external_icon_url
-        self._cover_image_url = cover_image_url
-        self._in_trash = in_trash
+        self._id = dto.id
+        self._created_time = dto.created_time
+        self._created_by = dto.created_by
+        self._last_edited_time = dto.last_edited_time
+        self._last_edited_by = dto.last_edited_by
+        self._in_trash = dto.in_trash
+        self._parent = dto.parent
+        self._url = dto.url
+        self._public_url = dto.public_url
+
+        self._emoji_icon = self._extract_emoji_icon(dto)
+        self._external_icon_url = self._extract_external_icon_url(dto)
+        self._cover_image_url = self._extract_cover_image_url(dto)
+
         self._user_service = user_service or UserService()
+        self._file_upload_service = file_upload_service or NotionFileUpload()
+
+    @staticmethod
+    def _extract_emoji_icon(dto: EntityResponseDto) -> str | None:
+        if dto.icon is None:
+            return None
+        if dto.icon.type is not IconType.EMOJI:
+            return None
+
+        emoji_icon = cast(EmojiIcon, dto.icon)
+        return emoji_icon.emoji
+
+    @staticmethod
+    def _extract_external_icon_url(dto: EntityResponseDto) -> str | None:
+        if dto.icon is None:
+            return None
+
+        if dto.icon.type == IconType.EXTERNAL:
+            external_icon = cast(ExternalFile, dto.icon)
+            return external_icon.external.url
+        elif dto.icon.type == IconType.FILE:
+            notion_file_icon = cast(NotionHostedFile, dto.icon)
+            return notion_file_icon.file.url
+
+        return None
+
+    @staticmethod
+    def _extract_cover_image_url(dto: EntityResponseDto) -> str | None:
+        if dto.cover is None:
+            return None
+
+        if dto.cover.type == FileType.EXTERNAL:
+            external_cover = cast(ExternalFile, dto.cover)
+            return external_cover.external.url
+        elif dto.cover.type == FileType.FILE:
+            notion_file_cover = cast(NotionHostedFile, dto.cover)
+            return notion_file_cover.file.url
+
+        return None
 
     @classmethod
     @abstractmethod
@@ -59,10 +97,7 @@ class Entity(LoggingMixin, ABC):
 
     @property
     @abstractmethod
-    def _entity_metadata_update_client(self) -> EntityMetadataUpdateClient:
-        # functionality for updating properties like title, icon, cover, archive status depends on interface for template like implementation
-        # has to be implementated by inheritants to correctly use the methods below
-        ...
+    def _entity_metadata_update_client(self) -> EntityMetadataUpdateClient: ...
 
     @property
     def id(self) -> str:
@@ -93,12 +128,35 @@ class Entity(LoggingMixin, ABC):
         return self._cover_image_url
 
     @property
-    def created_by(self) -> PartialUserDto:
-        return self._created_by
+    def url(self) -> str:
+        return self._url
 
     @property
-    def last_edited_by(self) -> PartialUserDto:
-        return self._last_edited_by
+    def public_url(self) -> str | None:
+        return self._public_url
+
+    def get_parent_database_id_if_present(self) -> str | None:
+        if self._parent.type == ParentType.DATABASE_ID:
+            return self._parent.database_id
+        return None
+
+    def get_parent_data_source_id_if_present(self) -> str | None:
+        if self._parent.type == ParentType.DATA_SOURCE_ID:
+            return self._parent.data_source_id
+        return None
+
+    def get_parent_page_id_if_present(self) -> str | None:
+        if self._parent.type == ParentType.PAGE_ID:
+            return self._parent.page_id
+        return None
+
+    def get_parent_block_id_if_present(self) -> str | None:
+        if self._parent.type == ParentType.BLOCK_ID:
+            return self._parent.block_id
+        return None
+
+    def is_workspace_parent(self) -> bool:
+        return self._parent.type == ParentType.WORKSPACE
 
     async def get_created_by_user(self) -> BaseUser | None:
         return await self._user_service.get_user_by_id(self._created_by.id)
@@ -108,15 +166,26 @@ class Entity(LoggingMixin, ABC):
 
     async def set_emoji_icon(self, emoji: str) -> None:
         entity_response = await self._entity_metadata_update_client.patch_emoji_icon(emoji)
-        self._emoji_icon = entity_response.icon.emoji if entity_response.icon else None
+        self._emoji_icon = self._extract_emoji_icon(entity_response)
         self._external_icon_url = None
 
     async def set_external_icon(self, icon_url: str) -> None:
         entity_response = await self._entity_metadata_update_client.patch_external_icon(icon_url)
         self._emoji_icon = None
-        self._external_icon_url = (
-            entity_response.icon.external.url if entity_response.icon and entity_response.icon.external else None
-        )
+        self._external_icon_url = self._extract_external_icon_url(entity_response)
+
+    async def set_icon_from_file(self, file_path: Path, filename: str | None = None) -> None:
+        upload_response = await self._file_upload_service.upload_file(file_path, filename)
+        await self._set_icon_from_file_upload(upload_response.id)
+
+    async def set_icon_from_bytes(self, file_content: bytes, filename: str, content_type: str | None = None) -> None:
+        upload_response = await self._file_upload_service.upload_from_bytes(file_content, filename, content_type)
+        await self._set_icon_from_file_upload(upload_response.id)
+
+    async def _set_icon_from_file_upload(self, file_upload_id: str) -> None:
+        entity_response = await self._entity_metadata_update_client.patch_icon_from_file_upload(file_upload_id)
+        self._emoji_icon = None
+        self._external_icon_url = self._extract_external_icon_url(entity_response)
 
     async def remove_icon(self) -> None:
         await self._entity_metadata_update_client.remove_icon()
@@ -125,9 +194,21 @@ class Entity(LoggingMixin, ABC):
 
     async def set_cover_image_by_url(self, image_url: str) -> None:
         entity_response = await self._entity_metadata_update_client.patch_external_cover(image_url)
-        self._cover_image_url = (
-            entity_response.cover.external.url if entity_response.cover and entity_response.cover.external else None
-        )
+        self._cover_image_url = self._extract_cover_image_url(entity_response)
+
+    async def set_cover_image_from_file(self, file_path: Path, filename: str | None = None) -> None:
+        upload_response = await self._file_upload_service.upload_file(file_path, filename)
+        await self._set_cover_image_from_file_upload(upload_response.id)
+
+    async def set_cover_image_from_bytes(
+        self, file_content: bytes, filename: str, content_type: str | None = None
+    ) -> None:
+        upload_response = await self._file_upload_service.upload_from_bytes(file_content, filename, content_type)
+        await self._set_cover_image_from_file_upload(upload_response.id)
+
+    async def _set_cover_image_from_file_upload(self, file_upload_id: str) -> None:
+        entity_response = await self._entity_metadata_update_client.patch_cover_from_file_upload(file_upload_id)
+        self._cover_image_url = self._extract_cover_image_url(entity_response)
 
     async def set_random_gradient_cover(self) -> None:
         random_cover_url = self._get_random_gradient_cover()

notionary/shared/models/file.py

@@ -1,21 +1,49 @@
 from enum import StrEnum
-from typing import Literal, Self
+from typing import Annotated, Literal, Self
 
-from pydantic import BaseModel
+from pydantic import BaseModel, Field
 
 
 class FileType(StrEnum):
     EXTERNAL = "external"
+    FILE = "file"
+    FILE_UPLOAD = "file_upload"
 
 
-class ExternalFile(BaseModel):
+class ExternalFileData(BaseModel):
     url: str
 
 
-class ExternalRessource(BaseModel):
+class ExternalFile(BaseModel):
     type: Literal[FileType.EXTERNAL] = FileType.EXTERNAL
-    external: ExternalFile
+    external: ExternalFileData
 
     @classmethod
     def from_url(cls, url: str) -> Self:
-        return cls(external=ExternalFile(url=url))
+        return cls(external=ExternalFileData(url=url))
+
+
+class NotionHostedFileData(BaseModel):
+    url: str
+    expiry_time: str
+
+
+class NotionHostedFile(BaseModel):
+    type: Literal[FileType.FILE] = FileType.FILE
+    file: NotionHostedFileData
+
+
+class FileUploadedFileData(BaseModel):
+    id: str
+
+
+class FileUploadFile(BaseModel):
+    type: Literal[FileType.FILE_UPLOAD] = FileType.FILE_UPLOAD
+    file_upload: FileUploadedFileData
+
+    @classmethod
+    def from_id(cls, id: str) -> Self:
+        return cls(file_upload=FileUploadedFileData(id=id))
+
+
+type File = Annotated[ExternalFile | NotionHostedFile | FileUploadFile, Field(discriminator="type")]

notionary/shared/models/icon.py

@@ -1,14 +1,16 @@
 from enum import StrEnum
-from typing import Literal, Self
+from typing import Literal
 
 from pydantic import BaseModel
 
-from notionary.shared.models.file import ExternalFile
+from notionary.shared.models.file import File
 
 
 class IconType(StrEnum):
     EMOJI = "emoji"
     EXTERNAL = "external"
+    FILE = "file"
+    FILE_UPLOAD = "file_upload"
 
 
 class EmojiIcon(BaseModel):
@@ -16,13 +18,4 @@ class EmojiIcon(BaseModel):
     emoji: str
 
 
-class ExternalIcon(BaseModel):
-    type: Literal[IconType.EXTERNAL] = IconType.EXTERNAL
-    external: ExternalFile
-
-    @classmethod
-    def from_url(cls, url: str) -> Self:
-        return cls(external=ExternalFile(url=url))
-
-
-Icon = EmojiIcon | ExternalIcon
+type Icon = EmojiIcon | File

notionary/user/bot.py

@@ -20,6 +20,18 @@ class BotUser(BaseUser):
         self._workspace_file_upload_limit_in_bytes = workspace_file_upload_limit_in_bytes
         self._owner_type = owner_type
 
+    @property
+    def workspace_name(self) -> str | None:
+        return self._workspace_name
+
+    @property
+    def workspace_file_upload_limit_in_bytes(self) -> int:
+        return self._workspace_file_upload_limit_in_bytes
+
+    @property
+    def owner_type(self) -> WorkspaceOwnerType | None:
+        return self._owner_type
+
     @classmethod
     def _get_expected_user_type(cls) -> UserType:
         return UserType.BOT
@@ -54,17 +66,5 @@ class BotUser(BaseUser):
             owner_type=owner_type,
         )
 
-    @property
-    def workspace_name(self) -> str | None:
-        return self._workspace_name
-
-    @property
-    def workspace_file_upload_limit_in_bytes(self) -> int:
-        return self._workspace_file_upload_limit_in_bytes
-
-    @property
-    def owner_type(self) -> WorkspaceOwnerType | None:
-        return self._owner_type
-
     def __repr__(self) -> str:
         return f"BotUser(id={self._id!r}, name={self._name!r}, avatar_url={self._avatar_url!r}, workspace_name={self._workspace_name!r}, workspace_file_upload_limit_in_bytes={self._workspace_file_upload_limit_in_bytes!r}, owner_type={self._owner_type!r})"

notionary/utils/decorators.py

@@ -9,10 +9,10 @@ P = ParamSpec("P")
 R = TypeVar("R")
 T = TypeVar("T")
 
-type SyncFunc = Callable[P, R]
-type AsyncFunc = Callable[P, Coroutine[Any, Any, R]]
-type SyncDecorator = Callable[[SyncFunc], SyncFunc]
-type AsyncDecorator = Callable[[AsyncFunc], AsyncFunc]
+type _SyncFunc = Callable[P, R]
+type _AsyncFunc = Callable[P, Coroutine[Any, Any, R]]
+type _SyncDecorator = Callable[[_SyncFunc], _SyncFunc]
+type _AsyncDecorator = Callable[[_AsyncFunc], _AsyncFunc]
 
 
 def singleton(cls):
@@ -26,8 +26,8 @@ def singleton(cls):
     return wrapper
 
 
-def time_execution_sync(additional_text: str = "", min_duration_to_log: float = 0.25) -> SyncDecorator:
-    def decorator(func: SyncFunc) -> SyncFunc:
+def time_execution_sync(additional_text: str = "", min_duration_to_log: float = 0.25) -> _SyncDecorator:
+    def decorator(func: _SyncFunc) -> _SyncFunc:
         @functools.wraps(func)
         def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
             start_time = time.perf_counter()
@@ -49,8 +49,8 @@ def time_execution_sync(additional_text: str = "", min_duration_to_log: float =
 def time_execution_async(
     additional_text: str = "",
     min_duration_to_log: float = 0.25,
-) -> AsyncDecorator:
-    def decorator(func: AsyncFunc) -> AsyncFunc:
+) -> _AsyncDecorator:
+    def decorator(func: _AsyncFunc) -> _AsyncFunc:
         @functools.wraps(func)
         async def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
             start_time = time.perf_counter()