bootstrap-sample-env.py

"""Bootstrap the Notion objects referenced by the sample documentation.

The sample documentation links to and mentions a Notion page, user and
database. These only exist in a particular workspace. This script creates the
page and database in a workspace of your choice, picks a user to mention, and
writes their IDs to an environment file (``sample.env`` by default) that
``sample/conf.py`` reads when building the sample.

Run it with the integration token in the environment::

    export NOTION_TOKEN="your_integration_token_here"
    uv run --all-extras python bootstrap-sample-env.py \
        --parent-page-id parent_page_id
"""

from pathlib import Path

import click
import cloup
from beartype import beartype
from ultimate_notion import Session


@beartype
def _env_file_contents(
    *,
    page_id: str,
    user_id: str,
    database_id: str,
) -> str:
    """Render the environment file contents for the given IDs."""
    lines = [
        "# Generated by bootstrap-sample-env.py.",
        f"NOTION_SAMPLE_PAGE_ID={page_id}",
        f"NOTION_SAMPLE_USER_ID={user_id}",
        f"NOTION_SAMPLE_DATABASE_ID={database_id}",
    ]
    return "\n".join(lines) + "\n"


@cloup.command()
@cloup.option(
    "--parent-page-id",
    help="ID of a page (shared with the integration) to create objects under",
    required=True,
)
@cloup.option(
    "--output",
    help="Path to the environment file to write",
    default="sample.env",
    show_default=True,
    type=cloup.Path(path_type=Path, file_okay=True, dir_okay=False),
)
@beartype
def main(
    *,
    parent_page_id: str,
    output: Path,
) -> None:
    """Create the sample's Notion objects and write their IDs to a
    file.
    """
    session = Session()
    try:
        parent = session.get_page(page_ref=parent_page_id)
        page = session.create_page(
            parent=parent,
            title="Sphinx-Notionbuilder sample linked page",
        )
        database = session.create_ds(
            parent=parent,
            title="Sphinx-Notionbuilder sample database",
            inline=True,
        )
        people = [user for user in session.all_users() if user.is_person]
        user = people[0] if people else session.whoami()
        user_id = str(object=user.id)
    finally:
        session.close()

    contents = _env_file_contents(
        page_id=page.id.hex,
        user_id=user_id,
        database_id=database.id.hex,
    )
    output.write_text(data=contents, encoding="utf-8")
    click.echo(message=f"Wrote {output}")


if __name__ == "__main__":
    main()