Skip to content

How tos

Jump to bottom
Chen Jianzhang edited this page Aug 1, 2022 · 1 revision

How-to: work with databases

Create a database

The database can be created using the client.databases.create method. See the official documentation for specific parameter requirements.

  • Dictionary parameter style
client.databases.create({
    "parent": {
        "type": "page_id",
        "page_id": "your_page_id"
    },
    "title": [
        {
            "type": "text",
            "text": {
                "content": "Meal List",
                "link": None
            }
        }
    ],
    "properties": {
        "Name": {
            "title": {}
        },
    }
})
  • Keyword parameter style
client.databases.create(
    parent={
        "type": "page_id",
        "page_id": "your_page_id"
    },
    title=[
        {
            "type": "text",
            "text": {
                "content": "Meal List",
                "link": None
            }
        }
    ],
    properties={
        "Name": {
            "title": {}
        },
    }
)

Get the basic information of a database

By using the client.databases.retrieve method. See the official documentation for specific parameter requirements.

client.databases.retrieve("your_database_id")

Querying a database

By using the client.databases.query method. See the official documentation for specific parameter requirements.

  • Dictionary parameter style
client.databases.query("your_database_id", {
    "filter": {
        "property": "Name",
        "title": {"equals": "Mango"}
    }
})
  • Keyword parameter style
client.databases.query("your_database_id", filter={
    "property": "Name",
    "title": {"equals": "Mango"}
})

Update a database

By using the client.databases.update method. See official documentation for specific parameter requirements.

  • Dictionary parameter style
client.databases.update("your_database_id", {
    "title": [
        {
            "text": {
                "content": "Today'\''s official_guides list"
            }
        }
    ],
    "description": [
        {
            "text": {
                "content": "Grocery list for just kale 🥬 (updated by mumu-notion!)"
            }
        }
    ],
    "properties": {
        "+1": None,
        "Photo": {
            "url": {}
        },
        "Store availability": {
            "multi_select": {
                "options": [
                    {
                        "name": "Duc Loi Market"
                    },
                    {
                        "name": "Rainbow Grocery"
                    },
                    {
                        "name": "Gus'\''s Community Market"
                    },
                    {
                        "name": "The Good Life Grocery",
                    },
                    {
                        "name": "Walmart",
                        "color": "gray"
                    }
                ]
            }
        }
    }
})
  • Keyword parameter style
client.databases.update(
    "your_database_id",
    title=[
        {
            "text": {
                "content": "Today'\''s official_guides list"
            }
        }
    ],
    description=[
        {
            "text": {
                "content": "Grocery list for just kale 🥬 (updated by mumu-notion!)"
            }
        }
    ],
    properties={
        "+1": None,
        "Photo": {
            "url": {}
        },
        "Store availability": {
            "multi_select": {
                "options": [
                    {
                        "name": "Duc Loi Market"
                    },
                    {
                        "name": "Rainbow Grocery"
                    },
                    {
                        "name": "Gus'\''s Community Market"
                    },
                    {
                        "name": "The Good Life Grocery",
                    },
                    {
                        "name": "Walmart",
                        "color": "gray"
                    }
                ]
            }
        }
    }
)

How-to: work with pages

Create a page

By using the client.pages.create method. See official documentation for specific parameter requirements.

  • Dictionary parameter style
client.pages.create({
    "cover": {
        "type": "external",
        "external": {
            "url": "https://upload.wikimedia.org/wikipedia/commons/6/62/Tuscankale.jpg"
        }
    },
    "icon": {
        "type": "emoji",
        "emoji": "🥬"
    },
    "parent": {
        "type": "page_id",  # The default parent is page
        "page_id": ""  # Need to fill
    },
    "properties": {
        "title": [
            {
                "text": {
                    "content": "Tuscan kale"
                }
            }
        ]
    },
    "children": [
        {
            "object": "block",
            "heading_2": {
                "rich_text": [
                    {
                        "text": {
                            "content": "Lacinato kale"
                        }
                    }
                ]
            }
        },
        {
            "object": "block",
            "paragraph": {
                "rich_text": [
                    {
                        "text": {
                            "content": "Lacinato 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.",
                            "link": {
                                "url": "https://en.wikipedia.org/wiki/Lacinato_kale"
                            }
                        },
                        "href": "https://en.wikipedia.org/wiki/Lacinato_kale"
                    }
                ],
                "color": "default"
            }
        }
    ]
})
  • Keyword parameter style
