Session
session ¶
Functionality to initialize a Notion Session.
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, databases, 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], exc_value: BaseException, traceback: TracebackType) -> 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 within a page.
In case a title and a schema ware provided, title overrides the schema's db_title attribute if it exists.
create_dbs(parents: Page | list[Page], schemas: list[type[Schema]]) -> list[Database] ¶
Create new databases in the right order in case there a relations between them.
create_page(parent: Page | Database, title: Text | str | None = None, blocks: Sequence[Block] | None = None) -> Page ¶
Create a new page in a parent page or database 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 Notion database by uuid
get_or_create(*args: Any, **kwargs: Any) -> Session classmethod ¶
Return the current active session or create a new session.
get_or_create_db(parent: Page, schema: type[Schema]) -> Database ¶
Get or create the database.
get_or_create_page(parent: Page | Database, 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_db(db_name: str | None = None, *, exact: bool = True, reverse: bool = False, deleted: bool = False) -> SList[Database] ¶
Search a database by name or return all if db_name is None.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
db_name | str | None | name/title of the database, 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 databases 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.