Skip to content

Core

core

Base classes for working with the Notion API.

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

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

logger = logging.getLogger(__name__) module-attribute

GenericObject

The base for all API objects.

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

build(*args, **kwargs) 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) -> Self

Update the internal attributes with new data.

NotionEntity

A materialized entity, which was created by a user.

created_by: UserRef = None class-attribute instance-attribute

created_time: datetime = None class-attribute instance-attribute

id: UUID = None class-attribute instance-attribute

last_edited_time: datetime = None class-attribute instance-attribute

parent: SerializeAsAny[ParentRef] = None 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, ...

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

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

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=None, **kwargs)

__pydantic_init_subclass__(*, object=None, **kwargs) 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: Any property writable

Return the nested object.

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

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

Register the subtypes of the TypedObject subclass.

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

extract_id(text: str) -> str | None

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