notionhelper 0.1.5__tar.gz → 0.1.7__tar.gz

notionhelper-0.1.7/.claude/settings.local.json

@@ -0,0 +1,12 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(uv sync:*)",
+      "Bash(pytest:*)",
+      "Bash(uv run pytest:*)",
+      "Bash(git add:*)"
+    ],
+    "deny": [],
+    "ask": []
+  }
+}

notionhelper-0.1.7/.github/workflows/claude-code-review.yml

@@ -0,0 +1,78 @@
+name: Claude Code Review
+
+on:
+  pull_request:
+    types: [opened, synchronize]
+    # Optional: Only run on specific file changes
+    # paths:
+    #   - "src/**/*.ts"
+    #   - "src/**/*.tsx"
+    #   - "src/**/*.js"
+    #   - "src/**/*.jsx"
+
+jobs:
+  claude-review:
+    # Optional: Filter by PR author
+    # if: |
+    #   github.event.pull_request.user.login == 'external-contributor' ||
+    #   github.event.pull_request.user.login == 'new-developer' ||
+    #   github.event.pull_request.author_association == 'FIRST_TIME_CONTRIBUTOR'
+    
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+      issues: read
+      id-token: write
+    
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Run Claude Code Review
+        id: claude-review
+        uses: anthropics/claude-code-action@beta
+        with:
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+
+          # Optional: Specify model (defaults to Claude Sonnet 4, uncomment for Claude Opus 4.1)
+          # model: "claude-opus-4-1-20250805"
+
+          # Direct prompt for automated review (no @claude mention needed)
+          direct_prompt: |
+            Please review this pull request and provide feedback on:
+            - Code quality and best practices
+            - Potential bugs or issues
+            - Performance considerations
+            - Security concerns
+            - Test coverage
+            
+            Be constructive and helpful in your feedback.
+
+          # Optional: Use sticky comments to make Claude reuse the same comment on subsequent pushes to the same PR
+          # use_sticky_comment: true
+          
+          # Optional: Customize review based on file types
+          # direct_prompt: |
+          #   Review this PR focusing on:
+          #   - For TypeScript files: Type safety and proper interface usage
+          #   - For API endpoints: Security, input validation, and error handling
+          #   - For React components: Performance, accessibility, and best practices
+          #   - For tests: Coverage, edge cases, and test quality
+          
+          # Optional: Different prompts for different authors
+          # direct_prompt: |
+          #   ${{ github.event.pull_request.author_association == 'FIRST_TIME_CONTRIBUTOR' && 
+          #   'Welcome! Please review this PR from a first-time contributor. Be encouraging and provide detailed explanations for any suggestions.' ||
+          #   'Please provide a thorough code review focusing on our coding standards and best practices.' }}
+          
+          # Optional: Add specific tools for running tests or linting
+          # allowed_tools: "Bash(npm run test),Bash(npm run lint),Bash(npm run typecheck)"
+          
+          # Optional: Skip review for certain conditions
+          # if: |
+          #   !contains(github.event.pull_request.title, '[skip-review]') &&
+          #   !contains(github.event.pull_request.title, '[WIP]')
+

notionhelper-0.1.7/.github/workflows/claude.yml

