Skip to content

Core

core

Base classes for working with the Notion API.

Warning

To have proper type checking and inference, covariant type parameters are sometimes used even though they may violate the LSP (Liskov Substitution Principle) in some cases. This was done to improve the usability and flexibility of the API, allowing for more intuitive code while still maintaining type safety. Especially in this complex class hierarchy, Pydantic, which is heavily used in the API, relies on these covariant type parameters to function correctly. As an alternative approach, Protocol classes were tried, but they introduced their own complexities and limitations.

BASE_URL_PATTERN = 'https://(www.)?notion.so/' module-attribute

BLOCK_URL_LONG_RE = re.compile(f'^{BASE_URL_PATTERN}(?P<username>.*)/(?P<title>.*)-(?P<page_id>{UUID_PATTERN})\#(?P<block_id>{UUID_PATTERN})$', flags=(re.IGNORECASE | re.VERBOSE)) module-attribute

PAGE_URL_LONG_RE = re.compile(f'^{BASE_URL_PATTERN}(?P<title>.*)-(?P<page_id>{UUID_PATTERN})$', flags=(re.IGNORECASE | re.VERBOSE)) module-attribute

PAGE_URL_SHORT_RE = re.compile(f'^{BASE_URL_PATTERN}(?P<page_id>{UUID_PATTERN})$', flags=(re.IGNORECASE | re.VERBOSE)) module-attribute

T = TypeVar('T') module-attribute

TO_co = TypeVar('TO_co', covariant=True, default=Any) module-attribute

UUID_PATTERN = '[0-9a-f]{8}-?[0-9a-f]{4}-?[0-9a-f]{4}-?[0-9a-f]{4}-?[0-9a-f]{12}' module-attribute

UUID_RE = re.compile(f'^(?P<id>{UUID_PATTERN})$') module-attribute

Unset: UnsetType = UnsetType() module-attribute

GenericObject

The base for all API objects.

model_config = ConfigDict(extra=('ignore' if is_stable_release() else 'forbid')) class-attribute instance-attribute

__eq__(other: Any) -> bool

Compare two objects for equality by comparing all their fields.

__hash__() -> int

Compute a hash value for the object by hashing all its fields.

build(*args: Any, **kwargs: Any) -> Self classmethod

Use the standard constructur to build the instance. Will be overwritten for more complex types.

serialize_for_api() -> dict[str, Any]

Serialize the object for sending it to the Notion API.

update(**data: Any) -> None

Update the internal attributes with new data in place.

NotionEntity

A materialized entity, which was created by a user.

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

created_time: datetime | UnsetType = Unset class-attribute instance-attribute

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

last_edited_time: datetime | UnsetType = Unset class-attribute instance-attribute

parent: SerializeAsAny[ParentRef] | UnsetType = Unset class-attribute instance-attribute

NotionObject

A top-level Notion API resource.

Many objects in the Notion API follow a standard pattern with a object property, which defines the general object type, e.g. page, database, user, block, ...

object: str = Field(default=None) class-attribute instance-attribute

object is a string that identifies the general object type, e.g. page, database, user, block, ...

request_id: UUID | None = None class-attribute instance-attribute

request_id is a UUID that is used to track requests in the Notion API

__init_subclass__(*, object: str | None = None, **kwargs: Any) -> None

__pydantic_init_subclass__(*, object: str | None = None, **kwargs: Any) -> None classmethod

Update GenericObject defaults for the named object.

Needed since model_fields are not available during init_subclass See: pydantic/pydantic#5369

TypedObject

A type-referenced object.

Many objects in the Notion API follow a standard pattern with a type property followed by additional data. These objects must specify a type attribute to ensure that the correct object is created.

For example, this contains a nested 'detail' object:

data = {
    type: "detail",
    ...
    detail: {
        ...
    }
}

type: str = Field(default=None) class-attribute instance-attribute

type is a string that identifies the specific object type, e.g. heading_1, paragraph, equation, ...

value: TO_co property writable

Return the nested object.

__init_subclass__(*, type: str | None = None, polymorphic_base: bool = False, **kwargs: Any) -> None

__pydantic_init_subclass__(*, type: str | None = None, **kwargs: Any) -> None classmethod

Register the subtypes of the TypedObject subclass.

This is needed since model_fields is not available during init_subclass. See: pydantic/pydantic#5369

UniqueObject

A Notion object that has a unique ID.

This is the base class for all Notion objects that have a unique identifier, i.e. id.

Warning

The id field is only set when the object is sent or retrieved from the API, not when created locally.

id: UUID | str | UnsetType = Field(union_mode='left_to_right', default=Unset) class-attribute instance-attribute

id is an UUID if possible or a string (possibly not unique) depending on the object

UnsetType

Sentinel type for missing default values.

A sentinel type for indicating that a value is unset or missing for cases when None has another meaning. In the Notion API, None is also used to delete properties, so a way to represent "no value" explicitly is needed.

__slots__ = () class-attribute instance-attribute

unset_marker: bool = Field(default=True, exclude=False) class-attribute instance-attribute

__hash__() -> int

__new__(*args: Any, **kwargs: Any) -> UnsetType

__repr__() -> str

extract_id(text: str) -> str | None

Examine the given text to find a valid Notion object ID.

is_unset(v: Any) -> TypeIs[UnsetType]

Check if the given value is unset.

raise_unset(obj: T | UnsetType) -> T 

raise_unset(obj: UnsetType) -> NoReturn

raise_unset(obj: T) -> T

Raise an error if the object is unset.