Notions CLI

Notions - Notion 用 Python クライアントライブラリおよび CLI

Notion 用のコマンドラインクライアントおよび Python クライアントライブラリです。

Notion API を使用して、Notion のページやデータベースと通信します。

• ホームページ: https://github.com/micktwomey/notions
• リポジトリ: https://github.com/micktwomey/notions
• PyPI プロジェクトページ: https://pypi.org/project/notions/

• Notions - Notion 用 Python クライアントライブラリおよび CLI
• インストール
  • CLI 用 Homebrew
  • どこでも CLI を使える pipx
  • pip
  • poetry
  • pipenv
• 認証
• コマンドラインの使い方
  • 出力形式
  • コマンド
    • notions api
    • notions search
    • notions database list
    • notions database query
    • notions page get
• API
• Notions の開発
  • 実際の Notion API に対するテスト
• 名前の由来

インストール

CLI 用 Homebrew

notions tap を使ってインストールできます。

brew tap micktwomey/notions
brew install notions

# Or in one line: `brew install micktwomey/notions/notions`

どこでも CLI を使える pipx

CLI としてインストールして PATH から利用できるようにするには、pipx を使ってインストールできます。

pipx install notions

pip

pip を使ってインストールするには：

pip install notions

poetry

poetry を使って依存関係に追加するには：

poetry add notions

pipenv

pipenv を使って依存関係に追加するには：

pipenv install notions

認証

現在は Notion API トークンによる認証のみをサポートしています（詳細については、Notion のスタートガイドをご覧ください）。

トークンを取得する手順の概要：

1. https://www.notion.so/my-integrations にアクセスします
2. 新しい内部インテグレーションを作成します
3. API キーを控えておきます。後で必要になります
4. Notion のデータベースまたはページ（サイドバーの最上位項目）に移動し、共有ボタンをクリックします
5. インテグレーションを共有先に追加します。共有したいデータベースごとに設定する必要があります。Notion はデフォルトではすべてを公開しません。

コマンドラインの使い方

1. まず認証を行い、認証を参照して API トークンを取得します（以下では YOUR_KEY_GOES_HERE と表記します）
2. クライアントを呼び出すたびに notions --notion-api-key YOUR_KEY_GOES_HERE でキーを渡すか、NOTION_API_KEY 環境変数を設定します。
   1. fish で設定する場合：set -Ux NOTION_API_KEY YOUR_KEY_GOES_HERE
   2. bash/zsh で設定する場合：export NOTION_API_KEY=YOUR_KEY_GOES_HERE
3. notions --help を実行して、使用できるオプションを確認します

一部のオプションはグローバルで、コマンドの前に指定します。例：notions --output-format notion_yaml database query --query foo。

出力形式

notions --output-format で指定できる形式

1. notion_json - API の出力を解析し、複数の項目をリストに格納した JSON として出力します。
2. notion_jsonl - API の出力を解析し、1 行に 1 つの JSON オブジェクトを出力します。
3. notion_yaml - API の出力を解析し、複数の項目をリストに格納した YAML として出力します。
4. text（デフォルト） - API の出力を解析し、シンプルなテキスト表現を返します。ページ ID やデータベース ID を調べるのに便利です。
5. json - API の出力を解析し、テンプレート作成や処理に適した、よりフラットな JSON として出力します。複数の項目はリストに格納されます。
6. jsonl - API の出力を解析し、テンプレート作成や処理に適した、よりフラットな JSON を 1 行に 1 つずつ出力します。
7. yaml - API の出力を解析し、テンプレート作成や処理に適した、よりフラットな YAML として出力します。複数の項目はリストに格納されます。
8. tsv - API の出力を解析し、タブ区切り値として書き出します。
9. csv - API の出力を解析し、カンマ区切り値として書き出します。

コマンド

notions api

notions api を使うと、クライアントの認証機能を利用してリクエストを送信できます。

1. リクエストを送信してレスポンスの JSON を取得するには、notions api METHOD PATH を実行します。
2. ページネーションのサポートを利用してリクエストを送信するには（レスポンスを解析し、YAML などの形式で出力するオプションを利用できます）、notions api --paginate METHOD PATH を実行します。フラグの処理方法により、解析を開始して異なる出力形式を利用するには --paginate が必要です。

# Get all databases, without pagination and return raw JSON from Notion's API
notions api GET /v1/databases/

# Get all databases with pagination and format output as YAML
# This is the same as `notions --output-format yaml database list`
notions --output-format yaml api GET /v1/databases/ --paginate

notions search

notions search を使うと、作成した Notion インテグレーションと共有しているすべてのデータベースとページを検索できます。--query SOME_QUERY_STRING で検索対象を絞り込むと、一致するタイトルを持つ項目が返されます。

# show all pages and dbs with "example" in their title
notions search --query example

notions database list

notions database list を実行すると、インテグレーションがアクセスできるすべてのデータベースが一覧表示されます。

notions database query

指定したデータベース内のすべてのページに対してクエリを実行します。notions database list などを使って、データベースの UUID を取得する必要があります。

