notionary 0.2.10__py3-none-any.whl → 0.2.12__py3-none-any.whl

notionary/page/notion_page_factory.py

@@ -2,10 +2,12 @@ from typing import List, Optional, Dict, Any, Tuple
 from difflib import SequenceMatcher
 
 from notionary import NotionPage, NotionClient
-from notionary.util.logging_mixin import LoggingMixin
-from notionary.util.page_id_utils import format_uuid, extract_and_validate_page_id
-
+from notionary.telemetry import track_usage
+from notionary.util import LoggingMixin
+from notionary.util import format_uuid, extract_and_validate_page_id
+from notionary.util import singleton
 
+@singleton
 class NotionPageFactory(LoggingMixin):
     """
     Factory class for creating NotionPage instances.
@@ -14,10 +16,14 @@ class NotionPageFactory(LoggingMixin):
 
     MATCH_THRESHOLD = 0.6
     MAX_SUGGESTIONS = 5
+    PAGE_SIZE = 100
+    EARLY_STOP_THRESHOLD = 0.95
 
     @classmethod
+    @track_usage('page_factory_method_used', {'method': 'from_page_id'})
     def from_page_id(cls, page_id: str, token: Optional[str] = None) -> NotionPage:
         """Create a NotionPage from a page ID."""
+        
         try:
             formatted_id = format_uuid(page_id) or page_id
             page = NotionPage(page_id=formatted_id, token=token)
@@ -30,6 +36,7 @@ class NotionPageFactory(LoggingMixin):
             raise
 
     @classmethod
+    @track_usage('page_factory_method_used', {'method': 'from_url'})
     def from_url(cls, url: str, token: Optional[str] = None) -> NotionPage:
         """Create a NotionPage from a Notion URL."""
 
@@ -49,6 +56,7 @@ class NotionPageFactory(LoggingMixin):
             raise
 
     @classmethod
+    @track_usage('page_factory_method_used', {'method': 'from_page_name'})
     async def from_page_name(
         cls, page_name: str, token: Optional[str] = None
     ) -> NotionPage:
@@ -56,20 +64,16 @@ class NotionPageFactory(LoggingMixin):
         cls.logger.debug("Searching for page with name: %s", page_name)
 
         client = NotionClient(token=token)
-
+        
         try:
-            # Fetch pages
-            pages = await cls._search_pages(client)
-            if not pages:
-                cls.logger.warning("No pages found matching '%s'", page_name)
-                raise ValueError(f"No pages found matching '{page_name}'")
-
-            # Find best match
-            best_match, best_score, suggestions = cls._find_best_match(pages, page_name)
+            # Search with pagination and early stopping
+            best_match, best_score, all_suggestions = (
+                await cls._search_pages_with_matching(client, page_name)
+            )
 
             # Check if match is good enough
             if best_score < cls.MATCH_THRESHOLD or not best_match:
-                suggestion_msg = cls._format_suggestions(suggestions)
+                suggestion_msg = cls._format_suggestions(all_suggestions)
                 cls.logger.warning(
                     "No good match found for '%s'. Best score: %.2f",
                     page_name,
@@ -105,22 +109,157 @@ class NotionPageFactory(LoggingMixin):
             raise
 
     @classmethod
-    async def _search_pages(cls, client: NotionClient) -> List[Dict[str, Any]]:
-        """Search for pages using the Notion API."""
-        cls.logger.debug("Using search endpoint to find pages")
+    async def _search_pages_with_matching(
+        cls, client: NotionClient, query: str
+    ) -> Tuple[Optional[Dict[str, Any]], float, List[str]]:
+        """
+        Search for pages with pagination and find the best match.
+        Includes early stopping for performance optimization.
+        """
+        cls.logger.debug("Starting paginated search for query: %s", query)
+
+        best_match = None
+        best_score = 0
+        all_suggestions = []
+        page_count = 0
+
+        # Track suggestions across all pages
+        all_matches = []
+
+        next_cursor = None
+
+        while True:
+            # Fetch current page batch
+            pages_batch = await cls._fetch_pages_batch(client, next_cursor)
+
+            if not pages_batch:
+                cls.logger.debug("No more pages to fetch")
+                break
+
+            pages = pages_batch.get("results", [])
+            page_count += len(pages)
+            cls.logger.debug(
+                "Processing batch of %d pages (total processed: %d)",
+                len(pages),
+                page_count,
+            )
+
+            # Process current batch
+            batch_match, batch_score, batch_suggestions = cls._find_best_match_in_batch(
+                pages, query, best_score
+            )
+
+            # Update global best if we found a better match
+            if batch_score > best_score:
+                best_score = batch_score
+                best_match = batch_match
+                cls.logger.debug("New best match found with score: %.2f", best_score)
+
+            # Collect all matches for suggestions
+            for page in pages:
+                title = cls._extract_title_from_page(page)
+                score = SequenceMatcher(None, query.lower(), title.lower()).ratio()
+                all_matches.append((title, score))
+
+            # Early stopping: if we found a very good match, stop searching
+            if best_score >= cls.EARLY_STOP_THRESHOLD:
+                cls.logger.info(
+                    "Early stopping: found excellent match with score %.2f", best_score
+                )
+                break
+
+            # Check for next page
+            next_cursor = pages_batch.get("next_cursor")
+            if not next_cursor:
+                cls.logger.debug("Reached end of pages")
+                break
+
+        # Generate final suggestions from all matches
+        all_matches.sort(key=lambda x: x[1], reverse=True)
+        all_suggestions = [title for title, _ in all_matches[: cls.MAX_SUGGESTIONS]]
 
+        cls.logger.info(
+            "Search completed. Processed %d pages. Best score: %.2f",
+            page_count,
+            best_score,
+        )
+
+        return best_match, best_score, all_suggestions
+
+    @classmethod
+    async def _fetch_pages_batch(
+        cls, client: NotionClient, next_cursor: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """Fetch a single batch of pages from the Notion API."""
         search_payload = {
             "filter": {"property": "object", "value": "page"},
-            "page_size": 100,
+            "page_size": cls.PAGE_SIZE,
         }
 
-        response = await client.post("search", search_payload)
+        if next_cursor:
+            search_payload["start_cursor"] = next_cursor
+
+        try:
+            response = await client.post("search", search_payload)
+
+            if not response:
+                cls.logger.error("Empty response from search endpoint")
+                return {}
 
-        if not response or "results" not in response:
-            cls.logger.error("Failed to fetch pages using search endpoint")
-            raise ValueError("Failed to fetch pages using search endpoint")
+            return response
 
-        return response.get("results", [])
+        except Exception as e:
+            cls.logger.error("Error fetching pages batch: %s", str(e))
+            raise
+
+    @classmethod
+    def _find_best_match_in_batch(
+        cls, pages: List[Dict[str, Any]], query: str, current_best_score: float
+    ) -> Tuple[Optional[Dict[str, Any]], float, List[str]]:
+        """Find the best matching page in a single batch."""
+        batch_best_match = None
+        batch_best_score = current_best_score
+
+        for page in pages:
+            title = cls._extract_title_from_page(page)
+            score = SequenceMatcher(None, query.lower(), title.lower()).ratio()
+
+            if score > batch_best_score:
+                batch_best_score = score
+                batch_best_match = page
+
+        # Get batch suggestions (not used in the main algorithm but kept for compatibility)
+        batch_suggestions = []
+
+        return batch_best_match, batch_best_score, batch_suggestions
+
+    @classmethod
+    async def _search_pages(cls, client: NotionClient) -> List[Dict[str, Any]]:
+        """
+        Legacy method - kept for backward compatibility.
+        Now uses the paginated approach internally.
+        """
+        cls.logger.warning(
+            "_search_pages is deprecated. Use _search_pages_with_matching instead."
+        )
+
+        all_pages = []
+        next_cursor = None
+
+        while True:
+            batch = await cls._fetch_pages_batch(client, next_cursor)
+            if not batch:
+                break
+
+            pages = batch.get("results", [])
+            all_pages.extend(pages)
+
+            next_cursor = batch.get("next_cursor")
+            if not next_cursor:
+                break
+
+        cls.logger.info("Loaded %d total pages", len(all_pages))
+        return all_pages
 
     @classmethod
     def _find_best_match(

notionary/page/properites/database_property_service.py

@@ -1,6 +1,6 @@
 from typing import Dict, List, Optional, Any, Tuple
 from notionary.notion_client import NotionClient
-from notionary.util.logging_mixin import LoggingMixin
+from notionary.util import LoggingMixin
 
 
 class DatabasePropertyService(LoggingMixin):

notionary/page/properites/page_property_manager.py

@@ -9,7 +9,7 @@ from notionary.page.relations.page_database_relation import PageDatabaseRelation
 from notionary.page.properites.property_value_extractor import (
     PropertyValueExtractor,
 )
-from notionary.util.logging_mixin import LoggingMixin
+from notionary.util import LoggingMixin
 
 
 class PagePropertyManager(LoggingMixin):

notionary/page/properites/property_formatter.py

@@ -1,6 +1,6 @@
 from typing import Any, Dict, Optional
 
-from notionary.util.logging_mixin import LoggingMixin
+from notionary.util import LoggingMixin
 
 
 class NotionPropertyFormatter(LoggingMixin):

notionary/page/properites/property_value_extractor.py

@@ -1,7 +1,7 @@
 import asyncio
 from typing import Any, Awaitable, Callable
 
-from notionary.util.logging_mixin import LoggingMixin
+from notionary.util import LoggingMixin
 
 
 class PropertyValueExtractor(LoggingMixin):

notionary/page/relations/notion_page_relation_manager.py

@@ -5,7 +5,7 @@ from notionary.notion_client import NotionClient
 from notionary.page.relations.notion_page_title_resolver import (
     NotionPageTitleResolver,
 )
-from notionary.util.logging_mixin import LoggingMixin
+from notionary.util import LoggingMixin
 
 
 class NotionPageRelationManager(LoggingMixin):

notionary/page/relations/notion_page_title_resolver.py

@@ -1,6 +1,6 @@
 from typing import Optional, Dict, Any, List
 from notionary.notion_client import NotionClient
-from notionary.util.logging_mixin import LoggingMixin
+from notionary.util import LoggingMixin
 
 
 class NotionPageTitleResolver(LoggingMixin):

notionary/page/relations/page_database_relation.py

@@ -1,7 +1,7 @@
 from typing import Dict, Optional, Any
 from notionary.models.notion_page_response import DatabaseParent, NotionPageResponse
 from notionary.notion_client import NotionClient
-from notionary.util.logging_mixin import LoggingMixin
+from notionary.util import LoggingMixin
 
 
 class PageDatabaseRelation(LoggingMixin):

notionary/prompting/element_prompt_content.py

@@ -40,6 +40,7 @@ class ElementPromptContent:
         if not self.when_to_use:
             raise ValueError("Usage guidelines are required")
 
+
 class ElementPromptBuilder:
     """
     Builder class for creating ElementPromptContent with a fluent interface.

