Skip to content

Reference

ultimate_notion

Ultimate Notion provides a pythonic, high-level API for Notion.

Notion-API: https://developers.notion.com/reference/intro

AnyBlock: TypeAlias = Block[Any] module-attribute

For type hinting purposes, especially for lists of blocks, i.e. list[AnyBlock], in user code.

__all__ = ['PDF', 'AggFunc', 'AnyBlock', 'BGColor', 'Bookmark', 'Breadcrumb', 'BulletedItem', 'Callout', 'Code', 'CodeLang', 'Color', 'Column', 'Columns', 'Condition', 'Database', 'Divider', 'Embed', 'Emoji', 'Equation', 'File', 'FileInfo', 'Heading1', 'Heading2', 'Heading3', 'Image', 'LinkPreview', 'LinkToPage', 'NumberFormat', 'NumberedItem', 'Option', 'OptionNS', 'Page', 'Paragraph', 'PropType', 'Property', 'Quote', 'SList', 'Schema', 'SelfRef', 'Session', 'SyncedBlock', 'Table', 'TableOfContents', 'TableRow', 'ToDoItem', 'ToggleItem', 'User', 'VState', 'Video', '__version__', 'get_active_session', 'join', 'math', 'mention', 'prop', 'text'] module-attribute

__version__ = version('ultimate-notion') module-attribute

AggFunc

Aggregation functions for formulas.

The categories naming corresonds mostly to the naming in the Notion App but also eliminates some inconsistencies. The first part of the tuple is the string used in the Notion API, the second part is an alias corresoinding to the defined category num.

AVERAGE = ('average', 'average') class-attribute instance-attribute

COUNT_ALL = ('count', 'count_all') class-attribute instance-attribute

COUNT_CHECKED = ('checked', 'count_checked') class-attribute instance-attribute

COUNT_EMPTY = ('empty', 'count_empty') class-attribute instance-attribute

COUNT_NOT_EMPTY = ('not_empty', 'count_not_empty') class-attribute instance-attribute

COUNT_PER_GROUP = ('count_per_group', 'count_per_group') class-attribute instance-attribute

COUNT_UNCHECKED = ('unchecked', 'count_unchecked') class-attribute instance-attribute

COUNT_UNIQUE_VALUES = ('unique', 'count_unique_values') class-attribute instance-attribute

COUNT_VALUES = ('count_values', 'count_values') class-attribute instance-attribute

DATE_RANGE = ('date_range', 'date_range') class-attribute instance-attribute

EARLIEST_DATE = ('earliest_date', 'earliest_date') class-attribute instance-attribute

LATEST_DATE = ('latest_date', 'latest_date') class-attribute instance-attribute

MAX = ('max', 'max') class-attribute instance-attribute

MEDIAN = ('median', 'median') class-attribute instance-attribute

MIN = ('min', 'min') class-attribute instance-attribute

PERCENT_CHECKED = ('percent_checked', 'percent_checked') class-attribute instance-attribute

PERCENT_EMPTY = ('percent_empty', 'percent_empty') class-attribute instance-attribute

PERCENT_NOT_EMPTY = ('percent_not_empty', 'percent_not_empty') class-attribute instance-attribute

PERCENT_PER_GROUP = ('percent_per_group', 'percent_per_group') class-attribute instance-attribute

RANGE = ('range', 'range') class-attribute instance-attribute

SHOW_ORIGINAL = ('show_original', 'show_original') class-attribute instance-attribute

SHOW_UNIQUE = ('show_unique', 'show_unique') class-attribute instance-attribute

SUM = ('sum', 'sum') class-attribute instance-attribute

alias: str instance-attribute

__new__(value: str, alias: str = '') -> AggFunc

from_alias(alias: str) -> AggFunc classmethod

BGColor

Background colors for most textual blocks, e.g. paragraphs, callouts, etc.

BLUE = 'blue_background' class-attribute instance-attribute

BROWN = 'brown_background' class-attribute instance-attribute

DEFAULT = 'default' class-attribute instance-attribute

GRAY = 'gray_background' class-attribute instance-attribute

GREEN = 'green_background' class-attribute instance-attribute

ORANGE = 'orange_background' class-attribute instance-attribute

PINK = 'pink_background' class-attribute instance-attribute

PURPLE = 'purple_background' class-attribute instance-attribute

