Skip to content

Commit 90882e9

Browse files
Sumeet213Sumeet213
committed
Add intro-to-notion-api example for Python SDK
1 parent efccd0f commit 90882e9

File tree

13 files changed

+935
-0
lines changed

13 files changed

+935
-0
lines changed

‎examples/intro_to_notion_api/.env.example‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
NOTION_API_KEY=<your-notion-api-key>
2+
NOTION_PAGE_ID=<notion-page-id>

‎examples/intro_to_notion_api/README.md‎

Lines changed: 157 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,157 @@
1+
# Introduction to using Notion's SDK for Python
2+
3+
## Learn how to make Public API requests
4+
5+
Use this sample code to learn how to make Public API requests with varying
6+
degrees of difficulty.
7+
8+
The sample code is split into two sections:
9+
10+
1. `basic`
11+
2. `intermediate`
12+
13+
(An `advanced` section will soon be added, as well.)
14+
15+
If you are new to Notion's SDK for Python, start with the code samples in the
16+
`/basic` directory to get more familiar to basic concepts.
17+
18+
The files in each directory will build on each other to increase in complexity.
19+
For example, in `/intermediate`, first you will see how to create a database,
20+
then how to create a database and add a page to it, and finally create a
21+
database, add a page, and query/sort the database.
22+
23+
## Table of contents
24+
25+
In case you are looking for example code for a specific task, the files are
26+
divided as follows:
27+
28+
- `basic/1_add_block.py`: Create a new block and append it to an existing
29+
Notion page.
30+
- `basic/2_add_linked_block.py`: Create and append new blocks, and add a link
31+
to the text of a new block.
32+
- `basic/3_add_styled_block.py`: Create and append new blocks, and apply text
33+
styles to them.
34+
- `intermediate/1_create_a_database.py`: Create a new database with defined
35+
properties.
36+
- `intermediate/2_add_page_to_database.py`: Create a new database and add new
37+
pages to it.
38+
- `intermediate/3_query_database.py`: Create a new database, add pages to it,
39+
and filter the database entries (pages).
40+
- `intermediate/4_sort_database.py`: Create a new database, add pages to it,
41+
and filter/sort the database entries (pages).
42+
- `intermediate/5_upload_file.py`: Upload a file to Notion and attach it to a
43+
page as an image block.
44+
45+
## Running locally
46+
47+
### 1. Clone project and install dependencies
48+
49+
To use this example on your machine, clone the repo and move into your local
50+
copy:
51+
52+
```bash
53+
git clone https://github.com/ramnes/notion-sdk-py.git
54+
cd notion-sdk-py
55+
```
56+
57+
Next, move into this example in the `/examples` directory, and install its
58+
dependencies:
59+
60+
```bash
61+
cd examples/intro_to_notion_api
62+
pip install -r requirements.txt
63+
```
64+
65+
Alternatively, you can create a virtual environment:
66+
67+
```bash
68+
cd examples/intro_to_notion_api
69+
python -m venv venv
70+
source venv/bin/activate # On Windows use: venv\Scripts\activate
71+
pip install -r requirements.txt
72+
```
73+
74+
### 2. Set your environment variables in a `.env` file
75+
76+
A `.env.example` file has been included and can be renamed `.env` (or you can
77+
run `cp .env.example .env` to copy the file).
78+
79+
Update the environment variables below:
80+
81+
```bash
82+
NOTION_API_KEY=<your-notion-api-key>
83+
NOTION_PAGE_ID=<notion-page-id>
84+
```
85+
86+
`NOTION_API_KEY`: Create a new integration in the
87+
[integrations dashboard](https://www.notion.com/my-integrations) and retrieve
88+
the API key from the integration's `Secrets` page.
89+
90+
`NOTION_PAGE_ID`: Use the ID of any Notion page that you want to test adding
91+
content to.
92+
93+
The page ID is the 32 character string at the end of any page URL.
94+
![A Notion page URL with the ID highlighted](./assets/page_id.png)
95+
96+
### 3. Give the integration access to your page
97+
98+
Your Notion integration will need permission to interact with the Notion page
99+
being used for your `NOTION_PAGE_ID` variable. To provide access, do the
100+
following:
101+
102+
1. Go to the page in your workspace.
103+
2. Click the `•••` (more menu) on the top-right corner of the page.
104+
3. Scroll to the bottom of the menu and click `Add connections`.
105+
4. Search for and select your integration in the `Search for connections...`
106+
menu.
107+
108+
Once selected, your integration will have permission to read content from the
109+
page.
110+
111+
**If you are receiving authorization errors, make sure the integration has
112+
permission to access the page.**
113+
114+
### 4. Run individual examples
115+
116+
You have several options to run the examples:
117+
118+
#### Option 1: Run directly with python
119+
120+
```bash
121+
python basic/1_add_block.py
122+
python basic/2_add_linked_block.py
123+
python basic/3_add_styled_block.py
124+
125+
python intermediate/1_create_a_database.py
126+
python intermediate/2_add_page_to_database.py
127+
python intermediate/3_query_database.py
128+
python intermediate/4_sort_database.py
129+
python intermediate/5_upload_file.py
130+
```
131+
132+
#### Option 2: Run as modules
133+
134+
```bash
135+
python -m basic.1_add_block
136+
python -m intermediate.1_create_a_database
137+
```
138+
139+
---
140+
141+
## Additional resources
142+
143+
To learn more, read the
144+
[Public API docs](https://developers.notion.com/) for additional information
145+
on using Notion's API. The API docs include a series of
146+
[guides](https://developers.notion.com/docs) and the
147+
[API reference](https://developers.notion.com/reference/intro), which has a
148+
full list of available endpoints.
149+
150+
To see more examples of what you can build with Notion, see our other sample
151+
integrations in the parent `/examples` directory. To learn how to build an
152+
internal integration with an interactive frontend, read the
153+
[Build your first integration](https://developers.notion.com/docs/create-a-notion-integration)
154+
guide.
155+
156+
To connect with other developers building with Notion, join the
157+
[Notion Developers Slack group](https://join.slack.com/t/notiondevs/shared_invite/zt-20b5996xv-DzJdLiympy6jP0GGzu3AMg).

‎examples/intro_to_notion_api/assets/page_id.png‎

38.9 KB
Loading

‎examples/intro_to_notion_api/basic/1_add_block.py‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
import json
2+
import os
3+
4+
from notion_client import Client
5+
6+
try:
7+
from dotenv import load_dotenv
8+
9+
load_dotenv()
10+
except ModuleNotFoundError:
11+
pass
12+
13+
page_id = os.getenv("NOTION_PAGE_ID")
14+
api_key = os.getenv("NOTION_API_KEY")
15+
16+
notion = Client(auth=api_key)
17+
18+
# ---------------------------------------------------------------------------
19+
20+
"""
21+
Resources:
22+
- Appending block children endpoint (notion.blocks.children.append(): https://developers.notion.com/reference/patch-block-children)
23+
- Working with page content guide: https://developers.notion.com/docs/working-with-page-content
24+
"""
25+
26+
27+
def main():
28+
block_id = page_id # Blocks can be appended to other blocks *or* pages. Therefore, a page ID can be used for the block_id parameter
29+
new_heading_response = notion.blocks.children.append(
30+
block_id=block_id,
31+
# Pass an array of blocks to append to the page: https://developers.notion.com/reference/block#block-type-objects
32+
children=[
33+
{
34+
"heading_2": {
35+
"rich_text": [
36+
{
37+
"text": {
38+
"content": "Types of kale", # This is the text that will be displayed in Notion
39+
},
40+
},
41+
],
42+
},
43+
},
44+
],
45+
)
46+
47+
# Print the new block(s) response
48+
print(json.dumps(new_heading_response, indent=2))
49+
50+
51+
if __name__ == "__main__":
52+
main()

‎examples/intro_to_notion_api/basic/2_add_linked_block.py‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
import json
2+
import os
3+
4+
from notion_client import Client
5+
6+
try:
7+
from dotenv import load_dotenv
8+
9+
load_dotenv()
10+
except ModuleNotFoundError:
11+
pass
12+
13+
page_id = os.getenv("NOTION_PAGE_ID")
14+
api_key = os.getenv("NOTION_API_KEY")
15+
16+
notion = Client(auth=api_key)
17+
18+
# ---------------------------------------------------------------------------
19+
20+
"""
21+
Resources:
22+
- Appending block children endpoint (notion.blocks.children.append(): https://developers.notion.com/reference/patch-block-children)
23+
- Rich text options: https://developers.notion.com/reference/rich-text
24+
- Working with page content guide: https://developers.notion.com/docs/working-with-page-content
25+
"""
26+
27+
28+
def main():
29+
block_id = page_id # Blocks can be appended to other blocks *or* pages. Therefore, a page ID can be used for the block_id parameter
30+
linked_text_response = notion.blocks.children.append(
31+
block_id=block_id,
32+
# Pass an array of blocks to append to the page: https://developers.notion.com/reference/block#block-type-objects
33+
children=[
34+
{
35+
"heading_3": {
36+
"rich_text": [
37+
{
38+
"text": {
39+
"content": "Tuscan kale", # This is the text that will be displayed in Notion
40+
},
41+
},
42+
],
43+
},
44+
},
45+
{
46+
"paragraph": {
47+
"rich_text": [
48+
{
49+
"text": {
50+
"content": "Tuscan kale is a variety of kale with a long tradition in Italian cuisine, especially that of Tuscany. It is also known as Tuscan kale, Italian kale, dinosaur kale, kale, flat back kale, palm tree kale, or black Tuscan palm.",
51+
"link": {
52+
# Include a url to make the paragraph a link in Notion
53+
"url": "https://en.wikipedia.org/wiki/Kale",
54+
},
55+
},
56+
},
57+
],
58+
},
59+
},
60+
],
61+
)
62+
63+
# Print the new block(s) response
64+
print(json.dumps(linked_text_response, indent=2))
65+
66+
67+
if __name__ == "__main__":
68+
main()

‎examples/intro_to_notion_api/basic/3_add_styled_block.py‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
import json
2+
import os
3+
4+
from notion_client import Client
5+
6+
try:
7+
from dotenv import load_dotenv
8+
9+
load_dotenv()
10+
except ModuleNotFoundError:
11+
pass
12+
13+
page_id = os.getenv("NOTION_PAGE_ID")
14+
api_key = os.getenv("NOTION_API_KEY")
15+
16+
notion = Client(auth=api_key)
17+
18+
# ---------------------------------------------------------------------------
19+
20+
"""
21+
Resources:
22+
- Appending block children endpoint (notion.blocks.children.append(): https://developers.notion.com/reference/patch-block-children)
23+
- Rich text options: https://developers.notion.com/reference/rich-text
24+
- Working with page content guide: https://developers.notion.com/docs/working-with-page-content
25+
"""
26+
27+
28+
def main():
29+
block_id = page_id # Blocks can be appended to other blocks *or* pages. Therefore, a page ID can be used for the block_id parameter
30+
styled_link_text_response = notion.blocks.children.append(
31+
block_id=block_id,
32+
children=[
33+
{
34+
"heading_3": {
35+
"rich_text": [
36+
{
37+
"text": {
38+
"content": "Tuscan kale",
39+
},
40+
},
41+
],
42+
},
43+
},
44+
{
45+
"paragraph": {
46+
"rich_text": [
47+
{
48+
"text": {
49+
# Paragraph text
50+
"content": "Tuscan kale is a variety of kale with a long tradition in Italian cuisine, especially that of Tuscany. It is also known as Tuscan kale, Italian kale, dinosaur kale, kale, flat back kale, palm tree kale, or black Tuscan palm.",
51+
"link": {
52+
# Paragraph link
53+
"url": "https://en.wikipedia.org/wiki/Kale",
54+
},
55+
},
56+
"annotations": {
57+
# Paragraph styles
58+
"bold": True,
59+
"italic": True,
60+
"strikethrough": True,
61+
"underline": True,
62+
"color": "green",
63+
},
64+
},
65+
],
66+
},
67+
},
68+
],
69+
)
70+
71+
# Print the new block(s) response
72+
print(json.dumps(styled_link_text_response, indent=2))
73+
74+
75+
if __name__ == "__main__":
76+
main()

0 commit comments

Comments
 (0)