client.pages.create(
    cover={
        "type": "external",
        "external": {
            "url": "https://upload.wikimedia.org/wikipedia/commons/6/62/Tuscankale.jpg"
        }
    },
    icon={
        "type": "emoji",
        "emoji": "🥬"
    },
    parent={
        "type": "page_id",  # The default parent is page
        "page_id": ""  # Need to fill
    },
    properties={
        "title": [
            {
                "text": {
                    "content": "Tuscan kale"
                }
            }
        ]
    },
    children=[
        {
            "object": "block",
            "heading_2": {
                "rich_text": [
                    {
                        "text": {
                            "content": "Lacinato kale"
                        }
                    }
                ]
            }
        },
        {
            "object": "block",
            "paragraph": {
                "rich_text": [
                    {
                        "text": {
                            "content": "Lacinato 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.",
                            "link": {
                                "url": "https://en.wikipedia.org/wiki/Lacinato_kale"
                            }
                        },
                        "href": "https://en.wikipedia.org/wiki/Lacinato_kale"
                    }
                ],
                "color": "default"
            }
        }
    ]
)

Get basic information about a page

By using the client.pages.retrieve method. See the official documentation for specific parameter requirements.

client.pages.retrieve("your_page_id")

Update the information of a page

By using the client.pages.update method. See official documentation for specific parameter requirements.

  • Dictionary parameter style
client.pages.update("your_page_id", {
    "properties": {
        "title": [
            {
                "text": {
                    "content": "A new title created by PyNotion!"
                }
            }
        ]
    }
})
  • Keyword Parameter Style
client.pages.update(
    "your_page_id",
    properties={
        "title": [
            {
                "text": {
                    "content": "A new title created by PyNotion!"
                }
            }
        ]
    }
)

How-to: work with blocks

Get basic information about a block

By using the client.blocks.retrieve method. See official documentation for specific parameter requirements.

client.blocks.retrieve("your_block_id")

Update a block

By using the client.blocks.update method. See official documentation for specific parameter requirements.

  • Dictionary parameter style
client.blocks.update("your_block_id", {
    "heading_2": {
        "rich_text": [
            {
                "text": {
                    "content": "Lacinato kale (Updated by mumu-notion!)"
                },
                "annotations": {
                    "color": "green"
                }
            }
        ]
    }
})
  • Keyword parameter style
client.blocks.update(
    "your_block_id",
    heading_2={
        "rich_text": [
            {
                "text": {
                    "content": "Lacinato kale (Updated by mumu-notion!)"
                },
                "annotations": {
                    "color": "green"
                }
            }
        ]
    }
)

Get the block children of a block

By using the client.blocks.children.list method. See the official documentation for specific parameter requirements.

client.blocks.children.list("your_block_id")

Append block children

By using the client.blocks.children.append method. See the official documentation for specific parameter requirements.

  • Dictionary parameter style
client.blocks.children.append("your_block_id", {
    "children": [
        {
            "heading_2": {
                "rich_text": [
                    {
                        "text": {
                            "content": "Lacinato kale"
                        }
                    }
                ]
            }
        },
        {
            "paragraph": {
                "rich_text": [
                    {
                        "text": {
                            "content": "Lacinato 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.",
                            "link": {
                                "url": "https://en.wikipedia.org/wiki/Lacinato_kale"
                            }
                        }
                    }
                ]
            }
        }
    ]
})
  • Keyword parameter style
client.blocks.children.append(
    "your_block_id",
    children=[
        {
            "heading_2": {
                "rich_text": [
                    {
                        "text": {
                            "content": "Lacinato kale"
                        }
                    }
                ]
            }
        },
        {
            "paragraph": {
                "rich_text": [
                    {
                        "text": {
                            "content": "Lacinato 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.",
                            "link": {
                                "url": "https://en.wikipedia.org/wiki/Lacinato_kale"
                            }
                        }
                    }
                ]
            }
        }
    ]
)

Delete a block

By using the client.blocks.delete method. See official documentation for specific parameter requirements.

client.blocks.delete("your_block_id")

How-to: work with comments

Retrieve comments

By using the client.comments.list method. See official documentation for specific parameter requirements.

  • Dictionary parameter style
client.comments.list({"block_id": "your_block_or_page_id"})
  • Keyword parameter style
client.comments.list(block_id="your_block_or_page_id")

Create a comment on a page

By using the client.comments.create method. See official documentation for specific parameter requirements.

  • Dictionary parameter style
client.comments.create({
    "parent": {
        "page_id": "your_page_id"
    },
    "rich_text": [
        {
            "text": {
                "content": "Hello world"
            }
        }
    ]
})
  • keyword parameter style
client.comments.create(
    parent={
        "page_id": "your_page_id"
    },
    rich_text=[
        {
            "text": {
                "content": "Hello world"
            }
        }
    ]
)

How-to: work with users

Get basic information of a user

By using the client.users.retrieve method. See the official documentation for specific parameter requirements.

client.users.retrieve("user_id")

List all users

By using the client.users.list method. See official documentation for specific parameter requirements.

  • No parameters are provided
client.users.list()
  • Dictionary parameter style
client.users.list({
    "page_size": 100
})
  • Keyword parameter style
client.users.list(page_size=100)

Get the bot user information corresponding to the token

by using the client.users.me method. See the official documentation for the specific parameter requirements.

client.users.me()

Clone this wiki locally