RED = 'red_background' class-attribute instance-attribute

YELLOW = 'yellow_background' class-attribute instance-attribute

Bookmark(url: str, *, caption: str | None = None)

Bookmark block.

url: str | None property writable

Return the URL of the bookmark.

to_markdown() -> str

Breadcrumb(*args: Any, **kwargs: Any)

Breadcrumb block.

to_markdown() -> str

BulletedItem(text: str, *, color: Color | BGColor = Color.DEFAULT)

Bulleted list item.

to_markdown() -> str

Callout(text: str, *, color: Color | BGColor = Color.DEFAULT, icon: FileInfo | Emoji | CustomEmoji | None = None)

Callout block.

Note

The default icon is an electric light bulb, i.e. 💡 in case None is passed as icon. It is not possible to remove the icon, but you can change it to a different emoji or a file.

icon: FileInfo | Emoji | CustomEmoji property writable

get_default_icon() -> Emoji staticmethod

Return the default icon of a callout block.

to_markdown() -> str

Code(text: str, *, language: CodeLang = CodeLang.PLAIN_TEXT, caption: str | None = None)

Code block.

language: CodeLang property writable

Return the programming language of the code block.

to_markdown() -> str

Return the code content of this block as Markdown.

CodeLang

Coding languages for code blocks.

ABAP = 'abap' class-attribute instance-attribute

ARDUINO = 'arduino' class-attribute instance-attribute

BASH = 'bash' class-attribute instance-attribute

BASIC = 'basic' class-attribute instance-attribute

C = 'c' class-attribute instance-attribute

CLOJURE = 'clojure' class-attribute instance-attribute

COFFEESCRIPT = 'coffeescript' class-attribute instance-attribute

CPP = 'c++' class-attribute instance-attribute

CSHARP = 'c#' class-attribute instance-attribute

CSS = 'css' class-attribute instance-attribute

DART = 'dart' class-attribute instance-attribute

DIFF = 'diff' class-attribute instance-attribute

DOCKER = 'docker' class-attribute instance-attribute

ELIXIR = 'elixir' class-attribute instance-attribute

ELM = 'elm' class-attribute instance-attribute

ERLANG = 'erlang' class-attribute instance-attribute

FLOW = 'flow' class-attribute instance-attribute

FORTRAN = 'fortran' class-attribute instance-attribute

FSHARP = 'f#' class-attribute instance-attribute

GHERKIN = 'gherkin' class-attribute instance-attribute

GLSL = 'glsl' class-attribute instance-attribute

GO = 'go' class-attribute instance-attribute

GRAPHQL = 'graphql' class-attribute instance-attribute

GROOVY = 'groovy' class-attribute instance-attribute

HASKELL = 'haskell' class-attribute instance-attribute

HTML = 'html' class-attribute instance-attribute

JAVA = 'java' class-attribute instance-attribute

JAVASCRIPT = 'javascript' class-attribute instance-attribute

JSON = 'json' class-attribute instance-attribute

JULIA = 'julia' class-attribute instance-attribute

KOTLIN = 'kotlin' class-attribute instance-attribute

LATEX = 'latex' class-attribute instance-attribute

LESS = 'less' class-attribute instance-attribute

LISP = 'lisp' class-attribute instance-attribute

LIVESCRIPT = 'livescript' class-attribute instance-attribute

LUA = 'lua' class-attribute instance-attribute

MAKEFILE = 'makefile' class-attribute instance-attribute

MARKDOWN = 'markdown' class-attribute instance-attribute

MARKUP = 'markup' class-attribute instance-attribute

MATLAB = 'matlab' class-attribute instance-attribute

MERMAID = 'mermaid' class-attribute instance-attribute

MISC = 'java/c/c++/c#' class-attribute instance-attribute

NIX = 'nix' class-attribute instance-attribute

OBJECTIVE_C = 'objective-c' class-attribute instance-attribute

OCAML = 'ocaml' class-attribute instance-attribute

PASCAL = 'pascal' class-attribute instance-attribute

PERL = 'perl' class-attribute instance-attribute

PHP = 'php' class-attribute instance-attribute

PLAIN_TEXT = 'plain text' class-attribute instance-attribute

POWERSHELL = 'powershell' class-attribute instance-attribute

PROLOG = 'prolog' class-attribute instance-attribute

