Release 1.0.0

.github/workflows/pull.yml

@@ -0,0 +1,70 @@
+name: Pull workflow
+
+on:
+  pull_request:
+    branches:
+      - 'develop'
+
+jobs:
+  run-tests:
+    if: true
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Print info
+        run: echo "Hello world"
+
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.head_ref }}
+
+      - name: Install Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install Poetry
+        uses: abatilo/actions-poetry@v2
+        with:
+          poetry-version: 'latest'
+
+      - name: Setup local venv
+        run: |
+          poetry config virtualenvs.create true --local
+          poetry config virtualenvs.in-project true --local
+          poetry run python --version
+
+      - name: Restore dependencies
+        id: restore-dependencies
+        uses: actions/cache/restore@v4
+        with:
+          path: ./.venv
+          key: venv-${{ hashFiles('poetry.lock') }}
+
+      - name: Install dependencies
+        if: steps.restore-dependencies.outputs.cache-hit != 'true'
+        run: poetry install -vvv
+
+      - name: Cache dependencies
+        uses: actions/cache/save@v4
+        with:
+          path: ./.venv
+          key: ${{ steps.restore-dependencies.outputs.cache-primary-key }}
+
+      - name: Install project
+        run: poetry install --only-root
+
+      - name: Run tests
+        run: poetry run pytest --junitxml=junit/test-results.xml
+        env:
+          NOTION_TOKEN: ${{ secrets.NOTION_TOKEN }}
+
+      - name: Publish test report
+        uses: mikepenz/action-junit-report@v5
+        if: always()
+        with:
+          report_paths: 'junit/test-results.xml'
+
+      - name: Run pre-commit
+        uses: pre-commit/action@v3.0.1

.github/workflows/release.yml

@@ -0,0 +1,73 @@
+name: Release workflow
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        type: string
+        required: true
+        description: 'Version number to release in X.Y.Z format'
+      dry_run:
+        type: boolean
+        default: true
+        description: 'Dry run'
+  pull_request:
+    types:
+      - closed
+    branches:
+      - 'main'
+
+jobs:
+  release_workflow:
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Gitflow action
+      id: gitflow-action
+      uses: hoangvvo/gitflow-workflow-action@0.3.7
+      with:
+        develop_branch: "develop"
+        main_branch: "main"
+        version: ${{ inputs.version }}
+        version_increment: ${{ contains(github.head_ref, 'hotfix/') && 'patch' || ''   }}
+        dry_run: ${{ inputs.dry_run }}
+      env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+    - name: Checkout code
+      uses: actions/checkout@v4
+      with:
+        ref: ${{ steps.gitflow-action.outputs.release_branch || 'main' }}
+
+    - name: Install Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.11'
+
+    - name: Install Poetry
+      uses: abatilo/actions-poetry@v2
+      with:
+        poetry-version: 'latest'
+
+    # Bumping version if we are in the 'create release PR mode'
+    - name: Bump version
+      if: ${{ steps.gitflow-action.outputs.release_branch }}
+      env:
+        VERSION: ${{ steps.gitflow-action.outputs.version  }}
+      run: poetry version $VERSION
+
+    # Committing bumped version to the release branch
+    - name: Commit new version
+      if: ${{ steps.gitflow-action.outputs.release_branch }}
+      uses: stefanzweifel/git-auto-commit-action@v5
+      with:
+        commit_message: "Bump version to ${{ steps.gitflow-action.outputs.version }}"
+
+    # Building and publishing if we are in 'created new release mode'
+    - name: Build and publish package
+      if: ${{ !steps.gitflow-action.outputs.release_branch }}
+      env:
+        PYPI_TOKEN: ${{ secrets.PYPI_TOKEN  }}
+      run: |
+        poetry config pypi-token.pypi $PYPI_TOKEN
+        poetry publish --build

.gitignore

@@ -1,2 +1,5 @@
 *.egg-info
 __pycache__
+dist
+site
+.DS_Store

CHANGELOG.md

@@ -4,6 +4,10 @@ All notable changes to this project will be documented in this file.
 
 ## Unreleased
 
