Skip to content

Blocks

blocks

Blocks that make up the content of a page.

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

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

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

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

Abstract Notion block.

Parent class of all block types.

discussions: tuple[Discussion, ...] property

Return comments of this block as list of discussions, i.e. threads of comments.

insert_after(blocks: Block | Sequence[Block]) -> None

Insert a block or several blocks after this block.

reload() -> Self

Reload the block from the API.

replace(blocks: Block | Sequence[Block]) -> None

Replace this block with another block or blocks.

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

ChildDatabase()

Child database block.

Note

To create a child database block as an end-user, create a new database with the corresponding parent. This block is used only internally.

db: Database property

Return the actual Database object.

title: str property

Return the title of the child database

to_markdown() -> str

ChildPage()

Child page block.

Note

To create a child page block, create a new page with the corresponding parent. This block is used only internally.

page: Page property

Return the actual Page object.

title: str property

Return the title of the child page.

to_markdown() -> str

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: tuple[Block, ...] property

Return the children of this block.

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

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

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

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

Abstract Text block with color.

Parent class of all text block types with color.

color: Color | BGColor property writable

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

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

Mixin for objects that can have comments and discussions.

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

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

block_url: str property

Return the URL of the block.

Note

Databases and pages are also considered blocks in Notion but they also have a long-form URL. Use the url property to get the long-form URL.

has_children: bool property

Return whether the object has children.

is_deleted: bool property

Return wether the object is in trash.

last_edited_by: User property

Return the user who last edited the block.

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

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

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

Abstract Block for file-based blocks.

Parent class of all file-based block types.

caption: Text property writable

file_info: FileInfo property

Return the file information of this block as a copy.

url: str property

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

Abstract Heading block.

Parent class of all heading block types.

toggleable: bool property writable

Return whether the heading is toggleable.

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

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

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

Numbered list item.

to_markdown() -> str

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

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

Paragraph block.

to_markdown() -> str

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

Quote block.

to_markdown() -> str

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 

__getitem__(index: int) -> TableRow

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

__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

Template()

Template block.

Deprecated

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

to_markdown() -> str

TextBlock(text: str)

Abstract Text block.

Parent class of all text block types.

rich_text: Text property writable

Return the text content of this text block.

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

Unsupported()

Unsupported block in the API.

to_markdown() -> str

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