Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/lolipopshock/notion-df
Seamlessly Connecting Notion Database with Python Pandas DataFrame
https://github.com/lolipopshock/notion-df
notion notion-api python
Last synced: 5 days ago
JSON representation
Seamlessly Connecting Notion Database with Python Pandas DataFrame
- Host: GitHub
- URL: https://github.com/lolipopshock/notion-df
- Owner: lolipopshock
- License: mit
- Created: 2022-01-04T03:17:48.000Z (almost 3 years ago)
- Default Branch: main
- Last Pushed: 2023-09-08T13:42:30.000Z (about 1 year ago)
- Last Synced: 2024-10-16T11:46:47.409Z (20 days ago)
- Topics: notion, notion-api, python
- Language: Python
- Homepage:
- Size: 60.5 KB
- Stars: 82
- Watchers: 7
- Forks: 14
- Open Issues: 22
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# `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
```bash
pip install notion-df
```
## Usage
- Before starting, please follow the instructions to [create a new integration](https://www.notion.com/my-integrations) and [add it to your Notion page or database](https://developers.notion.com/docs/getting-started#step-2-share-a-database-with-your-integration).
- We'll refer `Internal Integration Token` as the `api_key` below.
- Pandas-flavored APIs: Just need to add two additional lines of code:
```python
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
```python
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
```python
df = notion_df.download(notion_database_url, nrows=nrows) #e.g., 10
```
What if your table has a relation column?
```python
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:
```python
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:
```python
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?
```python
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:
```bash
git clone [email protected]:lolipopshock/notion-df.git
cd notion-df
pip install -e .[dev]
```
2. How to run tests?
```bash
NOTION_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`