# Show all pages in the given db and sort by the HP property in descending order
notions database query cc5ef123-05f5-409e-9b34-38043df965b0 --sort-property HP:descending

notions page get

単一のページを取得します。

# Get a page in YAML
notions --output-format yaml page get ccad10e7-c776-423e-9662-6ad5fb1256d6

API

このライブラリを使う主な方法は、HTTP クライアントを利用することです（同じコードは examples/basic.py を参照してください）。

"""Example showing basic use of the client for API calls
"""

import asyncio
import os
import typing

import httpx

from notions.client import NotionAsyncClient
from notions.models.database import Database


async def http_list_databases(notion_client: NotionAsyncClient) -> httpx.Response:
    """Do a HTTP call with authentication to list databases

    This uses notions as a convenience for HTTP calls using httpx
    """
    async with notion_client.async_client() as client:
        url = notion_client.get_url_for_path("/v1/databases")
        return await client.request("GET", url.url)


async def list_databases(
    notion_client: NotionAsyncClient,
) -> typing.AsyncIterable[Database]:
    """Do a list db call (automatically reads all pages)

    This is the same underlying call as `http_list_databases` above
    but will also parse the response and handle pagination.

    Will yield notions.models.database.Database
    """
    async for db in notion_client.list_databases():
        yield db


async def main():
    api_token = os.environ.get("NOTION_API_KEY", "no-token-set")
    notion_client = NotionAsyncClient(api_token)

    response = await http_list_databases(notion_client)
    print(response)
    print(response.json())
    response.raise_for_status()

    async for db in list_databases(notion_client):
        print(db.id)
        print(db.title)
        print(db)


if __name__ == "__main__":
    asyncio.run(main())

examples/ にも例があります。実行には、さらに環境変数の設定が必要になる場合があります（設定方法については、下記の実際の Notion API に対するテストを参照してください）。

Notions の開発

ローカルで開発するには、asdf と poetry をインストールするのが最も簡単です。注意：asdf の just プラグインにはバグがあるため、asdf plugin add just [email protected]:heliumbrain/asdf-just.git を使ってインストールする必要がある場合があります。

その後、次のコマンドを実行できます。

1. asdf install を実行して、必要なすべての Python と開発ツールをインストールします。
2. just bootstrap-dev-env を実行して、開発環境をセットアップします。
3. サポート対象のすべての Python でテストするには just nox を、使用中の Python でより直接的にテストを実行するには just pytest-all を実行します。テストを高速に行うには、just pytest（または単に just）を実行できます。

Notion を対象に開発するには、Notion インテグレーション（API アクセス）を作成できる Notion プランが必要です。このライブラリに興味があるなら、すでにお持ちだと思います :D

リリースするには、現在の main の状態に問題がないことを確認し、just prepare-release を実行してから just do-release を実行してください。

Notion API の実際の環境でのテスト

すべてのサンプルは、テストの一部としても実行できます。そのためには、少し準備が必要です。

1. Notion で新しいトップレベルページを作成します。見つけやすいように「notions-test」のような名前を付けてください。自分だけが閲覧できる非公開ページでも構いません。
2. 以前作成した API インテグレーションと共有されていることを確認します（上記の認証を参照）。ページ右上の「Share」から共有できます。
3. ページの ID を取得します。方法のひとつは、「Share」→「Copy link」でリンクを取得することです。その後、ID をコピーできます。たとえば、https://www.notion.so/twomeylee/notions-test-76c28a7477334346807696ce8622a9fc は、テストでは 76c28a7477334346807696ce8622a9fc となります。
4. 次の 2 つの環境変数を設定してください（.env ファイルを使うか、シェルでエクスポートします）。
   1. NOTION_API_KEY - 認証の手順で作成したインテグレーションの API キーです。
   2. NOTIONS_PARENT_PAGE_UUID - 上記で作成したページの ID です。
   3. 任意：NOTIONS_KEEP_EXAMPLE_PAGES - 何らかの値を設定すると、後で確認できるよう、サンプルの実行中に作成されたページが保持されます。
5. just pytest-all を実行すると、これらのテストが実行されます。または、python example/the_example.py を使ってサンプルを直接実行できます。

残念ながら、現時点では API を使ってサンプルの実行で残る不要なデータをすべてきれいに削除することはできないため、いくつかの後片付けが必要です。

1. 任意：テストページ（上記の「notions-test」）の下に作成されたデータベースやページを削除します。テストを繰り返し実行する場合は、実行のたびに削除できます。
2. テストページ（上記の「notions-test」）を削除します。サンプルを再度実行するには、新しいページを作成し、NOTIONS_PARENT_PAGE_UUID を設定し直す必要があります。

名前の由来は？

「Notions」は、アイルランドで、自分の身分にそぐわない考えを持っている人を指すことがあります（「あの人は notions がある」）。典型的なアイルランドの言い回しで、少し意地悪な意味がありますが、皮肉として使われることもよくあります。面白いと思ったので、この名前を選びました（そして、Notion という会社が提供する製品のクライアントライブラリを書くなんて、私も大それたことを考えているのかもしれません）。