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__(value: object) -> bool
¶
__hash__() -> int
¶
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.
extract_id(text: str) -> str | None
¶
Examine the given text to find a valid Notion object ID.
raise_unset(obj: T | UnsetType) -> T
¶
raise_unset(obj: UnsetType) -> NoReturn
raise_unset(obj: T) -> T
Raise an error if the object is unset.