Skip to content

Changelog

Unreleased

Version 0.10.1, 2026-06-28

  • Fix: Populate the high-level children cache when constructing Tabs or Columns directly, so an offline-built block exposes its tabs/columns (.tabs/.columns, has_children) and uploads its children instead of an empty container when pushed to Notion. Previously only the low-level obj_ref was filled, contradicting the documented offline build-then-push workflow, issue #424.

Version 0.10, 2026-06-27

  • New: Support tab blocks via the new Tabs block, which groups content into labeled tabs. Each tab is a Paragraph whose text is the tab label and whose children hold the tab content. Create tabs up front with Tabs([...labels]) or add them later with Tabs.add_tab(), issue #188.
  • New: Support icons on tab labels (and paragraphs): read or write a paragraph's icon via the new Paragraph.icon property (mirroring Page.icon), pass an optional icon to Tabs.add_tab(), and render it in Tabs.to_markdown(), issue #421.
  • New: Support the Heading4 block introduced by the Notion API (March 30, 2026 changelog), mirroring Heading1/Heading2/Heading3 and rendering as a level-5 markdown heading, issue #405.
  • New: Lock or unlock pages, data sources, and databases for editing via the writable Page.is_locked, DataSource.is_locked, and Database.is_locked properties, and move a data source to a different parent database with DataSource.move(). Enabled by the Notion API version 2025-09-03, issue #402.
  • New: Better logging of model validation errors, issue #152.

  • Breaking: Adopt the Notion API version 2025-09-03, which splits the former "database" into two concepts: a data source (holds the schema and pages) and a database (a container of one or more data sources), issue #118. This requires notion-client~=2.7.0 and renames much of the high-level API. To migrate:

    • The former Database class (schema + pages) is now DataSource. The name Database now refers to the new container; access its data sources via Database.data_sources.
    • Rename these calls: Session.search_db() → search_ds(), Session.create_db() → create_ds(), Session.get_or_create_db() → get_or_create_ds(), Schema.bind_db() → bind_ds(), and Page.parent_db → Page.parent_ds.
    • Session.get_db() still exists but now returns the new Database container; use Session.get_ds() to get what get_db() returned before (a single data source).
    • The db_title= and db_id= arguments on Schema subclasses are unchanged.

  • Fix: Capture the read-only block_type field Notion sends on unsupported blocks (e.g. button or AI blocks), which previously raised a pydantic ValidationError on dev/CI installs (extra='forbid') and made the whole children list — including sibling blocks after the unsupported one — inaccessible, issue #356.

