Session
session ¶
Functionality to initialize a Notion Session.
T_cache = TypeVar('T_cache', bound='DataObject | User') module-attribute ¶
Session(cfg: Config | None = None, *, client: notion_client.Client | None = None, **kwargs: Any) ¶
A session for the Notion API.
The session keeps tracks of all objects, e.g. pages, data sources, etc. in an object store to avoid unnecessary calls to the API.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
cfg | Config | None | configuration object | None |
**kwargs | Any | Arguments for the Notion SDK Client | {} |
api: NotionAPI = NotionAPI(self.client) instance-attribute ¶
cache: dict[UUID, DataObject | User] = {} class-attribute ¶
client: notion_client.Client = create_notion_client(cfg, **kwargs) if client is None else client instance-attribute ¶
__enter__() -> Session ¶
__exit__(exc_type: type[BaseException] | None, exc_value: BaseException | None, traceback: TracebackType | None) -> None ¶
all_users() -> list[User] ¶
Retrieve all users of this workspace.
close() -> None ¶
Close the session and release resources.
create_db(parent: Page, *, schema: type[Schema] | None = None, title: str | None = None, inline: bool = False) -> Database ¶
Create a new database (a container of data sources) within a page.
In API version 2025-09-03+ every data source lives inside a database container. This creates that container together with its first data source (from schema, or a default single-title schema) and returns the Database. Use db.create_ds(...) to add further data sources, and db.data_sources to list them. Pass inline=True to display the database inline on the page.
create_ds(parent: Page, *, schema: type[Schema] | None = None, title: str | None = None, inline: bool = False) -> DataSource ¶
Create a new data source within a page.
In API version 2025-09-03+ a data source under a page is created via the Create Database endpoint, which creates the database container together with its initial data source. This method returns that data source. Pass inline=True to display the database inline on the page.
In case a title and a schema are provided, title overrides the schema's db_title attribute if it exists.
create_page(parent: Page | DataSource, title: Text | str | None = None, blocks: Sequence[Block] | None = None, *, cover: AnyFile | None = None, icon: AnyFile | Emoji | CustomEmoji | str | None = None) -> Page ¶
Create a new page in a parent page or data source with a given title.
The blocks are optional and can be used to create a page with content right away. Note that some nested blocks may not be supported by the API and must be created separately, i.e. with an append call to a given block.
get_active() -> Session classmethod ¶
Return the current active session or None.
get_block(block_ref: UUID | str, *, use_cache: bool = True) -> Block ¶
Retrieve a single block by an object reference.
get_db(db_ref: UUID | str, *, use_cache: bool = True) -> Database ¶
Retrieve a Notion database (a container of data sources) by uuid.
get_ds(ds_ref: UUID | str, *, use_cache: bool = True) -> DataSource ¶
Retrieve Notion data source by uuid.
get_or_create(*args: Any, **kwargs: Any) -> Session classmethod ¶
Return the current active session or create a new session.
get_or_create_ds(parent: Page, schema: type[Schema]) -> DataSource ¶
Get or create the data source.
get_or_create_page(parent: Page | DataSource, title: str | None = None) -> Page ¶
Get an existing page or create a new one if it doesn't exist.
get_page(page_ref: UUID | str, *, use_cache: bool = True) -> Page ¶
Retrieve a page by uuid.
get_user(user_ref: UUID | str, *, use_cache: bool = True, raise_on_unknown: bool = True) -> User ¶
Get a user by uuid.
In case the user is not found and raise_on_unknown is False, an User object is returned with the name Unknown User, where the property is_unknown is set to True.
Warning
Trying to retrieve yourself, i.e. the bot integration, only works if use_cache is true, since the low-level api, i.e. api.users.retrieve() does not work for the bot integration. Better use whoami() to get the bot integration user object.
import_url(url: str, file_name: str, *, block: bool = True) -> UploadedFile ¶
Import a file from a URL.
is_closed() -> bool ¶
Determine if the session is closed or not.
list_uploads(filter: FileUploadStatus | None = None) -> list[UploadedFile] ¶
List all uploaded files and optionally filter by status.
raise_for_status() -> None ¶
Confirm that the session is active and raise otherwise.
Raises SessionError if there is a problem, otherwise returns None.
search_ds(name: str | None = None, *, exact: bool = True, reverse: bool = False, deleted: bool = False) -> SList[DataSource] ¶
Search a data source by name or return all if name is None.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
name | str | None | name/title of the data source, return all if | None |
exact | bool | perform an exact search, not only a substring match | True |
reverse | bool | search in the reverse order, i.e. the least recently edited results first | False |
deleted | bool | include deleted data sources in search | False |
search_page(title: str | None = None, *, exact: bool = True, reverse: bool = False) -> SList[Page] ¶
Search a page by name. Deleted pages, i.e. in trash, are not included in the search.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
title | str | None | title of the page, return all if | None |
exact | bool | perform an exact search, not only a substring match | True |
reverse | bool | search in the reverse order, i.e. the least recently edited results first | False |
search_user(name: str) -> SList[User] ¶
Search a user by name.
upload(file: BinaryIO, *, file_name: str | None = None, mime_type: str | None = None) -> UploadedFile ¶
Upload a file to Notion.
whoami() -> Bot ¶
Return the integration as bot object.