notionhelper 0.3.2__py3-none-any.whl → 0.4.1__py3-none-any.whl

notionhelper/__init__.py

@@ -1,3 +1,4 @@
 from .helper import NotionHelper
+from .ml_logger import MLNotionHelper
 
-__all__ = ["NotionHelper"]
+__all__ = ["NotionHelper", "MLNotionHelper"]

notionhelper/helper.py

@@ -174,8 +174,118 @@ class NotionHelper:
         response = self._make_request("POST", url, payload)
         return response.get("results", [])
 
-    def get_page(self, page_id: str) -> Dict[str, Any]:
-        """Retrieves the JSON of the page properties and an array of blocks on a Notion page given its page_id."""
+    def _blocks_to_markdown(self, blocks: List[Dict[str, Any]]) -> str:
+        """Converts Notion blocks to markdown format.
+
+        Parameters:
+            blocks (list): List of block objects from Notion API
+
+        Returns:
+            str: Markdown formatted string
+        """
+        markdown_lines = []
+
+        for block in blocks:
+            block_type = block.get("type", "")
+            block_data = block.get(block_type, {})
+
+            if block_type == "paragraph":
+                text = self._extract_rich_text(block_data.get("rich_text", []))
+                if text:
+                    markdown_lines.append(text)
+                markdown_lines.append("")
+
+            elif block_type == "heading_1":
+                text = self._extract_rich_text(block_data.get("rich_text", []))
+                markdown_lines.append(f"# {text}")
+                markdown_lines.append("")
+
+            elif block_type == "heading_2":
+                text = self._extract_rich_text(block_data.get("rich_text", []))
+                markdown_lines.append(f"## {text}")
+                markdown_lines.append("")
+
+            elif block_type == "heading_3":
+                text = self._extract_rich_text(block_data.get("rich_text", []))
+                markdown_lines.append(f"### {text}")
+                markdown_lines.append("")
+
+            elif block_type == "bulleted_list_item":
+                text = self._extract_rich_text(block_data.get("rich_text", []))
+                markdown_lines.append(f"- {text}")
+
+            elif block_type == "numbered_list_item":
+                text = self._extract_rich_text(block_data.get("rich_text", []))
+                markdown_lines.append(f"1. {text}")
+
+            elif block_type == "code":
+                code_text = self._extract_rich_text(block_data.get("rich_text", []))
+                language = block_data.get("language", "")
+                markdown_lines.append(f"```{language}")
+                markdown_lines.append(code_text)
+                markdown_lines.append("```")
+                markdown_lines.append("")
+
+            elif block_type == "image":
+                image_data = block_data.get("external", {}) or block_data.get("file", {})
+                image_url = image_data.get("url", "")
+                if image_url:
+                    markdown_lines.append(f"![Image]({image_url})")
+                    markdown_lines.append("")
+
+            elif block_type == "divider":
+                markdown_lines.append("---")
+                markdown_lines.append("")
+
+            elif block_type == "quote":
+                text = self._extract_rich_text(block_data.get("rich_text", []))
+                markdown_lines.append(f"> {text}")
+                markdown_lines.append("")
+
+        return "\n".join(markdown_lines).strip()
+
+    def _extract_rich_text(self, rich_text_array: List[Dict[str, Any]]) -> str:
+        """Extracts and formats rich text from Notion rich_text array.
+
+        Parameters:
+            rich_text_array (list): Array of rich text objects
+
+        Returns:
+            str: Formatted text with markdown syntax
+        """
+        result = []
+
+        for text_obj in rich_text_array:
+            content = text_obj.get("text", {}).get("content", "")
+            annotations = text_obj.get("annotations", {})
+            href = text_obj.get("href", None)
+
+            # Apply markdown formatting based on annotations
+            if annotations.get("bold"):
+                content = f"**{content}**"
+            if annotations.get("italic"):
+                content = f"*{content}*"
+            if annotations.get("strikethrough"):
+                content = f"~~{content}~~"
+            if annotations.get("code"):
+                content = f"`{content}`"
+            if href:
+                content = f"[{content}]({href})"
+
+            result.append(content)
+
+        return "".join(result)
+
+    def get_page(self, page_id: str, return_markdown: bool = False) -> Dict[str, Any]:
+        """Retrieves the JSON of the page properties and an array of blocks on a Notion page given its page_id.
+
+        Parameters:
+            page_id (str): The ID of the Notion page
+            return_markdown (bool): If True, converts blocks to markdown. If False, returns raw JSON. Defaults to False.
+
+        Returns:
+            dict: Dictionary with 'properties' and 'content' (as JSON or markdown string)
+        """
 
         # Retrieve the page properties
         page_url = f"https://api.notion.com/v1/pages/{page_id}"
