Skip to content

Objects

objects

Wrapper for various Notion API objects like parents, mentions, emojis & users.

Similar to other records, these object provide access to the primitive data structure used in the Notion API.

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.

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

MAX_TEXT_OBJECT_SIZE = 2000 module-attribute

The max text size according to the Notion API is 2000 characters.

T = TypeVar('T', default=Any) module-attribute

Annotations

Style information for RichTextObject's.

bold: bool = False class-attribute instance-attribute

code: bool = False class-attribute instance-attribute

color: Color | BGColor | UnsetType = Unset class-attribute instance-attribute

italic: bool = False class-attribute instance-attribute

strikethrough: bool = False class-attribute instance-attribute

underline: bool = False class-attribute instance-attribute

BlockRef

Reference a block.

block_id: UUID instance-attribute

build(block_ref: Block | str | UUID) -> BlockRef classmethod

Compose a BlockRef from the given reference object.

Bot

Represents a Bot in Notion.

bot: BotTypeData = Field(default_factory=BotTypeData) class-attribute instance-attribute

BotTypeData

Type data for a Bot.

owner: WorkspaceRef | MentionUser | None = None class-attribute instance-attribute

workspace_limits: WorkSpaceLimits = Field(default_factory=WorkSpaceLimits) class-attribute instance-attribute

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

Comment

A Notion comment object.

discussion_id: UUID instance-attribute

display_name: TypeData instance-attribute

rich_text: list[RichTextBaseObject] instance-attribute

TypeData

resolved_name: str instance-attribute
type: str instance-attribute

CommentRef

Reference a comment.

comment_id: UUID instance-attribute

build(comment_ref: Comment | str | UUID) -> CommentRef classmethod

Compose a CommentRef from the given reference object.

CustomEmojiObject

A Notion custom emoji object.

Within text a custom emoji is represented as a mention. For this reason there is no MentionCustomEmoji class, but the CustomEmojiObject itself can be used to build a mention object.

custom_emoji: CustomEmojiObjectTypeData instance-attribute

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

Build a mention object for this custom emoji.

build_mention_from(custom_emoji: CustomEmojiObject, *, style: Annotations | None = None) -> MentionObject classmethod

CustomEmojiObjectTypeData

Type data for a CustomEmojiObject.

id: UUID instance-attribute

name: str instance-attribute

url: str instance-attribute

DatabaseRef

Reference a database.

database_id: UUID instance-attribute

build(db_ref: Database | str | UUID) -> DatabaseRef classmethod

Compose a DatabaseRef from the given reference object.

DateRange

A Notion date range, with an optional end date.

end: dt.date | dt.datetime | None = None class-attribute instance-attribute

start: dt.date | dt.datetime instance-attribute

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

__str__() -> str

build(dt_spec: str | DateTimeOrRange) -> DateRange classmethod

Compose a DateRange object from the given properties.

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

to_pendulum() -> DateTimeOrRange

Convert the DateRange to a pendulum object.

EmojiObject

A Notion emoji object.

Within text an emoji is represented as unicode string.

emoji: str instance-attribute

build(emoji: str) -> EmojiObject classmethod

Compose an EmojiObject from the given emoji string.

EquationObject

Notion equation element.

equation: TypeData instance-attribute

TypeData

expression: str instance-attribute

build(expression: str, *, href: str | None = None, style: Annotations | None = None) -> EquationObject classmethod

Compose a TextObject from the given properties.

Parameters:

Name Type Description Default
expression str

expression

 required
href str | None

optional link for this object

 None
style Annotations | None

optional annotations for styling this text

 None

ExternalFile

A Notion external file object.

external: ExternalFileTypeData instance-attribute

build(url: str, *, name: str | None = None, caption: list[RichTextBaseObject] | None = None) -> ExternalFile classmethod

Create a new ExternalFile from the given URL.

ExternalFileTypeData

Type data for ExternalFile.

url: str instance-attribute

FileImportError

Result of a failed file import operation.

error: FileImportTypeData instance-attribute

imported_time: dt.datetime | None = None class-attribute instance-attribute

FileImportSuccess

