💡 [REQUEST] - Expose parameters to create page with icon/cover and update multiple properties at once, reducing API calls

[ivanlonel]

Describe your use-case or problem

The ultimate-notion high level API doesn't have a Page.update or Session.update_page or Database.update_page or Schema.update method, to allow updating the values of multiple properties of a page at once. When I want to update all properties of a page (which I read from another source, like a CSV or another web API), I need to use the setter for each property for each page I want to update (which uses more API calls and therefore takes longer) or use the obj_api directly, as PagesEndpoint does have an update method that accepts a dict of properties.

And even the obj_api create/update methods don't take advantage of the fact that the notion-sdk-py's underlying create/update methods accept icon and cover as parameters, which allows setting both in the same API call used to create the page or update it.

Proposed solution / feature

1. Include update methods in the high level API that use the obj_apis PagesEndpoint.update` method, allowing to update all properties of a page with a single API call.

2. Expose icon and cover parameters from notion-sdk-py's PagesEndpoint methods to the obj_api 'create' and 'update' methods, and then to the high level API methods that use them.

Additional context or examples

Exposing 'icon' and 'cover' parameters would allow the application to trade this:

page = my_schema.create(**my_properties)
page.icon = icon  # separate API call
page.cover = cover  # separate API call

for this:

page = my_schema.create(**my_properties, icon=icon, cover=cover)

Also, implementing methods to update all properties of a page at once would allow the application to trade this:

page.props.p0 = my_properties["p0"]
page.props.p1 = my_properties["p1"]
page.props.p2 = my_properties["p2"]
page.props.p3 = my_properties["p3"]
page.props.p4 = my_properties["p4"]
page.props.p5 = my_properties["p5"]
page.props.p6 = my_properties["p6"]
page.props.p7 = my_properties["p7"]
page.props.p8 = my_properties["p8"]
page.props.p9 = my_properties["p9"]
...
page.props.pn = my_properties["pn"]
page.icon = icon
page.cover = cover

for this:

 my_schema.update(page, **my_properties, icon=icon, cover=cover)

[FlorianWilhelm]

Thanks for this request @ivanlonel. Just for context, is your goal purely efficiency or do you have a specific use-case in mind? For me to fully understand your request, it would be really helpful to get more details about what you want to accomplish.

In general, the idea of Ultimate Notion never was to only provide high-level access to the functionality of notion-sdk-py but to build a high-level level that is actually user-friendly and pythonic. That's the goal, which drives my design decisions.

As a side note, Ultimate Notion has a low-level API, which is an object-based kind of high-level API to notion-sdk-py if you wish. You'll find it under the obj_api subpackage within the endpoints module. This module provides direct access to notion-sdk-py functionality but with Python objects instead of JSON-like structures. Maybe that helps?

Regarding your API suggestions. Having

session.create_page(parent, title, blocks, icon, cover)

is a really nice idea as people might want to use Ultimate Notion to create pages directly with a given icon and cover in the pages hierarchy. I would definitily include a PR that adds this.

On the other hand

page = my_schema.create(**my_properties, icon=icon, cover=cover)

is problematic as now you are assuming that no one ever calls a property icon or cover in their databases. So this syntax would not work in general. One would need to do something like

my_properties = {'name': 'Peter', ....}
my_schema.create(properties=my_properties, icon=icon, cover=cover)

to prevent ambiguity, which I find quite ugly.

Regarding the bulk update of the pages properties, you are suggesting:

my_schema.update(page, **my_properties, icon=icon, cover=cover)

which I find quite unintuitive as you are using a method of a schema to update the page, which you are also passing.

Here I could be talked into accepting a method page.update_props(**my_properties). So if you want to, please consider contributing a PR. Since icon and cover are semantically different compared to properties, I would sacrifice the efficiency of a single call for a clearer API, unless you come up with an idea to make sure that a property name never clashes with the attributes icon and cover.

I hope you don't mind my direct and blunt response and I hope to made make it clear that I really appreciate your input.

[ivanlonel]

Thanks for your reply, @FlorianWilhelm. There's nothing blunt about it. You make really good points and patiently explain the reasoning behind them.

My goal was both increasing efficiency and reducing verbosity in the final user's code, preferably without giving up the consistency checks and auto-caching provided by the high level API.

But I agree my examples are problematic. I actually had a dict of properties in mind first (like in obj_api's PagesEndpoint.create) but changed it to an unpacking of kwargs to be more in line with existing functions in ultimate-notion, without realizing the problem this created, which is pretty obvious now that you pointed it. I don't see a way to fit everything in a single call without passing all properties as a single parameter, be it a dict, namedtuple, dataclass or any other container. But as you said, that's not necessarily a beautiful solution. Perhaps, creating/updating a page with properties + icon + cover in a single call shoud be left to the lower level PagesEndpoint class, whose create and update methods already take a dict as parameter. They just need the icon and cover parameters, which they would need to serialize and add to the request dict, before passing it to the raw api (notion-sdk-py).

Specifically about the update example, it was an unfortunate choice basing it off Schema.create out of all methods that create a page. I mean, if we already have the page instantiated, we obviously don't need the schema instance to be a part of this. What I ment was something like page.update(**my_properties, icon=icon, cover=cover), which still has the kwargs problem discussed above. But I really like your suggestion of a page.update_props(**my_properties) method. While not including icon and cover, it still reduces significantly the number of API requests when updating multiple properties per page.

So what I'd like to propose is:

1. Adding icon and cover parameters to PagesEndpoint methods create and update in the obj_api;
2. Also adding icon and cover parameters to Session.create_page, like you suggested;
3. Creating Page.update_props(**kwargs) like you suggested.

What do you think?

I won't be home until friday, but once I have access to my desktop I can try implementing those myself and send a PR.

[ivanlonel]

Actually, regarding item 1, the update method in PagesEndpoint doesn't currently take a dict as a single parameter. Only create does that. update still uses unpacking for the properties. My mistake.

That means there are two possible courses of action for the update method:

1. Leave it untouched;
2. Change its signature to expect properties as a single parameter, like in create, and add the other parameters.

These are the pros and cons I can see for option 2:

Pros:

• Consistency with create, which already expects properties to be a dict[str, PropertyValue];
• Consistency with the underlying update method from notion-sdk-py, considering the obj_api acts as an object-based higher level API for notion-sdk-py;
• Being able to update meta-properties (like icon and cover) and schema properties in a single API call for each page.

Cons:

• It's a breaking change. Existing calls to PagesEndpoint.update must change how properties are passed.

Since ultimate-notion is still in pre-release (version 0.*), changes in the public API are expected. If we do go with option 2, it might be better suited for 0.10.0 than to 0.9.5, so I´d probably put it in a separate PR.

Still, it's a bigger change than the others, so I'll undestand if you prefer to leave the update method as it is.

[FlorianWilhelm]

@ivanlonel, that sounds really good and thanks for wanting to contribute.

Regarding your points:

1. Within obj_api I see your point of wanting to stay as close as possible to the API of notion-sdk-py. So let's do that. As you argue correctly, we are still in a sub 1.0 version and I guess that most users don't work on the obj_api level anyway. It makes sense to have the design goal of the low-level API to be a kind of notion-sdky-py but with actual Python objects.
2. Adding icon and cover parameters to Session.create_page is a no brainer, so let's do that.
3. Having a Page.update_props(**kwargs) would be a nice compromise of what you suggested and users that update several properties of their database entries frequently will like it.

So if you want to provide a PR, that would be really awesome 😃 Please let me know if you need any help with that or miss something in the contributing docs. The whole unit test suite is kind of complicated due to vcr.py and the whole fact that we are testing against a backend we don't own.

[ivanlonel]

Hey there, @FlorianWilhelm! I just sent PR #149.

Your input will be very welcome, as I created tests for my changes but I did it kinda mimicking existing tests, since I don't have a lot of experience with unit testing (shame on me), and I had never heard of vcr.py before. I also never used hatch, and I didn't manage to get the test suite running at all. I tested my changes against Notion manually, but I'm waiting for GitHub actions to run the unit tests for me on the PR so I can fix eventual problems.

I also updated the changelog, but please review it as I created a new entry for 0.10 and put the note about PagesEndpoint.update in there. But I'm not sure that's how it will be released. I first planned to create a separate PR for it, but it was very semantically related to the remaining changes in this PR, so I just did it as the last commit and sent everything. If you feel it would be better to move it to it's own PR, it can be easily done.

Lastly, I added a mention about the new Page.update_props method in the documentation. Please let me know if you think I should have done that differently.