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

notionary/user/notion_user.py

@@ -0,0 +1,256 @@
+from __future__ import annotations
+
+from typing import Optional, List
+from notionary.user.base_notion_user import BaseNotionUser
+from notionary.user.client import NotionUserClient
+from notionary.user.models import (
+    NotionUserResponse,
+)
+from notionary.util import factory_only
+from notionary.util.fuzzy import find_best_matches
+
+
+class NotionUser(BaseNotionUser):
+    """
+    Manager for Notion person users.
+    Handles person-specific operations and information.
+    """
+
+    NO_USERS_FOUND_MSG = "No users found in workspace"
+    NO_PERSON_USERS_FOUND_MSG = "No person users found in workspace"
+
+    @factory_only("from_user_id", "from_user_response", "from_name")
+    def __init__(
+        self,
+        user_id: str,
+        name: Optional[str] = None,
+        avatar_url: Optional[str] = None,
+        email: Optional[str] = None,
+        token: Optional[str] = None,
+    ):
+        """Initialize person user with person-specific properties."""
+        super().__init__(user_id, name, avatar_url, token)
+        self._email = email
+
+    @classmethod
+    async def from_user_id(
+        cls, user_id: str, token: Optional[str] = None
+    ) -> Optional[NotionUser]:
+        """
+        Create a NotionUser from a user ID.
+        """
+        client = NotionUserClient(token=token)
+        user_response = await client.get_user(user_id)
+
+        if user_response is None:
+            cls.logger.error("Failed to load user data for ID: %s", user_id)
+            return None
+
+        # Ensure this is actually a person user
+        if user_response.type != "person":
+            cls.logger.error(
+                "User %s is not a person user (type: %s)", user_id, user_response.type
+            )
+            return None
+
+        return cls._create_from_response(user_response, token)
+
+    @classmethod
+    async def from_name(
+        cls, name: str, token: Optional[str] = None, min_similarity: float = 0.6
+    ) -> Optional[NotionUser]:
+        """
+        Create a NotionUser by finding a person user with fuzzy matching on the name.
+        """
+        from notionary.util import find_best_match
+
+        client = NotionUserClient(token=token)
+
+        try:
+            # Get all users from workspace
+            all_users_response = await client.get_all_users()
+
+            if not all_users_response:
+                cls.logger.warning(cls.NO_USERS_FOUND_MSG)
+                raise ValueError(cls.NO_USERS_FOUND_MSG)
+
+            person_users = [
+                user
+                for user in all_users_response
+                if user.type == "person" and user.name
+            ]
+
+            if not person_users:
+                cls.logger.warning(cls.NO_PERSON_USERS_FOUND_MSG)
+                raise ValueError(cls.NO_PERSON_USERS_FOUND_MSG)
+
+            cls.logger.debug(
+                "Found %d person users for fuzzy matching: %s",
+                len(person_users),
+                [user.name for user in person_users[:5]],
+            )
+
+            # Use fuzzy matching to find best match
+            best_match = find_best_match(
+                query=name,
+                items=person_users,
+                text_extractor=lambda user: user.name or "",
+                min_similarity=min_similarity,
+            )
+
+            if not best_match:
+                available_names = [user.name for user in person_users[:5]]
+                cls.logger.warning(
+                    "No sufficiently similar person user found for '%s' (min: %.3f). Available: %s",
+                    name,
+                    min_similarity,
+                    available_names,
+                )
+                raise ValueError(
+                    f"No sufficiently similar person user found for '{name}'"
+                )
+
+            cls.logger.info(
+                "Found best match: '%s' with similarity %.3f for query '%s'",
+                best_match.matched_text,
+                best_match.similarity,
+                name,
+            )
+
+            # Create NotionUser from the matched user response
+            return cls._create_from_response(best_match.item, token)
+
+        except Exception as e:
+            cls.logger.error("Error finding user by name '%s': %s", name, str(e))
+            raise
+
+    @classmethod
+    def from_user_response(
+        cls, user_response: NotionUserResponse, token: Optional[str] = None
+    ) -> NotionUser:
+        """
+        Create a NotionUser from an existing API response.
+        """
+        if user_response.type != "person":
+            raise ValueError(f"Cannot create NotionUser from {user_response.type} user")
+
+        return cls._create_from_response(user_response, token)
+
+    @classmethod
+    async def search_users_by_name(
+        cls,
+        name: str,
+        token: Optional[str] = None,
+        min_similarity: float = 0.3,
+        limit: Optional[int] = 5,
+    ) -> List[NotionUser]:
+        """
+        Search for multiple person users by name using fuzzy matching.
+
+        Args:
+            name: The name to search for
+            token: Optional Notion API token
+            min_similarity: Minimum similarity threshold (0.0 to 1.0), default 0.3
+            limit: Maximum number of results to return, default 5
+
+        Returns:
+            List[NotionUser]: List of matching users sorted by similarity (best first)
+        """
+        client = NotionUserClient(token=token)
+
+        try:
+            # Get all users from workspace
+            all_users_response = await client.get_all_users()
+
+            if not all_users_response:
+                cls.logger.warning(cls.NO_USERS_FOUND_MSG)
+                return []
+
+            # Filter to only person users (not bots)
+            person_users = [
+                user
+                for user in all_users_response
+                if user.type == "person" and user.name
+            ]
+
+            if not person_users:
+                cls.logger.warning(cls.NO_PERSON_USERS_FOUND_MSG)
+                return []
+
+            # Use fuzzy matching to find all matches
+            matches = find_best_matches(
+                query=name,
+                items=person_users,
+                text_extractor=lambda user: user.name or "",
+                min_similarity=min_similarity,
+                limit=limit,
+            )
+
+            cls.logger.info(
+                "Found %d matching users for query '%s'", len(matches), name
+            )
+
+            # Convert to NotionUser instances
+            result_users = []
+            for match in matches:
+                try:
+                    user = cls._create_from_response(match.item, token)
+                    result_users.append(user)
+                except Exception as e:
+                    cls.logger.warning(
+                        "Failed to create user from match '%s': %s",
+                        match.matched_text,
+                        str(e),
+                    )
+                    continue
+
+            return result_users
+
+        except Exception as e:
+            cls.logger.error("Error searching users by name '%s': %s", name, str(e))
+            return []
+
+    @property
+    def email(self) -> Optional[str]:
+        """
+        Get the user email (requires proper integration capabilities).
+        """
+        return self._email
+
+    @property
+    def user_type(self) -> str:
+        """Get the user type."""
+        return "person"
+
+    @property
+    def is_person(self) -> bool:
+        """Check if this is a person user."""
+        return True
+
+    @property
+    def is_bot(self) -> bool:
+        """Check if this is a bot user."""
+        return False
+
+    @classmethod
+    def _create_from_response(
+        cls, user_response: NotionUserResponse, token: Optional[str]
+    ) -> NotionUser:
+        """Create NotionUser instance from API response."""
+        email = user_response.person.email if user_response.person else None
+
+        instance = cls(
+            user_id=user_response.id,
+            name=user_response.name,
+            avatar_url=user_response.avatar_url,
+            email=email,
+            token=token,
+        )
+
+        cls.logger.info(
+            "Created person user: '%s' (ID: %s)",
+            user_response.name or "Unknown",
+            user_response.id,
+        )
+
+        return instance

