`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

Clone the repo and install the dependencies:

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

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`	-

lolipopshock/notion-df

notion-df: Seamlessly Connecting Notion Database with Pandas DataFrame

Installation

Usage

Development

TODOs

`notion-df`: Seamlessly Connecting Notion Database with Pandas DataFrame