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 PageShema that holds Property objects with a name and an actual PropertyType, e.g. Text, Number.

The source of truth is always the obj_ref and a PropertyType 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 an database, the method _remap_obj_refs rewires this when a schema is used to create a database.

T = TypeVar('T', bound=obj_schema.PropertyType) module-attribute

Checkbox(*args, **kwargs)

Defines a checkbox property in database.

CreatedBy(*args, **kwargs)

Defines the created-by property in a database.

CreatedTime(*args, **kwargs)

Defines the created-time property in a database.

Date(*args, **kwargs)

Defines a date property in a database.

DefaultSchema

Default database schema of Notion.

As inferred by just creating an empty database in the Notion UI.

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

tags = Property('Tags', MultiSelect([])) class-attribute instance-attribute

Email(*args, **kwargs)

Defines an e-mail property in a database.

Files(*args, **kwargs)

Defines a files property in a database.

Formula(expression: str)

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 API.

ID(*args, **kwargs)

Defines a unique ID property in a database.

allowed_at_creation = False class-attribute instance-attribute

prefix: str property

LastEditedBy(*args, **kwargs)

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

LastEditedTime(*args, **kwargs)

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

MultiSelect(options: list[Option] | type[OptionNS])

Defines a multi-select property in a database.

options: dict[str, Option] property

Number(number_format: NumberFormat)

Defines a number property in a database.

PageSchema

Base class for the schema of a database.

db_desc: RichText | None instance-attribute

db_title: RichText | None instance-attribute

__init_subclass__(db_title: RichText | str | 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

bind_db(db: Database) classmethod

Bind the PageSchema to the corresponding database for back-reference.

create(**kwargs) -> Page classmethod

Create a page using this schema with a bound database.

from_dict(schema_dct: dict[str, PropertyType], db_title: str | None = None, db_desc: str | None = None) -> type[PageSchema] classmethod

Creation of a schema from a dictionary for easy support of dynamically created schemas.

get_db() -> Database classmethod

Get the database that is bound to this schema.

get_prop(prop_name: str) -> Property classmethod

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_title_prop() -> Property classmethod

Returns the property holding the title of the pages.

is_bound() -> bool classmethod

Determines if the schema is bound to a database.

is_consistent_with(other_schema: type[PageSchema]) -> bool classmethod

Is this schema consistent with another ignoring backward relations if not in other schema.

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

Show the schema as html or as simple table.

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

Convert this schema to a dictionary.

People(*args, **kwargs)

Defines a people property in a database.

PhoneNumber(*args, **kwargs)

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

People = People class-attribute instance-attribute

PhoneNumber = PhoneNumber 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, type: PropertyType)

Database property/column with a name and a certain property type for defining a Notion database schema.

This is implemented as a descriptor.

attr_name: str property

name: str property writable

type: PropertyType property writable

__repr__() -> str

__set_name__(owner: type[PageSchema], name: str)

PropertyType(*args, **kwargs)

Base class for Notion property objects.

Property types define the value types of properties 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

id: str | None property

Return identifier of this property type.

name: str | None property

Return name of this property type.

obj_ref: T = obj_api_type.build(*args, **kwargs) instance-attribute

Reference to the low-level object representation of this property type

prop_ref: Property | None = None class-attribute instance-attribute

Back reference to the property having this type

prop_value: type[PropertyValue] property

Return the corresponding property value of this property type.

readonly: bool property

Return if this property type is read-only.

__eq__(other: object) -> bool

__hash__() -> int

__repr__() -> str

__str__() -> str

ReadOnlyPropertyError(prop: Property)

Raised when an attempt is made to write to a write-protected property.

prop = prop instance-attribute

Relation(schema: type[PageSchema] | None = None, *, two_way_prop: Property | 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.

schema: type[PageSchema] | None property

Schema of the relation database.

two_way_prop: Property | None property

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

RelationError(message)

Error if a Relation cannot be initialised.

Rollup(relation: Property, property: Property, calculate: AggFunc)

Defines the rollup property in a database.

RollupError(message)

Error if definition of rollup is wrong.

SchemaError(message)

Raised when there are issues with the schema of a database.

SchemaNotBoundError(schema: type[PageSchema])

Raised when the schema is not bound to a database.

schema = schema instance-attribute

Select(options: list[Option] | type[OptionNS])

Defines a select property in a database.

options: dict[str, Option] property

SelfRef

Target schema for self-referencing database relations.

Status(*args, **kwargs)

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

allowed_at_creation = False class-attribute instance-attribute

groups: list[OptionGroup] property

options: list[Option] property

Text(*args, **kwargs)

Defines a text property in a database.

Title(*args, **kwargs)

Defines the mandatory title property in a database.

URL(*args, **kwargs)

Defines a URL property in a database.

Verification(*args, **kwargs)

Defines a unique ID property in a database.

allowed_at_creation = False class-attribute instance-attribute