notion-df: Seamlessly Connecting Notion Database with Pandas DataFrame

Please Note: This project is currently in pre-alpha stage. The code are not appropriately documented and tested. Please report any issues you find. Thanks!

Installation

pip install notion-df

Usage

• Before starting, please follow the instructions to create a new integration and add it to your Notion page or database.

  • We'll refer Internal Integration Token as the api_key below.

• Pandas-flavored APIs: Just need to add two additional lines of code:

  import notion_df
  notion_df.pandas() #That's it!
  
  page_url = "paste your page url from Notion"
  api_key = "paste your api key (internal integration key)"
  
  import pandas as pd
  df = pd.read_notion(page_url, api_key=api_key)
  df.to_notion(page_url, api_key=api_key)

• Download your Notion table as a pandas DataFrame

  import notion_df
  df = notion_df.download(notion_database_url, api_key=api_key)
  # Equivalent to: df = pd.read_notion(notion_database_url, api_key=api_key)
  df.head()

  Only downloading the first `nrows` from a database

  df = notion_df.download(notion_database_url, nrows=nrows) #e.g., 10

  What if your table has a relation column?

  df = notion_df.download(notion_database_url, 
                          resolve_relation_values=True)

  The resolve_relation_values=True will automatically resolve the linking for all the relation columns whose target can be accessed by the current notion integration.

  In details, let's say the "test" column in df is a relation column in Notion.

  1. When resolve_relation_values=False, the return results for that column will be a list of UUIDs of the target page: ['65e04f11-xxxx', 'b0ffcb4b-xxxx', ].
  2. When resolve_relation_values=True, the return results for that column will be a list of regular strings corresponding to the name column of the target pages: ['page1', 'page2', ].

• Append a local df to a Notion database:

  import notion_df
  notion_df.upload(df, notion_database_url, title="page-title", api_key=api_key)
  # Equivalent to: df.to_notion(notion_database_url, title="page-title", api_key=api_key)

• Upload a local df to a newly created database in a Notion page:

  import notion_df
  notion_df.upload(df, notion_page_url, title="page-title", api_key=api_key)
  # Equivalent to: df.to_notion(notion_page_url, title="page-title", api_key=api_key)

• Tired of typing api_key=api_key each time?

  import notion_df
  notion_df.config(api_key=api_key) # Or set an environment variable `NOTION_API_KEY`
  df = notion_df.download(notion_database_url)
  notion_df.upload(df, notion_page_url, title="page-title")
  # Similarly in pandas APIs: df.to_notion(notion_page_url, title="page-title")

Development

1. Clone the repo and install the dependencies:

   git clone git@github.com:lolipopshock/notion-df.git
   cd notion-df
   pip install -e .[dev]

2. How to run tests?

   NOTION_API_KEY="<the-api-key>" pytest tests/

   The tests are dependent on a list of notebooks, specified by the following environment variables:

Environment Variable	Description
NOTION_API_KEY	The API key for your Notion integration
NOTION_ROLLUP_DF	-
NOTION_FILES_DF	-
NOTION_FORMULA_DF	-
NOTION_RELATION_DF	-
NOTION_RELATION_TARGET_DF	-
NOTION_LONG_STRING_DF	-
NOTION_RICH_TEXT_DF	-

TODOs

• Add tests for
  • load
  • upload
  • values.py
  • configs.py
  • base.py
• Better class organizations/namings for *Configs and *Values