add helpers and update docs

[indirectlylit]

Adds some new convenience methods for working with embedded collection view blocks, and updates documentation.

See eff303d for an overview of changes.

Feedback on the API is welcome

[indirectlylit]

@jamalex left some notes inline

[indirectlylit]

switching the parent from cvb to page did not seem to matter

[jamalex]

Hmm, maybe it's not used much internally. Still good to follow what Notion does internally, though, whenever we can -- in case there's some function that does end up using it. (parent is definitely used for collection records, in any case)

[indirectlylit]

there's a circular reference problem I'm not sure how to bootstrap:

collection = client.get_collection(client.create_record("collection", parent=cvb)
cvb = page.children.add_new(CollectionViewBlock, collection=collection)

[jamalex]

I'm guessing the reason a collection is attached to a CVB is so it knows where the "primary/home location" of the collection is, so it can show stuff like this:

The circularity issue does seem puzzling, so I looked into it a bit. Turns out Notion is tricksy when it comes to this. It avoids the issue by the combination of the following two facts:

1. UUIDs in Notion are generated on the client side, and are random. You can choose whatever you want (as long as it's not taken on that table).
2. It can make transaction requests, with multiple operations across numerous records taking place as part of a single atomic API request.

So what it does is create the database page (or inline block), the view, and the collection as a single transaction. So then it doesn't matter that the UUID references are circular, as it can already know what the Collection ID is when putting together the initial View data, and vice versa.

I'm wondering whether a decent idiom for this in notion-py might be to automatically create a Collection when you create a CollectionViewBlock/CollectionViewPageBlock or perhaps better a CollectionView, when you don't pass in an existing Collection. Then, we can internally handle the transaction/circular reference stuff.

What do you think?

Here's an example of the main pieces in the transaction, with the actual IDs replaced with placeholders for ease of reading:

Create the collection view page.

    {
      "id": "<COLLECTION_VIEW_PAGE_ID>",
      "table": "block",
      "path": [],
      "command": "update",
      "args": {
        "id": "<COLLECTION_VIEW_PAGE_ID>",
        "type": "collection_view_page",
        "collection_id": "<COLL_ID>",
        "view_ids": [
          "<VIEW_ID>"
        ],
        "properties": {},
        "created_time": 1566346433677,
        "last_edited_time": 1566346433677
      }
    },

Create the view.

    {
      "id": "<VIEW_ID>",
      "table": "collection_view",
      "path": [],
      "command": "update",
      "args": {
        "id": "<VIEW_ID>",
        "version": 0,
        "type": "table",
        "name": "Default View",
        "format": {
          "table_properties": [{"property": "title", "visible": true, "width": 276}, {"property": "4FoW", "visible": true}, {"property": "6xO9", "visible": true}],
          "table_wrap": true
        },
        "query": {
          "aggregate": [
            {
              "id": "count",
              "property": "title",
              "type": "title",
              "aggregation_type": "count",
              "view_type": "table"
            }
          ]
        },
        "page_sort": [],
        "parent_id": "<COLLECTION_VIEW_PAGE_ID>",
        "parent_table": "block",
        "alive": true
      }
    },

Create the collection.

    {
      "id": "<COLL_ID>",
      "table": "collection",
      "path": [],
      "command": "update",
      "args": {
        "id": "<COLL_ID>",
        "schema": {
          "title": {
            "name": "Name",
            "type": "title"
          },
          "4FoW": {
            "name": "Tags",
            "type": "multi_select"
          },
          "6xO9": {
            "name": "Files",
            "type": "file"
          }
        },
        "format": {
          "collection_page_properties": [
            {
              "property": "4FoW",
              "visible": true
            },
            {
              "property": "6xO9",
              "visible": true
            }
          ]
        },
        "parent_id": "<COLLECTION_VIEW_PAGE_ID>",
        "parent_table": "block",
        "alive": true
      }
    }```

[jamalex]

As discussed separately, I'll merge this and then we can keep thinking about nice idioms for this.

[jamalex]

Thanks -- approved! Left a couple small suggestions in case you want to do any of them, then we can merge.

[jamalex]

Hmm, maybe it's not used much internally. Still good to follow what Notion does internally, though, whenever we can -- in case there's some function that does end up using it. (parent is definitely used for collection records, in any case)

[indirectlylit]

pushed some updates.

Also

• left this question/comment: https://github.com/jamalex/notion-py/pull/38/files#r315920266
• filed this new issue: Views in collection view blocks are not ready to have filters added immediately after creation #46

[jamalex]

Yay, thanks!