@@ -187,10 +297,13 @@ class NotionHelper:
 
         # Extract all properties as a JSON object
         properties = page.get("properties", {})
-        content = [block for block in blocks["results"]]
+        content_blocks = [block for block in blocks["results"]]
 
-        # Print the full JSON of the properties
-        print(properties)
+        # Convert to markdown if requested
+        if return_markdown:
+            content = self._blocks_to_markdown(content_blocks)
+        else:
+            content = content_blocks
 
         # Return the properties JSON and blocks content
         return {"properties": properties, "content": content}
@@ -654,177 +767,3 @@ class NotionHelper:
         }
         response = requests.patch(update_url, headers=headers, json=data)
         return response.json()
-
-    def dict_to_notion_schema(self, data: Dict[str, Any], title_key: str) -> Dict[str, Any]:
-        """Converts a dictionary into a Notion property schema for database creation.
-
-        Parameters:
-            data (dict): Dictionary containing sample values to infer types from.
-            title_key (str): The key that should be used as the title property.
-
-        Returns:
-            dict: A dictionary defining the Notion property schema.
-        """
-        properties = {}
-
-        for key, value in data.items():
-            # Handle NumPy types
-            if hasattr(value, "item"):
-                value = value.item()
-
-            # Debug output to help diagnose type issues
-            print(f"DEBUG: key='{key}', value={value}, type={type(value).__name__}, isinstance(bool)={isinstance(value, bool)}, isinstance(int)={isinstance(value, int)}")
-
-            if key == title_key:
-                properties[key] = {"title": {}}
-            # IMPORTANT: Check for bool BEFORE (int, float) because bool is a subclass of int in Python
-            elif isinstance(value, bool):
-                properties[key] = {"checkbox": {}}
-                print(f"  → Assigned as CHECKBOX")
-            elif isinstance(value, (int, float)):
-                properties[key] = {"number": {"format": "number"}}
-                print(f"  → Assigned as NUMBER")
-            else:
-                properties[key] = {"rich_text": {}}
-                print(f"  → Assigned as RICH_TEXT")
-
-        return properties
-
-    def dict_to_notion_props(self, data: Dict[str, Any], title_key: str) -> Dict[str, Any]:
-        """Converts a dictionary into Notion property values for page creation.
-
-        Parameters:
-            data (dict): Dictionary containing the values to convert.
-            title_key (str): The key that should be used as the title property.
-
-        Returns:
-            dict: A dictionary defining the Notion property values.
-        """
-        notion_props = {}
-        for key, value in data.items():
-            # Handle NumPy types
-            if hasattr(value, "item"):
-                value = value.item()
-
-            if key == title_key:
-                ts = datetime.now().strftime("%Y-%m-%d %H:%M")
-                notion_props[key] = {"title": [{"text": {"content": f"{value} ({ts})"}}]}
-
-            # FIX: Handle Booleans
-            elif isinstance(value, bool):
-                # Option A: Map to a Checkbox column in Notion
-                # notion_props[key] = {"checkbox": value}
-
-                # Option B: Map to a Rich Text column as a string (since you added a rich text field)
-                notion_props[key] = {"rich_text": [{"text": {"content": str(value)}}]}
-
-            elif isinstance(value, (int, float)):
-                if pd.isna(value) or np.isinf(value): continue
-                notion_props[key] = {"number": float(value)}
-            else:
-                notion_props[key] = {"rich_text": [{"text": {"content": str(value)}}]}
-        return notion_props
-
-    def log_ml_experiment(
-        self,
-        data_source_id: str,
-        config: Dict,
-        metrics: Dict,
-        plots: List[str] = None,
-        target_metric: str = "sMAPE",      # Re-added these
-        higher_is_better: bool = False,   # to fix the error
-        file_paths: Optional[List[str]] = None, # Changed to list
-        file_property_name: str = "Output Files"
-    ):
-        """Logs ML experiment and compares metrics with multiple file support."""
-        improvement_tag = "Standard Run"
-        new_score = metrics.get(target_metric)
-
-        # 1. Leaderboard Logic (Champions)
-        if new_score is not None:
-            try:
-                df = self.get_data_source_pages_as_dataframe(data_source_id, limit=100)
-                if not df.empty and target_metric in df.columns:
-                    valid_scores = pd.to_numeric(df[target_metric], errors='coerce').dropna()
-                    if not valid_scores.empty:
-                        current_best = valid_scores.max() if higher_is_better else valid_scores.min()
-                        is_improvement = (new_score > current_best) if higher_is_better else (new_score < current_best)
-                        if is_improvement:
-                            improvement_tag = f"🏆 NEW BEST {target_metric} (Prev: {current_best:.2f})"
-                        else:
-                            diff = abs(new_score - current_best)
-                            improvement_tag = f"No Improvement (+{diff:.2f} {target_metric})"
-            except Exception as e:
-                print(f"Leaderboard check skipped: {e}")
-
-        # 2. Prepare Notion Properties
-        data_for_notion = metrics.copy()
-        data_for_notion["Run Status"] = improvement_tag
-        combined_payload = {**config, **data_for_notion}
-        title_key = list(config.keys())[0]
-        properties = self.dict_to_notion_props(combined_payload, title_key)
-
-        try:
-            # 3. Create the row
-            new_page = self.new_page_to_data_source(data_source_id, properties)
-            page_id = new_page["id"]
-
-            # 4. Handle Plots (Body)
-            if plots:
-                for plot_path in plots:
-                    if os.path.exists(plot_path):
-                        self.one_step_image_embed(page_id, plot_path)
-
-            # 5. Handle Multiple File Uploads (Property)
-            if file_paths:
-                file_assets = []
-                for path in file_paths:
-                    if os.path.exists(path):
-                        print(f"Uploading {path}...")
-                        upload_resp = self.upload_file(path)
-                        file_assets.append({
-                            "type": "file_upload",
-                            "file_upload": {"id": upload_resp["id"]},
-                            "name": os.path.basename(path),
-                        })
-
-                if file_assets:
-                    # Attach all files in one request
-                    update_url = f"https://api.notion.com/v1/pages/{page_id}"
-                    file_payload = {"properties": {file_property_name: {"files": file_assets}}}
-                    self._make_request("PATCH", update_url, file_payload)
-                    print(f"✅ {len(file_assets)} files attached to {file_property_name}")
-
-            return page_id
-        except Exception as e:
-            print(f"Log error: {e}")
-            return None
-
-    def create_ml_database(self, parent_page_id: str, db_title: str, config: Dict, metrics: Dict, file_property_name: str = "Output Files") -> str:
-        """
-        Analyzes dicts to create a new Notion Database with the correct schema.
-        Uses dict_to_notion_schema() for universal type conversion.
-        """
-        combined = {**config, **metrics}
-        title_key = list(config.keys())[0]
-
-        # Use the universal dict_to_notion_schema() method
-        properties = self.dict_to_notion_schema(combined, title_key)
-
-        # Add 'Run Status' if not already present
-        if "Run Status" not in properties:
-            properties["Run Status"] = {"rich_text": {}}
-
-        # Add the Multi-file property
-        properties[file_property_name] = {"files": {}}
-
-        print(f"Creating database '{db_title}' with {len(properties)} columns...")
-
-        response = self.create_database(
-            parent_page_id=parent_page_id,
-            database_title=db_title,
-            initial_data_source_properties=properties
-        )
-
-        data_source_id = response.get("initial_data_source", {}).get("id")
-        return data_source_id if data_source_id else response.get("id")

