notionary 0.2.15__tar.gz → 0.2.16__tar.gz

{notionary-0.2.15 → notionary-0.2.16}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: notionary
-Version: 0.2.15
+Version: 0.2.16
 Summary: Python library for programmatic Notion workspace management - databases, pages, and content with advanced Markdown support
 License: MIT
 Author: Mathis Arends
@@ -14,6 +14,7 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Requires-Dist: httpx (>=0.28.0)
+Requires-Dist: posthog (>=6.3.1,<7.0.0)
 Requires-Dist: pydantic (>=2.11.4)
 Requires-Dist: python-dotenv (>=1.1.0)
 Project-URL: Homepage, https://github.com/mathisarends/notionary

{notionary-0.2.15 → notionary-0.2.16}/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-0.2.15 → notionary-0.2.16}/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-0.2.15 → notionary-0.2.16}/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,6 +27,8 @@ 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__(
@@ -52,6 +59,10 @@ class NotionDatabase(LoggingMixin):
         Create a NotionDatabase from a database ID using NotionDatabaseProvider.
         """
         provider = cls.get_database_provider()
+        cls.telemetry.capture(
+            DatabaseFactoryUsedEvent(factory_method="from_database_id")
+        )
+
         return await provider.get_database_by_id(id, token)
 
     @classmethod
@@ -65,6 +76,9 @@ 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
@@ -129,9 +143,7 @@ class NotionDatabase(LoggingMixin):
 
             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.id
-            )
+            self.database_provider.invalidate_database_cache(database_id=self.id)
             return True
 
         except Exception as e:
@@ -149,9 +161,7 @@ class NotionDatabase(LoggingMixin):
 
             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.id
-            )
+            self.database_provider.invalidate_database_cache(database_id=self.id)
             return True
 
         except Exception as e:
@@ -168,9 +178,7 @@ class NotionDatabase(LoggingMixin):
             )
 
             if result.cover and result.cover.external:
-                self.database_provider.invalidate_database_cache(
-                    database_id=self.id
-                )
+                self.database_provider.invalidate_database_cache(database_id=self.id)
                 return result.cover.external.url
             return None
 
@@ -197,9 +205,7 @@ class NotionDatabase(LoggingMixin):
             )
 
             if result.icon and result.icon.external:
-                self.database_provider.invalidate_database_cache(
-                    database_id=self.id
-                )
+                self.database_provider.invalidate_database_cache(database_id=self.id)
                 return result.icon.external.url
             return None
 
@@ -251,9 +257,15 @@ class NotionDatabase(LoggingMixin):
         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,7 +301,7 @@ 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
 
@@ -352,7 +364,9 @@ class NotionDatabase(LoggingMixin):
                 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

{notionary-0.2.15 → notionary-0.2.16}/notionary/database/notion_database_provider.py

@@ -57,18 +57,14 @@ class NotionDatabaseProvider(LoggingMixin, metaclass=SingletonMetaClass):
 
         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.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.id})"
-        )
+        self.logger.debug(f"Cached database: {database.title} (ID: {database.id})")
 
         return database
 

{notionary-0.2.15 → notionary-0.2.16}/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(
-                id=parent_database_id, token=token
-            )
+            await NotionDatabase.from_database_id(id=parent_database_id, token=token)
             if parent_database_id
             else None
         )

notionary-0.2.16/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-0.2.16/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-0.2.16/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-0.2.15 → notionary-0.2.16}/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",
 ]

{notionary-0.2.15 → notionary-0.2.16}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "notionary"
-version = "0.2.15"
+version = "0.2.16"
 description = "Python library for programmatic Notion workspace management - databases, pages, and content with advanced Markdown support"
 readme = "README.md"
 requires-python = ">=3.9"
@@ -12,6 +12,7 @@ dependencies = [
     "httpx>=0.28.0",
     "python-dotenv>=1.1.0",
     "pydantic>=2.11.4",
+    "posthog (>=6.3.1,<7.0.0)",
 ]
 
 [project.urls]
@@ -24,4 +25,5 @@ build-backend = "poetry.core.masonry.api"
 [tool.poetry.group.dev.dependencies]
 mkdocs = "^1.6.1"
 mkdocs-material = "^9.6.15"
+black = "^25.1.0"