PROTOBUF = 'protobuf' class-attribute instance-attribute

PYTHON = 'python' class-attribute instance-attribute

R = 'r' class-attribute instance-attribute

REASON = 'reason' class-attribute instance-attribute

RUBY = 'ruby' class-attribute instance-attribute

RUST = 'rust' class-attribute instance-attribute

SASS = 'sass' class-attribute instance-attribute

SCALA = 'scala' class-attribute instance-attribute

SCHEME = 'scheme' class-attribute instance-attribute

SCSS = 'scss' class-attribute instance-attribute

SHELL = 'shell' class-attribute instance-attribute

SQL = 'sql' class-attribute instance-attribute

SWIFT = 'swift' class-attribute instance-attribute

TOML = 'toml' class-attribute instance-attribute

TYPESCRIPT = 'typescript' class-attribute instance-attribute

VB_NET = 'vb.net' class-attribute instance-attribute

VERILOG = 'verilog' class-attribute instance-attribute

VHDL = 'vhdl' class-attribute instance-attribute

VISUAL_BASIC = 'visual basic' class-attribute instance-attribute

WEBASSEMBLY = 'webassembly' class-attribute instance-attribute

XML = 'xml' class-attribute instance-attribute

YAML = 'yaml' class-attribute instance-attribute

Color

Basic colors

DEFAULT is a light gray, which is the default color in the Notion App.

BLUE = 'blue' class-attribute instance-attribute

BROWN = 'brown' class-attribute instance-attribute

DEFAULT = 'default' class-attribute instance-attribute

GRAY = 'gray' class-attribute instance-attribute

GREEN = 'green' class-attribute instance-attribute

ORANGE = 'orange' class-attribute instance-attribute

PINK = 'pink' class-attribute instance-attribute

PURPLE = 'purple' class-attribute instance-attribute

RED = 'red' class-attribute instance-attribute

YELLOW = 'yellow' class-attribute instance-attribute

Column()

Column block.

width_ratio: float | None property

Return the width ratio of this column.

to_markdown() -> str

Return the content of this column as Markdown.

Columns(columns: int | Sequence[float | int])

Columns block holding multiple Column blocks.

This block is used to create a layout with multiple columns in a single page. Either specify the number of columns as an integer or provide a sequence of width ratios, which can be positive integers or floats.

width_ratios: tuple[float | None, ...] property writable

Return the width ratios of the columns.

__getitem__(index: int) -> Column

add_column(index: int | None = None) -> Self

Add a new column to this block of columns at the given index.

The index must be between 0 and the number of columns (inclusive). If no index is given, the new column is added at the end.

To specify the width ratio of the new column, use the width_ratios property.

append(blocks: Block | Sequence[Block], *, after: Block | None = None) -> Self

Append a block or a sequence of blocks to the content of this block.

to_markdown() -> str

Return the content of all columns as Markdown.

Condition

Base class for filter query conditions.

is_method: bool = False class-attribute instance-attribute

__and__(other: Condition) -> Condition

__iand__(other: Condition) -> Condition

__ior__(other: Condition) -> Condition

__or__(other: Condition) -> Condition

__repr__() -> str abstractmethod

__str__() -> str

create_obj_ref(db: Database) -> obj_query.QueryFilter abstractmethod

Database(*args: Any, **kwargs: Any)

A Notion database.

This object always represents an original database, not a linked database.

API reference: https://developers.notion.com/docs/working-with-databases

cover: FileInfo | None property

Return the cover of this database as file.

description: Text | None property writable

Return the description of this database as rich text.

icon: FileInfo | Emoji | CustomEmoji | None property

Return the icon of this database as file or emoji.

is_db: bool property

Return whether the object is a database.

is_empty: bool property

Return whether the database is empty.

is_inline: bool property

Return whether the database is inline.

is_wiki: bool property

Return whether the database is a wiki.

query: Query property

Return a Query object to build and execute a database query.

schema: type[Schema] property writable

Schema of the database.

title: str | Text property writable

Return the title of this database as rich text.

url: str property

Return the URL of this database.

__bool__() -> bool

Overwrite default behaviour.

__len__() -> int

Return the number of pages in this database.

__repr__() -> str

__str__()

create_page(**kwargs) -> Page

Create a page with properties according to the schema within the corresponding database.

delete() -> Self

Delete this database.

get_all_pages() -> View

