Origami

启动、编辑和分享Jupyter笔记本 自动化。

安装 | 入门 | 文档 | 许可证 | 行为准则 | 贡献

Origami简介

Origami是一个用于与Noteable笔记本通信的🐍 Python库。这是访问API调用和异步Python中的访问模式的完整范围的官方方式，以实现丰富的程序化访问笔记本。您可以快速注册使用Noteable。

要求

Python 3.8+

安装

对于稳定版本

pip install noteable-origami

poetry add noteable-origami

对于alpha预发布

pip install noteable-origami --pre

入门

注意 开发者笔记：有关 1.0 版本之前的信息，请参阅预 1.0 README

API 令牌

Noteable API 需要一个身份验证令牌。您可以在 Noteable 用户设置页面管理令牌。

1. 登录到 Noteable（免费注册）。
2. 在“用户设置”选项卡中，导航到“API 令牌”并生成新的令牌。
3. 将生成的令牌复制到剪贴板并保存在安全位置，以便稍后读入 Python 环境。

令牌可以直接在初始化时传递给 APIClient，或者设置为环境变量 NOTEABLE_TOKEN。

用法

以下示例将指导您了解创建笔记本、添加内容、执行代码以及查看输出的基础知识。有关更多示例，请参阅我们的用例部分。

设置 APIClient

使用您之前创建的 API 令牌，将其加载到笔记本环境中，以便可以直接传递给 APIClient。 （如果您在 Noteable 中，您可以创建一个密钥，该密钥可以读取为环境变量。）

import os
from origami.clients.api import APIClient

# if we have the `NOTEABLE_TOKEN` environment variable set,
# we don't need to pass it in to the APIClient directly
api_client = APIClient()

APIClient 是我们将用于向 Noteable 的 REST API 发送 HTTP 请求的工具。

检查您的用户信息

user = await api_client.user_info()
user

User(
    id=UUID('f1a2b3c4-5678-4d90-ef01-23456789abcd'),
    created_at=datetime.datetime(2023, 1, 1, 0, 0, 0, 0, tzinfo=datetime.timezone.utc),
    updated_at=datetime.datetime(2023, 1, 1, 0, 0, 0, 0, tzinfo=datetime.timezone.utc),
    deleted_at=None,
    handle='ori.gami',
    email='origami@noteable.io',
    first_name='Ori',
    last_name='Gami',
    origamist_default_project_id=UUID('a1b2c3d4-e5f6-4a7b-8123-abcdef123456'),
    principal_sub='pat:0a1b2c3d4e5f6g7h8i9j10k11l',
    auth_type='pat:0a1b2c3d4e5f6g7h8i9j10k11l'
)

（返回的信息应与之前生成的 API 令牌关联的用户账户信息相匹配。）

创建新的笔记本

注意 在此示例中，我们使用的是 origamist_default_project_id，这是一个默认项目，旨在由 ChatGPT 插件使用。您可以用您在 Noteable 中可访问的项目替换它！

提供文件 path 以及笔记本将存在的 project_id（UUID）。

project_id = user.origamist_default_project_id

file = await api_client.create_notebook(
    project_id=project_id,
    path="Origami Demo.ipynb"
)
file

File(
    id=UUID('bcd12345-6789-4abc-d012-3456abcdef90'),
    created_at=datetime.datetime(2023, 2, 2, 0, 0, 0, 0, tzinfo=datetime.timezone.utc),
    updated_at=datetime.datetime(2023, 2, 2, 0, 0, 0, 0, tzinfo=datetime.timezone.utc),
    deleted_at=None,
    filename='Origami Demo.ipynb',
    path=PosixPath('Origami Demo.ipynb'),
    project_id=UUID('a1b2c3d4-e5f6-4a7b-8123-abcdef123456'),
    space_id=UUID('7890ab12-3412-4cde-8901-2345abcdef67'),
    size=0,
    mimetype=None,
    type='notebook',
    current_version_id=None,
    presigned_download_url=None,
    url='https://app.noteable.io/f/abc12312-3412-4abc-8123-abc12312abc1/Origami Demo.ipynb'
)

启动内核

至少需要 Notebook 的 file_id。此外，您还可以指定

• kernel_name（默认 python3，有关更多信息，请参阅可用的内核）
• hardware_size（默认 small，有关更多信息，请参阅硬件选项）。

kernel_session = await api_client.launch_kernel(file_id=file.id)
kernel_session

