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