notionary 0.2.15__tar.gz → 0.2.17__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: notionary
-Version: 0.2.15
+Version: 0.2.17
 Summary: Python library for programmatic Notion workspace management - databases, pages, and content with advanced Markdown support
 License: MIT
 Author: Mathis Arends
@@ -13,7 +13,9 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: aiofiles (>=24.1.0,<25.0.0)
 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.17/notionary/__init__.py

@@ -0,0 +1,17 @@
+from .database import NotionDatabase, DatabaseFilterBuilder
+from .page.notion_page import NotionPage
+from .workspace import NotionWorkspace
+from .user import NotionUser, NotionUserManager, NotionBotUser
+from .file_upload import NotionFileUpload, NotionFileUploadClient
+
+__all__ = [
+    "NotionDatabase",
+    "DatabaseFilterBuilder",
+    "NotionPage",
+    "NotionWorkspace",
+    "NotionUser",
+    "NotionUserManager",
+    "NotionBotUser",
+    "NotionFileUpload",
+    "NotionFileUploadClient",
+]

{notionary-0.2.15 → notionary-0.2.17}/notionary/base_notion_client.py

@@ -93,14 +93,17 @@ class BaseNotionClient(LoggingMixin, ABC):
         self._is_initialized = False
         self.logger.debug("NotionClient closed")
 
-    async def get(self, endpoint: str) -> Optional[Dict[str, Any]]:
+    async def get(
+        self, endpoint: str, params: Optional[Dict[str, Any]] = None
+    ) -> Optional[Dict[str, Any]]:
         """
         Sends a GET request to the specified Notion API endpoint.
 
         Args:
             endpoint: The API endpoint (without base URL)
+            params: Query parameters to include in the request
         """
-        return await self._make_request(HttpMethod.GET, endpoint)
+        return await self._make_request(HttpMethod.GET, endpoint, params=params)
 
     async def post(
         self, endpoint: str, data: Optional[Dict[str, Any]] = None
@@ -141,6 +144,7 @@ class BaseNotionClient(LoggingMixin, ABC):
         method: Union[HttpMethod, str],
         endpoint: str,
         data: Optional[Dict[str, Any]] = None,
+        params: Optional[Dict[str, Any]] = None,
     ) -> Optional[Dict[str, Any]]:
         """
         Executes an HTTP request and returns the data or None on error.
@@ -149,6 +153,7 @@ class BaseNotionClient(LoggingMixin, ABC):
             method: HTTP method to use
             endpoint: API endpoint
             data: Request body data (for POST/PATCH)
+            params: Query parameters (for GET requests)
         """
         await self.ensure_initialized()
 
@@ -160,15 +165,21 @@ class BaseNotionClient(LoggingMixin, ABC):
         try:
             self.logger.debug("Sending %s request to %s", method_str.upper(), url)
 
+            request_kwargs = {}
+
+            # Add query parameters for GET requests
+            if params:
+                request_kwargs["params"] = params
+
             if (
                 method_str in [HttpMethod.POST.value, HttpMethod.PATCH.value]
                 and data is not None
             ):
-                response: httpx.Response = await getattr(self.client, method_str)(
-                    url, json=data
-                )
-            else:
-                response: httpx.Response = await getattr(self.client, method_str)(url)
+                request_kwargs["json"] = data
+
+            response: httpx.Response = await getattr(self.client, method_str)(
+                url, **request_kwargs
+            )
 
             response.raise_for_status()
             result_data = response.json()
@@ -194,7 +205,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.17}/notionary/blocks/__init__.py

@@ -26,6 +26,7 @@ from .divider_element import DividerElement
 from .heading_element import HeadingElement
 from .mention_element import MentionElement
 from .qoute_element import QuoteElement
+from .document_element import DocumentElement
 
 from .registry.block_registry import BlockRegistry
 from .registry.block_registry_builder import BlockRegistryBuilder