notionhelper/ml_logger.py

@@ -0,0 +1,206 @@
+from typing import Optional, Dict, List, Any
+import pandas as pd
+import numpy as np
+import os
+from datetime import datetime
+
+from .helper import NotionHelper
+
+
+class MLNotionHelper(NotionHelper):
+    """
+    ML experiment tracking helper that extends NotionHelper.
+
+    Provides specialized methods for logging and tracking machine learning experiments,
+    automatically comparing metrics against historical runs and logging results to Notion.
+
+    Methods
+    -------
+    log_ml_experiment(data_source_id, config, metrics, plots, target_metric,
+                     higher_is_better, file_paths, file_property_name):
+        Logs an ML experiment run with metrics, plots, and artifacts.
+
+    create_ml_database(parent_page_id, db_title, config, metrics, file_property_name):
+        Creates a new Notion database optimized for ML experiment tracking.
+
+    dict_to_notion_schema(data, title_key):
+        Converts a dictionary into a Notion property schema.
+
+    dict_to_notion_props(data, title_key):
+        Converts a dictionary into Notion property values.
+    """
+
+    def dict_to_notion_schema(self, data: Dict[str, Any], title_key: str) -> Dict[str, Any]:
+        """Converts a dictionary into a Notion property schema for database creation.
+
+        Parameters:
+            data (dict): Dictionary containing sample values to infer types from.
+            title_key (str): The key that should be used as the title property.
+
+        Returns:
+            dict: A dictionary defining the Notion property schema.
+        """
+        properties = {}
+
+        for key, value in data.items():
+            # Handle NumPy types
+            if hasattr(value, "item"):
+                value = value.item()
+
+            # Debug output to help diagnose type issues
+            print(f"DEBUG: key='{key}', value={value}, type={type(value).__name__}, isinstance(bool)={isinstance(value, bool)}, isinstance(int)={isinstance(value, int)}")
+
+            if key == title_key:
+                properties[key] = {"title": {}}
+            # IMPORTANT: Check for bool BEFORE (int, float) because bool is a subclass of int in Python
+            elif isinstance(value, bool):
+                properties[key] = {"checkbox": {}}
+                print(f"  → Assigned as CHECKBOX")
+            elif isinstance(value, (int, float)):
+                properties[key] = {"number": {"format": "number"}}
+                print(f"  → Assigned as NUMBER")
+            else:
+                properties[key] = {"rich_text": {}}
+                print(f"  → Assigned as RICH_TEXT")
+
+        return properties
+
+    def dict_to_notion_props(self, data: Dict[str, Any], title_key: str) -> Dict[str, Any]:
+        """Converts a dictionary into Notion property values for page creation.
+
+        Parameters:
+            data (dict): Dictionary containing the values to convert.
+            title_key (str): The key that should be used as the title property.
+
+        Returns:
+            dict: A dictionary defining the Notion property values.
+        """
+        notion_props = {}
+        for key, value in data.items():
+            # Handle NumPy types
+            if hasattr(value, "item"):
+                value = value.item()
+
+            if key == title_key:
+                ts = datetime.now().strftime("%Y-%m-%d %H:%M")
+                notion_props[key] = {"title": [{"text": {"content": f"{value} ({ts})"}}]}
+
+            # FIX: Handle Booleans
+            elif isinstance(value, bool):
+                # Option A: Map to a Checkbox column in Notion
+                # notion_props[key] = {"checkbox": value}
+
+                # Option B: Map to a Rich Text column as a string (since you added a rich text field)
+                notion_props[key] = {"rich_text": [{"text": {"content": str(value)}}]}
+
+            elif isinstance(value, (int, float)):
+                if pd.isna(value) or np.isinf(value):
+                    continue
+                notion_props[key] = {"number": float(value)}
+            else:
+                notion_props[key] = {"rich_text": [{"text": {"content": str(value)}}]}
+        return notion_props
+
+    def log_ml_experiment(
+        self,
+        data_source_id: str,
+        config: Dict,
+        metrics: Dict,
+        plots: List[str] = None,
+        target_metric: str = "sMAPE",
+        higher_is_better: bool = False,
+        file_paths: Optional[List[str]] = None,
+        file_property_name: str = "Output Files"
+    ):
+        """Logs ML experiment and compares metrics with multiple file support."""
+        improvement_tag = "Standard Run"
+        new_score = metrics.get(target_metric)
+
+        # 1. Leaderboard Logic (Champions)
+        if new_score is not None:
+            try:
+                df = self.get_data_source_pages_as_dataframe(data_source_id, limit=100)
+                if not df.empty and target_metric in df.columns:
+                    valid_scores = pd.to_numeric(df[target_metric], errors='coerce').dropna()
+                    if not valid_scores.empty:
+                        current_best = valid_scores.max() if higher_is_better else valid_scores.min()
+                        is_improvement = (new_score > current_best) if higher_is_better else (new_score < current_best)
+                        if is_improvement:
+                            improvement_tag = f"🏆 NEW BEST {target_metric} (Prev: {current_best:.2f})"
+                        else:
+                            diff = abs(new_score - current_best)
+                            improvement_tag = f"No Improvement (+{diff:.2f} {target_metric})"
+            except Exception as e:
+                print(f"Leaderboard check skipped: {e}")
+
+        # 2. Prepare Notion Properties
+        data_for_notion = metrics.copy()
+        data_for_notion["Run Status"] = improvement_tag
+        combined_payload = {**config, **data_for_notion}
+        title_key = list(config.keys())[0]
+        properties = self.dict_to_notion_props(combined_payload, title_key)
+
+        try:
+            # 3. Create the row
+            new_page = self.new_page_to_data_source(data_source_id, properties)
+            page_id = new_page["id"]
+
+            # 4. Handle Plots (Body)
+            if plots:
+                for plot_path in plots:
+                    if os.path.exists(plot_path):
+                        self.one_step_image_embed(page_id, plot_path)
+
+            # 5. Handle Multiple File Uploads (Property)
+            if file_paths:
+                file_assets = []
+                for path in file_paths:
+                    if os.path.exists(path):
+                        print(f"Uploading {path}...")
+                        upload_resp = self.upload_file(path)
+                        file_assets.append({
+                            "type": "file_upload",
+                            "file_upload": {"id": upload_resp["id"]},
+                            "name": os.path.basename(path),
+                        })
+
+                if file_assets:
+                    # Attach all files in one request
+                    update_url = f"https://api.notion.com/v1/pages/{page_id}"
+                    file_payload = {"properties": {file_property_name: {"files": file_assets}}}
+                    self._make_request("PATCH", update_url, file_payload)
+                    print(f"✅ {len(file_assets)} files attached to {file_property_name}")
+
+            return page_id
+        except Exception as e:
+            print(f"Log error: {e}")
+            return None
+
+    def create_ml_database(self, parent_page_id: str, db_title: str, config: Dict, metrics: Dict, file_property_name: str = "Output Files") -> str:
+        """
+        Analyzes dicts to create a new Notion Database with the correct schema.
+        Uses dict_to_notion_schema() for universal type conversion.
+        """
+        combined = {**config, **metrics}
+        title_key = list(config.keys())[0]
+
+        # Use the universal dict_to_notion_schema() method
+        properties = self.dict_to_notion_schema(combined, title_key)
+
+        # Add 'Run Status' if not already present
+        if "Run Status" not in properties:
+            properties["Run Status"] = {"rich_text": {}}
+
+        # Add the Multi-file property
+        properties[file_property_name] = {"files": {}}
+
+        print(f"Creating database '{db_title}' with {len(properties)} columns...")
+
+        response = self.create_database(
+            parent_page_id=parent_page_id,
+            database_title=db_title,
+            initial_data_source_properties=properties
+        )
+
+        data_source_id = response.get("initial_data_source", {}).get("id")
+        return data_source_id if data_source_id else response.get("id")