notionary/telemetry/__init__.py

@@ -0,0 +1,7 @@
+from .telemetry import NotionaryTelemetry
+from .track_usage_decorator import track_usage
+
+__all__ = [
+    "NotionaryTelemetry",
+    "track_usage",
+]

notionary/telemetry/telemetry.py

@@ -0,0 +1,226 @@
+import os
+import uuid
+import atexit
+import signal
+import threading
+from pathlib import Path
+from typing import Dict, Any, Optional
+from posthog import Posthog
+from dotenv import load_dotenv
+
+from notionary.util import LoggingMixin
+from notionary.util import singleton
+
+load_dotenv()
+
+@singleton
+class NotionaryTelemetry(LoggingMixin):
+    """
+    Anonymous telemetry for Notionary - enabled by default.
+    Disable via: ANONYMIZED_TELEMETRY=false
+    """
+
+    USER_ID_PATH = str(Path.home() / ".cache" / "notionary" / "telemetry_user_id")
+    PROJECT_API_KEY = (
+        "phc_gItKOx21Tc0l07C1taD0QPpqFnbWgWjVfRjF6z24kke"  # write-only so no worries
+    )
+    HOST = "https://eu.i.posthog.com"
+    
+    _logged_init_message = False
+
+    def __init__(self):
+        # Default: enabled, disable via ANONYMIZED_TELEMETRY=false
+        telemetry_setting = os.getenv("ANONYMIZED_TELEMETRY", "true").lower()
+        self.enabled = telemetry_setting != "false"
+
+        self._user_id = None
+        self._client = None
+        self._shutdown_lock = threading.Lock()
+        self._is_shutdown = False
+        self._shutdown_registered = False
+
+        if self.enabled:
+            self._initialize_client()
+            self._register_shutdown_handlers()
+
+    def _register_shutdown_handlers(self):
+        """Register shutdown handlers for clean exit"""
+        with self._shutdown_lock:
+            if self._shutdown_registered:
+                return
+            
+            try:
+                # Register atexit handler for normal program termination
+                atexit.register(self._atexit_handler)
+                
+                # Register signal handlers for SIGINT (Ctrl+C) and SIGTERM
+                signal.signal(signal.SIGINT, self._signal_handler)
+                signal.signal(signal.SIGTERM, self._signal_handler)
+                
+                self._shutdown_registered = True
+                self.logger.debug("Telemetry shutdown handlers registered")
+                
+            except Exception as e:
+                self.logger.debug(f"Failed to register shutdown handlers: {e}")
+
+    def _signal_handler(self, signum, frame):
+        """Handle SIGINT (Ctrl+C) and SIGTERM signals"""
+        signal_name = "SIGINT" if signum == signal.SIGINT else f"SIG{signum}"
+        self.logger.debug(f"Received {signal_name}, shutting down telemetry...")
+        
+        self.shutdown(timeout=5.0)  # Quick shutdown for signals
+        
+        # Let the original signal handler take over (or exit)
+        if signum == signal.SIGINT:
+            # Restore default handler and re-raise
+            signal.signal(signal.SIGINT, signal.SIG_DFL)
+            os.kill(os.getpid(), signal.SIGINT)
+
+    def _atexit_handler(self):
+        """Handle normal program exit"""
+        self.logger.debug("Normal program exit, shutting down telemetry...")
+        self.shutdown(timeout=10.0)
+
+    @property
+    def user_id(self) -> str:
+        """Anonymous, persistent user ID"""
+        if self._user_id:
+            return self._user_id
+
+        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._user_id = new_user_id
+            else:
+                with open(self.USER_ID_PATH, "r") as f:
+                    self._user_id = f.read().strip()
+
+            return self._user_id
+        except Exception as e:
+            self.logger.debug(f"Error getting user ID: {e}")
+            return "anonymous_user"
+
+    def capture(self, event_name: str, properties: Optional[Dict[str, Any]] = None):
+        """
+        Safe event tracking that never affects library functionality
+
+        Args:
+            event_name: Event name (e.g. 'page_factory_used')
+            properties: Event properties as dictionary
+        """
+        if not self.enabled or not self._client or self._is_shutdown:
+            return
+
+        try:
+            # Add base properties
+            event_properties = {
+                "library": "notionary",
+                "library_version": self._get_notionary_version(),
+                **(properties or {}),
+            }
+
+            self._client.capture(
+                distinct_id=self.user_id, event=event_name, properties=event_properties
+            )
+
+        except Exception:
+            pass
+
+    def flush(self, timeout: float = 5.0):
+        """
+        Flush events with timeout
+        
+        Args:
+            timeout: Maximum time to wait for flush to complete
+        """
+        if not self.enabled or not self._client or self._is_shutdown:
+            return
+
+        try:
+            # PostHog flush doesn't support timeout directly, so we do it in a thread
+            flush_thread = threading.Thread(target=self._client.flush)
+            flush_thread.daemon = True
+            flush_thread.start()
+            flush_thread.join(timeout=timeout)
+            
+            if flush_thread.is_alive():
+                self.logger.warning(f"Telemetry flush timed out after {timeout}s")
+            else:
+                self.logger.debug("Telemetry events flushed successfully")
+                
+        except Exception as e:
+            self.logger.debug(f"Error during telemetry flush: {e}")
+
+    def shutdown(self, timeout: float = 10.0):
+        """
+        Clean shutdown of telemetry with timeout
+        
+        Args:
+            timeout: Maximum time to wait for shutdown
+        """
+        with self._shutdown_lock:
+            if self._is_shutdown:
+                return
+            
+            self._is_shutdown = True
+            
+        try:
+            if self._client:
+                # First try to flush remaining events
+                self.logger.debug("Flushing telemetry events before shutdown...")
+                self.flush(timeout=timeout * 0.7)  # Use 70% of timeout for flush
+                
+                # Then shutdown the client
+                shutdown_thread = threading.Thread(target=self._client.shutdown)
+                shutdown_thread.daemon = True
+                shutdown_thread.start()
+                shutdown_thread.join(timeout=timeout * 0.3)  # Use 30% for shutdown
+                
+                if shutdown_thread.is_alive():
+                    self.logger.warning(f"Telemetry client shutdown timed out after {timeout}s")
+                else:
+                    self.logger.debug("Telemetry client shut down successfully")
+                    
+        except Exception as e:
+            self.logger.debug(f"Error during telemetry shutdown: {e}")
+        finally:
+            self._client = None
+
+    def _initialize_client(self):
+        """Initializes PostHog client and shows startup message"""
+        try:
+            self._client = Posthog(
+                project_api_key=self.PROJECT_API_KEY,
+                host=self.HOST,
+                disable_geoip=True,
+            )
+            if not self._logged_init_message:
+                self.logger.info(
+                    "Anonymous telemetry enabled to improve Notionary. "
+                    "To disable: export ANONYMIZED_TELEMETRY=false"
+                )
+                self._logged_init_message = True
+
+            self._track_initialization()
+
+        except Exception as e:
+            self.logger.debug(f"Telemetry initialization failed: {e}")
+            self.enabled = False
+            self._client = None
+
+    def _track_initialization(self):
+        """Tracks library initialization"""
+        self.capture(
+            "notionary_initialized",
+            {
+                "version": self._get_notionary_version(),
+            },
+        )
+
+    def _get_notionary_version(self) -> str:
+        """Determines the Notionary version"""
+        import notionary
+        return getattr(notionary, "__version__", "0.2.10")

