Skip to content

Schema

schema

Functionality around defining a database schema.

Currently only normal databases, no wiki databases, can be created [1]. Neither the Unique ID nor Status nor the Verfication page property can be set as a database property in a custom Schema when creating the database.

[1] https://developers.notion.com/docs/working-with-databases#wiki-databases

Design Principles

A schema is a subclass of Schema that holds Property objects, which define the name and the type of the property, e.g. Text, Number.

The source of truth is always the obj_ref and a Property holds only auxilliary information if actually needed. Since the object references obj_ref must always point to the actual obj_api.blocks.Database.properties value if the schema is bound to a database, the method _set_obj_refs rewires this when a schema is used to create a database.

GO_co = TypeVar('GO_co', bound=PropertyGO, default=PropertyGO, covariant=True) module-attribute

PropertyGO: TypeAlias = obj_schema.Property[obj_core.GenericObject] module-attribute

T = TypeVar('T') module-attribute

Button(name: str | None = None, **kwargs: Any)

Defines a button property in a database.

allowed_at_creation = False class-attribute instance-attribute

Checkbox(name: str | None = None, **kwargs: Any)

Defines a checkbox property in database.

CreatedBy(name: str | None = None, **kwargs: Any)

Defines the created-by property in a database.

CreatedTime(name: str | None = None, **kwargs: Any)

Defines the created-time property in a database.

Date(name: str | None = None, **kwargs: Any)

Defines a date property in a database.

DefaultSchema

name = Title('Name') class-attribute instance-attribute

Email(name: str | None = None, **kwargs: Any)

Defines an e-mail property in a database.

Files(name: str | None = None, **kwargs: Any)

Defines a files property in a database.

Formula(name: str | None = None, **kwargs: Any)

Defines a formula property in a database.

Currently the formula expression cannot reference other formula properties, e.g. prop("other formula") This is a limitation of the Notion API.

formula: str property writable

Return the formula of this property.

ID(name: str | None = None, **kwargs: Any)

Defines a unique ID property in a database.

allowed_at_creation = False class-attribute instance-attribute

prefix: str property

LastEditedBy(name: str | None = None, **kwargs: Any)

Defines the last-edited-by property in a database.

LastEditedTime(name: str | None = None, **kwargs: Any)

Defines the last-edited-time property in a database.

MultiSelect(name: str | None = None, *, options: list[Option] | type[OptionNS])

Defines a multi-select property in a database.

options: list[Option] property writable

Return the options of this multi-select property.

Number(name: str | None = None, *, format: NumberFormat | str = NumberFormat.NUMBER)

Defines a number property in a database.

format: NumberFormat property writable

Return the number format of this number property.

Person(name: str | None = None, **kwargs: Any)

Defines a person/people property in a database.

Phone(name: str | None = None, **kwargs: Any)

Defines a phone number property in a database.

PropType

Namespace class of all property types of a database for easier access.

Checkbox = Checkbox class-attribute instance-attribute

CreatedBy = CreatedBy class-attribute instance-attribute

CreatedTime = CreatedTime class-attribute instance-attribute

Date = Date class-attribute instance-attribute

Email = Email class-attribute instance-attribute

Files = Files class-attribute instance-attribute

Formula = Formula class-attribute instance-attribute

ID = ID class-attribute instance-attribute

LastEditedBy = LastEditedBy class-attribute instance-attribute

LastEditedTime = LastEditedTime class-attribute instance-attribute

MultiSelect = MultiSelect class-attribute instance-attribute

Number = Number class-attribute instance-attribute

Person = Person class-attribute instance-attribute

Phone = Phone class-attribute instance-attribute

Relation = Relation class-attribute instance-attribute

Rollup = Rollup class-attribute instance-attribute

Select = Select class-attribute instance-attribute

Status = Status class-attribute instance-attribute

Text = Text class-attribute instance-attribute

Title = Title class-attribute instance-attribute

URL = URL class-attribute instance-attribute

Verification = Verification class-attribute instance-attribute

Property(name: str | None = None, **kwargs: Any)

Base class for Notion property objects.

A property defines the name and type of a property in a database, e.g. number, date, text, etc.

allowed_at_creation = True class-attribute instance-attribute

If the Notion API allows to create a new database with a property of this type

attr_name: str property writable

Return the Python attribute name of the property in the schema.

description: str | None property

Return the description of this property.

id: str | None property

Return identifier of this property.

name: str property writable

Return name of this property.

obj_ref = obj_api_type.build(**kwargs) instance-attribute

prop_value: type[PropertyValue] property

Return the corresponding property value of this property.

readonly: bool property

Return if this property is read-only.

__eq__(other: object) -> bool

__hash__() -> int

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

__repr__() -> str

__str__() -> str

delete() -> None

Delete this property from the schema.

wrap_obj_ref(obj_ref: GO_co) -> Self classmethod

Wrap the object reference for this property.

Relation(name: str | None = None, *, schema: type[Schema] | None = None, two_way_prop: Relation | str | None = None)

Relation to another database.

is_self_ref: bool property

Determines if this relation is self referencing the same schema.

is_two_way: bool property

Determine if this relation is a two-way relation.

obj_ref: obj_schema.Relation property writable

Initialize the low-level object references for this relation.

schema: type[Schema] property writable

Schema of the relation database.

two_way_prop: Property | None property writable