Retrieve all pages and return a view.

reload() -> Self

Reload this database.

restore() -> Self

Restore this database.

to_markdown() -> str

Return the reference to this database as Markdown.

Divider(*args: Any, **kwargs: Any)

Divider block.

to_markdown() -> str

Embed(url: str, *, caption: str | None = None)

Embed block.

url: str | None property writable

Return the URL of the embedded item.

to_markdown() -> str

Emoji(emoji: str)

Unicode emoji object which behaves like str.

name: str property

Return the name of the emoji.

obj_ref = objs.EmojiObject.build(emoji) instance-attribute

__repr__() -> str

__str__() -> str

Equation(latex: str)

Equation block.

LaTeX equation in display mode, e.g. $$ \mathrm{E=mc^2} $$, but without the $$ signs.

latex: str property writable

Return the LaTeX expression of the equation.

to_markdown() -> str

Return the LaTeX expression of the equation as Markdown.

File(name: str, url: str, *, caption: str | None = None)

File block.

Note

Only the caption and name can be modified, the URL is read-only. Note that only the file name not the file suffix can be modified, the suffix is determined initially by the url.

name: str property writable

Return the name of the file.

to_markdown() -> str

Return the file link as Markdown.

FileInfo(*, url: str, name: str | None = None, caption: str | None = None)

Information about a web resource e.g. for the files property.

caption: Text | None property writable

Return the caption of the file.

name: str | None property writable

Return the name of the file.

obj_ref: objs.FileObject instance-attribute

url: str property writable

Return the URL of this file.

__eq__(other: object) -> bool

__hash__()

__repr__() -> str

__str__() -> str

wrap_obj_ref(obj_ref: objs.FileObject) -> FileInfo classmethod

Wrap an existing low-level FileObject into a FileInfo.

Heading1(text: str, *, color: Color | BGColor = Color.DEFAULT, toggleable: bool = False)

Heading 1 block.

to_markdown() -> str

Heading2(text: str, *, color: Color | BGColor = Color.DEFAULT, toggleable: bool = False)

Heading 2 block.

to_markdown() -> str

Heading3(text: str, *, color: Color | BGColor = Color.DEFAULT, toggleable: bool = False)

Heading 3 block.

to_markdown() -> str

Image(url: str, *, caption: str | None = None)

Image block.

Note

Only the caption can be modified, the URL is read-only.

to_markdown() -> str

Return the image as Markdown.

LinkPreview(url: str)

Link preview block.

Not Supported

The link_preview block can only be returned as part of a response. The Notion API does not support creating or appending link_preview blocks.

url: str | None property

to_markdown() -> str

LinkToPage(page: Page)

Link to page block.

Note

Updating a link to page block is not supported by the Notion API. Use .replace(new_block) instead.

page: Page property writable

Return the page this block links to.

to_markdown() -> str

"Return the link to page block as Markdown.

NumberFormat

Number formats for numbers.

ARGENTINE_PESO = 'argentine_peso' class-attribute instance-attribute

AUSTRALIAN_DOLLAR = 'australian_dollar' class-attribute instance-attribute

BAHT = 'baht' class-attribute instance-attribute

CANADIAN_DOLLAR = 'canadian_dollar' class-attribute instance-attribute

CHILEAN_PESO = 'chilean_peso' class-attribute instance-attribute

COLOMBIAN_PESO = 'colombian_peso' class-attribute instance-attribute

DANISH_KRONE = 'danish_krone' class-attribute instance-attribute

DIRHAM = 'dirham' class-attribute instance-attribute

DOLLAR = 'dollar' class-attribute instance-attribute

EURO = 'euro' class-attribute instance-attribute

FORINT = 'forint' class-attribute instance-attribute

FRANC = 'franc' class-attribute instance-attribute

HONG_KONG_DOLLAR = 'hong_kong_dollar' class-attribute instance-attribute

KORUNA = 'koruna' class-attribute instance-attribute

KRONA = 'krona' class-attribute instance-attribute

LEU = 'leu' class-attribute instance-attribute

LIRA = 'lira' class-attribute instance-attribute

MEXICAN_PESO = 'mexican_peso' class-attribute instance-attribute

NEW_TAIWAN_DOLLAR = 'new_taiwan_dollar' class-attribute instance-attribute