Version 0.9.11, 2026-06-24

  • New: Export the user-facing icon subtypes BuiltInIcon and CustomEmoji from the top-level package, alongside the already-exported Emoji, so icons returned by Page.icon/DataSource.icon/Database.icon can be narrowed with isinstance without reaching into ultimate_notion.emoji, issue #353.
  • Fix: Skip the two-way relation backward rename in Relation._update_bwd_rel when no backward name is defined, instead of attempting RenameProp(name=None) and raising a pydantic ValidationError, issue #325.
  • Fix: Raise a clear UnsetError from Bot.workspace_info when the workspace name or id is unavailable (i.e. for any bot other than the integration's own), instead of an opaque pydantic ValidationError, issue #326.
  • Chg: Replace hasattr-based checks in obj_api.core with type-safe alternatives (a structural pattern match on UniqueObject in ObjectRef.build, a typed ClassVar sentinel for the UnsetType singleton, and a None-defaulted ClassVar sentinel for the TypedObject._typemap registry).
  • Chg: Replace the hasattr-based Property._is_init check with a None-defaulted sentinel for Wrapper._obj_ref, so initialization is an explicit is not None check that the type checker understands.
  • Chg: Make _Node generic in its wrapped type and pin children to list[_Node[Block]], encoding the invariant that only a root node wraps a Page while every child wraps a Block, so building child obj_refs no longer needs to launder the element type, issue #339.

Version 0.9.10, 2026-06-24

  • Fix: Split deeply-nested block trees reconstructed via Block.wrap_obj_ref() from serialized JSON into Notion-compliant requests on append(). Children carried in obj_ref.value.children (where has_children is False) were previously left untouched by the chunker and sent in a single over-nested request, which Notion rejected with a 400, issue #305.

Version 0.9.9, 2026-06-23

  • Fix: Accept Notion's built-in (icon gallery) icons, which use the icon sub-type with a name and color and previously broke loading any page/database (and cascaded into search/list endpoints) that used one, issue #295.
  • Fix: Omit the read-only is_archived field from nested block children when appending a block hierarchy, which previously leaked into the children and was rejected by the Notion API, issue #291.
  • Chg: Validate polymorphic TypedObject sub-types and user references on construction, and wrap any resulting Pydantic ValidationError with contextual information about the failing type, issue #152.
  • Fix: Accept the undocumented in_trash field the Notion API sends on file_upload objects, which previously broke every file upload in development mode, issue #299.

Version 0.9.8, 2026-06-22

  • Fix: Tolerate page/database objects that omit properties, which the search endpoint returns for stripped-down records (e.g. trashed or limited-access pages) and which previously broke search_page()/search_db(), issue #273.

Version 0.9.7, 2026-06-22

  • Fix: Add support for pydantic 2.13, which previously broke parsing of Notion user objects (e.g. people properties), issue #189.
  • Fix: Accept the new is_archived field the Notion API sends on pages and databases, which previously broke search_page()/search_db() in development mode, issue #202.
  • Fix: Accept the nullable icon field returned for paragraph blocks and omit read-only archive fields when creating blocks.

Version 0.9.6, 2025-11-23

  • New: Add the new Place database/source property.
  • Fix: Allow to bind a schema with a two-way target property to an existing database, issue #134.
  • Fix: session.get_page(PAGE) no longer fails if parent of Page is not accessible by the integration, issue #135.
  • Fix: Added BGColor type annotation for color parameter in text() and Text, issue #140.
  • Chg: Add cover and item parameters to PagesEndpoint.create() and Session.create_page(), issue #144.
  • New: Add method Page.update_props() to allow updating multiple properties of a page at once from the high level API.
  • Chg: Alter PagesEndpoint.update() method signature to include cover, item and in_trash parameters, issue #144.
  • Fix: Have a nicer CLI output in case of an exception.
  • Fix: Determing the correct mime type of a file, which is now done using mimetypes instead of filetypes, issue #141.
  • New: Add the new workspace_id field to the Bot.
  • Fix: Unify texts locally the same way as remote, which is necessary for comparison, issue #136 & #160.
  • Fix: Resolution of polymorphic TypedObject, which led to wrong schema inference, issue #134.
  • Fix: Resolution of user reference in mention object, issue #166.
  • Chg: Removed the low level UnknownUser object as it is just a UserRef, issue #166.
  • Fix: Uploading a file via an import URL was cast to a None instead of FileImportSuccess.
  • Chg: Return FileUploadStatus in UploadedFile.file_import_result for easier usage.
  • Fix: All objects are no longer hashable as they are mutable and thus the former behaviour was semantically incorrect.
  • Fix: Comparison of off-/online MentionObjects works, also when UserRef or an ObjectRef to a page is used, issue #170.
  • Fix: An Unset annotations (e.g. a mention built with style=None) now compares equal to the default Annotations returned by the Notion API, issue #174.

Version 0.9.5, 2025-10-24

  • Fix: Pin notion-sdk-py to version 2.5 as version 2.6 has breaking changes, issue #153.

Version 0.9.4, 2025-10-01

  • Chg: Allow the creation of a unique ID property, which is now supported by the Notion API.
  • New: Allow changing the prefix of a unique ID property.
  • Chg: The reload() method of a database has a rebind_schema property, which is activated by default.
  • Doc: Updated the Getting started docs to the current version of Notion.
  • Doc: Updated the Configuration docs.

Version 0.9.3, 2025-09-26

  • Fix: Map file type audio/x-wav to audio/wav and add a mime_type parameter to upload, issue #127.

Version 0.9.2, 2025-09-25

  • New: Add new is_locked property to show if a page is locked or not.
  • Fix: Pagination when appending block children no longer leads to repeated appendings.
  • Fix: Assembling a hierarchy of blocks offline and appending it will result in automatic batching adhering to the Notion API limits, issue #119, #120.
  • Fix: Appended blocks are now added to session cache.
  • New: Added support for the Notion audio block, issue #123.
  • New: Allow comparing offline blocks to the ones synchronized to Notion, issue #124.

Version 0.9.1, 2025-09-03

  • Fix: Add missing link mention object, which led to an exception.
  • Fix: Linked databases are handled as ChildDatabase objects and no longer resolved, issue #110.
  • Chg: Have a User hierarchy with Bot, Person, etc. to reflect the actual Notion API.
  • Doc: Completed missing parts in the documentation and example for file uploads.
  • New: Allow uploading and appending a file as block to a page via the CLI.
  • Fix: Fix user mention problem, which was caused by a Notion API change.

Version 0.9, 2025-09-01

First Beta release:

  • New: Allow updating if a database is inline or not, issue #80.
  • Chg: create_db has a title parameter to set a title if no schema is used or needs to be overwritten.
  • Chg: Removed from_dict class method of Schema since this can now be more easily done manually.
  • Chg: Unify Property and PropertyType to simplify declarative approach to schemas, issue #81.
  • Fix: Possible collision of attribute names in Page and Schema, issue #86.
  • Fix: Wrong equality check between properties as well as property values.
  • New: Bind a schema automatically with bind_schema() if db_id or db_title is set in the Schema.
  • Chg: Consistently return None for title, description, caption if these are not set instead of an empty string.
  • Fix: More strict typing and checks which led to many small bug fixes in edge cases, e.g. issue #96.
  • Fix: Too strict dependencies that too often lead to conflicts with other packages, e.g. issue #90.
  • New: uno command line interface to show the current resolved config and integration info.
  • New: Allow offline assembly of blocks to create a page with content in one call, issue #94.
  • Fix: Different blocks now have a different hash, equality works as expected, issue #100.
  • Fix: Retrieve a page object even without access access to the parent database, issue #103.
  • Chg: Renamed FileInfo to AnyFile and have several subtypes like UploadedFile, etc.
  • New: Added file_upload, import_url and list_uploads to support the file upload endpoints, issue #71.

Version 0.8, 2025-06-23

  • New: Added support for creating inline databases by Tzumx
  • Chg: Have a proper hierarchy of Ultimate Notion exception classes.
  • New: The schema of a database provides a to_pydantic_model class for evaluating input.
  • New: More schema validations like checking for a title property and distinct property names.
  • Fix: Fix error when setting a (multi-)select option with no color specified.
  • New: Added a button property value.
  • New: Added support for Polars, i.e. to_polars method of database views, issue #55.
  • New: Add support for custom emoji icons, issue #70.
  • Chg: Return None instead of an empty string "" when a text property or block is unset, issue #59.
  • New: Setting the width ratios of page columns is supported, issue #74.
  • Fix: Adding a column with add_column(index) at a given index is no longer off by 1.
  • Add: Updating a database schema, i.e. adding/removing properties or changing their types, issue #76.
  • Add: Changing database properties, e.g. name, formula of formula property, options, etc, issue #77.
  • Add: Added the display_name field of comments

Version 0.7.1, 2025-01-05

  • Fix: Added missing tomli dependency, issue #62.
  • Fix: Support button property of databases to fix error when retrieving a page or database, issue #63.

Version 0.7, 2024-12-10

  • New: Reading and inserting comments is implemented.
  • Chg: SList is part of the public API now, i.e. is in the ultimate_notion namespace.
  • Fix: Added missing link_to_page subtype comment_id.
  • Chg: Remove Text as direct import, use text instead.
  • Chg: .props namespace of a page now behaves like a mapping, i.e. read-only dictionary.
  • Fix: Added missing .value function of several PropertyValues.
  • Add: Page method get_property to allow fetching a single property without reloading the whole page.
  • Fix: Resolving page properties correctly if they contain more than 25 references.
  • Fix: PropertiesEndpoint.retrieve now actually works and either returns a single property item or a list.
  • Chg: Renamed db.fetch_all() to db.get_all_pages().
  • New: Query databases with a PySpark/Polars inspired DSL, e.g. uno.prop('Name') == 'Linus Torvalds', implemented.
  • Fix: Database pages created with db.create_page are now added to the session cache.
  • New: Easily activate a debug mode within the config file.
  • Fix: Rollup property defined on a self-referencing relation works now.
  • Doc: Added a page about querying a database.
  • Chg: Renamed property types People to Person and PhoneNumber to Phone.

Version 0.6, 2024-09-28

  • New: Also use the session cache for blocks.
  • New: Properties of blocks can be updated.
  • Fix: has_children doesn't return a wrong value anymore for pages and databases.
  • Fix: Several issues with blocks and duplicated but ID-equivalent objects.
  • Chg: Simplified dealing with rich texts by introducing text, mention and math.
  • Chg: Children of pages are proper pages/databases instead of ChildPage/ChildDatabase.
  • Chg: Renamed PageSchema to Schema.
  • Chg: Accessing the properties of a page directly returns the primitive data types.
  • Chg: Completely reworked the functionality of the Table block for more consistency and easier usage.

Version 0.5.1, 2024-08-09

  • Fix: Added type unknown in user data to generate UnknownUser, issue #39.

Version 0.5, 2024-08-07

  • New: Method page.append to append content to a page. Creation of blocks is supported!
  • New: Documentation on how to create the content of a page.
  • New: More robustness with respect to Notion API changes.
  • New: High-level method session.get_block to retrieve a single block.
  • Chg: Internally, archived property was renamed to in_trash.
  • Chg: Renamed .content to .children of a page for more consitency.
  • Chg: Use Property again to consistently refer to the columns of a database.
  • Chg: Make use of pendulum to represent DateRange values.
  • Chg: Renamed page.database to page.parent_db and page.in_db added as methods.
  • Chg: Large restructering of the code base.
  • Chg: Return None for various string attributes/properties if no string is set for consistency.

Version 0.4, 2024-02-14

  • New: Introduced a configuration file under ~/.ultimate-notion/config.toml.
  • New: Added a simple Google Tasks client.
  • New: Added a general sychronization task for Notion to other services.
  • New: Added a specific Google Tasks synchronization task.
  • Fix: A page property can be deleted by setting it to None.
  • Chg: Reworked the testing setup to use VCR.py more efficiently and be more robust.
  • Fix: Tons of fixes within blocks and general page content.
  • Chg: to_markdown() now uses an internal implementation instead of notion2md.

Version 0.3, 2023-12-26

  • Chg: RichText is now a subtype of str for a more convenient & consistent usage.
  • Doc: Added more documentation about using databases.
  • Chg: icon attribute of database now returns Emoji instead of str.
  • New: Allow setting the icon and cover attribute of a page.
  • New: Allow setting the title of a non-database page.
  • Fix: created_by and last_edited_by return proper User object.

Version 0.2, 2023-12-19

  • Fix: Notion API's undocumented description of SelectOption added.
  • New: Navigate pages using parent and children.
  • Chg: Rename parents to ancestors.
  • Fix: Wrong return value of PropertyType Status.value.
  • Chg: Make show consistent for Page, View, PageSchema.
  • Ref: Refactor value in PropertyValue.
  • Ref: Reduce unnecessary funtionality of Number, use value instead.

Version 0.1, 2023-12-16

  • First official alpha release.