Skip to content

Blocks

blocks

Blocks that make up the content of a page.

Following blocks can be nested, i.e. they can contain children:

  • Paragraph
  • Headings if toggleable (*)
  • Quote
  • Callout
  • BulletedItem
  • NumberedItem
  • ToDoItem
  • ToggleItem
  • Column within a Columns object (*)
  • Table as list of TableRow objects (*)
  • Synced Block
  • Template (read-only)

Blocks with (*) don't have an official children field in the Notion API call but can still contain children using the append method. They can also be created offline and populated with children offline before being pushed to Notion. This is a technical detail and should not affect the user experience.

B_co = TypeVar('B_co', bound=(obj_blocks.Block), default=(obj_blocks.Block), covariant=True) module-attribute

DO_co = TypeVar('DO_co', bound=(obj_blocks.DataObject), default=(obj_blocks.DataObject), covariant=True) module-attribute

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

HT = TypeVar('HT', bound=(obj_blocks.Heading)) module-attribute

MAX_BLOCKS_PER_REQUEST = 1000 module-attribute

The maximum number of blocks that can be created/updated/deleted in one API request.

Source: https://developers.notion.com/reference/request-limits#limits-for-property-values

MAX_BLOCK_CHILDREN = 100 module-attribute

"The maximum number of block children that can be appended in one API call.

Source: https://developers.notion.com/reference/patch-block-children

MAX_NESTING_LEVEL = 2 module-attribute

The maximum nesting level of blocks in Notion for one append call.

MIN_COLS = 2 module-attribute

Minimum number of columns when creating a column block to structure a page.

TB = TypeVar('TB', bound=(obj_blocks.ColoredTextBlock)) module-attribute

TB_co = TypeVar('TB_co', bound=(obj_blocks.TextBlock), default=(obj_blocks.TextBlock), covariant=True) module-attribute

Audio(file: AnyFile, *, caption: str | None = None)

Audio block.

Note

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

to_markdown() -> str

Return the audio as Markdown.

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.

parent: Block | Page | None property

Return the parent block or page, or None if not accessible.

__eq__(other: Any | Block) -> bool

Compare blocks by their content, not by their metadata like id, timestamp etc.

__hash__() -> int

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: AnyFile | str | 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: NotionFile | ExternalFile | Emoji | CustomEmoji property writable

get_default_icon() -> Emoji staticmethod

Return the default icon of a callout block.

to_markdown() -> str

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

Mixin for objects that can have captions.

caption: Text | None property writable

Return the caption of the code block.

ChildDatabase()

Child database block.

This block is used to represent a database if it is a child of e.g. a page. We try to resolve it via the API to get the actual database object. This does not work if it is a linked database as mentioned in the Notion API docs: https://developers.notion.com/reference/retrieve-a-database

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

Return the title of the child database

to_markdown() -> str

Return the child database as Markdown.

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 | None 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 or toggleable heading. The children property is mostly used to send a nested batch of blocks with children to Notion in one API call. It cannot be trusted though that the children property is always up-to-date, e.g. when blocks are appended as the Notion API often doesn't send the children property back in the response.

children: tuple[Block, ...] property

Return the children of this block.

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

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

If this block is already in Notion, the blocks are appended directly to Notion, otherwise they are prepared to be appended in one batch call, later. Note that explicitely defining sync will not affect the append behaviour itself but will raise an error if it is not what was expected, e.g. sync=True when this block is not yet in Notion.

Parameters:

Name Type Description Default
blocks Block | Sequence[Block]

A block or a sequence of blocks to append.

 required
after Block | None

A block to append the new blocks after.

 None
sync bool | None

Whether to sync the changes with Notion directly or in one batch call later. If sync = None (default), the blocks are appended directly if this block is already in Notion, otherwise they are prepared to be appended in one batch call, later.

 None

Code(text: str, *, language: str | 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.

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

Return the color of the text block.

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, sync: bool | 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.

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.

url: str 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

Return the LaTeX expression of the equation.

to_markdown() -> str

Return the LaTeX expression of the equation as Markdown.

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

File block.

Note

Only the caption and name can be modified, the file object 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.

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

Abstract Block for file-based blocks.

Parent class of all file-based block types.

file_info: AnyFile property

Return the file information of this block as a copy.

url: str property

Return the URL of the file.

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, sync: bool | 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(file: AnyFile, *, 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.

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

Numbered list item.

to_markdown() -> str

PDF(file: AnyFile, *, caption: 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.

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

Paragraph block.

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

A block that holds children blocks, mainly used for type checking.

If there was no block like that, mypy would narrow a Block | Page object down to a Page object if we check for isinstance(i, ChildrenMixin) as Page inherits from ChildrenMixin and Block not. This is not what we want.

__eq__(other: Any) -> bool

__hash__() -> int

wrap_obj_ref(obj_ref: B_co) -> Self classmethod

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

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

Template()

Template block.

Deprecated

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

to_markdown() -> str

Return the template content as Markdown.

TextBlock(text: str)

Abstract Text block.

Parent class of all text block types.

rich_text: Text | None property writable

Return the text content of this text block.

__str__() -> str

Return the text content of this block as string.

to_markdown() -> str

Return the text content of this block as Markdown.

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.

Some blocks like buttons, AI blocks, or templates are not supported by the Notion API. They will be returned as Unsupported blocks when fetched, but cannot be created or modified.

to_markdown() -> str

Return a placeholder for unsupported blocks.

Video(file: AnyFile, *, caption: 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.

traverse_blocks(blocks: Sequence[Block]) -> Iterator[Block]

Recursively traverse blocks and their children in depth-first order.

wrap_icon(icon_obj: objs.FileObject | objs.EmojiObject | objs.CustomEmojiObject) -> NotionFile | ExternalFile | CustomEmoji | Emoji

Wrap the icon object into the corresponding class.