+## [1.0.0]  - 2025/01/31
+
+- First public release
+
 ## [0.10.0] - 2024/12/20
 
 ### Added

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Colorifix
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,10 @@
+# Python Notion API
+
+<img src="./docs/img/logo.webp" alt="Logo" width="100"/>
+
+Python Notion API implements a client for talking with Notion API.
+
+The key features of this implementation are:
+
+* Async calls allowing you to send multiple requests at once
+* [pydantic](https://docs.pydantic.dev/latest/) wrappers around Notion pages, properties and databases

docs/api/async.md

@@ -0,0 +1,3 @@
+# Async
+
+::: python_notion_api.async_api

docs/api/sync.md

@@ -0,0 +1 @@
+::: python_notion_api.sync_api.api

docs/get_started/blocks.md

@@ -0,0 +1,115 @@
+## Retrieve a block
+
+=== "Async"
+
+    ```python
+    async def main():
+        async_api = AsyncNotionAPI(access_token='<NOTION_TOKEN>')
+        block = await async_api.get_block(block_id='<BLOCK_ID>')
+    ```
+
+=== "Sync"
+
+    ```python
+    api = NotionAPI(access_token='<NOTION_TOKEN>')
+    block = api.get_block(block_id='<BLOCK_ID>')
+    ```
+
+## Retrieve page blocks
+
+=== "Async"
+
+    ```python
+    async def main():
+        async_api = AsyncNotionAPI(access_token='<NOTION_TOKEN>')
+        page = await async_api.get_page(page_id='<PAGE_ID>')
+        await for block in page.get_blocks():
+            ...
+    ```
+
+=== "Sync"
+
+    ```python
+    api = NotionAPI(access_token='<NOTION_TOKEN>')
+    page = api.get_page(page_id='<PAGE_ID>')
+
+    blocks = page.get_blocks()
+
+    for block in blocks:
+        ...
+    ```
+
+## Get and add block children
+
+
+=== "Async"
+
+    ```python
+    async def main():
+        async_api = AsyncNotionAPI(access_token='<NOTION_TOKEN>')
+        block = await async_api.get_block(block_id='<BLOCK_ID>')
+
+        p = ParagraphBlock(
+            rich_text=[RichTextObject.from_str("Some text to add through API")]
+        )
+        await block.add_child_block(content=[p])
+
+        block = await block.get_children_block()
+    ```
+
+=== "Sync"
+
+    ```python
+    api = NotionAPI(access_token='<NOTION_TOKEN>')
+    block = api.get_block(block_id='<BLOCK_ID>')
+
+    p = ParagraphBlock(
+        rich_text=[RichTextObject.from_str("Some text to add through API")]
+    )
+    block.add_child_block(content=[p])
+
+    child_blocks = block.get_child_blocks()
+    ```
+
+## Update a block
+
+All values must be updated at once.
+
+=== "Async"
+
+    ```python
+    from python_notion_api.models.blocks import ParagraphBlock
+
+    async def main():
+        async_api = AsyncNotionAPI(access_token='<NOTION_TOKEN>')
+        block = await async_api.get_block(block_id='<BLOCK_ID>')
+
+        new_block = ParagraphBlock.from_obj({'object': 'block',
+        'type': 'paragraph',
+        'paragraph': {'rich_text': [
+            {'plain_text': 'Text here not used for some reason', 'type': 'text',
+            'text': {'content': 'This is the text that will be added', 'link': None}}]}
+        })
+
+        await block.set(new_block)
+    ```
+
+=== "Sync"
+
+
+    ```python
+    from python_notion_api.models.blocks import ParagraphBlock
+
+    api = NotionAPI(access_token='<NOTION_TOKEN>')
+    block = api.get_block(block_id='<BLOCK_ID>')
+
+    new_block = ParagraphBlock.from_obj({'object': 'block',
+    'type': 'paragraph',
+    'paragraph': {'rich_text': [
+        {'plain_text': 'Text here not used for some reason', 'type': 'text',
+        'text': {'content': 'This is the text that will be added', 'link': None}}]}
+    })
+
+    block = api.get_block(block_id='<BLOCK_ID>')
+    block.set(new_block)
+    ```