Reference
ultimate_notion
¶
Ultimate Notion provides a pythonic, high-level API for Notion.
Notion-API: https://developers.notion.com/reference/intro
DateTimeOrRange: TypeAlias = dt.datetime | dt.date | pnd.Interval[pnd.DateTime] | pnd.Interval[pnd.Date]
module-attribute
¶
A type alias for various date, date time and interval representations.
Workspace: Final = _Workspace.ROOT
module-attribute
¶
This represents the actual root workspace in Notion.
WorkspaceType: TypeAlias = Literal[_Workspace.ROOT]
module-attribute
¶
This represents the type of the root workspace in Notion for type hinting.
__all__ = ['PDF', 'AggFunc', 'AnyFile', 'BGColor', 'Block', 'Bookmark', 'Breadcrumb', 'BulletedItem', 'Callout', 'Code', 'CodeLang', 'Color', 'Column', 'Columns', 'Condition', 'Database', 'DateTimeOrRange', 'Divider', 'Embed', 'Emoji', 'Equation', 'ExternalFile', 'File', 'FileUploadStatus', 'Heading1', 'Heading2', 'Heading3', 'Image', 'LinkPreview', 'LinkToPage', 'NotionFile', 'NumberFormat', 'NumberedItem', 'Option', 'OptionGroup', 'OptionGroupType', 'OptionNS', 'Page', 'Paragraph', 'PropType', 'Property', 'Quote', 'SList', 'Schema', 'SelfRef', 'Session', 'SyncedBlock', 'Table', 'TableOfContents', 'TableRow', 'ToDoItem', 'ToggleItem', 'User', 'VState', 'Video', 'Workspace', 'WorkspaceType', '__version__', 'get_active_session', 'join', 'math', 'mention', 'prop', 'text', 'url']
module-attribute
¶
__version__ = version('ultimate-notion')
module-attribute
¶
AggFunc
¶
Aggregation functions for formulas.
The categories naming corresonds mostly to the naming in the Notion App but also eliminates some inconsistencies. The first part of the tuple is the string used in the Notion API, the second part is an alias corresoinding to the defined category num.
AVERAGE = ('average', 'average')
class-attribute
instance-attribute
¶
COUNT_ALL = ('count', 'count_all')
class-attribute
instance-attribute
¶
COUNT_CHECKED = ('checked', 'count_checked')
class-attribute
instance-attribute
¶
COUNT_EMPTY = ('empty', 'count_empty')
class-attribute
instance-attribute
¶
COUNT_NOT_EMPTY = ('not_empty', 'count_not_empty')
class-attribute
instance-attribute
¶
COUNT_PER_GROUP = ('count_per_group', 'count_per_group')
class-attribute
instance-attribute
¶
COUNT_UNCHECKED = ('unchecked', 'count_unchecked')
class-attribute
instance-attribute
¶
COUNT_UNIQUE_VALUES = ('unique', 'count_unique_values')
class-attribute
instance-attribute
¶
COUNT_VALUES = ('count_values', 'count_values')
class-attribute
instance-attribute
¶
DATE_RANGE = ('date_range', 'date_range')
class-attribute
instance-attribute
¶
EARLIEST_DATE = ('earliest_date', 'earliest_date')
class-attribute
instance-attribute
¶
LATEST_DATE = ('latest_date', 'latest_date')
class-attribute
instance-attribute
¶
MAX = ('max', 'max')
class-attribute
instance-attribute
¶
MEDIAN = ('median', 'median')
class-attribute
instance-attribute
¶
MIN = ('min', 'min')
class-attribute
instance-attribute
¶
PERCENT_CHECKED = ('percent_checked', 'percent_checked')
class-attribute
instance-attribute
¶
PERCENT_EMPTY = ('percent_empty', 'percent_empty')
class-attribute
instance-attribute
¶
PERCENT_NOT_EMPTY = ('percent_not_empty', 'percent_not_empty')
class-attribute
instance-attribute
¶
PERCENT_PER_GROUP = ('percent_per_group', 'percent_per_group')
class-attribute
instance-attribute
¶
RANGE = ('range', 'range')
class-attribute
instance-attribute
¶
SHOW_ORIGINAL = ('show_original', 'show_original')
class-attribute
instance-attribute
¶
SHOW_UNIQUE = ('show_unique', 'show_unique')
class-attribute
instance-attribute
¶
SUM = ('sum', 'sum')
class-attribute
instance-attribute
¶
alias: str
instance-attribute
¶
__new__(value: str, alias: str = '') -> AggFunc
¶
from_alias(alias: str) -> AggFunc
classmethod
¶
AnyFile(*args: Any, **kwargs: Any)
¶
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
¶
Block(*args: Any, **kwargs: Any)
¶
Abstract Notion block.
Parent class of all block types.
discussions: tuple[Discussion, ...]
property
¶
Return comments of this block as list of discussions, i.e. threads of comments.
__eq__(other: object) -> bool
¶
__hash__() -> int
¶
insert_after(blocks: Block | Sequence[Block]) -> None
¶
Insert a block or several blocks after this block.
reload() -> Self
¶
Reload the block from the API.
replace(blocks: Block | Sequence[Block]) -> None
¶
Replace this block with another block or blocks.
Bookmark(url: str, *, caption: str | None = None)
¶
BulletedItem(text: str, *, color: Color | BGColor = Color.DEFAULT)
¶
Bulleted list item.
to_markdown() -> str
¶
Callout(text: str, *, color: Color | BGColor = Color.DEFAULT, icon: AnyFile | Emoji | CustomEmoji | None = None)
¶
Callout block.
Note
The default icon is an electric light bulb, i.e. 💡 in case None
is passed as icon. It is not possible to remove the icon, but you can change it to a different emoji or a file.
Code(text: str, *, language: str | CodeLang = CodeLang.PLAIN_TEXT, caption: str | None = None)
¶
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
¶
TOML = 'toml'
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
¶
Color
¶
Basic colors
DEFAULT is a light gray, which is the default color in the Notion App.
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()
¶
Columns(columns: int | Sequence[float | int])
¶
Columns block holding multiple Column
blocks.
This block is used to create a layout with multiple columns in a single page. Either specify the number of columns as an integer or provide a sequence of width ratios, which can be positive integers or floats.
width_ratios: tuple[float | None, ...]
property
writable
¶
Return the width ratios of the columns.
__getitem__(index: int) -> Column
¶
add_column(index: int | None = None) -> Self
¶
Add a new column to this block of columns at the given index.
The index must be between 0 and the number of columns (inclusive). If no index is given, the new column is added at the end.
To specify the width ratio of the new column, use the width_ratios
property.
append(blocks: Block | Sequence[Block], *, after: Block | None = None, sync: bool | None = None) -> Self
¶
Append a block or a sequence of blocks to the content of this block.
to_markdown() -> str
¶
Return the content of all columns as Markdown.
Condition
¶
Base class for filter query conditions.
is_method: bool = False
class-attribute
instance-attribute
¶
__and__(other: Condition) -> Condition
¶
__iand__(other: Condition) -> Condition
¶
__ior__(other: Condition) -> Condition
¶
__or__(other: Condition) -> Condition
¶
__repr__() -> str
abstractmethod
¶
__str__() -> str
¶
create_obj_ref(db: Database) -> obj_query.QueryFilter
abstractmethod
¶
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
cover: AnyFile | None
property
¶
Return the cover of this database as file.
description: Text | None
property
writable
¶
Return the description of this database as rich text.
icon: AnyFile | Emoji | CustomEmoji | None
property
¶
Return the icon of this database as file or emoji.
is_db: bool
property
¶
Return whether the object is a database.
is_empty: bool
property
¶
Return whether the database is empty.
is_inline: bool
property
writable
¶
Return whether the database is inline.
is_wiki: bool
property
¶
Return whether the database is a wiki.
query: Query
property
¶
Return a Query object to build and execute a database query.
schema: type[Schema]
property
writable
¶
Schema of the database.
title: str | Text | None
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__() -> str
¶
create_page(**kwargs: Any) -> Page
¶
Create a page with properties according to the schema within the corresponding database.
delete() -> Self
¶
Delete this database.
get_all_pages() -> View
¶
Retrieve all pages and return a view.
reload() -> Self
¶
Reload this database.
restore() -> Self
¶
Restore this database.
to_markdown() -> str
¶
Return the reference to this database as Markdown.
Embed(url: str, *, caption: str | None = None)
¶
Emoji(emoji: str)
¶
Equation(latex: str)
¶
ExternalFile(*, url: str, name: str | None = None, caption: str | None = None)
¶
File(file: AnyFile, *, name: str | None = None, caption: str | None = None)
¶
File block.
Note
Only the caption and name can be modified, the file object is read-only. Note that only the file name not the file suffix can be modified, the suffix is determined initially by the url.
FileUploadStatus
¶
Heading1(text: str, *, color: Color | BGColor = Color.DEFAULT, toggleable: bool = False)
¶
Heading 1 block.
to_markdown() -> str
¶
Heading2(text: str, *, color: Color | BGColor = Color.DEFAULT, toggleable: bool = False)
¶
Heading 2 block.
to_markdown() -> str
¶
Heading3(text: str, *, color: Color | BGColor = Color.DEFAULT, toggleable: bool = False)
¶
Heading 3 block.
to_markdown() -> str
¶
Image(file: AnyFile, *, caption: str | None = None)
¶
Image block.
Note
Only the caption can be modified, the URL is read-only.
to_markdown() -> str
¶
Return the image as Markdown.
LinkPreview(url: str)
¶
LinkToPage(page: Page)
¶
NotionFile(*, url: str, name: str | None = None, caption: str | None = None)
¶
NumberFormat
¶
Number formats for numbers.
ARGENTINE_PESO = 'argentine_peso'
class-attribute
instance-attribute
¶
AUSTRALIAN_DOLLAR = 'australian_dollar'
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
¶
NumberedItem(text: str, *, color: Color | BGColor = Color.DEFAULT)
¶
Numbered list item.
to_markdown() -> str
¶
Option(name: str, *, color: Color | str | UnsetType = Unset)
¶
Option for select & multi-select property.
OptionGroup(group_type: OptionGroupType | str, options: list[Option])
¶
Group of options for status property.
name: str
property
¶
Name of the option group.
options: list[Option]
property
¶
Options within this option group.
__eq__(other: object) -> bool
¶
__hash__() -> int
¶
__repr__() -> str
¶
__str__() -> str
¶
wrap_obj_ref(obj_ref: objs.SelectGroup, /, *, options: list[Option] | None = None) -> OptionGroup
classmethod
¶
Convienence constructor for the group of options.
OptionGroupType
¶
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 property types.
PDF(file: AnyFile, *, caption: str | None = None)
¶
PDF block.
Note
Only the caption can be modified, the URL is read-only.
to_markdown() -> str
¶
Return the PDF as Markdown.
Page(*args: Any, **kwargs: Any)
¶
A Notion page.
Attributes:
Name | Type | Description |
---|---|---|
props | PagePropertiesNS | accessor for all page properties |
comments: Discussion
property
¶
Return the discussion thread of this page.
A page can only have a single discussion thread in contrast to inline comments.
Note
This functionality requires that your integration was granted read comment capabilities.
cover: ExternalFile | NotionFile | None
property
writable
¶
Cover of the page.
icon: NotionFile | ExternalFile | Emoji | CustomEmoji | None
property
writable
¶
Icon of the page, i.e. emojis, Notion's icons, or custom images.
in_db: bool
property
¶
Return True if this page is located in a database.
is_page: bool
property
¶
Return whether the object is a page.
parent_db: Database | None
property
¶
If this page is located in a database return the database or None otherwise.
This is a convenience method to avoid the need to check and cast the type of the parent.
props: PagePropertiesNS
instance-attribute
¶
public_url: str | None
property
¶
Return the public URL of this database.
subdbs: list[Database]
property
¶
Return all contained databases within this page
subpages: list[Page]
property
¶
Return all contained pages within this page
title: Text | None
property
writable
¶
Title of the page.
url: str
property
¶
Return the URL of this page.
__repr__() -> str
¶
__str__() -> str
¶
delete() -> Self
¶
Delete this page.
Warning
Deleting a page will also delete all child pages and child databases recursively. If these objects are already cached in the session, they will not be updated. Use session.cache.clear()
to clear the cache or call reload()
on them.
get_property(prop_name: str) -> Any
¶
Directly retrieve the property value from the API.
Use this method only if you want to retrieve a specific property value that might have been updated on the server side without reloading the whole page. In all other cases, use the props
namespace of the page to avoid unnecessary API calls.
reload() -> Self
¶
Reload this page.
restore() -> Self
¶
Restore this page.
show(*, simple: bool | None = None) -> None
¶
Show the content of the page, rendered in JupyterLab
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.
Note
This will not include nested blocks, i.e. the children of top-level blocks.
wrap_obj_ref(obj_ref: obj_blocks.Page) -> Self
classmethod
¶
Paragraph(text: str, *, color: Color | BGColor = Color.DEFAULT)
¶
Paragraph block.
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.
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.
SelfRef
¶
Target schema for self-referencing database relations.
_ = Title('title')
class-attribute
instance-attribute
¶
Session(cfg: Config | None = None, *, client: notion_client.Client | 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 | {} |
api: NotionAPI = NotionAPI(self.client)
instance-attribute
¶
cache: dict[UUID, DataObject | User] = {}
class-attribute
¶
client: notion_client.Client = create_notion_client(cfg, **kwargs) if client is None else client
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() -> None
¶
Close the session and release resources.
create_db(parent: Page, *, schema: type[Schema] | None = None, title: str | None = None, inline: bool = False) -> Database
¶
Create a new database within a page.
In case a title and a schema ware provided, title overrides the schema's db_title
attribute if it exists.
create_dbs(parents: Page | list[Page], schemas: list[type[Schema]]) -> list[Database]
¶
Create new databases in the right order in case there a relations between them.
create_page(parent: Page | Database, title: Text | str | None = None, blocks: list[Block] | None = None) -> Page
¶
Create a new page in a parent
page or database with a given title
.
The blocks
are optional and can be used to create a page with content right away. Note that some nested blocks may not be supported by the API and must be created separately, i.e. with an append
call to a given block.
get_active() -> Session
classmethod
¶
Return the current active session or None.
get_block(block_ref: UUID | str, *, use_cache: bool = True) -> Block
¶
Retrieve a single block by an object reference.
get_db(db_ref: UUID | str, *, use_cache: bool = True) -> Database
¶
Retrieve Notion database by uuid
get_or_create(*args: Any, **kwargs: Any) -> Session
classmethod
¶
Return the current active session or create a new session.
get_or_create_db(parent: Page, schema: type[Schema]) -> Database
¶
Get or create the database.
get_or_create_page(parent: Page | Database, title: str | None = None) -> Page
¶
Get an existing page or create a new one if it doesn't exist.
get_page(page_ref: UUID | str, *, use_cache: bool = True) -> Page
¶
Retrieve a page by uuid.
get_user(user_ref: UUID | str, *, use_cache: bool = True, raise_on_unknown: bool = True) -> User
¶
Get a user by uuid.
In case the user is not found and raise_on_unknown
is False
, an User
object is returned with the name Unknown User
, where the property is_unknown
is set to True
.
Warning
Trying to retrieve yourself, i.e. the bot integration, only works if use_cache
is true, since the low-level api, i.e. api.users.retrieve()
does not work for the bot integration. Better use whoami()
to get the bot integration user object.
import_url(url: str, file_name: str, *, block: bool = True) -> UploadedFile
¶
Import a file from a URL.
is_closed() -> bool
¶
Determine if the session is closed or not.
list_uploads(filter: FileUploadStatus | None = None) -> list[UploadedFile]
¶
List all uploaded files and optionally filter by status.
raise_for_status() -> None
¶
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) -> SList[Page]
¶
Search a page by name. Deleted pages, i.e. in trash, are not included in the search.
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 |
search_user(name: str) -> SList[User]
¶
Search a user by name.
upload(file: BinaryIO, *, file_name: str | None = None) -> UploadedFile
¶
Upload a file to Notion.
whoami() -> Bot
¶
Return the integration as bot object.
SyncedBlock(blocks: Block | Sequence[Block])
¶
Synced block - either original or synced.
is_original: bool
property
¶
Return if this block is the original block.
is_synced: bool
property
¶
Return if this block is synced from another block.
create_synced() -> SyncedBlock
¶
Return the synced block for appending.
get_original() -> SyncedBlock
¶
Return the original block.
to_markdown(*, with_comment: bool = True) -> str
¶
Return the content of this synced block as Markdown.
Table(n_rows: int, n_cols: int, *, header_col: bool = False, header_row: bool = False)
¶
Table block.
children: tuple[TableRow, ...]
property
¶
Return all rows of the table.
has_header_col: bool
property
writable
¶
Return whether the table has a header column.
has_header_row: bool
property
writable
¶
Return whether the table has a header row.
shape: tuple[int, int]
property
¶
Return the shape of the table.
width: int
property
¶
Return the width, i.e. number of columns, of the table.
__getitem__(index: int | tuple[int, int]) -> Text | TableRow | None
¶
__getitem__(index: int) -> TableRow
__getitem__(index: tuple[int, int]) -> Text | None
__setitem__(index: int | tuple[int, int], value: str | Sequence[str | None] | None) -> None
¶
__str__() -> str
¶
append_row(values: Sequence[str]) -> Self
¶
Append a new row to the table.
insert_row(index: int, values: Sequence[str]) -> Self
¶
Insert a new row at the given index.
to_markdown() -> str
¶
Return the table as Markdown.
TableOfContents(*, color: Color | BGColor = Color.DEFAULT)
¶
Table of Contents block.
to_markdown() -> str
¶
TableRow(*cells: str | None)
¶
ToDoItem(text: str, *, checked: bool = False, color: Color | BGColor = Color.DEFAULT)
¶
ToggleItem(text: str, *, color: Color | BGColor = Color.DEFAULT)
¶
Toggle list item.
to_markdown() -> str
¶
User(*args: Any, **kwargs: Any)
¶
User object for persons, bots and unknown users.
Unknown users are users, which no longer participate in the workspace or were revoked access. They are represented by their ID and have the name Unknown User
.
avatar_url: str | None
property
¶
Return the avatar URL of this user.
id: UUID
property
¶
Return the ID of this user.
is_bot: bool
property
¶
Return True if this user is a bot.
is_person: bool
property
¶
Return True if this user is a person.
is_unknown: bool
property
¶
Return True if this user is an unknown user.
name: str | None
property
¶
Return the name of this user.
__eq__(other: object) -> bool
¶
__hash__() -> int
¶
__repr__() -> str
¶
__str__() -> str
¶
VState
¶
Video(file: AnyFile, *, caption: str | None = None, name: str | None = None)
¶
Video block.
Note
Only the caption can be modified, the URL is read-only.
to_markdown() -> str
¶
Return the video as Markdown.
get_active_session() -> Session
¶
Return the current active session or raise an exception.
Avoids cyclic imports when used within the package itself. For internal use mostly.
join(texts: Sequence[str], *, delim: str = ' ') -> Text
¶
Join multiple str objects, including Text, into a single Text object with a given delimeter.
math(expression: str, *, bold: bool = False, italic: bool = False, strikethrough: bool = False, code: bool = False, underline: bool = False, color: Color = Color.DEFAULT) -> Text
¶
Create a Text that holds a formula.
mention(target: User | Page | Database | CustomEmoji | objs.DateTimeOrRange, *, bold: bool = False, italic: bool = False, strikethrough: bool = False, code: bool = False, underline: bool = False, color: Color = Color.DEFAULT) -> Text
¶
Create a Text that mentions another object.
prop(prop_name: str) -> PageProperty
¶
Create a property object.
text(text: str, *, bold: bool = False, italic: bool = False, strikethrough: bool = False, code: bool = False, underline: bool = False, color: Color | None = None, href: str | None = None) -> Text
¶
Create a rich text Text object from a normal string with formatting.
Warning
If a Text
object is passed, the original formatting will be lost!
url(url: str, *, name: str | None = None, caption: str | None = None) -> NotionFile | ExternalFile
¶
Create a NotionFile or ExternalFile based on the URL.
A name and caption can be provided and will be used as default values, e.g. in a File block.