notionary/telemetry/track_usage_decorator.py

@@ -0,0 +1,76 @@
+from functools import wraps
+from typing import Any, Callable, Dict, Optional
+from notionary.telemetry import NotionaryTelemetry
+
+
+def track_usage(event_name: Optional[str] = None, properties: Optional[Dict[str, Any]] = None):
+    """
+    Simple decorator to track function usage.
+    
+    Args:
+        event_name: Custom event name (defaults to function name)
+        properties: Additional properties to track
+        
+    Usage:
+        @track_usage()
+        def my_function():
+            pass
+            
+        @track_usage('custom_event_name')
+        def my_function():
+            pass
+            
+        @track_usage('custom_event', {'feature': 'advanced'})
+        def my_function():
+            pass
+    """
+    def decorator(func: Callable) -> Callable:
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            telemetry = NotionaryTelemetry()
+            
+            # Generate event name and properties
+            event = event_name or _generate_event_name(func, args)
+            event_properties = _build_properties(func, args, properties)
+            
+            # Track and execute
+            telemetry.capture(event, event_properties)
+            return func(*args, **kwargs)
+        
+        return wrapper
+    return decorator
+
+
+def _get_class_name(func: Callable, args: tuple) -> Optional[str]:
+    """Extract class name from function or arguments."""
+    if args and hasattr(args[0], '__class__'):
+        return args[0].__class__.__name__
+    
+    if hasattr(func, '__qualname__') and '.' in func.__qualname__:
+        return func.__qualname__.split('.')[0]
+    
+    return None
+
+
+def _generate_event_name(func: Callable, args: tuple) -> str:
+    """Generate event name from function and class info."""
+    class_name = _get_class_name(func, args)
+    
+    if class_name:
+        return f"{class_name.lower()}_{func.__name__}_used"
+    
+    return f"{func.__name__}_used"
+
+
+def _build_properties(func: Callable, args: tuple, properties: Optional[Dict[str, Any]]) -> Dict[str, Any]:
+    """Build event properties with function and class info."""
+    event_properties = {
+        'function_name': func.__name__,
+        **(properties or {})
+    }
+    
+    class_name = _get_class_name(func, args)
+    if class_name:
+        event_properties['class_name'] = class_name
+    
+    return event_properties