NEW_ZEALAND_DOLLAR = 'new_zealand_dollar' class-attribute instance-attribute

NORWEGIAN_KRONE = 'norwegian_krone' class-attribute instance-attribute

NUMBER = 'number' class-attribute instance-attribute

NUMBER_WITH_COMMAS = 'number_with_commas' class-attribute instance-attribute

PERCENT = 'percent' class-attribute instance-attribute

PHILIPPINE_PESO = 'philippine_peso' class-attribute instance-attribute

POUND = 'pound' class-attribute instance-attribute

RAND = 'rand' class-attribute instance-attribute

REAL = 'real' class-attribute instance-attribute

RINGGIT = 'ringgit' class-attribute instance-attribute

RIYAL = 'riyal' class-attribute instance-attribute

RUBLE = 'ruble' class-attribute instance-attribute

RUPEE = 'rupee' class-attribute instance-attribute

RUPIAH = 'rupiah' class-attribute instance-attribute

SHEKEL = 'shekel' class-attribute instance-attribute

URUGUAYAN_PESO = 'uruguayan_peso' class-attribute instance-attribute

WON = 'won' class-attribute instance-attribute

YEN = 'yen' class-attribute instance-attribute

YUAN = 'yuan' class-attribute instance-attribute

ZLOTY = 'zloty' class-attribute instance-attribute

NumberedItem(text: str, *, color: Color | BGColor = Color.DEFAULT)

Numbered list item.

to_markdown() -> str

Option(name: str, *, color: Color | str | None = None)

Option for select & multi-select property.

color: Color property

Color of the option.

description: str property

Description of the option.

id: str property

ID of the option.

name: str property

Name of the option.

__eq__(other: object) -> bool

__hash__() -> int

__repr__() -> str

__str__() -> str

OptionNS

Option namespace to simplify working with (Multi-)Select options.

to_list() -> list[Option] classmethod

Convert the enum to a list as needed by the (Multi)Select property types.

PDF(url: str, *, caption: str | None = None, name: str | None = None)

PDF block.

Note

Only the caption can be modified, the URL is read-only.

to_markdown() -> str

Return the PDF as Markdown.

Page(*args: Any, **kwargs: Any)

A Notion page.

Attributes:

Name Type Description
props PagePropertiesNS

accessor for all page properties

comments: Discussion property

Return the discussion thread of this page.

A page can only have a single discussion thread in contrast to inline comments.

Note

This functionality requires that your integration was granted read comment capabilities.

cover: FileInfo | None property writable

Cover of the page.

icon: FileInfo | Emoji | CustomEmoji | None property writable

Icon of the page, i.e. emojis, Notion's icons, or custom images.

in_db: bool property

Return True if this page is located in a database.

is_page: bool property

Return whether the object is a page.

parent_db: Database | None property

If this page is located in a database return the database or None otherwise.

This is a convenience method to avoid the need to check and cast the type of the parent.

props: PagePropertiesNS instance-attribute

public_url: str | None property

Return the public URL of this database.

subdbs: list[Database] property

Return all contained databases within this page

subpages: list[Page] property

Return all contained pages within this page

title: Text | None property writable

Title of the page.

url: str property

Return the URL of this page.

__repr__() -> str

__str__() -> str

delete() -> Self

Delete this page.

Warning

Deleting a page will also delete all child pages and child databases recursively. If these objects are already cached in the session, they will not be updated. Use session.cache.clear() to clear the cache or call reload() on them.

get_property(prop_name: str) -> Any

Directly retrieve the property value from the API.

Use this method only if you want to retrieve a specific property value that might have been updated on the server side without reloading the whole page. In all other cases, use the props namespace of the page to avoid unnecessary API calls.

reload() -> Self

Reload this page.

restore() -> Self

Restore this page.

show(*, simple: bool | None = None)

Show the content of the page, rendered in JupyterLab

to_html(*, raw: bool = False) -> str

Return the content of the page as HTML.

to_markdown() -> str

Return the content of the page as Markdown.

Note

This will not include nested blocks, i.e. the children of top-level blocks.

wrap_obj_ref(obj_ref: obj_blocks.Page) -> Self classmethod

Paragraph(text: str, *, color: Color | BGColor = Color.DEFAULT)

Paragraph block.

PropType

Namespace class of all property types of a database for easier access.

Checkbox = Checkbox class-attribute instance-attribute

