Skip to content

Blocks

blocks

Wrapper for Notion API blocks.

Blocks are the base for all Notion content.

For validation the Pydantic model fields specify if a field is optional or not. Some fields are always set, e.g. id, when retrieving an object but must not be set when sending the object to the Notion API in order to create the object. To model this behavior, the default sentinel value Unset is used for those objects, e.g. 

class SelectOption(GenericObject)
    id: str | UnsetType = Unset
Be aware that this is important when updating to differentiate between the actual set values from default/unset values.

CB = TypeVar('CB', bound=Block, default=Block) module-attribute

CTB_co = TypeVar('CTB_co', bound=ColoredTextBlockTypeData, default=ColoredTextBlockTypeData, covariant=True) module-attribute

GO_co = TypeVar('GO_co', bound=GenericObject, default=GenericObject, covariant=True) module-attribute

TB_co = TypeVar('TB_co', bound=TextBlockTypeData, default=TextBlockTypeData, covariant=True) module-attribute

Audio

An audio block in Notion.

audio: SerializeAsAny[FileObject] | None = None class-attribute instance-attribute

Block

A standard block object in Notion.

Note

The equality and hash implementation only considers the content of the block, i.e., the type and the actual type data, but ignores meta fields like id, created_time, last_edited_time, etc.

__eq__(other: Any) -> bool

serialize_for_api() -> dict[str, Any]

Serialize the block for sending it to the Notion API.

Bookmark

A bookmark block in Notion.

bookmark: BookmarkTypeData instance-attribute

build(url: str, caption: list[RichTextBaseObject]) -> Bookmark classmethod

BookmarkTypeData

Type data for Bookmark block.

url: str instance-attribute

Breadcrumb

A breadcrumb block in Notion.

breadcrumb: BreadcrumbTypeData = Field(default_factory=BreadcrumbTypeData) class-attribute instance-attribute

BreadcrumbTypeData

Type data for Breadcrumb block.

BulletedListItem

A bulleted list item in Notion.

bulleted_list_item: BulletedListItemTypeData = Field(default_factory=BulletedListItemTypeData) class-attribute instance-attribute

BulletedListItemTypeData

Type data for BulletedListItem block.

Callout

A callout block in Notion.

callout: CalloutTypeData = Field(default_factory=CalloutTypeData) class-attribute instance-attribute

CalloutTypeData

Type data for Callout block.

Note: children is undocumented and behaves inconsistently. It is used during creation but not filled when retrieved.

icon: SerializeAsAny[FileObject] | EmojiObject | CustomEmojiObject | BuiltInIconObject | UnsetType | None = Unset class-attribute instance-attribute

CaptionMixin

Mixin for blocks having a caption.

caption: list[SerializeAsAny[RichTextBaseObject]] = Field(default_factory=list) class-attribute instance-attribute

ChildDatabase

A child database block in Notion.

child_database: ChildDatabaseTypeData instance-attribute

ChildDatabaseTypeData

Type data for ChildDatabase block.

title: str instance-attribute

ChildPage

A child page block in Notion.

child_page: ChildPageTypeData instance-attribute

ChildPageTypeData

Type data for ChildPage block.

title: str instance-attribute

Code

A code block in Notion.

code: CodeTypeData = Field(default_factory=CodeTypeData) class-attribute instance-attribute

CodeTypeData

Type data for Code block.

language: CodeLang = CodeLang.PLAIN_TEXT class-attribute instance-attribute

ColoredTextBlock

A standard abstract text block object in Notion with color.

ColoredTextBlockTypeData

Type data for TextBlock with color.

color: Color | BGColor = Color.DEFAULT class-attribute instance-attribute

Column

A column block in Notion.

column: ColumnTypeData = Field(default_factory=ColumnTypeData) class-attribute instance-attribute

build(width_ratio: float | None = None) -> Column classmethod

ColumnList

A column list block in Notion.

column_list: ColumnListTypeData = Field(default_factory=ColumnListTypeData) class-attribute instance-attribute

ColumnListTypeData

Type data for ColumnList block.

Note that children will not be populated when getting this block. See https://developers.notion.com/changelog/column-list-and-column-support