KernelSession(
    id=UUID('e1f2a345-6789-4b01-cdef-1234567890ab'),
    kernel=KernelDetails(
        name='python3',
        last_activity=datetime.datetime(2023, 2, 2, 1, 0, 0, 0, tzinfo=datetime.timezone.utc),
        execution_state='idle'
    )
)

添加单元

内容更新和代码执行通过 Noteable 实时更新（RTU）WebSocket 连接处理。

realtime_notebook = await api_client.connect_realtime(file)

警告 您可能会看到类似 Received un-modeled RTU message msg.channel= ... 的消息。这是我们更新 Noteable 后端服务的消息时预期的。

一旦 RTU 客户端连接，我们就可以开始添加单元、执行代码等等！首先，让我们添加一个带有基本 Python print 语句的代码单元。

from origami.models.notebook import CodeCell

cell = CodeCell(source="print('Hello World')")
await realtime_notebook.add_cell(cell=cell)

（您还可以通过将代码源直接传递给 .add_cell(source='CODE HERE') 作为快捷方式。）

运行代码单元

返回值是一个 asyncio.Future 字典。等待这些 futures 将阻塞，直到单元执行完成。Futures 的返回值是更新后的单元。如果有输出，将在单元元数据上设置一个输出集合 ID。

import asyncio

queued_execution = await realtime_notebook.queue_execution(cell.id)
cells = await asyncio.gather(*queued_execution)
cell = cells[0]
cell

CodeCell(
    id='2345ab6c-de78-4901-bcde-f1234567890a',
    source="print('Hello World')",
    metadata={
        'noteable': {'output_collection_id': UUID('d1234e5f-6789-4a0b-c123-4567890abcdef')},
        'ExecuteTime': {
            'start_time': '2023-02-02T01:00:00.000000+00:00',
            'end_time': '2023-02-02T01:00:00.050000+00:00'
        }
    },
    cell_type='code',
    execution_count=None,
    outputs=[]
)

获取单元输出

我们可以直接在单元上调用 .output_collection_id 属性，而不是解析单元元数据。

output_collection = await api_client.get_output_collection(cell.output_collection_id)
output_collection

KernelOutputCollection(
    id=UUID('d1234e5f-6789-4a0b-c123-4567890abcdef'),
    created_at=datetime.datetime(2023, 2, 2, 1, 0, 1, 000000, tzinfo=datetime.timezone.utc),
    updated_at=datetime.datetime(2023, 2, 2, 1, 0, 1, 000000, tzinfo=datetime.timezone.utc),
    deleted_at=None,
    cell_id='2345ab6c-de78-4901-bcde-f1234567890a',
    widget_model_id=None,
    file_id=UUID('bcd12345-6789-4abc-d012-3456abcdef90'),
    outputs=[
        KernelOutput(
            id=UUID('abcdef90-1234-4a56-7890-abcdef123456'),
            created_at=datetime.datetime(2023, 2, 2, 1, 0, 1, 000000, tzinfo=datetime.timezone.utc),
            updated_at=datetime.datetime(2023, 2, 2, 1, 0, 1, 000000, tzinfo=datetime.timezone.utc),
            deleted_at=None,
            type='stream',
            display_id=None,
            available_mimetypes=['text/plain'],
            content_metadata=KernelOutputContent(raw='{"name":"stdout"}', url=None, mimetype='application/json'),
            content=KernelOutputContent(raw='Hello World\n', url=None, mimetype='text/plain'),
            content_for_llm=KernelOutputContent(raw='Hello World\n', url=None, mimetype='text/plain'),
            parent_collection_id=UUID('d1234e5f-6789-4a0b-c123-4567890abcdef')
        )
    ]
)

CLI

Origami 有一个用于获取笔记本内容的简单 CLI，以及跟踪笔记本以查看在相关 RTU 通道上发出的所有 RTU 消息。

pip install noteable-origami[cli]
poetry install -E cli

1. 获取笔记本内容并写入文件：origami fetch <文件ID> > notebook.ipynb
2. 跟踪笔记本，当调试RTU消息时很有用：origami tail <文件ID>

开发环境设置

• 使用NOTEABLE_API_URL指向非生产集群，例如，用于本地Gate开发：http://localhost:8001/api
• E2E测试在运行时将使用环境变量TEST_SPACE_ID、TEST_PROJECT_ID和TEST_USER_ID，在CI中很有用

贡献

参见CONTRIBUTING.md。

由Noteable以❤️开源给社区。