notionary 0.2.14__py3-none-any.whl → 0.2.16__py3-none-any.whl

notionary/base_notion_client.py

@@ -194,7 +194,7 @@ class BaseNotionClient(LoggingMixin, ABC):
         token = next(
             (
                 os.getenv(var)
-                for var in ("NOTION_SECRET", "NOTION_API_KEY", "NOTION_TOKEN")
+                for var in ("NOTION_SECRET", "NOTION_INTEGRATION_KEY", "NOTION_TOKEN")
                 if os.getenv(var)
             ),
             None,

notionary/blocks/registry/block_registry.py

@@ -8,6 +8,12 @@ from notionary.page.markdown_syntax_prompt_generator import (
 from notionary.blocks.text_inline_formatter import TextInlineFormatter
 
 from notionary.blocks import NotionBlockElement
+from notionary.telemetry import (
+    ProductTelemetry,
+    NotionMarkdownSyntaxPromptEvent,
+    MarkdownToNotionConversionEvent,
+    NotionToMarkdownConversionEvent,
+)
 
 
 class BlockRegistry:
@@ -28,6 +34,8 @@ class BlockRegistry:
             for element in elements:
                 self.register(element)
 
+        self.telemetry = ProductTelemetry()
+
     def register(self, element_class: Type[NotionBlockElement]) -> bool:
         """
         Register an element class.
@@ -57,13 +65,13 @@ class BlockRegistry:
 
     def contains(self, element_class: Type[NotionBlockElement]) -> bool:
         """
-        Prüft, ob ein bestimmtes Element im Registry enthalten ist.
+        Checks if a specific element is contained in the registry.
 
         Args:
-            element_class: Die zu prüfende Element-Klasse
+            element_class: The element class to check.
 
         Returns:
-            bool: True, wenn das Element enthalten ist, sonst False
+            bool: True if the element is contained, otherwise False.
         """
         return element_class in self._elements
 
@@ -77,14 +85,28 @@ class BlockRegistry:
     def markdown_to_notion(self, text: str) -> Optional[Dict[str, Any]]:
         """Convert markdown to Notion block using registered elements."""
         handler = self.find_markdown_handler(text)
+
         if handler:
+            self.telemetry.capture(
+                MarkdownToNotionConversionEvent(
+                    handler_element_name=handler.__name__,
+                )
+            )
+
             return handler.markdown_to_notion(text)
         return None
 
     def notion_to_markdown(self, block: Dict[str, Any]) -> Optional[str]:
         """Convert Notion block to markdown using registered elements."""
         handler = self._find_notion_handler(block)
+
         if handler:
+            self.telemetry.capture(
+                NotionToMarkdownConversionEvent(
+                    handler_element_name=handler.__name__,
+                )
+            )
+
             return handler.notion_to_markdown(block)
         return None
 
@@ -106,6 +128,8 @@ class BlockRegistry:
         if "TextInlineFormatter" not in formatter_names:
             element_classes = element_classes + [TextInlineFormatter]
 
+        self.telemetry.capture(NotionMarkdownSyntaxPromptEvent())
+
         return MarkdownSyntaxPromptGenerator.generate_system_prompt(element_classes)
 
     def _find_notion_handler(

notionary/database/notion_database.py

@@ -13,6 +13,11 @@ from notionary.page.notion_page import NotionPage
 from notionary.database.notion_database_provider import NotionDatabaseProvider
 
 from notionary.database.filter_builder import FilterBuilder
+from notionary.telemetry import (
+    ProductTelemetry,
+    DatabaseFactoryUsedEvent,
+    QueryOperationEvent,
+)
 from notionary.util import factory_only, LoggingMixin
 
 
@@ -22,11 +27,13 @@ class NotionDatabase(LoggingMixin):
     Focused exclusively on creating basic pages and retrieving page managers
     for further page operations.
     """
+    
+    telemetry = ProductTelemetry()
 
     @factory_only("from_database_id", "from_database_name")
     def __init__(
         self,
-        database_id: str,
+        id: str,
         title: str,
         url: str,
         emoji_icon: Optional[str] = None,
@@ -36,7 +43,7 @@ class NotionDatabase(LoggingMixin):
         """
         Initialize the minimal database manager.
         """
-        self._database_id = database_id
+        self._id = id
         self._title = title
         self._url = url
         self._emoji_icon = emoji_icon
@@ -46,13 +53,17 @@ class NotionDatabase(LoggingMixin):
 
     @classmethod
     async def from_database_id(
-        cls, database_id: str, token: Optional[str] = None
+        cls, id: str, token: Optional[str] = None
     ) -> NotionDatabase:
         """
         Create a NotionDatabase from a database ID using NotionDatabaseProvider.
         """
         provider = cls.get_database_provider()
-        return await provider.get_database_by_id(database_id, token)
+        cls.telemetry.capture(
+            DatabaseFactoryUsedEvent(factory_method="from_database_id")
+        )
+
+        return await provider.get_database_by_id(id, token)
 
     @classmethod
     async def from_database_name(
@@ -65,12 +76,15 @@ class NotionDatabase(LoggingMixin):
         Create a NotionDatabase by finding a database with fuzzy matching on the title using NotionDatabaseProvider.
         """
         provider = cls.get_database_provider()
+        cls.telemetry.capture(
+            DatabaseFactoryUsedEvent(factory_method="from_database_name")
+        )
         return await provider.get_database_by_name(database_name, token, min_similarity)
 
     @property
-    def database_id(self) -> str:
+    def id(self) -> str:
         """Get the database ID (readonly)."""
-        return self._database_id
+        return self._id
 
     @property
     def title(self) -> str:
@@ -109,7 +123,7 @@ class NotionDatabase(LoggingMixin):
         """
         try:
             create_page_response: NotionPageResponse = await self.client.create_page(
-                parent_database_id=self.database_id
+                parent_database_id=self.id
             )
 
             return await NotionPage.from_page_id(page_id=create_page_response.id)
@@ -124,14 +138,12 @@ class NotionDatabase(LoggingMixin):
         """
         try:
             result = await self.client.update_database_title(
-                database_id=self.database_id, title=new_title
+                database_id=self.id, title=new_title
             )
 
             self._title = result.title[0].plain_text
             self.logger.info(f"Successfully updated database title to: {new_title}")
-            self.database_provider.invalidate_database_cache(
-                database_id=self.database_id
-            )
+            self.database_provider.invalidate_database_cache(database_id=self.id)
             return True
 
         except Exception as e:
@@ -144,14 +156,12 @@ class NotionDatabase(LoggingMixin):
         """
         try:
             result = await self.client.update_database_emoji(
-                database_id=self.database_id, emoji=new_emoji
+                database_id=self.id, emoji=new_emoji
             )
 
             self._emoji_icon = result.icon.emoji if result.icon else None
             self.logger.info(f"Successfully updated database emoji to: {new_emoji}")
-            self.database_provider.invalidate_database_cache(
-                database_id=self.database_id
-            )
+            self.database_provider.invalidate_database_cache(database_id=self.id)
             return True
 
         except Exception as e:
@@ -164,13 +174,11 @@ class NotionDatabase(LoggingMixin):
         """
         try:
             result = await self.client.update_database_cover_image(
-                database_id=self.database_id, image_url=image_url
+                database_id=self.id, image_url=image_url
             )
 
             if result.cover and result.cover.external:
-                self.database_provider.invalidate_database_cache(
-                    database_id=self.database_id
-                )
+                self.database_provider.invalidate_database_cache(database_id=self.id)
                 return result.cover.external.url
             return None
 
@@ -193,13 +201,11 @@ class NotionDatabase(LoggingMixin):
         """
         try:
             result = await self.client.update_database_external_icon(
-                database_id=self.database_id, icon_url=external_icon_url
+                database_id=self.id, icon_url=external_icon_url
             )
 
             if result.icon and result.icon.external:
-                self.database_provider.invalidate_database_cache(
-                    database_id=self.database_id
-                )
+                self.database_provider.invalidate_database_cache(database_id=self.id)
                 return result.icon.external.url
             return None
 
@@ -244,16 +250,22 @@ class NotionDatabase(LoggingMixin):
         """
         search_results: NotionQueryDatabaseResponse = (
             await self.client.query_database_by_title(
-                database_id=self.database_id, page_title=page_title
+                database_id=self.id, page_title=page_title
             )
         )
 
         page_results: List[NotionPage] = []
 
         for page in search_results.results:
-            page = NotionPage.from_page_id(page_id=page.id, token=self.client.token)
+            page = await NotionPage.from_page_id(
+                page_id=page.id, token=self.client.token
+            )
             page_results.append(page)
 
+        self.telemetry.capture(
+            QueryOperationEvent(query_type="query_database_by_title")
+        )
+
         return page_results
 
     async def iter_pages_updated_within(
@@ -289,14 +301,14 @@ class NotionDatabase(LoggingMixin):
             ISO 8601 timestamp string of the last database edit, or None if request fails.
         """
         try:
-            db = await self.client.get_database(self.database_id)
+            db = await self.client.get_database(self.id)
 
             return db.last_edited_time
 
         except Exception as e:
             self.logger.error(
                 "Error fetching last_edited_time for database %s: %s",
-                self.database_id,
+                self.id,
                 str(e),
             )
             return None
@@ -345,14 +357,16 @@ class NotionDatabase(LoggingMixin):
                 current_body["start_cursor"] = start_cursor
 
             result = await self.client.query_database(
-                database_id=self.database_id, query_data=current_body
+                database_id=self.id, query_data=current_body
             )
 
             if not result or not result.results:
                 return
 
             for page in result.results:
-                yield await NotionPage.from_page_id(page_id=page.id, token=self.client.token)
+                yield await NotionPage.from_page_id(
+                    page_id=page.id, token=self.client.token
+                )
 
             has_more = result.has_more
             start_cursor = result.next_cursor if has_more else None
@@ -368,7 +382,7 @@ class NotionDatabase(LoggingMixin):
         emoji_icon = cls._extract_emoji_icon(db_response)
 
         instance = cls(
-            database_id=db_response.id,
+            id=db_response.id,
             title=title,
             url=db_response.url,
             emoji_icon=emoji_icon,

notionary/database/notion_database_provider.py

@@ -55,20 +55,16 @@ class NotionDatabaseProvider(LoggingMixin, metaclass=SingletonMetaClass):
             database_name, token, min_similarity
         )
 
-        id_cache_key = self._create_id_cache_key(database.database_id)
+        id_cache_key = self._create_id_cache_key(database.id)
         if not force_refresh and id_cache_key in self._database_cache:
-            self.logger.debug(
-                f"Found existing cached database by ID: {database.database_id}"
-            )
+            self.logger.debug(f"Found existing cached database by ID: {database.id}")
             existing_database = self._database_cache[id_cache_key]
 
             self._database_cache[name_cache_key] = existing_database
             return existing_database
 
         self._cache_database(database, token, database_name)
-        self.logger.debug(
-            f"Cached database: {database.title} (ID: {database.database_id})"
-        )
+        self.logger.debug(f"Cached database: {database.title} (ID: {database.id})")
 
         return database
 
@@ -96,7 +92,7 @@ class NotionDatabaseProvider(LoggingMixin, metaclass=SingletonMetaClass):
         name_keys_to_remove = [
             cache_key
             for cache_key, cached_db in self._database_cache.items()
-            if (cache_key.startswith("name:") and cached_db.database_id == database_id)
+            if (cache_key.startswith("name:") and cached_db.id == database_id)
         ]
 
         for name_key in name_keys_to_remove:
@@ -173,7 +169,7 @@ class NotionDatabaseProvider(LoggingMixin, metaclass=SingletonMetaClass):
     ) -> None:
         """Cache a database by both ID and name (if provided)."""
         # Always cache by ID
-        id_cache_key = self._create_id_cache_key(database.database_id)
+        id_cache_key = self._create_id_cache_key(database.id)
         self._database_cache[id_cache_key] = database
 
         if original_name:
@@ -199,7 +195,7 @@ class NotionDatabaseProvider(LoggingMixin, metaclass=SingletonMetaClass):
         emoji_icon = self._extract_emoji_icon(db_response)
 
         instance = NotionDatabase(
-            database_id=db_response.id,
+            id=db_response.id,
             title=title,
             url=db_response.url,
             emoji_icon=emoji_icon,

notionary/page/notion_page.py

@@ -500,9 +500,7 @@ class NotionPage(LoggingMixin):
         parent_database_id = cls._extract_parent_database_id(page_response)
 
         parent_database = (
-            await NotionDatabase.from_database_id(
-                database_id=parent_database_id, token=token
-            )
+            await NotionDatabase.from_database_id(id=parent_database_id, token=token)
             if parent_database_id
             else None
         )

notionary/telemetry/__init__.py

@@ -0,0 +1,19 @@
+from .service import ProductTelemetry
+from .views import (
+    BaseTelemetryEvent,
+    DatabaseFactoryUsedEvent,
+    QueryOperationEvent,
+    NotionMarkdownSyntaxPromptEvent,
+    MarkdownToNotionConversionEvent,
+    NotionToMarkdownConversionEvent,
+)
+
+__all__ = [
+    "ProductTelemetry",
+    "BaseTelemetryEvent",
+    "DatabaseFactoryUsedEvent",
+    "QueryOperationEvent",
+    "NotionMarkdownSyntaxPromptEvent",
+    "MarkdownToNotionConversionEvent",
+    "NotionToMarkdownConversionEvent",
+]

notionary/telemetry/service.py

@@ -0,0 +1,136 @@
+import os
+import uuid
+from pathlib import Path
+from typing import Dict, Any, Optional
+from posthog import Posthog
+from dotenv import load_dotenv
+
+from notionary.telemetry.views import BaseTelemetryEvent
+from notionary.util import SingletonMetaClass, LoggingMixin
+
+load_dotenv()
+
+POSTHOG_EVENT_SETTINGS = {
+    "process_person_profile": True,
+}
+
+
+class ProductTelemetry(LoggingMixin, metaclass=SingletonMetaClass):
+    """
+    Anonymous telemetry for Notionary - enabled by default.
+    Disable via: ANONYMIZED_NOTIONARY_TELEMETRY=false
+    """
+
+    USER_ID_PATH = str(Path.home() / ".cache" / "notionary" / "telemetry_user_id")
+    PROJECT_API_KEY = "phc_gItKOx21Tc0l07C1taD0QPpqFnbWgWjVfRjF6z24kke"
+    HOST = "https://eu.i.posthog.com"
+    UNKNOWN_USER_ID = "UNKNOWN"
+
+    _logged_init_message = False
+    _curr_user_id = None
+
+    def __init__(self):
+        # Default: enabled, disable via environment variable
+        telemetry_setting = os.getenv("ANONYMIZED_NOTIONARY_TELEMETRY", "true").lower()
+        telemetry_disabled = telemetry_setting == "false"
+        self.debug_logging = os.getenv("NOTIONARY_DEBUG", "false").lower() == "true"
+
+        if telemetry_disabled:
+            self._posthog_client = None
+        else:
+            if not self._logged_init_message:
+                self.logger.info(
+                    "Anonymous telemetry enabled to improve Notionary. "
+                    "To disable: export ANONYMIZED_NOTIONARY_TELEMETRY=false"
+                )
+                self._logged_init_message = True
+
+            self._posthog_client = Posthog(
+                project_api_key=self.PROJECT_API_KEY,
+                host=self.HOST,
+                disable_geoip=True,
+                enable_exception_autocapture=True,
+            )
+
+            # Silence posthog's logging unless debug mode
+            if not self.debug_logging:
+                import logging
+
+                posthog_logger = logging.getLogger("posthog")
+                posthog_logger.disabled = True
+
+        if self._posthog_client is None:
+            self.logger.debug("Telemetry disabled")
+
+    def capture(self, event: BaseTelemetryEvent) -> None:
+        """
+        Safe event tracking that never affects library functionality
+
+        Args:
+            event: BaseTelemetryEvent instance to capture
+        """
+        if self._posthog_client is None:
+            return
+
+        self._direct_capture(event)
+
+    def _direct_capture(self, event: BaseTelemetryEvent) -> None:
+        """
+        Direct capture method - PostHog handles threading internally
+        Should not be thread blocking because posthog magically handles it
+        """
+        if self._posthog_client is None:
+            return
+
+        try:
+            self._posthog_client.capture(
+                distinct_id=self.user_id,
+                event=event.name,
+                properties={
+                    "library": "notionary",
+                    **event.properties,
+                    **POSTHOG_EVENT_SETTINGS,
+                },
+            )
+
+        except Exception as e:
+            self.logger.error(f"Failed to send telemetry event {event.name}: {e}")
+
+    def flush(self) -> None:
+        """
+        Flush pending events - simplified without threading complexity
+        """
+        if not self._posthog_client:
+            self.logger.debug("PostHog client not available, skipping flush.")
+            return
+
+        try:
+            self._posthog_client.flush()
+            self.logger.debug("PostHog client telemetry queue flushed.")
+        except Exception as e:
+            self.logger.error(f"Failed to flush PostHog client: {e}")
+
+    @property
+    def user_id(self) -> str:
+        """Anonymous, persistent user ID"""
+        if self._curr_user_id:
+            return self._curr_user_id
+
+        # File access may fail due to permissions or other reasons.
+        # We don't want to crash so we catch all exceptions.
+        try:
+            if not os.path.exists(self.USER_ID_PATH):
+                os.makedirs(os.path.dirname(self.USER_ID_PATH), exist_ok=True)
+                with open(self.USER_ID_PATH, "w") as f:
+                    new_user_id = str(uuid.uuid4())
+                    f.write(new_user_id)
+                self._curr_user_id = new_user_id
+            else:
+                with open(self.USER_ID_PATH, "r") as f:
+                    self._curr_user_id = f.read().strip()
+
+            return self._curr_user_id
+        except Exception as e:
+            self.logger.debug(f"Error getting user ID: {e}")
+            self._curr_user_id = self.UNKNOWN_USER_ID
+            return self._curr_user_id

notionary/telemetry/views.py

@@ -0,0 +1,64 @@
+from abc import ABC, abstractmethod
+from dataclasses import asdict, dataclass
+from typing import Any, Optional
+
+
+@dataclass
+class BaseTelemetryEvent(ABC):
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        pass
+
+    @property
+    def properties(self) -> dict[str, Any]:
+        return {k: v for k, v in asdict(self).items() if k != "name"}
+
+
+@dataclass
+class DatabaseFactoryUsedEvent(BaseTelemetryEvent):
+    """Event fired when a database factory method is used"""
+
+    factory_method: str
+
+    @property
+    def name(self) -> str:
+        return "database_factory_used"
+
+@dataclass
+class QueryOperationEvent(BaseTelemetryEvent):
+    """Event fired when a query operation is performed"""
+
+    query_type: str
+
+    @property
+    def name(self) -> str:
+        return "query_operation"
+    
+@dataclass
+class NotionMarkdownSyntaxPromptEvent(BaseTelemetryEvent):
+    """Event fired when Notion Markdown syntax is used"""
+
+    @property
+    def name(self) -> str:
+        return "notion_markdown_syntax_used"
+
+# Tracks markdown conversion
+@dataclass
+class MarkdownToNotionConversionEvent(BaseTelemetryEvent):
+    """Event fired when markdown is converted to Notion blocks"""
+    handler_element_name: Optional[str] = None  # e.g. "HeadingElement", "ParagraphElement"
+    
+    @property
+    def name(self) -> str:
+        return "markdown_to_notion_conversion"
+
+
+@dataclass
+class NotionToMarkdownConversionEvent(BaseTelemetryEvent):
+    """Event fired when Notion blocks are converted to markdown"""
+    handler_element_name: Optional[str] = None  # e.g. "HeadingElement", "ParagraphElement"  
+    
+    @property
+    def name(self) -> str:
+        return "notion_to_markdown_conversion"

notionary/util/__init__.py

@@ -3,6 +3,7 @@ from .singleton_decorator import singleton
 from .page_id_utils import format_uuid
 from .fuzzy_matcher import FuzzyMatcher
 from .factory_decorator import factory_only
+from .singleton_metaclass import SingletonMetaClass
 
 __all__ = [
     "LoggingMixin",
@@ -11,4 +12,5 @@ __all__ = [
     "FuzzyMatcher",
     "factory_only",
     "singleton",
+    "SingletonMetaClass",
 ]