notionary/util/__init__.py

@@ -0,0 +1,5 @@
+from .logging_mixin import LoggingMixin
+from .singleton import singleton
+from .page_id_utils import format_uuid, extract_and_validate_page_id
+
+__all__ = ["LoggingMixin", "singleton", "format_uuid", "extract_and_validate_page_id"]

notionary/util/logging_mixin.py

@@ -10,6 +10,9 @@ def setup_logging():
     )
 
 
+setup_logging()
+
+
 class LoggingMixin:
     # Class attribute with proper typing
     logger: ClassVar[logging.Logger] = None

notionary/util/singleton.py

@@ -0,0 +1,18 @@
+def singleton(cls):
+    """
+    Simple singleton decorator that ensures only one instance of a class exists.
+
+    Usage:
+        @singleton
+        class MyClass:
+            pass
+    """
+    instances = {}
+
+    def __new__(cls, *args, **kwargs):
+        if cls not in instances:
+            instances[cls] = super(cls, cls).__new__(cls)
+        return instances[cls]
+
+    cls.__new__ = __new__
+    return cls

{notionary-0.2.10.dist-info → notionary-0.2.12.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: notionary
-Version: 0.2.10
+Version: 0.2.12
 Summary: A toolkit to convert between Markdown and Notion blocks
 Home-page: https://github.com/mathisarends/notionary
 Author: Mathis Arends
@@ -13,6 +13,8 @@ License-File: LICENSE
 Requires-Dist: httpx>=0.28.0
 Requires-Dist: python-dotenv>=1.1.0
 Requires-Dist: pydantic>=2.11.4
+Requires-Dist: posthog>=3.0.0
+Requires-Dist: click>=8.0.0
 Dynamic: author
 Dynamic: author-email
 Dynamic: classifier