feat: Add TIFF.open_sync to synchronously open a TIFF

[kylebarron]

Change list

• Add a new synchronous API to open a TIFF TIFF.open_sync.

Questions

I think the "primary" API of the library should be async, in the sense that if someone is doing synchronous operations, there's not much of a point of using async-tiff over rasterio.

But I think it makes sense to have sync operations because 1) it's not hard to implement sync wrappers and 2) it's useful for testing.

But if we do have sync operations, then we need to be consistent on naming, and it seems like the most consistent naming is to make the async method end with an _async suffix.

[vincentsarago]

I think the "primary" API of the library should be async, in the sense that if someone is doing synchronous operations, there's not much of a point of using async-tiff over rasterio.

I would then say that you don't even need to have async_open

The whole library is named async so the user should expect to have to use await for all the methods

[kylebarron]

I think the "primary" API of the library should be async, in the sense that if someone is doing synchronous operations, there's not much of a point of using async-tiff over rasterio.

I would then say that you don't even need to have async_open

The whole library is named async so the user should expect to have to use await for all the methods

The idea is that an end user might need to just construct the GeoTIFF instance to pass to a library. But where the user themselves doesn't want or know how to touch async. As in the example I provided above with Lonboard.

The question is whether it's better to have

• sync: open_sync, async: open
• sync: open, async: open_async

The former is more "async-native" while the latter maintains better compatibility with obstore. Obstore is similar in the sense that users should use the async API over the sync one, but it also makes you suffix with _async in order to use any async APIs

[vincentsarago]

I don't want to be a blocker here and if it's the same with obstore let's use open_async

[maxrjones]

+1 on mirroring obstore's naming conventions

[kylebarron]

Another option is to use different names entirely:

• sync: __init__
• async: open

Since in Python __init__ can't be async, we could set that. (Technically, pyo3 implements __new__, not __init__, so I think it might be possible to make an async constructor, but users wouldn't be used to it)

[hrodmn]

+1 for *_async functions and methods

I agree with @vincentsarago that the name of the library suggests async features so async functions should be expected, but I think consistency with other related/familiar APIs like obstore is really valuable and will save us all some headaches.

[weiji14]

I think the "primary" API of the library should be async, in the sense that if someone is doing synchronous operations, there's not much of a point of using async-tiff over rasterio.

I would then say that you don't even need to have async_open

The whole library is named async so the user should expect to have to use await for all the methods

I would lean towards keeping things async only. Unlike obstore/object_store which has a manageable spec, (Geo)TIFF has too many things going on at the low level (see advice from #7), and I think doubling the amount of methods would lead to more confusion (see zarr-python's async and sync APIs). Also it looks duplicative if someone does

import async_tiff

await async_tiff.open_async(...)

We could make _async/_sync versions in async-geotiff, but I'd vote to keep things async only here.

[kylebarron]

I'm leaning now towards:

• This is an async-first library, whereas obstore is "half and half to support both equally"
• We should make the async operations the most obvious, while allowing fallbacks to synchronous APIs in some cases
• Therefore:
  • async open should be called await TIFF.open()
  • sync open should be called: TIFF.open_sync()

Any final thoughts?

[kylebarron]

I'm inclined to not merge this for the current release, and then we can keep thinking about whether this is useful

[vincentsarago]

I'm still not super convinced by one or the other. To be honest I was mostly surprised that async-tiff would provide synchronous methods.

If this not a user request, I would put this on hold to be honest.

I would not go for open_sync if we expect user to use obstore as well (because obstore does the opposite with open_async)