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 column 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 Column 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 column in database.
ColType ¶
Namespace class of all columns types 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 ¶
Column(name: str, type: PropertyType) ¶
CreatedBy(*args, **kwargs) ¶
Defines the created-by column in a database.
CreatedTime(*args, **kwargs) ¶
Defines the created-time column in a database.
Date(*args, **kwargs) ¶
Defines a date column in a database.
DefaultSchema ¶
Email(*args, **kwargs) ¶
Defines an e-mail column in a database.
Files(*args, **kwargs) ¶
Defines a files column in a database.
Formula(expression: str) ¶
Defines a formula column in a database.
Currently the formula expression cannot reference other formula columns, e.g. prop("other formula") This is a limitation of the API.
ID(*args, **kwargs) ¶
LastEditedBy(*args, **kwargs) ¶
Defines the last-edited-by column in a database.
LastEditedTime(*args, **kwargs) ¶
Defines the last-edited-time column in a database.
MultiSelect(options: list[Option] | type[OptionNS]) ¶
Defines a multi-select column in a database.
options: dict[str, Option] property ¶
Number(number_format: NumberFormat) ¶
Defines a number column 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_col(col_name: str) -> Column classmethod ¶
Get a specific column from this schema assuming that column names are unique.
get_cols() -> list[Column] classmethod ¶
Get all columns of this schema.
get_db() -> Database classmethod ¶
Get the database that is bound to this schema.
get_title_col() -> Column classmethod ¶
Returns the column 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 column in a database.
PhoneNumber(*args, **kwargs) ¶
Defines a phone number column in a database.
PropertyType(*args, **kwargs) ¶
Base class for Notion property objects.
Property types define the value types of columns in a database, e.g. number, date, text, etc.
allowed_at_creation = True class-attribute instance-attribute ¶
col_ref: Column | None = None class-attribute instance-attribute ¶
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 ¶
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 ¶
ReadOnlyColumnError(col: Column) ¶
Raised when a read-only columns tries to be written to.
col = col instance-attribute ¶
Relation(schema: type[PageSchema] | None = None, *, two_way_col: Column | 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_col: Column | None property ¶
Return the target column object of a two-way relation.
RelationError(message) ¶
Error if a Relation cannot be initialised.
Rollup(relation: Column, property: Column, calculate: AggFunc) ¶
Defines the rollup column 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 column in a database.
options: dict[str, Option] property ¶
SelfRef ¶
Target schema for self-referencing database relations.
Status(*args, **kwargs) ¶
Defines a status column in a database.
The Notion API doesn't allow to create a column 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 column missing... ignorance is bliss.
Also the Status configuration is not mentioned as a [Property Schema Object])https://developers.notion.com/reference/property-schema-object).
Text(*args, **kwargs) ¶
Defines a text column in a database.
Title(*args, **kwargs) ¶
Defines the mandatory title column in a database.
URL(*args, **kwargs) ¶
Defines a URL column in a database.