CreatedBy = CreatedBy class-attribute instance-attribute

CreatedTime = CreatedTime class-attribute instance-attribute

Date = Date class-attribute instance-attribute

Email = Email class-attribute instance-attribute

Files = Files class-attribute instance-attribute

Formula = Formula class-attribute instance-attribute

ID = ID class-attribute instance-attribute

LastEditedBy = LastEditedBy class-attribute instance-attribute

LastEditedTime = LastEditedTime class-attribute instance-attribute

MultiSelect = MultiSelect class-attribute instance-attribute

Number = Number class-attribute instance-attribute

Person = Person class-attribute instance-attribute

Phone = Phone class-attribute instance-attribute

Relation = Relation class-attribute instance-attribute

Rollup = Rollup class-attribute instance-attribute

Select = Select class-attribute instance-attribute

Status = Status class-attribute instance-attribute

Text = Text class-attribute instance-attribute

Title = Title class-attribute instance-attribute

URL = URL class-attribute instance-attribute

Verification = Verification class-attribute instance-attribute

Property(name: str, type: PropertyType)

Database property/column with a name and a Notion property type.

A schema is a collection of properties that define the structure of a database. This is implemented as a descriptor in Python.

attr_name: str property

Return the Python attribute name of the property in the schema.

name: str property writable

Return the name of this property.

type: PropertyType property writable

Return the property type of this property.

__repr__() -> str

__set_name__(owner: type[Schema], name: str)

delete() -> None

Delete this property from the schema.

Quote(text: str, *, color: Color | BGColor = Color.DEFAULT)

Quote block.

to_markdown() -> str

SList

A list that holds often only a single element.

item() -> T

Schema

Base class for the schema of a database.

db_desc: rich_text.Text | None instance-attribute

db_title: rich_text.Text | None instance-attribute

__init_subclass__(db_title: str | None, **kwargs: Any)

as_table(tablefmt: str | None = None) -> str classmethod

Return the schema in a given string table format.

Some table formats:

  • plain: no pseudographics
  • simple: Pandoc's simple table, i.e. only dashes to separate header from content
  • github: GitHub flavored Markdown
  • simple_grid: uses dashes & pipes to separate cells
  • html: standard html markup

Find more table formats under: astanin/python-tabulate#table-format

assert_consistency_with(other_schema: type[Schema], *, during_init: bool = False) -> None classmethod

Assert that this schema is consistent with another schema.

bind_db(db: Database) classmethod

Bind this schema to the corresponding database for back-reference.

create(**kwargs) -> Page classmethod

Create a page using this schema with a bound database.

from_dict(schema_dct: dict[str, PropertyType], db_title: str | None = None, db_desc: str | None = None) -> type[Schema] classmethod

Creation of a schema from a dictionary for easy support of dynamically created schemas.

get_db() -> Database classmethod

Get the database that is bound to this schema.

get_prop(prop_name: str) -> Property classmethod

Get a specific property from this schema assuming that property names are unique.

get_props() -> list[Property] classmethod

Get all properties of this schema.

get_ro_props() -> list[Property] classmethod

Get all read-only properties of this schema.

get_rw_props() -> list[Property] classmethod

Get all writeable properties of this schema.

get_title_prop() -> Property classmethod

Returns the property holding the title of the pages.

is_bound() -> bool classmethod

Determines if the schema is bound to a database.

show(*, simple: bool | None = None) classmethod

Show the schema as html or as simple table.

to_dict() -> dict[str, PropertyType] classmethod

Convert this schema to a dictionary of property names and corresponding types.

to_pydantic_model(*, with_ro_props: bool = False) -> type[SchemaModel] classmethod

Return a Pydantic model of this schema for validation.

This is useful for instance when writing a web API that receives data that should be validated before it is passed to Ultimate Notion. The actual values are converted to PropertyValue and thus value needs to be called to retrieve the actual Python type.

If with_ro_props is set to True, read-only properties are included in the model.

SelfRef

Target schema for self-referencing database relations.

_ = Property('title', Title()) class-attribute instance-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, 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, *, inline: bool = False) -> Database

Create a new database within a page.

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) -> Page

Create a new page in a parent page or database.

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, **kwargs) -> 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_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.

is_closed() -> bool

Determine if the session is closed or not.

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

 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

 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.

whoami() -> User

Return the user object of this bot.

