Skip to content

Blocks

blocks

Core building blocks for pages and databases.

AnyBlock: TypeAlias = Block[Any] module-attribute

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

BT = TypeVar('BT', bound=obj_blocks.Block) module-attribute

FT = TypeVar('FT', bound=obj_blocks.FileBase) module-attribute

T = TypeVar('T', bound=obj_blocks.DataObject) module-attribute

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

General Notion block.

block_url: str property

Return the URL of the block.

reload() -> Self

Reload the block from the API.

Bookmark(url: str, *, caption: str | RichText | RichTextBase | list[RichTextBase] | None = None)

Bookmark block.

url: str | None property

Return the URL of the bookmark.

to_markdown() -> str

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

Breadcrumb block.

to_markdown() -> str

BulletedItem(text: str | RichText | RichTextBase | list[RichTextBase], *, color: Color | BGColor = Color.DEFAULT)

Bulleted list item.

to_markdown() -> str

Callout(text: str | RichText | RichTextBase | list[RichTextBase], *, color: Color | BGColor = Color.DEFAULT, icon: FileInfo | Emoji | str | None = None)

Callout block.

icon: FileInfo | Emoji | None property

to_markdown() -> str

ChildDatabase()

Child database block.

Note

To create a child database block as an end-user, create a new database with the corresponding parent.

db: Database property

Return the actual Database object.

title: str property

Return the title of the child database

to_markdown() -> str

Return the reference to this database as Markdown.

ChildPage()

Child page block.

Note

To create a child page block, create a new page with the corresponding parent.

page: Page property

Return the actual Page object.

title: str property

Return the title of the child page.

to_markdown() -> str

Return the reference to this page as Markdown.

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

Mixin for data objects that can have children

Note that we don't use the children property of some Notion objects, e.g. paragraph, quote, etc., as not every object has this property, e.g. a page, database or toggable heading.

children: list[Block] property

Return the children of this block.

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

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

Code(text: str | RichText | RichTextBase | list[RichTextBase], *, language: CodeLang = CodeLang.PLAIN_TEXT, caption: str | RichText | RichTextBase | list[RichTextBase] | None = None)

Code block.

caption: RichText property

to_markdown() -> str

ColoredTextBlock(text: str | RichText | RichTextBase | list[RichTextBase], *, color: Color | BGColor = Color.DEFAULT)

Abstract Text block with color.

color: Color | BGColor property

Column()

Column block.

to_markdown() -> str

Columns(n_columns: int)

Columns block.

__getitem__(index: int) -> Column

to_markdown() -> str

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

The base type for all data-related types, i.e, pages, databases and blocks.

ancestors: tuple[DataObject, ...] property

Return all ancestors from the workspace to the actual record (excluding).

created_by: User property

Return the user who created the block.

created_time: datetime property

Return the time when the block was created.

has_children: bool property

Return whether the object has children.

id: UUID property

Return the ID of the block.

in_notion: bool property

Return whether the block was created in Notion.

is_db: bool property

Return whether the object is a database.

is_deleted: bool property

Return wether the object is in trash.

is_page: bool property

Return whether the object is a page.

last_edited_by: User property

Return the user who last edited the block.

last_edited_time: datetime property

Return the time when the block was last edited.

parent: DataObject | None property

Return the parent record or None if the workspace is the parent.

__eq__(other: object) -> bool

__hash__() -> int

delete() -> Self

Delete the block.

Pages and databases are moved to the trash, blocks are deleted permanently.

to_markdown() -> str abstractmethod

Return the content of the block as Markdown.

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

Divider block.

to_markdown() -> str

Embed(url: str, *, caption: str | RichText | RichTextBase | list[RichTextBase] | None = None)

Embed block.

caption: RichText property

url: str | None property

Return the URL of the embedded item.

to_markdown() -> str

Equation(expression: str)

Equation block.

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

expression: str property

to_markdown() -> str

File(name: str, url: str, *, caption: str | RichText | RichTextBase | list[RichTextBase] | None = None)

File block.

name: str property

to_markdown() -> str

FileBaseBlock(url: str, *, caption: str | RichText | RichTextBase | list[RichTextBase] | None = None)

Abstract Block for file-based blocks.

caption: RichText property

file: FileInfo property

url: str property

Heading(text: str | RichText | RichTextBase | list[RichTextBase], *, color: Color | BGColor = Color.DEFAULT, toggleable: bool = False)

Abstract Heading block.

toggleable: bool property

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

Heading1(text: str | RichText | RichTextBase | list[RichTextBase], *, color: Color | BGColor = Color.DEFAULT, toggleable: bool = False)

Heading 1 block.

to_markdown() -> str

Heading2(text: str | RichText | RichTextBase | list[RichTextBase], *, color: Color | BGColor = Color.DEFAULT, toggleable: bool = False)

Heading 2 block.

to_markdown() -> str

Heading3(text: str | RichText | RichTextBase | list[RichTextBase], *, color: Color | BGColor = Color.DEFAULT, toggleable: bool = False)

Heading 3 block.

to_markdown() -> str

Image(url: str, *, caption: str | RichText | RichTextBase | list[RichTextBase] | None = None)

Image block.

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.

page: Page property

url: str property

to_markdown() -> str

NumberedItem(text: str | RichText | RichTextBase | list[RichTextBase], *, color: Color | BGColor = Color.DEFAULT)

Numbered list item.

to_markdown() -> str

PDF(url: str, *, caption: str | RichText | RichTextBase | list[RichTextBase] | None = None)

PDF block.

to_markdown() -> str

Paragraph(text: str | RichText | RichTextBase | list[RichTextBase], *, color: Color | BGColor = Color.DEFAULT)

Paragraph block.

to_markdown() -> str

Quote(text: str | RichText | RichTextBase | list[RichTextBase], *, color: Color | BGColor = Color.DEFAULT)

Quote block.

to_markdown() -> str

SyncedBlock(blocks: Block | list[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, *, column_header: bool = False, row_header: bool = False)

Table block.

has_column_header: bool property

Return whether the table has a column header.

has_row_header: bool property

Return whether the table has a row header.

rows: list[TableRow] property

Return the rows of the table.

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: tuple[int, int]) -> RichText

to_markdown() -> str

Return the table as Markdown.

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

Table of contents block.

to_markdown() -> str

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

Table row block.

cells: list[RichText] property

to_markdown() -> str

Template()

Template block.

Deprecated

As of March 27, 2023 creation of template blocks will no longer be supported.

to_markdown() -> str

TextBlock(text: str | RichText | RichTextBase | list[RichTextBase])

Abstract Text block.

rich_text: RichText property

Return the text content of this text block.

ToDoItem(text: str | RichText | RichTextBase | list[RichTextBase], *, checked: bool = False, color: Color | BGColor = Color.DEFAULT)

ToDo list item.

is_checked() -> bool

to_markdown() -> str

ToggleItem(text: str | RichText | RichTextBase | list[RichTextBase], *, color: Color | BGColor = Color.DEFAULT)

Toggle list item.

to_markdown() -> str

Unsupported()

Unsupported block in the API.

to_markdown() -> str

Video(url: str, *, caption: str | RichText | RichTextBase | list[RichTextBase] | None = None)

Video block.

to_markdown() -> str