Skip to content

Reference

ultimate_notion

Ultimate Notion provides a pythonic, high-level API for Notion.

Notion-API: https://developers.notion.com/reference/intro

__all__ = ['AggFunc', 'BGColor', 'CodeLang', 'ColType', 'Color', 'Column', 'Database', 'Emoji', 'File', 'NumberFormat', 'Option', 'OptionNS', 'Page', 'PageSchema', 'RichText', 'SelfRef', 'Session', 'User', 'VState', '__version__'] module-attribute

__version__ = version('ultimate-notion') module-attribute

AggFunc

Aggregation functions for formulas.

AVERAGE = 'average' class-attribute instance-attribute

CHECKED = 'checked' class-attribute instance-attribute

COUNT = 'count' class-attribute instance-attribute

COUNT_PER_GROUP = 'count_per_group' class-attribute instance-attribute

COUNT_VALUES = 'count_values' class-attribute instance-attribute

DATE_RANGE = 'date_range' class-attribute instance-attribute

EARLIEST_DATE = 'earliest_date' class-attribute instance-attribute

EMPTY = 'empty' class-attribute instance-attribute

LATEST_DATE = 'latest_date' class-attribute instance-attribute

MAX = 'max' class-attribute instance-attribute

MEDIAN = 'median' class-attribute instance-attribute

MIN = 'min' class-attribute instance-attribute

NOT_EMPTY = 'not_empty' class-attribute instance-attribute

PERCENT_CHECKED = 'percent_checked' class-attribute instance-attribute

PERCENT_EMPTY = 'percent_empty' class-attribute instance-attribute

PERCENT_NOT_EMPTY = 'percent_not_empty' class-attribute instance-attribute

PERCENT_PER_GROUP = 'percent_per_group' class-attribute instance-attribute

RANGE = 'range' class-attribute instance-attribute

SHOW_ORIGINAL = 'show_original' class-attribute instance-attribute

SHOW_UNIQUE = 'show_unique' class-attribute instance-attribute

SUM = 'sum' class-attribute instance-attribute

UNCHECKED = 'unchecked' class-attribute instance-attribute

UNIQUE = 'unique' class-attribute instance-attribute

BGColor

Background colors for most textual blocks, e.g. paragraphs, callouts, etc.

BLUE = 'blue_background' class-attribute instance-attribute

BROWN = 'brown_background' class-attribute instance-attribute

DEFAULT = 'default' class-attribute instance-attribute

GRAY = 'gray_background' class-attribute instance-attribute

GREEN = 'green_background' class-attribute instance-attribute

ORANGE = 'orange_background' class-attribute instance-attribute

PINK = 'pink_background' class-attribute instance-attribute

PURPLE = 'purple_background' class-attribute instance-attribute

RED = 'red_background' class-attribute instance-attribute

YELLOW = 'yellow_background' class-attribute instance-attribute

CodeLang

Coding languages for code blocks.

ABAP = 'abap' class-attribute instance-attribute

ARDUINO = 'arduino' class-attribute instance-attribute

BASH = 'bash' class-attribute instance-attribute

BASIC = 'basic' class-attribute instance-attribute

C = 'c' class-attribute instance-attribute

CLOJURE = 'clojure' class-attribute instance-attribute

COFFEESCRIPT = 'coffeescript' class-attribute instance-attribute

CPP = 'c++' class-attribute instance-attribute

CSHARP = 'c#' class-attribute instance-attribute

CSS = 'css' class-attribute instance-attribute

DART = 'dart' class-attribute instance-attribute

DIFF = 'diff' class-attribute instance-attribute

DOCKER = 'docker' class-attribute instance-attribute

ELIXIR = 'elixir' class-attribute instance-attribute

ELM = 'elm' class-attribute instance-attribute

ERLANG = 'erlang' class-attribute instance-attribute

FLOW = 'flow' class-attribute instance-attribute

FORTRAN = 'fortran' class-attribute instance-attribute

FSHARP = 'f#' class-attribute instance-attribute

GHERKIN = 'gherkin' class-attribute instance-attribute

GLSL = 'glsl' class-attribute instance-attribute

GO = 'go' class-attribute instance-attribute

GRAPHQL = 'graphql' class-attribute instance-attribute

GROOVY = 'groovy' class-attribute instance-attribute

HASKELL = 'haskell' class-attribute instance-attribute

HTML = 'html' class-attribute instance-attribute

JAVA = 'java' class-attribute instance-attribute

JAVASCRIPT = 'javascript' class-attribute instance-attribute

JSON = 'json' class-attribute instance-attribute