notionary/user/notion_user_manager.py

@@ -0,0 +1,173 @@
+from typing import Any, Dict, Optional, List
+from notionary.user.client import NotionUserClient
+from notionary.user.notion_user import NotionUser
+from notionary.user.models import NotionUsersListResponse
+from notionary.util import LoggingMixin
+
+
+class NotionUserManager(LoggingMixin):
+    """
+    Manager for user operations within API limitations.
+
+    Note: The Notion API provides endpoints to list workspace users (excluding guests).
+    This manager provides utility functions for working with individual users and user lists.
+    """
+
+    def __init__(self, token: Optional[str] = None):
+        """Initialize the user manager."""
+        self.client = NotionUserClient(token=token)
+
+    async def get_current_bot_user(self) -> Optional[NotionUser]:
+        """
+        Get the current bot user from the API token.
+        """
+        return await NotionUser.current_bot_user(token=self.client.token)
+
+    async def get_user_by_id(self, user_id: str) -> Optional[NotionUser]:
+        """
+        Get a specific user by their ID.
+        """
+        return await NotionUser.from_user_id(user_id, token=self.client.token)
+
+    async def list_users(
+        self, page_size: int = 100, start_cursor: Optional[str] = None
+    ) -> Optional[NotionUsersListResponse]:
+        """
+        List users in the workspace (paginated).
+
+        Note: Guests are not included in the response.
+        """
+        try:
+            response = await self.client.list_users(page_size, start_cursor)
+            if response is None:
+                self.logger.error("Failed to list users")
+                return None
+
+            self.logger.info(
+                "Retrieved %d users (has_more: %s)",
+                len(response.results),
+                response.has_more,
+            )
+            return response
+
+        except Exception as e:
+            self.logger.error("Error listing users: %s", str(e))
+            return None
+
+    async def get_all_users(self) -> List[NotionUser]:
+        """
+        Get all users in the workspace as NotionUser objects.
+        Automatically handles pagination and converts responses to NotionUser instances.
+        """
+        try:
+            # Get raw user responses
+            user_responses = await self.client.get_all_users()
+
+            # Convert to NotionUser objects
+            notion_users = []
+            for user_response in user_responses:
+                try:
+                    # Use the internal creation method to convert response to NotionUser
+                    notion_user = NotionUser.from_notion_user_response(
+                        user_response, self.client.token
+                    )
+                    notion_users.append(notion_user)
+                except Exception as e:
+                    self.logger.warning(
+                        "Failed to convert user %s to NotionUser: %s",
+                        user_response.id,
+                        str(e),
+                    )
+                    continue
+
+            self.logger.info(
+                "Successfully converted %d users to NotionUser objects",
+                len(notion_users),
+            )
+            return notion_users
+
+        except Exception as e:
+            self.logger.error("Error getting all users: %s", str(e))
+            return []
+
+    async def get_users_by_type(self, user_type: str = "person") -> List[NotionUser]:
+        """
+        Get all users of a specific type (person or bot).
+        """
+        try:
+            all_users = await self.get_all_users()
+            filtered_users = [user for user in all_users if user.user_type == user_type]
+
+            self.logger.info(
+                "Found %d users of type '%s' out of %d total users",
+                len(filtered_users),
+                user_type,
+                len(all_users),
+            )
+            return filtered_users
+
+        except Exception as e:
+            self.logger.error("Error filtering users by type: %s", str(e))
+            return []
+
+    # TODO: Type this
+    async def get_workspace_info(self) -> Optional[Dict[str, Any]]:
+        """
+        Get available workspace information from the bot user.
+        """
+        bot_user = await self.get_current_bot_user()
+        if bot_user is None:
+            self.logger.error("Failed to get bot user for workspace info")
+            return None
+
+        workspace_info = {
+            "workspace_name": bot_user.workspace_name,
+            "bot_user_id": bot_user.id,
+            "bot_user_name": bot_user.name,
+            "bot_user_type": bot_user.user_type,
+        }
+
+        # Add workspace limits if available
+        if bot_user.is_bot:
+            limits = await bot_user.get_workspace_limits()
+            if limits:
+                workspace_info["workspace_limits"] = limits
+
+        # Add user count statistics
+        try:
+            all_users = await self.get_all_users()
+            workspace_info["total_users"] = len(all_users)
+            workspace_info["person_users"] = len([u for u in all_users if u.is_person])
+            workspace_info["bot_users"] = len([u for u in all_users if u.is_bot])
+        except Exception as e:
+            self.logger.warning("Could not get user statistics: %s", str(e))
+
+        return workspace_info
+
+    async def find_users_by_name(self, name_pattern: str) -> List[NotionUser]:
+        """
+        Find users by name pattern (case-insensitive partial match).
+
+        Note: The API doesn't support server-side filtering, so this fetches all users
+        and filters client-side.
+        """
+        try:
+            all_users = await self.get_all_users()
+            pattern_lower = name_pattern.lower()
+
+            matching_users = [
+                user
+                for user in all_users
+                if user.name and pattern_lower in user.name.lower()
+            ]
+
+            self.logger.info(
+                "Found %d users matching pattern '%s'",
+                len(matching_users),
+                name_pattern,
+            )
+            return matching_users
+
+        except Exception as e:
+            self.logger.error("Error finding users by name: %s", str(e))
+            return []

