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 输出并以 JSON 格式输出，每行一个 JSON 对象。
3. notion_yaml - 解析 API 输出并以 YAML 格式输出，多个项目包含在一个列表中。
4. text（默认）- 解析 API 输出并返回简单的文本表示。便于查找页面和数据库 ID。
5. json - 解析 API 输出并输出为结构更扁平的 JSON，更适合模板化和处理。多个项目会放在一个列表中。
6. jsonl - 解析 API 输出并输出为结构更扁平的 JSON，每行一个对象，更适合模板化和处理。
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 插件存在一个 bug，你可能需要使用 asdf plugin add just [email protected]:heliumbrain/asdf-just.git 来安装。

然后可以运行：

1. asdf install，安装所需的所有 Python 版本和开发工具。
2. just bootstrap-dev-env，设置开发环境。
3. just nox，测试所有受支持的 Python 版本；或者运行 just pytest-all，更直接地针对你的 Python 版本运行测试。若要更快地运行测试，可以执行 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. 确保设置以下两个环境变量（使用 .env 文件或在 shell 中导出）：
   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」有时用来指某人不安于自身地位、心怀不切实际的想法（「某某自以为是」）。这个说法通常带有爱尔兰特色，也有点刻薄，但经常以讽刺的方式使用。我选这个名字是因为觉得挺有趣（而且我可能也自以为是，竟然想为一家名为 Notion 的公司生产的产品编写客户端库）。