arcade-notion-toolkit 0.1.6__tar.gz

arcade_notion_toolkit-0.1.6/.gitignore

@@ -0,0 +1,175 @@
+.DS_Store
+credentials.yaml
+docker/credentials.yaml
+
+*.lock
+
+# example data
+examples/data
+scratch
+
+
+docs/source
+
+# From https://raw.githubusercontent.com/github/gitignore/main/Python.gitignore
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/

arcade_notion_toolkit-0.1.6/.pre-commit-config.yaml

@@ -0,0 +1,18 @@
+files: ^.*/notion/.*
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: "v4.4.0"
+    hooks:
+      - id: check-case-conflict
+      - id: check-merge-conflict
+      - id: check-toml
+      - id: check-yaml
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.6.7
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format

arcade_notion_toolkit-0.1.6/.ruff.toml

@@ -0,0 +1,44 @@
+target-version = "py310"
+line-length = 100
+fix = true
+
+[lint]
+select = [
+    # flake8-2020
+    "YTT",
+    # flake8-bandit
+    "S",
+    # flake8-bugbear
+    "B",
+    # flake8-builtins
+    "A",
+    # flake8-comprehensions
+    "C4",
+    # flake8-debugger
+    "T10",
+    # flake8-simplify
+    "SIM",
+    # isort
+    "I",
+    # mccabe
+    "C90",
+    # pycodestyle
+    "E", "W",
+    # pyflakes
+    "F",
+    # pygrep-hooks
+    "PGH",
+    # pyupgrade
+    "UP",
+    # ruff
+    "RUF",
+    # tryceratops
+    "TRY",
+]
+
+[lint.per-file-ignores]
+"**/tests/*" = ["S101"]
+
+[format]
+preview = true
+skip-magic-trailing-comma = false

arcade_notion_toolkit-0.1.6/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025, Arcade AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

arcade_notion_toolkit-0.1.6/Makefile

@@ -0,0 +1,55 @@
+.PHONY: help
+
+help:
+	@echo "🛠️ github Commands:\n"
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}'
+
+.PHONY: install
+install: ## Install the uv environment and install all packages with dependencies
+	@echo "🚀 Creating virtual environment and installing all packages using uv"
+	@uv sync --active --all-extras --no-sources
+	@if [ -f .pre-commit-config.yaml ]; then uv run --no-sources pre-commit install; fi
+	@echo "✅ All packages and dependencies installed via uv"
+
+.PHONY: install-local
+install-local: ## Install the uv environment and install all packages with dependencies with local Arcade sources
+	@echo "🚀 Creating virtual environment and installing all packages using uv"
+	@uv sync --active --all-extras
+	@if [ -f .pre-commit-config.yaml ]; then uv run pre-commit install; fi
+	@echo "✅ All packages and dependencies installed via uv"
+
+.PHONY: build
+build: clean-build ## Build wheel file using poetry
+	@echo "🚀 Creating wheel file"
+	uv build
+
+.PHONY: clean-build
+clean-build: ## clean build artifacts
+	@echo "🗑️ Cleaning dist directory"
+	rm -rf dist
+
+.PHONY: test
+test: ## Test the code with pytest
+	@echo "🚀 Testing code: Running pytest"
+	@uv run --no-sources pytest -W ignore -v --cov --cov-config=pyproject.toml --cov-report=xml
+
+.PHONY: coverage
+coverage: ## Generate coverage report
+	@echo "coverage report"
+	@uv run --no-sources coverage report
+	@echo "Generating coverage report"
+	@uv run --no-sources coverage html
+
+.PHONY: bump-version
+bump-version: ## Bump the version in the pyproject.toml file by a patch version
+	@echo "🚀 Bumping version in pyproject.toml"
+	uv version --no-sources --bump patch
+
+.PHONY: check
+check: ## Run code quality tools.
+	@if [ -f .pre-commit-config.yaml ]; then\
+		echo "🚀 Linting code: Running pre-commit";\
+		uv run --no-sources pre-commit run -a;\
+	fi
+	@echo "🚀 Static type checking: Running mypy"
+	@uv run --no-sources mypy --config-file=pyproject.toml

arcade_notion_toolkit-0.1.6/PKG-INFO

@@ -0,0 +1,19 @@
+Metadata-Version: 2.4
+Name: arcade_notion_toolkit
+Version: 0.1.6
+Summary: Arcade.dev LLM tools for Notion
+Author-email: Arcade <dev@arcade.dev>
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: arcade-tdk<3.0.0,>=2.0.0
+Requires-Dist: httpx<1.0.0,>=0.27.2
+Provides-Extra: dev
+Requires-Dist: arcade-ai[evals]<3.0.0,>=2.0.0; extra == 'dev'
+Requires-Dist: arcade-serve<3.0.0,>=2.0.0; extra == 'dev'
+Requires-Dist: mypy<1.6.0,>=1.5.1; extra == 'dev'
+Requires-Dist: pre-commit<3.5.0,>=3.4.0; extra == 'dev'
+Requires-Dist: pytest-asyncio<0.25.0,>=0.24.0; extra == 'dev'
+Requires-Dist: pytest-cov<4.1.0,>=4.0.0; extra == 'dev'
+Requires-Dist: pytest<8.4.0,>=8.3.0; extra == 'dev'
+Requires-Dist: ruff<0.8.0,>=0.7.4; extra == 'dev'
+Requires-Dist: tox<4.12.0,>=4.11.1; extra == 'dev'

