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', 'Database', 'Divider', 'Embed', 'Emoji', 'Equation', 'File', 'FileInfo', 'Heading1', 'Heading2', 'Heading3', 'Image', 'LinkPreview', 'LinkToPage', 'NumberFormat', 'NumberedItem', 'Option', 'OptionNS', 'Page', 'Paragraph', 'PropType', 'Property', 'Quote', 'Schema', 'SelfRef', 'Session', 'SyncedBlock', 'Table', 'TableOfContents', 'TableRow', 'Text', 'ToDoItem', 'ToggleItem', 'User', 'VState', 'Video', '__version__', 'get_active_session', 'join', 'math', 'mention', 'text'] module-attribute

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

AggFunc

Aggregation functions for formulas.

AVERAGE = 'average' class-attribute instance-attribute

CHECKED = 'checked' class-attribute instance-attribute

COUNT = 'count' class-attribute instance-attribute

COUNT_PER_GROUP = 'count_per_group' class-attribute instance-attribute

COUNT_VALUES = 'count_values' class-attribute instance-attribute

DATE_RANGE = 'date_range' class-attribute instance-attribute

EARLIEST_DATE = 'earliest_date' class-attribute instance-attribute

EMPTY = 'empty' class-attribute instance-attribute

LATEST_DATE = 'latest_date' class-attribute instance-attribute

MAX = 'max' class-attribute instance-attribute

MEDIAN = 'median' class-attribute instance-attribute

MIN = 'min' class-attribute instance-attribute

NOT_EMPTY = 'not_empty' class-attribute instance-attribute

PERCENT_CHECKED = 'percent_checked' class-attribute instance-attribute

PERCENT_EMPTY = 'percent_empty' class-attribute instance-attribute

PERCENT_NOT_EMPTY = 'percent_not_empty' class-attribute instance-attribute

PERCENT_PER_GROUP = 'percent_per_group' class-attribute instance-attribute

RANGE = 'range' class-attribute instance-attribute

SHOW_ORIGINAL = 'show_original' class-attribute instance-attribute

SHOW_UNIQUE = 'show_unique' class-attribute instance-attribute

SUM = 'sum' class-attribute instance-attribute

UNCHECKED = 'unchecked' class-attribute instance-attribute

UNIQUE = 'unique' class-attribute instance-attribute

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 | 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 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.

caption: Text property writable

language: CodeLang property writable

to_markdown() -> str

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

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.

to_markdown() -> str

Columns(n_columns: int)

Columns block.

__getitem__(index: int) -> Column

add_column(index: int = -1) -> Self

Add a new column to this block of columns.

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

to_markdown() -> str

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 property writable

Return the description of this database as rich text.

icon: FileInfo | Emoji | 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.

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.

fetch_all() -> View

Fetch all pages and return a view.

pydantic_model() -> BaseModel

Return a Pydantic model for this database.

query()

Query a (large) database for pages in a more specific way.

reload() -> Self

Reload this database.

restore() -> Self

Restore this database.

to_markdown() -> str

Return the content of this database as Markdown.

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

Divider block.

to_markdown() -> str

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

Embed block.

caption: Text property writable

Return the caption of the embedded item.

url: str | None property writable

Return the URL of the embedded item.

to_markdown() -> str

Emoji(emoji: str)

Emoji object which behaves like str.

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

__eq__(other: object) -> bool

__hash__()

__repr__() -> str

__str__() -> str

from_code(shortcode: str) -> Emoji classmethod

Create an Emoji object from a :shortcode:, e.g. 😄

to_code() -> str

Represent the emoji as :shortcode:, e.g. 😄

Equation(latex: str)

Equation block.

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

latex: str property writable

to_markdown() -> str

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

to_markdown() -> str

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

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

caption: Text property writable

name: str | None property writable

obj_ref: objs.FileObject instance-attribute

url: str property writable

__eq__(other: object) -> bool

__hash__()

__repr__() -> str

__str__() -> str

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

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

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

to_markdown() -> str

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 = Color.DEFAULT)

Option for select & multi-select property.

id: str property

ID of the option.

name: str property

Name of the option.

__eq__(other: object) -> bool

__hash__() -> int

__repr__() -> str

__str__() -> str

description() -> str

Description of the option.

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

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

A Notion page.

Attributes:

Name Type Description
props PagePropertiesNS

accessor for all page properties

cover: FileInfo | None property writable

Cover of the page.

icon: FileInfo | Emoji | 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 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.

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.

to_markdown() -> str

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

People = People class-attribute instance-attribute

PhoneNumber = PhoneNumber 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 certain property type for defining a Notion database schema.

This is implemented as a descriptor.

attr_name: str property

name: str property writable

type: PropertyType property writable

__repr__() -> str

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

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

Quote block.

to_markdown() -> str

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

bind_db(db: Database) classmethod

Bind the PageSchema 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_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.

is_consistent_with(other_schema: type[Schema]) -> bool classmethod

Is this schema consistent with another ignoring backward relations if not in other schema.

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.

SelfRef

Target schema for self-referencing database relations.

Session(cfg: Config | 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][https://ramnes.github.io/notion-sdk-py/reference/client/]

{}

api: NotionAPI = NotionAPI(self.client) instance-attribute

cache: dict[UUID, DataObject | User] = {} class-attribute

client: notion_client.Client = notion_client.Client(auth=auth, **kwargs) 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()

Close the session and release resources.

create_db(parent: Page, schema: type[Schema] | None = None) -> Database

Create a new database within a page.

Implementation:

1. initialize external forward relations, i.e. relations pointing to other databases
2. create the database using a Notion API call and potential external forward relations
3. initialize self-referencing forward relations
4. create properties with self-referencing forward relations using an update call
5. update the backward references, i.e. two-way relations, using an update call

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, title: Text | str | None = None) -> Page

Create a new page in a parent page.

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

Get a user by uuid.

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

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

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

__setitem__(index: int | tuple[int, int], value: str | Sequence[str]) -> 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)

Table row block behaving like a tuple.

__new__(*cells: str) -> TableRow

to_markdown() -> str

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

Text(text: str)

User-facing class holding several RichTextsBase objects.

obj_ref: list[objs.RichTextBaseObject] property

rich_texts: tuple[RichTextBase, ...] property

Return the rich texts as immutable tuple.

__add__(other: str) -> Text

__eq__(other: object) -> bool

__hash__()

from_markdown(text: str) -> Text classmethod

Create RichTextList by parsing the markdown.

from_plain_text(text: str) -> Text classmethod

Create RichTextList from plain text.

This method is a more explicit alias for the default constructor.

to_html() -> str

Return rich text as HTML.

to_markdown() -> str

Convert the list of RichText objects to markdown.

to_plain_text() -> str

Return rich text as plaintext

This method is a more explicit variant then just using the object.

wrap_obj_ref(obj_refs: list[objs.RichTextBaseObject] | None) -> Text 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

email: str | None property

id property

is_bot: bool property

is_person: bool property

is_unknown: bool property

name property

__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

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 | 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.

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.