{notionhelper-0.3.2.dist-info → notionhelper-0.4.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: notionhelper
-Version: 0.3.2
+Version: 0.4.1
 Summary: NotionHelper is a Python library that simplifies interactions with the Notion API, enabling easy management of databases, pages, and files within Notion workspaces.
 Author-email: Jan du Plessis <drjanduplessis@icloud.com>
 Requires-Python: >=3.10
@@ -74,7 +74,7 @@ Here is an example of how to use the library:
 
 ```python
 import os
-from notionhelper import NotionHelper
+from notionhelper import NotionHelper, MLNotionHelper
 ```
 
 ### Initialize the NotionHelper class
@@ -82,7 +82,11 @@ from notionhelper import NotionHelper
 ```python
 notion_token = os.getenv("NOTION_TOKEN")
 
+# For core Notion operations
 helper = NotionHelper(notion_token)
+
+# For ML experiment tracking (includes all NotionHelper methods)
+ml_helper = MLNotionHelper(notion_token)
 ```
 
 ### Retrieve a Database (Container)
@@ -164,6 +168,44 @@ helper.append_page_body(page_id, blocks)
 print(f"Successfully appended content to page ID: {page_id}")
 ```
 
+### Retrieve a Page and Convert to Markdown
+
+NotionHelper can retrieve page content and optionally convert it to markdown format for easy use in documents, blogs, or other applications.
+
+#### Get Page as JSON (Default)
+
+```python
+page_id = "your_page_id"
+result = helper.get_page(page_id)
+properties = result["properties"]  # Page properties
+content = result["content"]        # List of block objects (JSON)
+```
+
+#### Get Page as Markdown
+
+```python
+page_id = "your_page_id"
+result = helper.get_page(page_id, return_markdown=True)
+properties = result["properties"]  # Page properties
+markdown_content = result["content"]  # String in markdown format
+print(markdown_content)
+```
+
+The markdown conversion supports:
+- **Headings** (H1, H2, H3)
+- **Text formatting** (bold, italic, strikethrough, code, links)
+- **Lists** (bulleted and numbered)
+- **Code blocks** with language syntax highlighting
+- **Images**
+- **Dividers** and block quotes
+
+This is useful for:
+- Exporting Notion pages to markdown files
+- Integrating with static site generators
+- Creating blog posts from Notion content
+- Storing content in version control
+- Converting documentation to other formats
+
 ### Get all pages from a Data Source as a Pandas DataFrame
 
 ```python

notionhelper-0.4.1.dist-info/RECORD

@@ -0,0 +1,6 @@
+notionhelper/__init__.py,sha256=lidq1uQioToT1ePIu02XktGYTPMp_uY5Btw63GlNqOo,117
+notionhelper/helper.py,sha256=s2d2chVsQTFeE9zyn6onfVms21jpVstKENQEu1jhKaY,33007
+notionhelper/ml_logger.py,sha256=ex8Zy7reorLy5sOEfbDVZPwY2lsERJTTaJf3Ybj_vyg,8658
+notionhelper-0.4.1.dist-info/METADATA,sha256=T7ZINp4OGRKFKddgznBnbVjRRQG7Ol5X6DiD8FdB9mA,21227
+notionhelper-0.4.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+notionhelper-0.4.1.dist-info/RECORD,,

notionhelper-0.3.2.dist-info/RECORD

@@ -1,5 +0,0 @@
-notionhelper/__init__.py,sha256=_ShvAiiI4rspEoAjP71AHLPL1wrmcIlDBn0YUSqSMi8,61
-notionhelper/helper.py,sha256=NJdthOSNIqp1ESaDkV-V1Kb2x35LcQlAfG-KTyDnEl8,36279
-notionhelper-0.3.2.dist-info/METADATA,sha256=FQm2eSko-y1H26v28JJGG2Udg-HB4jfegiMF-TfRkfA,19906
-notionhelper-0.3.2.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-notionhelper-0.3.2.dist-info/RECORD,,