SyncedBlock(blocks: Block | Sequence[Block])

Synced block - either original or synced.

is_original: bool property

Return if this block is the original block.

is_synced: bool property

Return if this block is synced from another block.

create_synced() -> SyncedBlock

Return the synced block for appending.

get_original() -> SyncedBlock

Return the original block.

to_markdown(*, with_comment: bool = True) -> str

Return the content of this synced block as Markdown.

Table(n_rows: int, n_cols: int, *, header_col: bool = False, header_row: bool = False)

Table block.

children: tuple[TableRow, ...] property

Return all rows of the table.

has_header_col: bool property writable

Return whether the table has a header column.

has_header_row: bool property writable

Return whether the table has a header row.

shape: tuple[int, int] property

Return the shape of the table.

width: int property

Return the width, i.e. number of columns, of the table.

__getitem__(index: int | tuple[int, int]) -> Text | TableRow | None 

__getitem__(index: int) -> TableRow

__getitem__(index: tuple[int, int]) -> Text | None

__setitem__(index: int | tuple[int, int], value: str | Sequence[str | None] | None) -> None

__str__() -> str

append_row(values: Sequence[str]) -> Self

Append a new row to the table.

insert_row(index: int, values: Sequence[str]) -> Self

Insert a new row at the given index.

to_markdown() -> str

Return the table as Markdown.

TableOfContents(*, color: Color | BGColor = Color.DEFAULT)

Table of Contents block.

to_markdown() -> str

TableRow(*cells: str | None)

Table row block behaving like a tuple.

__new__(*cells: str | None) -> TableRow

to_markdown() -> str

Return the row as Markdown.

wrap_obj_ref(obj_ref: obj_blocks.TableRow) -> TableRow classmethod

ToDoItem(text: str, *, checked: bool = False, color: Color | BGColor = Color.DEFAULT)

ToDo list item.

checked: bool property writable

to_markdown() -> str

ToggleItem(text: str, *, color: Color | BGColor = Color.DEFAULT)

Toggle list item.

to_markdown() -> str

User(*args: Any, **kwargs: Any)

User object for persons, bots and unknown users.

Unknown users are users, which no longer participate in the workspace or were revoked access. They are represented by their ID and have the name Unknown User.

avatar_url property

Return the avatar URL of this user.

email: str | None property

Return the e-mail address of this user, if available.

id property

Return the ID of this user.

is_bot: bool property

Return True if this user is a bot.

is_person: bool property

Return True if this user is a person.

is_unknown: bool property

Return True if this user is an unknown user.

name property

Return the name of this user.

workspace_info: dict[str, str | int] | None property

Return the workspace info of this bot, if available.

__eq__(other: object) -> bool

__hash__() -> int

__repr__() -> str

__str__()

wrap_obj_ref(obj_ref: objs.User) -> User classmethod

VState

Verification states for pages in wiki databases.

UNVERIFIED = 'unverified' class-attribute instance-attribute

VERIFIED = 'verified' class-attribute instance-attribute

Video(url: str, *, caption: str | None = None, name: str | None = None)

Video block.

Note

Only the caption can be modified, the URL is read-only.

to_markdown() -> str

Return the video as Markdown.

get_active_session() -> Session

Return the current active session or raise an exception.

Avoids cyclic imports when used within the package itself. For internal use mostly.

join(texts: Sequence[str], *, delim: str = ' ') -> Text

Join multiple str objects, including Text, into a single Text object with a given delimeter.

math(expression: str, *, bold: bool = False, italic: bool = False, strikethrough: bool = False, code: bool = False, underline: bool = False, color: Color = Color.DEFAULT) -> Text

Create a Text that holds a formula.

mention(target: User | Page | Database | CustomEmoji | dt.datetime | dt.date | pnd.Interval, *, bold: bool = False, italic: bool = False, strikethrough: bool = False, code: bool = False, underline: bool = False, color: Color = Color.DEFAULT) -> Text

Create a Text that mentions another object.

prop(prop_name: str) -> Property

Create a property object.

text(text: str, *, bold: bool = False, italic: bool = False, strikethrough: bool = False, code: bool = False, underline: bool = False, color: Color = Color.DEFAULT, href: str | None = None) -> Text

Create a rich text Text object from a normal string with formatting.

Warning

If a Text object is passed, the original formatting will be lost!