notionary/user/notion_user_provider.py

@@ -0,0 +1 @@
+# for caching shit

notionary/util/__init__.py

@@ -1,15 +1,13 @@
 from .logging_mixin import LoggingMixin
-from .singleton_decorator import singleton
+from .singleton import singleton
 from .page_id_utils import format_uuid
-from .fuzzy_matcher import FuzzyMatcher
-from .factory_decorator import factory_only
+from .factory_only import factory_only
 from .singleton_metaclass import SingletonMetaClass
 
 __all__ = [
     "LoggingMixin",
-    "singleton_decorator",
+    "singleton",
     "format_uuid",
-    "FuzzyMatcher",
     "factory_only",
     "singleton",
     "SingletonMetaClass",

notionary/util/factory_decorator.py

@@ -1,33 +0,0 @@
-import functools
-import inspect
-
-
-def factory_only(*allowed_factories):
-    """
-    Decorator that ensures __init__ is only called from allowed factory methods.
-
-    Args:
-        *allowed_factories: Names of allowed factory methods (e.g. 'from_database_id')
-    """
-
-    def decorator(init_method):
-        @functools.wraps(init_method)
-        def wrapper(self, *args, **kwargs):
-            frame = inspect.currentframe()
-            try:
-                caller_frame = frame.f_back.f_back
-                if not caller_frame:
-                    return init_method(self, *args, **kwargs)
-                caller_name = caller_frame.f_code.co_name
-                if caller_name in allowed_factories or caller_name.startswith("_"):
-                    return init_method(self, *args, **kwargs)
-                else:
-                    raise RuntimeError(
-                        f"Direct instantiation not allowed! Use one of: {', '.join(allowed_factories)}"
-                    )
-            finally:
-                del frame
-
-        return wrapper
-
-    return decorator

notionary/util/factory_only.py

@@ -0,0 +1,37 @@
+import functools
+import inspect
+import warnings
+
+
+def factory_only(*allowed_factories):
+    """
+    Decorator that warns when __init__ is not called from allowed factory methods.
+
+    Args:
+        *allowed_factories: Names of allowed factory methods (e.g. 'from_database_id')
+    """
+
+    def decorator(init_method):
+        @functools.wraps(init_method)
+        def wrapper(self, *args, **kwargs):
+            frame = inspect.currentframe()
+            try:
+                caller_frame = frame.f_back.f_back
+                if not caller_frame:
+                    return init_method(self, *args, **kwargs)
+                caller_name = caller_frame.f_code.co_name
+                if caller_name in allowed_factories or caller_name.startswith("_"):
+                    return init_method(self, *args, **kwargs)
+
+                warnings.warn(
+                    f"Direct instantiation not recommended! Consider using one of: {', '.join(allowed_factories)}",
+                    UserWarning,
+                    stacklevel=3,
+                )
+                return init_method(self, *args, **kwargs)
+            finally:
+                del frame
+
+        return wrapper
+
+    return decorator

notionary/util/fuzzy.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+import difflib
+from typing import List, Any, TypeVar, Callable, Optional
+from dataclasses import dataclass
+
+T = TypeVar("T")
+
+
+@dataclass
+class MatchResult:
+    """Result of a fuzzy match operation."""
+
+    item: Any
+    similarity: float
+    matched_text: str
+
+
+def calculate_similarity(query: str, target: str) -> float:
+    """Calculate similarity between two strings using difflib."""
+    return difflib.SequenceMatcher(
+        None, query.lower().strip(), target.lower().strip()
+    ).ratio()
+
+
+def find_best_matches(
+    query: str,
+    items: List[T],
+    text_extractor: Callable[[T], str],
+    min_similarity: float = 0.0,
+    limit: Optional[int] = None,
+) -> List[MatchResult[T]]:
+    """
+    Find best fuzzy matches from a list of items.
+
+    Args:
+        query: The search query
+        items: List of items to search through
+        text_extractor: Function to extract text from each item
+        min_similarity: Minimum similarity threshold (0.0 to 1.0)
+        limit: Maximum number of results to return
+
+    Returns:
+        List of MatchResult objects sorted by similarity (highest first)
+    """
+    results = []
+
+    for item in items:
+        text = text_extractor(item)
+        similarity = calculate_similarity(query, text)
+
+        if similarity >= min_similarity:
+            results.append(
+                MatchResult(item=item, similarity=similarity, matched_text=text)
+            )
+
+    # Sort by similarity (highest first)
+    results.sort(key=lambda x: x.similarity, reverse=True)
+
+    # Apply limit if specified
+    if limit:
+        results = results[:limit]
+
+    return results
+
+
+def find_best_match(
+    query: str,
+    items: List[T],
+    text_extractor: Callable[[T], str],
+    min_similarity: float = 0.0,
+) -> Optional[MatchResult[T]]:
+    """Find the single best fuzzy match."""
+    matches = find_best_matches(query, items, text_extractor, min_similarity, limit=1)
+    return matches[0] if matches else None

notionary/util/logging_mixin.py

@@ -1,14 +1,24 @@
 import logging
-import inspect
 from typing import Optional, ClassVar
 
+import os
+from dotenv import load_dotenv
+
+load_dotenv()
+
 
 def setup_logging():
+    """
+    Sets up logging configuration for the application.
+    """
+    log_level = os.getenv("LOG_LEVEL", "WARNING").upper()
     logging.basicConfig(
-        level=logging.INFO,
+        level=getattr(logging, log_level),
         format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
     )
 
+    logging.getLogger("httpx").setLevel(logging.WARNING)
+
 
 setup_logging()
 
@@ -32,16 +42,6 @@ class LoggingMixin:
             self._logger = logging.getLogger(self.__class__.__name__)
         return self._logger
 
-    @staticmethod
-    def static_logger() -> logging.Logger:
-        """Static logger - for static methods"""
-        stack = inspect.stack()
-        for frame_info in stack[1:]:
-            class_name = LoggingMixin._get_class_name_from_frame(frame_info.frame)
-            if class_name:
-                return logging.getLogger(class_name)
-        return logging.getLogger("UnknownStaticContext")
-
     @staticmethod
     def _get_class_name_from_frame(frame) -> Optional[str]:
         local_vars = frame.f_locals