Return the target property object of a two-way relation.

Rollup(name: str | None = None, *, relation: Relation, rollup: Property, calculate: AggFunc | str = AggFunc.SHOW_ORIGINAL)

Defines the rollup property in a database.

If the relation propery is a self-referencing relation, i.e. uno.PropType.Relation(uno.SelfRef) in the schema, then the property must be a str of the corresponding property name.

calculate: AggFunc property

Return the aggregation function of the rollup.

is_self_ref: bool property

Determines if this rollup is self-referencing the same schema.

relation_prop: Relation property

Return the relation property object of the rollup.

rollup_prop: Property property

Return the rollup property object of the rollup.

Schema

Base class for the schema of a database.

__init_subclass__(db_title: str | None = None, db_id: str | None = None, **kwargs: Any)

as_table(tablefmt: str | None = None) -> str classmethod

Return the schema in a given string table format.

Some table formats:

  • plain: no pseudographics
  • simple: Pandoc's simple table, i.e. only dashes to separate header from content
  • github: GitHub flavored Markdown
  • simple_grid: uses dashes & pipes to separate cells
  • html: standard html markup

Find more table formats under: astanin/python-tabulate#table-format

assert_consistency_with(other_schema: type[Schema], *, during_init: bool = False) -> None classmethod

Assert that this schema is consistent with another schema.

bind_db(db: Database | None = None) -> None classmethod

Bind this schema to the corresponding database for back-reference and vice versa.

If None (default) is passed, search for the database using db_id or db_title and bind it to this schema.

create(**kwargs: Any) -> Page classmethod

Create a page using this schema with a bound database.

get_db() -> Database classmethod

Get the database that is bound to this schema.

get_prop(prop_name: str, *, default: object = Unset) -> Property | T classmethod 

get_prop(prop_name: str, *, default: UnsetType = ...) -> Property

get_prop(prop_name: str, *, default: T) -> Property | T

Get a specific property from this schema assuming that property names are unique.

get_props() -> list[Property] classmethod

Get all properties of this schema.

get_ro_props() -> list[Property] classmethod

Get all read-only properties of this schema.

get_rw_props() -> list[Property] classmethod

Get all writeable properties of this schema.

get_title_prop() -> Property classmethod

Returns the property holding the title of the pages.

has_prop(prop_name: str) -> bool classmethod

Check if a property exists in this schema.

is_bound() -> bool classmethod

Determines if the schema is bound to a database.

show(*, simple: bool | None = None) -> None classmethod

Show the schema as html or as simple table.

to_dict() -> dict[str, Property] classmethod

Convert this schema to a dictionary of property names and corresponding types.

to_pydantic_model(*, with_ro_props: bool = False) -> type[SchemaModel] classmethod

Return a Pydantic model of this schema for validation.

This is useful for instance when writing a web API that receives data that should be validated before it is passed to Ultimate Notion. The actual values are converted to PropertyValue and thus value needs to be called to retrieve the actual Python type.

If with_ro_props is set to True, read-only properties are included in the model.

SchemaModel

Base Pydantic model for schemas to validate pages within a database.

model_config = ConfigDict(arbitrary_types_allowed=True, extra='forbid') class-attribute instance-attribute

__repr__() -> str

to_dict() -> dict[str, Any]

Convert the Pydantic model to a dictionary.

SchemaType

Metaclass for the schema of a database.

This makes the schema class itself more user-friendly by providing a __magic__ methods, e.g. letting it behave like a dictionary for the properties although it is a class, not an instance.

__delitem__(prop_name: str) -> None

__getattr__(name: str) -> Property

__getitem__(prop_name: str) -> Property

__iter__() -> Iterator[Property]

__len__() -> int

__new__(metacls, name: str, bases: tuple[type, ...], namespace: dict[str, object], **kwargs: Any) -> SchemaType

__setattr__(name: str, value: Any) -> None

__setitem__(prop_name: str, prop_type: Property) -> None

__str__() -> str

Select(name: str | None = None, *, options: list[Option] | type[OptionNS])

Defines a select property in a database.

options: list[Option] property writable

Return the options of this select property.

SelfRef

Target schema for self-referencing database relations.

_ = Title('title') class-attribute instance-attribute

Status(name: str | None = None, *, to_do: list[Option] | type[OptionNS] | None = None, in_progress: list[Option] | type[OptionNS] | None = None, complete: list[Option] | type[OptionNS] | None = None)

Defines a status property in a database.

The Notion API doesn't allow to create a property of this type. Sending it to the API with options and option groups defined results in an error about the existence of the keys options and groups and removing them creates a database with the property missing... ignorance is bliss.

Also the Status configuration is not mentioned as a [Property Schema Object])https://developers.notion.com/reference/property-schema-object).

It can still be used to check a schema.

allowed_at_creation = False class-attribute instance-attribute

groups: list[OptionGroup] property

Return the option groups of this status property.

options: list[Option] property

Return the options of this status property.

Text(name: str | None = None, **kwargs: Any)

Defines a text property in a database.

Title(name: str | None = None, **kwargs: Any)

Defines the mandatory title property in a database.

URL(name: str | None = None, **kwargs: Any)

Defines a URL property in a database.

Verification(name: str | None = None, **kwargs: Any)

Defines a unique ID property in a database.

allowed_at_creation = False class-attribute instance-attribute