JULIA = 'julia' class-attribute instance-attribute

KOTLIN = 'kotlin' class-attribute instance-attribute

LATEX = 'latex' class-attribute instance-attribute

LESS = 'less' class-attribute instance-attribute

LISP = 'lisp' class-attribute instance-attribute

LIVESCRIPT = 'livescript' class-attribute instance-attribute

LUA = 'lua' class-attribute instance-attribute

MAKEFILE = 'makefile' class-attribute instance-attribute

MARKDOWN = 'markdown' class-attribute instance-attribute

MARKUP = 'markup' class-attribute instance-attribute

MATLAB = 'matlab' class-attribute instance-attribute

MERMAID = 'mermaid' class-attribute instance-attribute

MISC = 'java/c/c++/c#' class-attribute instance-attribute

NIX = 'nix' class-attribute instance-attribute

OBJECTIVE_C = 'objective-c' class-attribute instance-attribute

OCAML = 'ocaml' class-attribute instance-attribute

PASCAL = 'pascal' class-attribute instance-attribute

PERL = 'perl' class-attribute instance-attribute

PHP = 'php' class-attribute instance-attribute

PLAIN_TEXT = 'plain text' class-attribute instance-attribute

POWERSHELL = 'powershell' class-attribute instance-attribute

PROLOG = 'prolog' class-attribute instance-attribute

PROTOBUF = 'protobuf' class-attribute instance-attribute

PYTHON = 'python' class-attribute instance-attribute

R = 'r' class-attribute instance-attribute

REASON = 'reason' class-attribute instance-attribute

RUBY = 'ruby' class-attribute instance-attribute

RUST = 'rust' class-attribute instance-attribute

SASS = 'sass' class-attribute instance-attribute

SCALA = 'scala' class-attribute instance-attribute

SCHEME = 'scheme' class-attribute instance-attribute

SCSS = 'scss' class-attribute instance-attribute

SHELL = 'shell' class-attribute instance-attribute

SQL = 'sql' class-attribute instance-attribute

SWIFT = 'swift' class-attribute instance-attribute

TYPESCRIPT = 'typescript' class-attribute instance-attribute

VB_NET = 'vb.net' class-attribute instance-attribute

VERILOG = 'verilog' class-attribute instance-attribute

VHDL = 'vhdl' class-attribute instance-attribute

VISUAL_BASIC = 'visual basic' class-attribute instance-attribute

WEBASSEMBLY = 'webassembly' class-attribute instance-attribute

XML = 'xml' class-attribute instance-attribute

YAML = 'yaml' class-attribute instance-attribute

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

Color

Basic colors

BLUE = 'blue' class-attribute instance-attribute

BROWN = 'brown' class-attribute instance-attribute

DEFAULT = 'default' class-attribute instance-attribute

GRAY = 'gray' class-attribute instance-attribute

GREEN = 'green' class-attribute instance-attribute

ORANGE = 'orange' class-attribute instance-attribute

PINK = 'pink' class-attribute instance-attribute

PURPLE = 'purple' class-attribute instance-attribute

RED = 'red' class-attribute instance-attribute

YELLOW = 'yellow' class-attribute instance-attribute

Column(name: str, type: PropertyType)

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)

Database(*args: Any, **kwargs: Any)

A Notion database.

This object always represents an original database, not a linked database.

API reference: https://developers.notion.com/docs/working-with-databases

block_url: str property

URL of this database.

cover: File | None property

Return the cover of this database as file.

description: RichText property writable

Return the description of this database as rich text.

icon: File | Emoji | None property

Return the icon of this database as file or emoji.

is_empty: bool property

Is this database empty?

is_inline: bool property

Is this database an inline database?

is_wiki: bool property

Is this database a wiki database.

schema: type[PageSchema] property writable

Schema of the database.

title: RichText property writable

Return the title of this database as rich text.

url: str property

Return the URL of this database.

__bool__() -> bool

Overwrite default behaviour.

__len__() -> int

Return the number of pages in this database.

__repr__() -> str

__str__()

create_page(**kwargs) -> Page

Create a page with properties according to the schema within the corresponding database.

delete() -> Database

Delete/archive this database.

fetch_all() -> View

Fetch all pages and return a view.

query()

Query a (large) database for pages in a more specific way.

reload() -> Database

Reload this database.

restore() -> Database

Restore/unarchive this database.

Emoji(emoji: str)

Emoji object which behaves like str.

obj_ref = objs.EmojiObject.build(emoji) instance-attribute

__eq__(other: object) -> bool

__hash__()

__repr__() -> str

__str__() -> str