arcade_notion_toolkit-0.1.6/arcade_notion_toolkit/block_to_markdown_converter.py

@@ -0,0 +1,201 @@
+import asyncio
+from typing import Any
+
+from arcade_tdk import ToolContext
+
+from arcade_notion_toolkit.enums import BlockType
+from arcade_notion_toolkit.utils import get_page_url
+
+
+class BlockToMarkdownConverter:
+    """
+    A converter class that transforms Notion blocks into Markdown.
+
+    The class registers conversion handlers for different Notion block types.
+    If a block type does not have a handler, then the block's plain text is returned.
+    """
+
+    def __init__(self, context: ToolContext):
+        self.context = context
+        # block types whose conversion logic has been implemented
+        # TODO: implement conversion logic for more block types
+        self.handlers = {
+            BlockType.BULLETED_LIST_ITEM.value: self._convert_bulleted_list_item,
+            BlockType.EQUATION.value: self._convert_equation,
+            BlockType.HEADING_1.value: self._convert_heading_1,
+            BlockType.HEADING_2.value: self._convert_heading_2,
+            BlockType.HEADING_3.value: self._convert_heading_3,
+            BlockType.LINK_PREVIEW.value: self._convert_link_preview,
+            BlockType.NUMBERED_LIST_ITEM.value: self._convert_numbered_list_item,
+            BlockType.PARAGRAPH.value: self._convert_paragraph,
+        }
+
+    async def convert_block(self, block: dict[str, Any]) -> str:
+        """
+        Convert a single Notion block to a Markdown string
+
+        Args:
+            block (dict[str, Any]): A Notion block.
+
+        Returns:
+            str: A Markdown string.
+        """
+        block_type = block.get("type")
+        if block_type in self.handlers:
+            converter = self.handlers[block_type]
+            if asyncio.iscoroutinefunction(converter):
+                md: str = await converter(block)
+                return md
+            else:
+                return converter(block)
+        elif block_type == BlockType.CHILD_PAGE.value:
+            return await self._convert_child_page(block)
+        else:
+            return self._get_plaintext(block)
+
+    @staticmethod
+    def rich_text_to_markdown(rich_text_items: list[dict[str, Any]]) -> str:
+        """
+        Convert a list of rich text items (from a Notion block) into Markdown.
+
+        Handles formatting such as bold, italic, strikethrough, underline (via HTML),
+        inline code, text coloring, hyperlinks, and equations.
+        """
+        md = ""
+        for item in rich_text_items:
+            annotations = item.get("annotations", {})
+            type_val = item.get("type", "text")
+            link = None
+
+            # Special handling for inline equations.
+            if type_val == "equation":
+                expression = item.get("equation", {}).get("expression", "")
+                md += f"${expression}$"
+                continue
+
+            if type_val == "text":
+                text_obj = item.get("text", {})
+                text = text_obj.get("content", "")
+                link_obj = text_obj.get("link")
+                link = (
+                    link_obj.get("url")
+                    if (link_obj and isinstance(link_obj, dict))
+                    else item.get("href")
+                )
+            elif type_val == "mention":
+                text = item.get("plain_text", "")
+                link = item.get("href")
+            else:
+                text = item.get("plain_text", "")
+                link = item.get("href")
+
+            if text.strip() == "":
+                continue
+
+            # Apply annotation formatting.
+            text = BlockToMarkdownConverter.apply_formatting(text, annotations, link)
+
+            md += text
+
+        return md
+
+    @staticmethod
+    def apply_formatting(text: str, annotations: dict[str, Any], link: str | None = None) -> str:
+        """Apply formatting to a text string based on the annotations.
+        Used when converting rich text to markdown
+
+        Args:
+            text (str): The text to format.
+            annotations (dict[str, Any]): The annotations to apply to the text.
+            link (str | None): An optional link for a hyperlink.
+
+        Returns:
+            str: The formatted text.
+        """
+        # If code block, wrap in backticks and skip other formatting.
+        if annotations.get("code"):
+            return f"`{text}`"
+
+        # Add underline
+        if annotations.get("underline"):
+            text = f"<u>{text}</u>"
+
+        # Apply color
+        color = annotations.get("color", "default")
+        if color != "default":
+            text = f'<span style="color: {color};">{text}</span>'
+
+        # Add bold, italic, and strikethrough
+        markers = [
+            marker
+            for key, marker in (("bold", "**"), ("italic", "*"), ("strikethrough", "~~"))
+            if annotations.get(key)
+        ]
+        if markers:
+            text = "".join(markers) + text + "".join(reversed(markers))
+
+        # Add hyperlink
+        if link:
+            text = f"[{text}]({link})"
+
+        return text
+
+    def _get_plaintext(self, block: dict[str, Any]) -> str:
+        """
+        Extract and return the plain text from a Notion block.
+        This acts as a fallback for unsupported block types.
+        """
+        block_type: str = block.get("type", "")
+        content = block.get(block_type, {})
+        if isinstance(content, dict):
+            rich_text_items = content.get("rich_text", [])
+            return "".join(item.get("plain_text", "") for item in rich_text_items)
+        return ""
+
+    def _convert_text_block(self, block: dict[str, Any], element_key: str, prefix: str = "") -> str:
+        """
+        Helper method to convert a Notion block's rich_text element into a Markdown string.
+        Optionally, a prefix (like a markdown list marker or heading hashes) is added.
+        """
+        element = block.get(element_key, {})
+        rich_text_items = element.get("rich_text", [])
+        text = self.rich_text_to_markdown(rich_text_items)
+        return f"{prefix}{text}  \n"
+
+    async def _convert_child_page(self, block: dict[str, Any]) -> str:
+        """
+        Asynchronously convert a child page block. This requires fetching the page's URL.
+        """
+        page_url = await get_page_url(self.context, block.get("id", ""))
+        child_page = block.get("child_page", {})
+        rich_text_items = child_page.get("rich_text", [])
+        if rich_text_items:
+            title = self.rich_text_to_markdown(rich_text_items)
+        else:
+            title = child_page.get("title", "")
+        return f"[{title}]({page_url})  \n"
+
+    def _convert_bulleted_list_item(self, block: dict[str, Any]) -> str:
+        return self._convert_text_block(block, "bulleted_list_item", "- ")
+
+    def _convert_equation(self, block: dict[str, Any]) -> str:
+        expression = block.get("equation", {}).get("expression", "")
+        return f"$$ {expression} $$  \n"
+
+    def _convert_heading_1(self, block: dict[str, Any]) -> str:
+        return self._convert_text_block(block, "heading_1", "# ")
+
+    def _convert_heading_2(self, block: dict[str, Any]) -> str:
+        return self._convert_text_block(block, "heading_2", "## ")
+
+    def _convert_heading_3(self, block: dict[str, Any]) -> str:
+        return self._convert_text_block(block, "heading_3", "### ")
+
+    def _convert_link_preview(self, block: dict[str, Any]) -> str:
+        return self._convert_text_block(block, "link_preview")
+
+    def _convert_numbered_list_item(self, block: dict[str, Any]) -> str:
+        return self._convert_text_block(block, "numbered_list_item", "1. ")
+
+    def _convert_paragraph(self, block: dict[str, Any]) -> str:
+        return self._convert_text_block(block, "paragraph")