Result of a successful file import operation.

imported_time: dt.datetime | None = None class-attribute instance-attribute

success: FileImportTypeData instance-attribute

FileImportTypeData

Type data for FileImportSuccess and FileImportError.

For ease of use, the parameters of success and error are combined into a single class.

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

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

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

status_code: int | None = None class-attribute instance-attribute

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

FileObject

A Notion file object.

Depending on the context, a FileObject may require a name (such as in the Files property) or may have a caption, for instance when used within a File block, which makes the object hierarchy complex. Thus, we simply allow name and caption to be optional. It is the responsibility of the caller to set name if required by the API.

caption: list[SerializeAsAny[RichTextBaseObject]] | None = None class-attribute instance-attribute

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

FileUpload

A Notion file upload object.

This object is used to handle the process of uploading a file to Notion.

archived: bool instance-attribute

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

content_length: int | None = None class-attribute instance-attribute

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

created_by: User instance-attribute

created_time: dt.datetime instance-attribute

expiry_time: dt.datetime | None = None class-attribute instance-attribute

file_import_result: FileImportSuccess | FileImportError | None = None class-attribute instance-attribute

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

id: UUID instance-attribute

last_edited_time: dt.datetime instance-attribute

number_of_parts: NumberOfParts | None = None class-attribute instance-attribute

status: FileUploadStatus instance-attribute

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

NumberOfParts

Number of parts for the file upload.

sent: int instance-attribute
total: int instance-attribute

HostedFile

A Notion file object.

file: HostedTypedata instance-attribute

build(url: str, *, name: str | None = None, caption: list[RichTextBaseObject] | None = None, expiry_time: dt.datetime | None = None) -> HostedFile classmethod

Create a new HostedFile from the given URL.

HostedTypedata

Type data for HostedFile.

expiry_time: dt.datetime | None = None class-attribute instance-attribute

url: str instance-attribute

LinkObject

Reference a URL.

type: str = 'url' class-attribute instance-attribute

url: str instance-attribute

MentionBase

Base class for typed Mention objects.

Note that this class is different to MentionMixin, which is used to provide a build_mention method for objects that can be mentioned in Notion. Here, we have a class method to build a mention object from the target object.

build_mention_from(*args: Any, **kwargs: Any) -> MentionObject abstractmethod classmethod

Build a mention object for this type of mention from the actual target object.

MentionDatabase

Nested database information for Mention properties.

database: SerializeAsAny[ObjectRef] instance-attribute

build_mention_from(db: Database, *, style: Annotations | None = None) -> MentionObject classmethod

MentionDate

Nested date data for Mention properties.

date: DateRange instance-attribute

build_mention_from(date_range: DateRange, *, style: Annotations | None = None) -> MentionObject classmethod

Nested url data for Mention properties.

build_mention_from(href: str, title: str, *, style: Annotations | None = None) -> MentionObject classmethod

Build a mention object for this type of mention from the actual target object.

MentionLinkPreview

Nested url data for Mention properties.

Warning

Link previews cannot be created via the API.

build_mention_from(url: str, *, style: Annotations | None = None) -> MentionObject classmethod

Build a mention object for this type of mention from the actual target object.

MentionLinkPreviewTypeData

Type data for a MentionLinkPreview.

url: str instance-attribute

MentionLinkTypeData

Type data for a MentionLink.

href: str instance-attribute

title: str instance-attribute

MentionMixin

Mixin for objects that can be mentioned in Notion.

This mixin adds a build_mention property to the object, which can be used to reference the object in a mention.

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

Return a mention object for this object.

MentionObject

Notion mention element.

mention: SerializeAsAny[MentionBase] instance-attribute

MentionPage

Nested page data for Mention properties.

page: SerializeAsAny[ObjectRef] instance-attribute

build_mention_from(page: Page, *, style: Annotations | None = None) -> MentionObject classmethod

MentionTemplate

Nested template data for Mention properties.

template_mention: SerializeAsAny[MentionTemplateData] instance-attribute

MentionTemplateData

Nested template data for Mention properties.

MentionTemplateDate

Nested date template data for Mention properties.