from_code(shortcode: str) -> Emoji classmethod

Create an Emoji object from a :shortcode:, e.g. 😄

to_code() -> str

Represent the emoji as :shortcode:, e.g. 😄

File(*, url: str, name: str | None = None)

A web resource e.g. for the files property.

name: str | None property

obj_ref: objs.FileObject = objs.ExternalFile.build(url=url, name=name) instance-attribute

url: str property

__eq__(other: object) -> bool

__hash__()

__repr__() -> str

__str__() -> str

wrap_obj_ref(obj_ref: objs.FileObject) -> File classmethod

NumberFormat

Number formats for numbers.

ARGENTINE_PESO = 'argentine_peso' class-attribute instance-attribute

BAHT = 'baht' class-attribute instance-attribute

CANADIAN_DOLLAR = 'canadian_dollar' class-attribute instance-attribute

CHILEAN_PESO = 'chilean_peso' class-attribute instance-attribute

COLOMBIAN_PESO = 'colombian_peso' class-attribute instance-attribute

DANISH_KRONE = 'danish_krone' class-attribute instance-attribute

DIRHAM = 'dirham' class-attribute instance-attribute

DOLLAR = 'dollar' class-attribute instance-attribute

EURO = 'euro' class-attribute instance-attribute

FORINT = 'forint' class-attribute instance-attribute

FRANC = 'franc' class-attribute instance-attribute

HONG_KONG_DOLLAR = 'hong_kong_dollar' class-attribute instance-attribute

KORUNA = 'koruna' class-attribute instance-attribute

KRONA = 'krona' class-attribute instance-attribute

LEU = 'leu' class-attribute instance-attribute

LIRA = 'lira' class-attribute instance-attribute

MEXICAN_PESO = 'mexican_peso' class-attribute instance-attribute

NEW_TAIWAN_DOLLAR = 'new_taiwan_dollar' class-attribute instance-attribute

NEW_ZEALAND_DOLLAR = 'new_zealand_dollar' class-attribute instance-attribute

NORWEGIAN_KRONE = 'norwegian_krone' class-attribute instance-attribute

NUMBER = 'number' class-attribute instance-attribute

NUMBER_WITH_COMMAS = 'number_with_commas' class-attribute instance-attribute

PERCENT = 'percent' class-attribute instance-attribute

PHILIPPINE_PESO = 'philippine_peso' class-attribute instance-attribute

POUND = 'pound' class-attribute instance-attribute

RAND = 'rand' class-attribute instance-attribute

REAL = 'real' class-attribute instance-attribute

RINGGIT = 'ringgit' class-attribute instance-attribute

RIYAL = 'riyal' class-attribute instance-attribute

RUBLE = 'ruble' class-attribute instance-attribute

RUPEE = 'rupee' class-attribute instance-attribute

RUPIAH = 'rupiah' class-attribute instance-attribute

SHEKEL = 'shekel' class-attribute instance-attribute

URUGUAYAN_PESO = 'uruguayan_peso' class-attribute instance-attribute

WON = 'won' class-attribute instance-attribute

YEN = 'yen' class-attribute instance-attribute

YUAN = 'yuan' class-attribute instance-attribute

ZLOTY = 'zloty' class-attribute instance-attribute

Option(name: str, *, color: Color = Color.DEFAULT)

Option for select & multi-select property.

id: str property

ID of the option.

name: str property

Name of the option.

__eq__(other: object) -> bool

__hash__() -> int

__repr__() -> str

__str__() -> str

description() -> str

Description of the option.

OptionNS

Option namespace to simplify working with (Multi-)Select options.

to_list() -> list[Option] classmethod

Convert the enum to a list as needed by the (Multi)Select column types.

Page(*args: Any, **kwargs: Any)

A Notion page.

Attributes:

Name Type Description
props PageProperties

accessor for all page properties

children: list[Page | Database] property

Return all contained databases and pages within this page

content: list[Block] property

Return the content of this page, i.e. all blocks belonging to this page

cover: File | None property writable

Cover of the page.

database: Database | None property

If this page is located in a database return the database or None otherwise.

icon: File | Emoji | None property writable

Icon of the page, i.e. emojis, Notion's icons, or custom images.

props: PageProperties instance-attribute

title: RichText property writable

Title of the page.

url: str property

Return the URL of this database.

__repr__() -> str

__str__() -> str

delete() -> Page

Delete/archive this page.

reload() -> Page

Reload this page.

restore() -> Page

Restore/unarchive this page.

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

Show the content of the page, rendered in Jupyter Lab

to_html(*, raw: bool = False) -> str