children: list[Column] = Field(default_factory=list) class-attribute instance-attribute

ColumnTypeData

Type data for Column block.

Note that children will not be populated when getting this block. See https://developers.notion.com/changelog/column-list-and-column-support

width_ratio: float | None = None class-attribute instance-attribute

DataObject

The base type for all Notion objects that hold actual data.

archived: bool = False class-attribute instance-attribute

has_children: bool = False class-attribute instance-attribute

in_trash: bool = False class-attribute instance-attribute

is_archived: bool = False class-attribute instance-attribute

last_edited_by: UserRef | UnsetType = Unset class-attribute instance-attribute

Database

A database record type.

cover: SerializeAsAny[FileObject] | None = None class-attribute instance-attribute

description: list[SerializeAsAny[RichTextBaseObject]] | UnsetType = Unset class-attribute instance-attribute

icon: SerializeAsAny[FileObject] | EmojiObject | CustomEmojiObject | BuiltInIconObject | None = None class-attribute instance-attribute

is_inline: bool = False class-attribute instance-attribute

properties: dict[str, SerializeAsAny[Property]] = Field(default_factory=dict) class-attribute instance-attribute

public_url: str | None = None class-attribute instance-attribute

title: list[SerializeAsAny[RichTextBaseObject]] | UnsetType = Unset class-attribute instance-attribute

url: str | UnsetType = Unset class-attribute instance-attribute

build_mention(style: Annotations | None = None) -> MentionObject

Divider

A divider block in Notion.

divider: DividerTypeData = Field(default_factory=DividerTypeData) class-attribute instance-attribute

DividerTypeData

Type data for Divider block.

Embed

An embed block in Notion.

embed: EmbedTypeData instance-attribute

build(url: str, caption: list[RichTextBaseObject]) -> Embed classmethod

EmbedTypeData

Type data for Embed block.

url: str instance-attribute

Equation

An equation block in Notion.

equation: EquationTypeData = Field(default_factory=EquationTypeData) class-attribute instance-attribute

EquationTypeData

Type data for Equation block.

expression: str | None = None class-attribute instance-attribute

File

A file block in Notion.

file: SerializeAsAny[FileObject] | None = None class-attribute instance-attribute

FileBase

A abstract block referencing a FileObject.

Heading

Abstract Heading block.

Heading1

A heading_1 block in Notion.

heading_1: HeadingTypeData = Field(default_factory=HeadingTypeData) class-attribute instance-attribute

Heading2

A heading_2 block in Notion.

heading_2: HeadingTypeData = Field(default_factory=HeadingTypeData) class-attribute instance-attribute

Heading3

A heading_3 block in Notion.

heading_3: HeadingTypeData = Field(default_factory=HeadingTypeData) class-attribute instance-attribute

HeadingTypeData

Type data for Heading block.

is_toggleable: bool = False class-attribute instance-attribute

Image

An image block in Notion.

image: SerializeAsAny[FileObject] | None = None class-attribute instance-attribute

LinkPreview

A link_preview block in Notion.

LinkPreviewTypeData

Type data for LinkPreview block.

url: str instance-attribute

LinkToPage

A link_to_page block in Notion.

link_to_page: SerializeAsAny[ParentRef] instance-attribute

NumberedListItem

A numbered list item in Notion.

numbered_list_item: NumberedListItemTypeData = Field(default_factory=NumberedListItemTypeData) class-attribute instance-attribute

NumberedListItemTypeData

Type data for NumberedListItem block.

PDF

A pdf block in Notion.

pdf: SerializeAsAny[FileObject] | None = None class-attribute instance-attribute

Page

A standard Notion page object.

cover: SerializeAsAny[FileObject] | None = None class-attribute instance-attribute

icon: SerializeAsAny[FileObject] | EmojiObject | CustomEmojiObject | BuiltInIconObject | None = None class-attribute instance-attribute

is_locked: bool | UnsetType = Unset class-attribute instance-attribute

properties: dict[str, PropertyValue] = Field(default_factory=dict) class-attribute instance-attribute