template_mention_date: str instance-attribute

MentionTemplateUser

Nested user template data for Mention properties.

template_mention_user: str instance-attribute

MentionUser

Nested user data for Mention properties.

user: SerializeAsAny[User | UserRef] instance-attribute

build_mention_from(user: User, *, style: Annotations | None = None) -> MentionObject classmethod

ObjectRef

A general-purpose object reference in the Notion API.

id: UUID instance-attribute

build(ref: ParentRef | GenericObject | UUID | str) -> ObjectRef classmethod

Compose a reference to an object from the given reference.

Strings may be either UUID's or URL's to Notion content.

PageRef

Reference a page.

page_id: UUID instance-attribute

build(page_ref: Page | str | UUID) -> PageRef classmethod

Compose a PageRef from the given reference object.

ParentRef

Reference another block as a parent.

Notion API: Parent Object

This class is simply a placeholder for the typed concrete *Ref classes.

Callers should always instantiate the intended concrete versions.

Person

Represents a Person in Notion.

person: PersonTypeData = Field(default_factory=PersonTypeData) class-attribute instance-attribute

PersonTypeData

Type data for a Person.

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

RichTextBaseObject

Base class for Notion rich text elements.

annotations: Annotations | UnsetType = Unset class-attribute instance-attribute

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

plain_text: str instance-attribute

SelectGroup

Group of options for status objects.

color: Color | UnsetType = Unset class-attribute instance-attribute

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

name: str instance-attribute

option_ids: list[str] = Field(default_factory=list) class-attribute instance-attribute

__eq__(other: object) -> bool

__hash__() -> int

SelectOption

Options for select & multi-select objects.

Specifying no color will result in the default color being used, i.e. Color.DEFAULT, which is a light grey. Note that colors can't be changed after they are set.

color: Color | UnsetType = Unset class-attribute instance-attribute

description: list[RichTextBaseObject] | None = None class-attribute instance-attribute

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

name: str instance-attribute

__eq__(other: object) -> bool

Compare SelectOption objects by all attributes except id.

__hash__() -> int

Return a hash of the SelectOption based on name, color, and description.

build(name: str, color: Color = Color.DEFAULT) -> SelectOption classmethod

Create a SelectOption object from the given name and color.

TextObject

Notion text element.

text: TypeData instance-attribute

TypeData

content: str instance-attribute

build(text: str, *, href: str | None = None, style: Annotations | None = None) -> TextObject classmethod

Compose a TextObject from the given properties.

Parameters:

Name Type Description Default
text str

the plain text of this object

 required
href str | None

optional link for this object

 None
style Annotations | None

optional annotations for styling this text

 None

UnknownUser

Represents an unknown user in Notion.

This is a unofficial placeholder for a user that is not recognized by the API.

name: Literal['Unknown User'] = 'Unknown User' class-attribute instance-attribute

unknown: UnknownUserTypeData = Field(default_factory=UnknownUserTypeData) class-attribute instance-attribute

UnknownUserTypeData

Type data for an UnknownUser.

UploadedFile

A Notion uploaded file object. The result of completed FileUpload

file_upload: UploadedFileTypeData instance-attribute

build(id: UUID) -> UploadedFile classmethod

Create a new UploadedFile from the given ID.

UploadedFileTypeData

Type data for UploadedFile.

id: UUID instance-attribute

User

Represents a User in Notion.

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

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

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

UserRef

Reference to a user, e.g. in created_by, last_edited_by, mentioning, etc.

id: UUID instance-attribute

build(user_ref: User | str | UUID) -> UserRef classmethod

Compose a PageRef from the given reference object.

WorkSpaceLimits

Limits for a Notion workspace.

max_file_upload_size_in_bytes: int | None = None class-attribute instance-attribute

WorkspaceRef

Reference the workspace.

workspace: bool = True class-attribute instance-attribute

get_uuid(obj: str | UUID | ParentRef | NotionObject | BlockRef) -> UUID

Retrieves a UUID from an object reference.

Only meant for internal use.

rich_text_to_str(rich_texts: list[RichTextBaseObject]) -> str

Convert a list of rich texts to plain text.