Return the content of the page as HTML.

to_markdown() -> str

Return the content of the page as Markdown.

wrap_obj_ref(obj_ref: obj_blocks.Page) -> Page classmethod

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.

RichText(plain_text: str)

User-facing class holding several RichTexts.

obj_ref: list[objs.RichTextObject] property

__eq__(other: object) -> bool

__hash__()

from_markdown(text: str) -> RichText classmethod

Create RichTextList by parsing the markdown.

from_plain_text(text: str) -> RichText classmethod

Create RichTextList from plain text.

This method is a more explicit alias for the default constructor.

to_markdown() -> str

Convert the list of RichText objects to markdown.

to_plain_text() -> str

Return rich text as plaintext

This method is a more explicit variant then just using the object.

wrap_obj_ref(obj_refs: list[objs.RichTextObject] | None) -> RichText classmethod

SelfRef

Target schema for self-referencing database relations.

Session(cfg: Config | None = None, **kwargs: Any)

A session for the Notion API.

The session keeps tracks of all objects, e.g. pages, databases, etc. in an object store to avoid unnecessary calls to the API.

Parameters:

Name Type Description Default
cfg Config | None

configuration object

None
**kwargs Any

Arguments for the [Notion SDK Client][https://ramnes.github.io/notion-sdk-py/reference/client/]

{}

api: NotionAPI = NotionAPI(self.client) instance-attribute

cache: dict[UUID, DataObject | User] = {} class-attribute

client: notion_client.Client = notion_client.Client(auth=auth, **kwargs) instance-attribute

__enter__() -> Session

__exit__(exc_type: type[BaseException], exc_value: BaseException, traceback: TracebackType) -> None

all_users() -> list[User]

Retrieve all users of this workspace.

close()

Close the session and release resources.

create_db(parent: Page, schema: type[PageSchema] | None = None) -> Database

Create a new database within a page.

Implementation:

1. initialize external forward relations, i.e. relations pointing to other databases
2. create the database using a Notion API call and potential external forward relations
3. initialize self-referencing forward relations
4. create columns with self-referencing forward relations using an update call
5. update the backward references, i.e. two-way relations, using an update call

create_dbs(parents: Page | list[Page], schemas: list[type[PageSchema]]) -> list[Database]

Create new databases in the right order in case there a relations between them.

create_page(parent: Page, title: RichText | str | None = None) -> Page

Create a new page in a parent page.

get_active() -> Session classmethod

Return the current active session or None.

get_db(db_ref: ObjRef, *, use_cache: bool = True) -> Database

Retrieve Notion database by uuid

get_or_create(*args, **kwargs) -> Session classmethod

Return the current active session or create a new session.

get_or_create_db(parent: Page, schema: type[PageSchema]) -> Database

Get or create the database.

get_page(page_ref: ObjRef, *, use_cache: bool = True) -> Page

Retrieve a page by uuid.

get_user(user_ref: ObjRef, *, use_cache: bool = True) -> User

Get a user by uuid.

is_closed() -> bool

Determine if the session is closed or not.

raise_for_status()

Confirm that the session is active and raise otherwise.

Raises SessionError if there is a problem, otherwise returns None.

search_db(db_name: str | None = None, *, exact: bool = True, reverse: bool = False, deleted: bool = False) -> SList[Database]

Search a database by name or return all if db_name is None.

Parameters:

Name Type Description Default
db_name str | None

name/title of the database, return all if None

None
exact bool

perform an exact search, not only a substring match

True
reverse bool

search in the reverse order, i.e. the least recently edited results first

False
deleted bool

include deleted databases in search

False

search_page(title: str | None = None, *, exact: bool = True, reverse: bool = False, deleted: bool = False) -> SList[Page]

Search a page by name.

Parameters:

Name Type Description Default
title str | None

title of the page, return all if None

None
exact bool

perform an exact search, not only a substring match

True
reverse bool

search in the reverse order, i.e. the least recently edited results first

False
deleted bool

include deleted pages in search

False

search_user(name: str) -> SList[User]

Search a user by name.

whoami() -> User

Return the user object of this bot.

User(*args: Any, **kwargs: Any)

avatar_url property

email: str | None property

id property

is_bot: bool property

is_person: bool property

name property

__eq__(other: object) -> bool

__hash__() -> int

__repr__() -> str

__str__()

wrap_obj_ref(obj_ref: objs.User) -> User classmethod

VState

Verification states for pages in wiki databases.

UNVERIFIED = 'unverified' class-attribute instance-attribute

VERIFIED = 'verified' class-attribute instance-attribute