@@ -55,6 +56,7 @@ __all__ = [
     "BookmarkElement",
     "MentionElement",
     "QuoteElement",
+    "DocumentElement",
     "BlockRegistry",
     "BlockRegistryBuilder",
     "NotionBlockClient",

notionary-0.2.17/notionary/blocks/document_element.py

@@ -0,0 +1,194 @@
+import re
+from typing import Dict, Any, Optional, List
+
+from notionary.blocks import NotionBlockElement
+from notionary.blocks import ElementPromptContent, ElementPromptBuilder
+
+
+class DocumentElement(NotionBlockElement):
+    """
+    Handles conversion between Markdown document embeds and Notion file blocks.
+
+    Markdown document syntax (custom format):
+    - %[Caption](https://example.com/document.pdf) - Basic document with caption
+    - %[](https://example.com/document.pdf) - Document without caption
+    - %[Meeting Notes](https://drive.google.com/file/d/123/view) - Google Drive document
+    - %[Report](https://company.sharepoint.com/document.docx) - SharePoint document
+
+    Supports various document URLs including PDFs, Word docs, Excel files, PowerPoint,
+    Google Drive files, and other document formats that Notion can display.
+    """
+
+    PATTERN = re.compile(
+        r"^%\[(.*?)\]"  # %[Caption] part
+        + r'\((https?://[^\s"]+)'  # (URL part
+        + r"\)$"  # closing parenthesis
+    )
+
+    DOCUMENT_EXTENSIONS = [
+        ".pdf",
+        ".doc",
+        ".docx",
+        ".xls",
+        ".xlsx",
+        ".ppt",
+        ".pptx",
+        ".txt",
+        ".rtf",
+        ".odt",
+        ".ods",
+        ".odp",
+        ".pages",
+        ".numbers",
+        ".key",
+        ".epub",
+        ".mobi",
+    ]
+
+    @classmethod
+    def match_markdown(cls, text: str) -> bool:
+        """Check if text is a markdown document embed."""
+        text = text.strip()
+        return text.startswith("%[") and bool(cls.PATTERN.match(text))
+
+    @classmethod
+    def match_notion(cls, block: Dict[str, Any]) -> bool:
+        """Check if block is a Notion file (document)."""
+        return block.get("type") == "file"
+
+    @classmethod
+    def is_document_url(cls, url: str) -> bool:
+        """Check if URL points to a document file."""
+        url_lower = url.lower()
+
+        # Check for common document file extensions
+        if any(url_lower.endswith(ext) for ext in cls.DOCUMENT_EXTENSIONS):
+            return True
+
+        # Check for common document hosting services
+        document_services = [
+            "drive.google.com",
+            "docs.google.com",
+            "sheets.google.com",
+            "slides.google.com",
+            "sharepoint.com",
+            "onedrive.com",
+            "dropbox.com",
+            "box.com",
+            "scribd.com",
+            "slideshare.net",
+        ]
+
+        return any(service in url_lower for service in document_services)
+
+    @classmethod
+    def markdown_to_notion(cls, text: str) -> Optional[Dict[str, Any]]:
+        """Convert markdown document embed to Notion file block."""
+        doc_match = cls.PATTERN.match(text.strip())
+        if not doc_match:
+            return None
+
+        caption = doc_match.group(1)
+        url = doc_match.group(2)
+
+        if not url:
+            return None
+
+        # Verify this looks like a document URL
+        if not cls.is_document_url(url):
+            # Still proceed - user might know better than our detection
+            pass
+
+        # Prepare the file block
+        file_block = {
+            "type": "file",
+            "file": {"type": "external", "external": {"url": url}},
+        }
+
+        # Add caption if provided
+        if caption:
+            file_block["file"]["caption"] = [
+                {"type": "text", "text": {"content": caption}}
+            ]
+
+        return file_block
+
+    @classmethod
+    def notion_to_markdown(cls, block: Dict[str, Any]) -> Optional[str]:
+        """Convert Notion file block to markdown document embed."""
+        if block.get("type") != "file":
+            return None
+
+        file_data = block.get("file", {})
+
+        # Handle both external and file (uploaded) documents
+        if file_data.get("type") == "external":
+            url = file_data.get("external", {}).get("url", "")
+        elif file_data.get("type") == "file":
+            url = file_data.get("file", {}).get("url", "")
+        elif file_data.get("type") == "file_upload":
+            # Handle file uploads with special notion:// syntax
+            file_upload_id = file_data.get("file_upload", {}).get("id", "")
+            if file_upload_id:
+                url = f"notion://file_upload/{file_upload_id}"
+            else:
+                return None
+        else:
+            return None
+
+        if not url:
+            return None
+
+        # Extract caption if available
+        caption = ""
+        caption_rich_text = file_data.get("caption", [])
+        if caption_rich_text:
+            caption = cls._extract_text_content(caption_rich_text)
+
+        return f"%[{caption}]({url})"
+
+    @classmethod
+    def is_multiline(cls) -> bool:
+        """Document embeds are single-line elements."""
+        return False
+
+    @classmethod
+    def _extract_text_content(cls, rich_text: List[Dict[str, Any]]) -> str:
+        """Extract plain text content from Notion rich_text elements."""
+        result = ""
+        for text_obj in rich_text:
+            if text_obj.get("type") == "text":
+                result += text_obj.get("text", {}).get("content", "")
+            elif "plain_text" in text_obj:
+                result += text_obj.get("plain_text", "")
+        return result
+
+    @classmethod
+    def get_llm_prompt_content(cls) -> ElementPromptContent:
+        """Returns information for LLM prompts about this element."""
+        return (
+            ElementPromptBuilder()
+            .with_description(
+                "Embeds document files from external sources like PDFs, Word docs, Excel files, or cloud storage services."
+            )
+            .with_usage_guidelines(
+                "Use document embeds when you want to include reference materials, reports, presentations, or any "
+                "file-based content directly in your document. Documents can be viewed inline or downloaded by users. "
+                "Perfect for sharing contracts, reports, manuals, or any important files."
+            )
+            .with_syntax("%[Caption](https://example.com/document.pdf)")
+            .with_examples(
+                [
+                    "%[Project Proposal](https://drive.google.com/file/d/1a2b3c4d5e/view)",
+                    "%[Q4 Financial Report](https://company.sharepoint.com/reports/q4-2024.xlsx)",
+                    "%[User Manual](https://cdn.company.com/docs/manual-v2.1.pdf)",
+                    "%[Meeting Minutes](https://docs.google.com/document/d/1x2y3z4/edit)",
+                    "%[](https://example.com/contract.pdf)",
+                ]
+            )
+            .with_avoidance_guidelines(
+                "Only use for actual document files. For web pages or articles, use bookmark or embed elements instead. "
+                "Ensure document URLs are accessible to your intended audience."
+            )
+            .build()
+        )

{notionary-0.2.15 → notionary-0.2.17}/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.17/notionary/database/__init__.py

@@ -0,0 +1,4 @@
+from .database import NotionDatabase
+from .database_filter_builder import DatabaseFilterBuilder
+
+__all__ = ["NotionDatabase", "DatabaseFilterBuilder"]