Add intro-to-notion-api example for Python SDK

examples/intro_to_notion_api/.env.example

@@ -0,0 +1,2 @@
+NOTION_API_KEY=<your-notion-api-key>
+NOTION_PAGE_ID=<notion-page-id>

examples/intro_to_notion_api/README.md

@@ -0,0 +1,157 @@
+# Introduction to using Notion's SDK for Python
+
+## Learn how to make Public API requests
+
+Use this sample code to learn how to make Public API requests with varying
+degrees of difficulty.
+
+The sample code is split into two sections:
+
+1. `basic`
+2. `intermediate`
+
+(An `advanced` section will soon be added, as well.)
+
+If you are new to Notion's SDK for Python, start with the code samples in the
+`/basic` directory to get more familiar to basic concepts.
+
+The files in each directory will build on each other to increase in complexity.
+For example, in `/intermediate`, first you will see how to create a database,
+then how to create a database and add a page to it, and finally create a
+database, add a page, and query/sort the database.
+
+## Table of contents
+
+In case you are looking for example code for a specific task, the files are
+divided as follows:
+
+- `basic/1_add_block.py`: Create a new block and append it to an existing
+  Notion page.
+- `basic/2_add_linked_block.py`: Create and append new blocks, and add a link
+  to the text of a new block.
+- `basic/3_add_styled_block.py`: Create and append new blocks, and apply text
+  styles to them.
+- `intermediate/1_create_a_database.py`: Create a new database with defined
+  properties.
+- `intermediate/2_add_page_to_database.py`: Create a new database and add new
+  pages to it.
+- `intermediate/3_query_database.py`: Create a new database, add pages to it,
+  and filter the database entries (pages).
+- `intermediate/4_sort_database.py`: Create a new database, add pages to it,
+  and filter/sort the database entries (pages).
+- `intermediate/5_upload_file.py`: Upload a file to Notion and attach it to a
+  page as an image block.
+
+## Running locally
+
+### 1. Clone project and install dependencies
+
+To use this example on your machine, clone the repo and move into your local
+copy:
+
+```bash
+git clone https://github.com/ramnes/notion-sdk-py.git
+cd notion-sdk-py
+```
+
+Next, move into this example in the `/examples` directory, and install its
+dependencies:
+
+```bash
+cd examples/intro_to_notion_api
+pip install -r requirements.txt
+```
+
+Alternatively, you can create a virtual environment:
+
+```bash
+cd examples/intro_to_notion_api
+python -m venv venv
+source venv/bin/activate  # On Windows use: venv\Scripts\activate
+pip install -r requirements.txt
+```
+
+### 2. Set your environment variables in a `.env` file
+
+A `.env.example` file has been included and can be renamed `.env` (or you can
+run `cp .env.example .env` to copy the file).
+
+Update the environment variables below:
+
+```bash
+NOTION_API_KEY=<your-notion-api-key>
+NOTION_PAGE_ID=<notion-page-id>
+```
+
+`NOTION_API_KEY`: Create a new integration in the
+[integrations dashboard](https://www.notion.com/my-integrations) and retrieve
+the API key from the integration's `Secrets` page.
+
+`NOTION_PAGE_ID`: Use the ID of any Notion page that you want to test adding
+content to.
+
+The page ID is the 32 character string at the end of any page URL.
+![A Notion page URL with the ID highlighted](./assets/page_id.png)
+
+### 3. Give the integration access to your page
+
+Your Notion integration will need permission to interact with the Notion page
+being used for your `NOTION_PAGE_ID` variable. To provide access, do the
+following:
+
+1. Go to the page in your workspace.
+2. Click the `•••` (more menu) on the top-right corner of the page.
+3. Scroll to the bottom of the menu and click `Add connections`.
+4. Search for and select your integration in the `Search for connections...`
+   menu.
+
+Once selected, your integration will have permission to read content from the
+page.
+
+**If you are receiving authorization errors, make sure the integration has
+permission to access the page.**
+
+### 4. Run individual examples
+
+You have several options to run the examples:
+
+#### Option 1: Run directly with python
+
+```bash
+python basic/1_add_block.py
+python basic/2_add_linked_block.py
+python basic/3_add_styled_block.py
+
+python intermediate/1_create_a_database.py
+python intermediate/2_add_page_to_database.py
+python intermediate/3_query_database.py
+python intermediate/4_sort_database.py
+python intermediate/5_upload_file.py
+```
+
+#### Option 2: Run as modules
+
+```bash
+python -m basic.1_add_block
+python -m intermediate.1_create_a_database
+```
+
+---
+
+## Additional resources
+
+To learn more, read the
+[Public API docs](https://developers.notion.com/) for additional information
+on using Notion's API. The API docs include a series of
+[guides](https://developers.notion.com/docs) and the
+[API reference](https://developers.notion.com/reference/intro), which has a
+full list of available endpoints.
+
+To see more examples of what you can build with Notion, see our other sample
+integrations in the parent `/examples` directory. To learn how to build an
+internal integration with an interactive frontend, read the
+[Build your first integration](https://developers.notion.com/docs/create-a-notion-integration)
+guide.
+
+To connect with other developers building with Notion, join the
+[Notion Developers Slack group](https://join.slack.com/t/notiondevs/shared_invite/zt-20b5996xv-DzJdLiympy6jP0GGzu3AMg).

examples/intro_to_notion_api/basic/1_add_block.py

@@ -0,0 +1,52 @@
+import json
+import os
+
+from notion_client import Client
+
+try:
+    from dotenv import load_dotenv
+
+    load_dotenv()
+except ModuleNotFoundError:
+    pass
+
+page_id = os.getenv("NOTION_PAGE_ID")
+api_key = os.getenv("NOTION_API_KEY")
+
+notion = Client(auth=api_key)
+
+# ---------------------------------------------------------------------------
+
+"""
+Resources:
+- Appending block children endpoint (notion.blocks.children.append(): https://developers.notion.com/reference/patch-block-children)
+- Working with page content guide: https://developers.notion.com/docs/working-with-page-content
+"""
+
+
+def main():
+    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
+    new_heading_response = notion.blocks.children.append(
+        block_id=block_id,
+        # Pass an array of blocks to append to the page: https://developers.notion.com/reference/block#block-type-objects
+        children=[
+            {
+                "heading_2": {
+                    "rich_text": [
+                        {
+                            "text": {
+                                "content": "Types of kale",  # This is the text that will be displayed in Notion
+                            },
+                        },
+                    ],
+                },
+            },
+        ],
+    )
+
+    # Print the new block(s) response
+    print(json.dumps(new_heading_response, indent=2))
+
+
+if __name__ == "__main__":
+    main()

examples/intro_to_notion_api/basic/2_add_linked_block.py

@@ -0,0 +1,68 @@
+import json
+import os
+
+from notion_client import Client
+
+try:
+    from dotenv import load_dotenv
+
+    load_dotenv()
+except ModuleNotFoundError:
+    pass
+
+page_id = os.getenv("NOTION_PAGE_ID")
+api_key = os.getenv("NOTION_API_KEY")
+
+notion = Client(auth=api_key)
+
+# ---------------------------------------------------------------------------
+
+"""
+Resources:
+- Appending block children endpoint (notion.blocks.children.append(): https://developers.notion.com/reference/patch-block-children)
+- Rich text options: https://developers.notion.com/reference/rich-text
+- Working with page content guide: https://developers.notion.com/docs/working-with-page-content
+"""
+
+
+def main():
+    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
+    linked_text_response = notion.blocks.children.append(
+        block_id=block_id,
+        # Pass an array of blocks to append to the page: https://developers.notion.com/reference/block#block-type-objects
+        children=[
+            {
+                "heading_3": {
+                    "rich_text": [
+                        {
+                            "text": {
+                                "content": "Tuscan  kale",  # This is the text that will be displayed in Notion
+                            },
+                        },
+                    ],
+                },
+            },
+            {
+                "paragraph": {
+                    "rich_text": [
+                        {
+                            "text": {
+                                "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.",
+                                "link": {
+                                    # Include a url to make the paragraph a link in Notion
+                                    "url": "https://en.wikipedia.org/wiki/Kale",
+                                },
+                            },
+                        },
+                    ],
+                },
+            },
+        ],
+    )
+
+    # Print the new block(s) response
+    print(json.dumps(linked_text_response, indent=2))
+
+
+if __name__ == "__main__":
+    main()

examples/intro_to_notion_api/basic/3_add_styled_block.py

@@ -0,0 +1,76 @@
+import json
+import os
+
+from notion_client import Client
+
+try:
+    from dotenv import load_dotenv
+
+    load_dotenv()
+except ModuleNotFoundError:
+    pass
+
+page_id = os.getenv("NOTION_PAGE_ID")
+api_key = os.getenv("NOTION_API_KEY")
+
+notion = Client(auth=api_key)
+
+# ---------------------------------------------------------------------------
+
+"""
+Resources:
+- Appending block children endpoint (notion.blocks.children.append(): https://developers.notion.com/reference/patch-block-children)
+- Rich text options: https://developers.notion.com/reference/rich-text
+- Working with page content guide: https://developers.notion.com/docs/working-with-page-content
+"""
+
+
+def main():
+    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
+    styled_link_text_response = notion.blocks.children.append(
+        block_id=block_id,
+        children=[
+            {
+                "heading_3": {
+                    "rich_text": [
+                        {
+                            "text": {
+                                "content": "Tuscan  kale",
+                            },
+                        },
+                    ],
+                },
+            },
+            {
+                "paragraph": {
+                    "rich_text": [
+                        {
+                            "text": {
+                                # Paragraph text
+                                "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.",
+                                "link": {
+                                    # Paragraph link
+                                    "url": "https://en.wikipedia.org/wiki/Kale",
+                                },
+                            },
+                            "annotations": {
+                                # Paragraph styles
+                                "bold": True,
+                                "italic": True,
+                                "strikethrough": True,
+                                "underline": True,
+                                "color": "green",
+                            },
+                        },
+                    ],
+                },
+            },
+        ],
+    )
+
+    # Print the new block(s) response
+    print(json.dumps(styled_link_text_response, indent=2))
+
+
+if __name__ == "__main__":
+    main()