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 as well as higher-level methods.

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 value None is used for those objects, e.g. 

class SelectOption(GenericObject)
    id: str = None  # type: ignore  # to make sure mypy doesn't complain
Also be aware that this is import when updating to differentiate actual set values from default/unset values.

Annotations

Style information for RichTextObject's.

bold: bool = False class-attribute instance-attribute

code: bool = False class-attribute instance-attribute

color: BGColor = None 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) classmethod

Compose a BlockRef from the given reference object.

block_ref can be either a string, UUID, or block.

Bot

Represents a Bot in Notion.

bot: _NestedData = _NestedData() class-attribute instance-attribute

DatabaseRef

Reference a database.

database_id: UUID instance-attribute

build(db_ref: Database | str | UUID) classmethod

Compose a DatabaseRef from the given reference object.

DateRange

A Notion date range, with an optional end date.

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

start: date | datetime instance-attribute

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

EmojiObject

A Notion emoji object.

emoji: str instance-attribute

build(emoji) classmethod

Compose an EmojiObject from the given emoji string.

EquationObject

Notion equation element.

equation: _NestedData instance-attribute

ExternalFile

An external file object.

external: _NestedData instance-attribute

build(url, name=None) classmethod

Create a new ExternalFile from the given URL.

FileObject

A Notion file object.

Depending on the context, a FileObject may require a name (such as in the Files property). This makes the object hierarchy difficult, so here we simply allow name to be optional. It is the responsibility of the caller to set name if required by the API.

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

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

HostedFile

A Notion file object.

file: _NestedData instance-attribute

LinkObject

Reference a URL.

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

url: str = None class-attribute instance-attribute

MentionData

Base class for typed Mention data objects.

MentionDatabase

Nested database information for Mention properties.

database: ObjectReference instance-attribute

build(page) -> MentionObject classmethod

Build a Mention object for the specified database reference.

MentionDate

Nested date data for Mention properties.

date: DateRange instance-attribute

build(start, end=None) -> MentionObject classmethod

Build a Mention object for the specified URL.

MentionLinkPreview

Nested url data for Mention properties.

These objects cannot be created via the API.

MentionObject

Notion mention element.

mention: MentionData instance-attribute

MentionPage

Nested page data for Mention properties.

page: ObjectReference instance-attribute

build(page_ref) -> MentionObject classmethod

Build a Mention object for the specified page reference.

MentionTemplate

Nested template data for Mention properties.

template_mention: 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: User instance-attribute

build(user: User) -> MentionObject classmethod

Build a Mention object for the specified user.

The id field must be set for the given User. Other fields may cause errors if they do not match the specific type returned from the API.

ObjectReference

A general-purpose object reference in the Notion API.

id: UUID instance-attribute

build(ref) classmethod

Compose an ObjectReference from the given reference.

ref may be a UUID, str, ParentRef or GenericObject with an id.

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) 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: _NestedData = _NestedData() class-attribute instance-attribute

RichTextObject

Base class for Notion rich text elements.

annotations: Annotations | None = None class-attribute instance-attribute

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

plain_text: str instance-attribute

build(text: str, href: str | None = None, style: Annotations | None = None) 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

an optional link for this object

 None
style Annotations | None

an optional Annotations object for this text

 None

SelectGroup

Group of options for status objects.

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

id: str = None class-attribute instance-attribute

name: str instance-attribute

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

SelectOption

Options for select & multi-select objects.

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

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

id: str = None class-attribute instance-attribute

name: str instance-attribute

build(name, color=Color.DEFAULT) classmethod

Create a SelectOption object from the given name and color.

TextObject

Notion text element.

text: _NestedData = _NestedData() class-attribute instance-attribute

build(text: str, href: str | None = None, style: Annotations | None = None) 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

User

Represents a User in Notion.

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

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

UserRef

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

UserType

Available user types.

BOT = 'bot' class-attribute instance-attribute

PERSON = 'person' class-attribute instance-attribute

WorkspaceRef

Reference the workspace.

workspace: bool = True class-attribute instance-attribute