public_url: str | None = None class-attribute instance-attribute

title: list[RichTextBaseObject] property

Retrieve the title of the page from page properties.

url: str | UnsetType = Unset class-attribute instance-attribute

build_mention(style: Annotations | None = None) -> MentionObject

Paragraph

A paragraph block in Notion.

paragraph: ParagraphTypeData = Field(default_factory=ParagraphTypeData) class-attribute instance-attribute

ParagraphTypeData

Type data for Paragraph block.

icon: SerializeAsAny[FileObject] | EmojiObject | CustomEmojiObject | BuiltInIconObject | UnsetType | None = Unset class-attribute instance-attribute

Quote

A quote block in Notion.

quote: QuoteTypeData = Field(default_factory=QuoteTypeData) class-attribute instance-attribute

QuoteTypeData

Type data for Quote block.

SyncedBlock

A synced_block block in Notion - either original or synced.

synced_block: SyncedBlockTypeData = Field(default_factory=SyncedBlockTypeData) class-attribute instance-attribute

serialize_for_api() -> dict[str, Any]

Serialize the object for sending it to the Notion API.

SyncedBlockTypeData

Type data for SyncedBlock block.

synced_from: BlockRef | None = None class-attribute instance-attribute

Table

A table block in Notion.

table: TableTypeData = Field(default_factory=TableTypeData) class-attribute instance-attribute

TableOfContents

A table_of_contents block in Notion.

table_of_contents: TableOfContentsTypeData = Field(default_factory=TableOfContentsTypeData) class-attribute instance-attribute

TableOfContentsTypeData

Type data for TableOfContents block.

color: Color | BGColor = Color.DEFAULT class-attribute instance-attribute

TableRow

A table_row block in Notion.

table_row: TableRowTypeData = Field(default_factory=TableRowTypeData) class-attribute instance-attribute

build(n_cells: int) -> TableRow classmethod

TableRowTypeData

Type data for TableRow block.

cells: list[list[SerializeAsAny[RichTextBaseObject]]] = Field(default_factory=list) class-attribute instance-attribute

TableTypeData

Type data for Table block.

Note that children will not be populated when getting this block. See https://developers.notion.com/reference/block#table-blocks

children: list[TableRow] = Field(default_factory=list) class-attribute instance-attribute

has_column_header: bool = False class-attribute instance-attribute

has_row_header: bool = False class-attribute instance-attribute

table_width: int = 0 class-attribute instance-attribute

Template

A template block in Notion.

template: TemplateTypeData = Field(default_factory=TemplateTypeData) class-attribute instance-attribute

TemplateTypeData

Type data for Template block.

TextBlock

A standard abstract text block object in Notion.

TextBlockTypeData

Type data for TextBlock.

rich_text: Annotated[list[SerializeAsAny[RichTextBaseObject]], AfterValidator(normalize_text_objs)] = Field(default_factory=list) class-attribute instance-attribute

ToDo

A todo list item in Notion.

to_do: ToDoTypeData = Field(default_factory=ToDoTypeData) class-attribute instance-attribute

ToDoTypeData

Type data for ToDo block.

checked: bool = False class-attribute instance-attribute

Toggle

A toggle list item in Notion.

toggle: ToggleTypeData = Field(default_factory=ToggleTypeData) class-attribute instance-attribute

ToggleTypeData

Type data for Toggle block.

UnsupportedBlock

A placeholder for unsupported blocks in the API.

unsupported: UnsupportedBlockTypeData = Field(default_factory=UnsupportedBlockTypeData) class-attribute instance-attribute

UnsupportedBlockTypeData

Type data for UnsupportedBlock.

Video

A video block in Notion.

video: SerializeAsAny[FileObject] | None = None class-attribute instance-attribute

WithChildren

Type data mixin for blocks that can hold child blocks.

Provides a common base so that type data carrying children can be detected and narrowed with isinstance, e.g. when populating the children cache from the API.

children: list[SerializeAsAny[CB]] = Field(default_factory=list) class-attribute instance-attribute

normalize_text_objs(rt_objs: list[RichTextBaseObject]) -> list[RichTextBaseObject]