@@ -0,0 +1,64 @@
+name: Claude Code
+
+on:
+  issue_comment:
+    types: [created]
+  pull_request_review_comment:
+    types: [created]
+  issues:
+    types: [opened, assigned]
+  pull_request_review:
+    types: [submitted]
+
+jobs:
+  claude:
+    if: |
+      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) ||
+      (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+      issues: read
+      id-token: write
+      actions: read # Required for Claude to read CI results on PRs
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Run Claude Code
+        id: claude
+        uses: anthropics/claude-code-action@beta
+        with:
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+
+          # This is an optional setting that allows Claude to read CI results on PRs
+          additional_permissions: |
+            actions: read
+          
+          # Optional: Specify model (defaults to Claude Sonnet 4, uncomment for Claude Opus 4.1)
+          # model: "claude-opus-4-1-20250805"
+          
+          # Optional: Customize the trigger phrase (default: @claude)
+          # trigger_phrase: "/claude"
+          
+          # Optional: Trigger when specific user is assigned to an issue
+          # assignee_trigger: "claude-bot"
+          
+          # Optional: Allow Claude to run specific commands
+          # allowed_tools: "Bash(npm install),Bash(npm run build),Bash(npm run test:*),Bash(npm run lint:*)"
+          
+          # Optional: Add custom instructions for Claude to customize its behavior for your project
+          # custom_instructions: |
+          #   Follow our coding standards
+          #   Ensure all new code has tests
+          #   Use TypeScript for new files
+          
+          # Optional: Custom environment variables for Claude
+          # claude_env: |
+          #   NODE_ENV: test
+

notionhelper-0.1.7/CLAUDE.md

@@ -0,0 +1,74 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+NotionHelper is a Python library that provides a convenient interface for interacting with the Notion API. The library simplifies database management, page operations, file handling, and data conversion to Pandas DataFrames.
+
+## Development Commands
+
+### Package Management
+- Uses `uv` for dependency management (see `uv.lock`)
+- Install dependencies: `uv sync` or `uv sync --extra dev`
+- Build package: `uv build`
+
+### Testing
+- Full pytest test suite with 21 tests covering all major functionality
+- Run tests: `uv run pytest`
+- Run with coverage: `uv run pytest --cov=src/notionhelper --cov-report=term-missing`
+- Test configuration in `pytest.ini` and `pyproject.toml`
+- Install test dependencies: `uv sync --extra test`
+
+## Architecture
+
+### Core Structure
+- Main implementation: `src/notionhelper/helper.py`
+- Single class `NotionHelper` contains all functionality
+- Built on top of `notion-client`, `requests`, and `pandas`
+
+### Key Components
+
+**NotionHelper Class** (`src/notionhelper/helper.py:12`)
+- Single entry point for all Notion API interactions
+- Handles authentication via token-based auth
+- Provides both basic API wrappers and convenience methods
+
+**Database Operations**
+- `get_database()` - retrieve database schema
+- `create_database()` - create new databases
+- `get_all_pages_as_json()` / `get_all_pages_as_dataframe()` - bulk data retrieval with pagination
+
+**Page Operations** 
+- `new_page_to_db()` - add pages to databases
+- `append_page_body()` - add content blocks to pages
+- `notion_get_page()` - retrieve page properties and blocks
+
+**File Operations**
+- `upload_file()` - raw file upload to Notion
+- `attach_file_to_page()` / `embed_image_to_page()` - attach files/images to pages
+- `one_step_*` methods - convenience functions combining upload + attachment
+
+**Data Conversion**
+- `get_all_pages_as_dataframe()` - converts Notion data to pandas DataFrame
+- Handles 19+ Notion property types (title, status, number, date, etc.)
+- Includes pagination support and optional page ID inclusion
+
+### Authentication Pattern
+- Requires `NOTION_TOKEN` environment variable
+- Token passed to constructor: `NotionHelper(notion_token)`
+- Uses notion-client's `Client(auth=token)` for API access
+
+### Dependencies
+- `notion-client>=2.4.0` - Official Notion API client
+- `pandas>=2.3.1` - DataFrame operations 
+- `requests>=2.32.4` - Direct API calls for file operations
+- `mimetype>=0.1.5` - File type detection
+
+## Development Notes
+
+- The library uses synchronous operations only
+- File uploads use Notion's file upload API with direct HTTP requests
+- Pagination is handled automatically in bulk operations
+- Property extraction supports most common Notion field types
+- Complementary Streamlit app available for JSON construction: https://notioinapiassistant.streamlit.app

notionhelper-0.1.7/PKG-INFO

@@ -0,0 +1,256 @@
+Metadata-Version: 2.4
+Name: notionhelper
+Version: 0.1.7
+Summary: Add your description here
+Author-email: Jan du Plessis <drjanduplessis@icloud.com>
+Requires-Python: >=3.10
+Requires-Dist: mimetype>=0.1.5
+Requires-Dist: notion-client>=2.4.0
+Requires-Dist: pandas>=2.3.1
+Requires-Dist: requests>=2.32.4
+Provides-Extra: dev
+Requires-Dist: black>=23.0.0; extra == 'dev'
+Requires-Dist: flake8>=6.0.0; extra == 'dev'
+Requires-Dist: isort>=5.12.0; extra == 'dev'
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest-mock>=3.10.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Provides-Extra: test
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'test'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'test'
+Requires-Dist: pytest-mock>=3.10.0; extra == 'test'
+Requires-Dist: pytest>=7.0.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# NotionHelper
+
+![NotionHelper](https://github.com/janduplessis883/notionhelper/blob/master/images/helper_logo.png?raw=true)
+
+`NotionHelper` is a Python library that provides a convenient interface for interacting with the Notion API. It simplifies common tasks such as managing databases, pages, and file uploads, allowing you to integrate Notion's powerful features into your applications with ease.
+
+For help constructing the JSON for the properties, use the [Notion API - JSON Builder](https://notioinapiassistant.streamlit.app) Streamlit app.
+
+## Features
+
+-   **Synchronous Operations**: Uses `notion-client` and `requests` for straightforward API interactions.
+-   **Type Safety**: Full type hints for all methods ensuring better development experience and IDE support.
+-   **Error Handling**: Robust error handling for API calls and file operations.
+-   **Database Management**: Create, query, and retrieve Notion databases.
+-   **Page Operations**: Add new pages to databases and append content to existing pages.
+-   **File Handling**: Upload files and attach them to pages or page properties with built-in validation.
+-   **Pandas Integration**: Convert Notion database pages into a Pandas DataFrame for easy data manipulation.
+
+## Installation
+
+To install `NotionHelper`, you can use `pip`:
+
+```bash
+pip install notionhelper
+```
+
+This will also install all the necessary dependencies, including `notion-client`, `pandas`, and `requests`.
+
+## Authentication
+
+To use the Notion API, you need to create an integration and obtain an integration token.
+
+1.  **Create an Integration**: Go to [My Integrations](https://www.notion.so/my-integrations) and create a new integration.
+2.  **Get the Token**: Copy the "Internal Integration Token".
+3.  **Share with a Page/Database**: For your integration to access a page or database, you must share it with your integration from the "Share" menu in Notion.
+
+It is recommended to store your Notion token as an environment variable for security.
+
+```bash
+export NOTION_TOKEN="your_secret_token"
+```
+
+## Usage
+
+Here is an example of how to use the library:
+
+```python
+import os
+from notionhelper import NotionHelper
+```
+
+### Initialize the NotionHelper class
+
+```python
+notion_token = os.getenv("NOTION_TOKEN")
+
+helper = NotionHelper(notion_token)
+```
+
+### Retrieve a Database
+
+```python
+database_id = "your_database_id"
+database_schema = helper.get_database(database_id)
+print(database_schema)
+```
+
+### Create a New Page in a Database
+
+```python
+page_properties = {
+    "Name": {
+        "title": [
+            {
+                "text": {
+                    "content": "New Page from NotionHelper"
+                }
+            }
+        ]
+    }
+}
+new_page = helper.new_page_to_db(database_id, page_properties)
+print(new_page)
+```
+
+### Append Content to the New Page
+
+```python
+blocks = [
+    {
+        "object": "block",
+        "type": "heading_2",
+        "heading_2": {
+            "rich_text": [{"type": "text", "text": {"content": "Hello from NotionHelper!"}}]
+        }
+    },
+    {
+        "object": "block",
+        "type": "paragraph",
+        "paragraph": {
+            "rich_text": [
+                {
+                    "type": "text",
+                    "text": {
+                        "content": "This content was appended synchronously."
+                    }
+                }
+            ]
+        }
+    }
+]
+helper.append_page_body(page_id, blocks)
+print(f"Successfully appended content to page ID: {page_id}")
+```
+
+### Get all pages as a Pandas DataFrame
+
+```python
+  df = helper.get_all_pages_as_dataframe(database_id)
+  print(df.head())
+```
+
+### Upload a File and Attach to a Page
+
+```python
+try:
+    file_path = "path/to/your/file.pdf"  # Replace with your file path
+    upload_response = helper.upload_file(file_path)
+    file_upload_id = upload_response["id"]
+    # Replace with your page_id
+    page_id = "your_page_id"
+    attach_response = helper.attach_file_to_page(page_id, file_upload_id)
+    print(f"Successfully uploaded and attached file: {attach_response}")
+except Exception as e:
+    print(f"Error uploading file: {e}")
+```
+
+### Simplified File Operations
+
+NotionHelper provides convenient one-step methods that combine file upload and attachment operations:
+
+#### one_step_image_embed()
+Uploads an image and embeds it in a Notion page in a single call, combining what would normally require:
+1. Uploading the file
+2. Embedding it in the page
+
+```python
+page_id = "your_page_id"
+image_path = "path/to/image.png"
+response = helper.one_step_image_embed(page_id, image_path)
+print(f"Successfully embedded image: {response}")
+```
+
+#### one_step_file_to_page()
+Uploads a file and attaches it to a Notion page in one step, combining:
+1. Uploading the file
+2. Attaching it to the page
+
+```python
+page_id = "your_page_id"
+file_path = "path/to/document.pdf"
+response = helper.one_step_file_to_page(page_id, file_path)
+print(f"Successfully attached file: {response}")
+```
+
+#### one_step_file_to_page_property()
+Uploads a file and attaches it to a specific Files & Media property on a page, combining:
+1. Uploading the file
+2. Attaching it to the page property
+
+```python
+page_id = "your_page_id"
+property_name = "Files"  # Name of your Files & Media property
+file_path = "path/to/document.pdf"
+file_name = "Custom Display Name.pdf"  # Optional display name
+response = helper.one_step_file_to_page_property(page_id, property_name, file_path, file_name)
+print(f"Successfully attached file to property: {response}")
+```
+
+These methods handle all the intermediate steps automatically, making file operations with Notion much simpler.
+
+## Code Quality
+
+The NotionHelper library includes several quality improvements:
+
+- **Type Hints**: All methods include comprehensive type annotations for better IDE support and code clarity
+- **Error Handling**: Built-in validation and exception handling for common failure scenarios
+- **Clean Imports**: Explicit imports with `__all__` declaration for better namespace management
+- **Production Ready**: Removed debug output and implemented proper error reporting
+
+## Complete Function Reference
+
+The `NotionHelper` class provides the following methods:
+
+### Database Operations
+- **`get_database(database_id)`** - Retrieves the schema of a Notion database
+- **`create_database(parent_page_id, database_title, properties)`** - Creates a new database under a parent page
+- **`notion_search_db(database_id, query="")`** - Searches for pages in a database containing the query in their title
+
+### Page Operations  
+- **`new_page_to_db(database_id, page_properties)`** - Adds a new page to a database with specified properties
+- **`append_page_body(page_id, blocks)`** - Appends blocks of content to the body of a page
+- **`notion_get_page(page_id)`** - Retrieves page properties and content blocks as JSON
+
+### Data Retrieval & Conversion
+- **`get_all_page_ids(database_id)`** - Returns IDs of all pages in a database
+- **`get_all_pages_as_json(database_id, limit=None)`** - Returns all pages as JSON objects with properties
+- **`get_all_pages_as_dataframe(database_id, limit=None, include_page_ids=True)`** - Converts database pages to a Pandas DataFrame
+
+### File Operations
+- **`upload_file(file_path)`** - Uploads a file to Notion and returns the file upload object
+- **`attach_file_to_page(page_id, file_upload_id)`** - Attaches an uploaded file to a specific page
+- **`embed_image_to_page(page_id, file_upload_id)`** - Embeds an uploaded image into a page
+- **`attach_file_to_page_property(page_id, property_name, file_upload_id, file_name)`** - Attaches a file to a Files & Media property
+
+### One-Step Convenience Methods
+- **`one_step_image_embed(page_id, file_path)`** - Uploads and embeds an image in one operation
+- **`one_step_file_to_page(page_id, file_path)`** - Uploads and attaches a file to a page in one operation  
+- **`one_step_file_to_page_property(page_id, property_name, file_path, file_name)`** - Uploads and attaches a file to a page property in one operation
+
+### Utility Methods
+- **`info()`** - Displays comprehensive library information with all available methods (Jupyter notebook compatible)
+
+## Requirements
+
+- Python 3.10+
+- notion-client >= 2.4.0
+- pandas >= 2.3.1  
+- requests >= 2.32.4
+- mimetype >= 0.1.5