notionhelper 0.1.6__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.6/README.md → notionhelper-0.1.7/PKG-INFO

@@ -1,3 +1,29 @@
+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)
@@ -9,9 +35,11 @@ For help constructing the JSON for the properties, use the [Notion API - JSON Bu
 ## 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.
+-   **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
@@ -121,13 +149,16 @@ print(f"Successfully appended content to page ID: {page_id}")
 ### Upload a File and Attach to a Page
 
 ```python
-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}")
+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
@@ -173,3 +204,53 @@ 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

notionhelper-0.1.6/PKG-INFO → notionhelper-0.1.7/README.md

@@ -1,15 +1,3 @@
-Metadata-Version: 2.4
-Name: notionhelper
-Version: 0.1.6
-Summary: Add your description here
-Author-email: Jan du Plessis <drjanduplessis@icloud.com>
-Requires-Python: >=3.12
-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
-Description-Content-Type: text/markdown
-
 # NotionHelper
 
 ![NotionHelper](https://github.com/janduplessis883/notionhelper/blob/master/images/helper_logo.png?raw=true)
@@ -21,9 +9,11 @@ For help constructing the JSON for the properties, use the [Notion API - JSON Bu
 ## 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.
+-   **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
@@ -133,13 +123,16 @@ print(f"Successfully appended content to page ID: {page_id}")
 ### Upload a File and Attach to a Page
 
 ```python
-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}")
+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
@@ -185,3 +178,53 @@ 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

notionhelper-0.1.7/pyproject.toml

@@ -0,0 +1,64 @@
+[project]
+name = "notionhelper"
+version = "0.1.7"
+description = "Add your description here"
+readme = "README.md"
+authors = [
+    { name = "Jan du Plessis", email = "drjanduplessis@icloud.com" }
+]
+requires-python = ">=3.10"
+dependencies = [
+    "mimetype>=0.1.5",
+    "notion-client>=2.4.0",
+    "pandas>=2.3.1",
+    "requests>=2.32.4",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = "test_*.py"
+python_classes = "Test*"
+python_functions = "test_*"
+addopts = [
+    "--verbose",
+    "--strict-markers",
+    "--strict-config", 
+    "--tb=short",
+    "--cov=src/notionhelper",
+    "--cov-report=term-missing",
+    "--cov-report=html:htmlcov",
+    "--cov-report=xml",
+    "--cov-fail-under=80"
+]
+markers = [
+    "unit: Unit tests",
+    "integration: Integration tests", 
+    "slow: Slow tests that may take longer to run",
+    "network: Tests that require network access (normally mocked)"
+]
+filterwarnings = [
+    "ignore::DeprecationWarning",
+    "ignore::PendingDeprecationWarning"
+]
+
+[project.optional-dependencies]
+test = [
+    "pytest>=7.0.0",
+    "pytest-cov>=4.0.0",
+    "pytest-mock>=3.10.0",
+    "pytest-asyncio>=0.21.0"
+]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-cov>=4.0.0", 
+    "pytest-mock>=3.10.0",
+    "pytest-asyncio>=0.21.0",
+    "black>=23.0.0",
+    "isort>=5.12.0",
+    "flake8>=6.0.0",
+    "mypy>=1.0.0"
+]

notionhelper-0.1.7/pytest.ini

@@ -0,0 +1,28 @@
+[tool:pytest]
+# Pytest configuration for NotionHelper
+testpaths = tests
+python_files = test_*.py
+python_classes = Test*
+python_functions = test_*
+addopts = 
+    --verbose
+    --strict-markers
+    --strict-config
+    --tb=short
+    --cov=src/notionhelper
+    --cov-report=term-missing
+    --cov-report=html:htmlcov
+    --cov-report=xml
+    --cov-fail-under=80
+markers =
+    unit: Unit tests
+    integration: Integration tests
+    slow: Slow tests that may take longer to run
+    network: Tests that require network access (normally mocked)
+filterwarnings =
+    ignore::DeprecationWarning
+    ignore::PendingDeprecationWarning
+log_cli = true
+log_cli_level = INFO
+log_cli_format = %(asctime)s [%(levelname)8s] %(name)s: %(message)s
+log_cli_date_format = %Y-%m-%d %H:%M:%S

notionhelper-0.1.7/src/notionhelper/__init__.py

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