arcade_notion_toolkit-0.1.6/arcade_notion_toolkit/constants.py

@@ -0,0 +1,17 @@
+NOTION_API_URL = "https://api.notion.com/v1"
+
+
+ENDPOINTS = {
+    "create_a_page": "/pages",
+    "retrieve_block_children": "/blocks/{block_id}/children",
+    "search_by_title": "/search",
+    "query_a_database": "/databases/{database_id}/query",
+    "update_page_properties": "/pages/{page_id}",
+    "append_block_children": "/blocks/{block_id}/children",
+    "retrieve_a_database": "/databases/{database_id}",
+    "create_comment": "/comments",
+    "retrieve_a_page": "/pages/{page_id}",
+    "retrieve_a_block": "/blocks/{block_id}",
+}
+
+UNTITLED_TITLE = "New Page"

arcade_notion_toolkit-0.1.6/arcade_notion_toolkit/enums.py

@@ -0,0 +1,45 @@
+from enum import Enum
+
+
+class SortDirection(str, Enum):
+    ASCENDING = "ascending"
+    DESCENDING = "descending"
+
+
+class ObjectType(str, Enum):
+    PAGE = "page"
+    DATABASE = "database"
+
+
+class BlockType(str, Enum):
+    BOOKMARK = "bookmark"
+    BREADCRUMB = "breadcrumb"
+    BULLETED_LIST_ITEM = "bulleted_list_item"
+    CALLOUT = "callout"
+    CHILD_DATABASE = "child_database"
+    CHILD_PAGE = "child_page"
+    COLUMN = "column"
+    COLUMN_LIST = "column_list"
+    DIVIDER = "divider"
+    EMBED = "embed"
+    EQUATION = "equation"
+    FILE = "file"
+    HEADING_1 = "heading_1"
+    HEADING_2 = "heading_2"
+    HEADING_3 = "heading_3"
+    IMAGE = "image"
+    LINK_PREVIEW = "link_preview"
+    LINK_TO_PAGE = "link_to_page"
+    NUMBERED_LIST_ITEM = "numbered_list_item"
+    PARAGRAPH = "paragraph"
+    PDF = "pdf"
+    QUOTE = "quote"
+    SYNCED_BLOCK = "synced_block"
+    TABLE = "table"
+    TABLE_OF_CONTENTS = "table_of_contents"
+    TABLE_ROW = "table_row"
+    TEMPLATE = "template"
+    TO_DO = "to_do"
+    TOGGLE = "toggle"
+    UNSUPPORTED = "unsupported"
+    VIDEO = "video"