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: Color | BGColor = Color.DEFAULT 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: TypeData = TypeData() class-attribute instance-attribute

TypeData

owner: WorkspaceRef = None class-attribute instance-attribute
workspace_name: str = None class-attribute 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: dt.datetime | dt.date | pnd.Interval) -> Self classmethod

Compose a DateRange object from the given properties.

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

to_pendulum() -> pnd.DateTime | pnd.Date | pnd.Interval

Convert the DateRange to a pendulum object.

EmojiObject

A Notion emoji object.

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

An external file object.

external: TypeData instance-attribute

TypeData

url: str instance-attribute

build(url: str, *, name: str | None = None, caption: list[RichTextBaseObject] | None = None) -> Self 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[SerializeAsAny[RichTextBaseObject]] | None = None class-attribute instance-attribute

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

HostedFile

A Notion file object.

file: TypeData instance-attribute

TypeData

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 = None class-attribute instance-attribute

MentionBase

Base class for typed Mention objects.

MentionDatabase

Nested database information for Mention properties.

database: SerializeAsAny[ObjectReference] instance-attribute

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

MentionDate

Nested date data for Mention properties.

date: DateRange instance-attribute

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

MentionLinkPreview

Nested url data for Mention properties.

Warning

Link previews cannot be created via the API.

TypeData

url: str instance-attribute

MentionMixin

Mixin for objects that can be mentioned in Notion.

This mixin adds a 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[ObjectReference] instance-attribute

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

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: SerializeAsAny[User] instance-attribute

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

ObjectReference

A general-purpose object reference in the Notion API.

id: UUID instance-attribute

build(ref: ParentRef | GenericObject | UUID | str) -> Self 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) -> 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: TypeData = TypeData() class-attribute instance-attribute

TypeData

email: str = None class-attribute instance-attribute

RichTextBaseObject

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

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) -> Self classmethod

Create a SelectOption object from the given name and color.

TextObject

Notion text element.

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

TypeData

content: str = None class-attribute instance-attribute

build(text: str, *, href: str | None = None, style: Annotations | None = None) -> Self 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: TypeData = TypeData() class-attribute instance-attribute

TypeData

User

Represents a User in Notion.

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

id: UUID = 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.

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.