Skip to main content

A simple Python 3 library for Notion Home Monitoring

Project description

📟 aionotion: a Python3, asyncio-friendly library for Notion® Home Monitoring

CI PyPI Version License Code Coverage Maintainability

Buy Me A Coffee

aionotion is a Python 3, asyncio-friendly library for interacting with Notion home monitoring sensors.

Installation

pip install aionotion

Python Versions

aionotion is currently supported on:

  • Python 3.11
  • Python 3.12
  • Python 3.13

Usage

import asyncio

from aiohttp import ClientSession

from aionotion import async_get_client_with_credentials


async def main() -> None:
    """Create the aiohttp session and run the example."""
    client = await async_get_client_with_credentials(
        "<EMAIL>", "<PASSWORD>", session=session
    )

    # Get the UUID of the authenticated user:
    client.user_uuid
    # >>> xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

    # Get the current refresh token of the authenticated user (BE CAREFUL):
    client.refresh_token
    # >>> abcde12345

    # Get all "households" associated with the account:
    systems = await client.system.async_all()
    # >>> [System(...), System(...), ...]

    # Get a system by ID:
    system = await client.system.async_get(12345)
    # >>> System(...)

    # Get all bridges associated with the account:
    bridges = await client.bridge.async_all()
    # >>> [Bridge(...), Bridge(...), ...]

    # Get a bridge by ID:
    bridge = await client.bridge.async_get(12345)
    # >>> Bridge(...)

    # Get all sensors:
    sensors = await client.sensor.async_all()
    # >>> [Sensor(...), Sensor(...), ...]

    # Get a sensor by ID:
    sensor = await client.sensor.async_get(12345)
    # >>> Sensor(...)

    # Get "listeners" (conditions that a sensor is monitoring) for all sensors:
    listeners = await client.listener.async_all()
    # >>> [Listener(...), Listener(...), ...]

    # Get all listener definitions supported by Notion:
    definitions = await client.listener.async_definitions()
    # >>> [ListenerDefinition(...), ListenerDefinition(...), ...]

    # Get user info:
    user_info = await client.user.async_info()
    # >>> User(...)

    # Get user preferences:
    user_preferences = await client.user.async_preferences()
    # >>> UserPreferences(...)


asyncio.run(main())

Using a Refresh Token

During the normal course of operations, aionotion will automatically maintain a refresh token and use it when needed. At times, you may wish to manage that token yourself (so that you can use it later)–aionotion provides a few useful capabilities there.

Refresh Token Callbacks

aionotion allows implementers to defining callbacks that get called when a new refresh token is generated. These callbacks accept a single string parameter (the refresh token):

import asyncio

from aiohttp import ClientSession

from aionotion import async_get_client_with_credentials


async def main() -> None:
    """Create the aiohttp session and run the example."""
    client = await async_get_client_with_credentials(
        "<EMAIL>", "<PASSWORD>", session=session
    )

    def do_somethng_with_refresh_token(refresh_token: str) -> None:
        """Do something interesting."""
        pass

    # Attach the callback to the client:
    remove_callback = client.add_refresh_token_callback(do_somethng_with_refresh_token)

    # Later, if you want to remove the callback:
    remove_callback()


asyncio.run(main())

Getting a Client via a Refresh Token

All of previous examples retrieved an authenticated client with async_get_client_with_credentials. However, implementers may also create an authenticated client by providing a previously retrieved user UUID and refresh token:

import asyncio

from aiohttp import ClientSession

from aionotion import async_get_client_with_refresh_token


async def main() -> None:
    """Create the aiohttp session and run the example."""
    async with ClientSession() as session:
        # Create a Notion API client:
        client = await async_get_client_with_refresh_token(
            "<USER UUID>", "<REFRESH TOKEN>", session=session
        )

        # Get to work...


asyncio.run(main())

Connection Pooling

By default, the library creates a new connection to Notion with each coroutine. If you are calling a large number of coroutines (or merely want to squeeze out every second of runtime savings possible), an aiohttp ClientSession can be used for connection pooling:

import asyncio

from aiohttp import ClientSession

from aionotion import async_get_client_with_credentials


async def main() -> None:
    """Create the aiohttp session and run the example."""
    async with ClientSession() as session:
        # Create a Notion API client:
        client = await async_get_client_with_credentials(
            "<EMAIL>", "<PASSWORD>", session=session
        )

        # Get to work...


asyncio.run(main())

Check out the examples, the tests, and the source files themselves for method signatures and more examples.

Contributing

Thanks to all of our contributors so far!

  1. Check for open features/bugs or initiate a discussion on one.
  2. Fork the repository.
  3. (optional, but highly recommended) Create a virtual environment: python3 -m venv .venv
  4. (optional, but highly recommended) Enter the virtual environment: source ./.venv/bin/activate
  5. Install the dev environment: script/setup
  6. Code your new feature or bug fix on a new branch.
  7. Write tests that cover your new functionality.
  8. Run tests and ensure 100% code coverage: poetry run pytest --cov aionotion tests
  9. Update README.md with any new documentation.
  10. Submit a pull request!

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

aionotion-2025.2.0.tar.gz (16.9 kB view details)

Uploaded Source

Built Distribution

aionotion-2025.2.0-py3-none-any.whl (17.2 kB view details)

Uploaded Python 3

File details

Details for the file aionotion-2025.2.0.tar.gz.

File metadata

  • Download URL: aionotion-2025.2.0.tar.gz
  • Upload date:
  • Size: 16.9 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: uv/0.5.26

File hashes

Hashes for aionotion-2025.2.0.tar.gz
Algorithm Hash digest
SHA256 f0d6c0e8800ede19e5b4375b4097df07453be3b9e594c59429a38e451091e789
MD5 326fd739e15a090d38dc07a8a6bf47a0
BLAKE2b-256 6119d34ea131a290a878932ffd7fc1520f30204682ab474d7478cd235fec7282

See more details on using hashes here.

File details

Details for the file aionotion-2025.2.0-py3-none-any.whl.

File metadata

File hashes

Hashes for aionotion-2025.2.0-py3-none-any.whl
Algorithm Hash digest
SHA256 3d0a83e5bd9620cd6fe1df1e36dcac97c99df2aae1e4af8c1f699df53f5ad7fe
MD5 1e142a5a64a65f3413e13c496aad93df
BLAKE2b-256 9fcf55a245adb14ac8adfcec6ff59072e3c55aeba1872662266a78c034284317

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page