Missing information about how to start a read_only session

[meteoDaniel]

Dear guys from earthmover,

I am testing icechunk at the moment, and I am unable to find information/examples about how to initialize a read_only session.

This is e.g. the result of my last approach:

In [24]:         repo = icechunk.Repository.open(storage_config)
    ...:         session = repo.readonly_session("main")
---------------------------------------------------------------------------
TypeError                                 Traceback (most recent call last)
Cell In[24], line 2
      1 repo = icechunk.Repository.open(storage_config)
----> 2 session = repo.readonly_session("main")

TypeError: Repository.readonly_session() takes 1 positional argument but 2 were given

# possible solutions: 

session = repo.readonly_session(snapshot=repo.ancestry(branch="main")[-1].id)
session = repo.readonly_session(branch="main")

Would be great to see some further information in the docs.

[rabernat]

Thanks for reporting this Daniel! We have some documentation gaps at the moment (being fixed in #590).

[paraseba]

Sorry about this @meteoDaniel . We'll improve very soon. Your solution is correct, readonly_session now needs to know what kind of ref you want to resolve (branch, snapshot or tag). Most of the time we just use (branch="main")

[rabernat]

Most of the time we just use (branch="main")

Would this possibly be a good default?

[paraseba]

It could be. I wonder if default_branch would be a good new field for the RepositoryConfiguration, so people can for example persist in the configuration default_branch="dev" and then readonly_session() uses that.

Of course, the default default would be main

[meteoDaniel]

Actually, i do not know the most common usage.

So a kind of default that has been used can be benefical, otherwise it is necessary to return the default branch in case there is a definition for it.

From my point of view, even if I have made a wrong assumption using icechunk correctly, I would require to have an example of how to do it better.

So I think working on your documentation will clarify a lot 🤗