OMERO.tables read API: start/stop edge case support

[sbesson]

Follow-up of #430, this issues aims to capture the current discrepancies in the omero.grid.Table.read() API with regards to the start and end parameters and some options to resolve them.

Using the published documentation as a starting point:

• the OMERO API documentation only contains a link to the former PyTables documentation which is now 404. Using a snapshot of the page, the historical PyTables API documentation reads as follows:

The start, stop and step parameters can be used to select only a range of rows in the table.
Their meanings are the same as in the built-in range() Python function, except that negative values of step are not allowed yet. 
Moreover, if only start is specified, then stop will be set to start+1. If you do not specify neither start nor stop, then all the rows in the table are selected.

• the current OMERO documentation has the following informations:

start (long) – The index of the first row to retrieve.
stop (long) – The index of the last+1 row to retrieve (uses similar semantics to range()).

start=0, stop=0 currently returns the first row instead of empty as would be expected using the normal Python range semantics. This may change in future

The current behavior of the omero.grid.Table.read API as of OMERO.py 5.19.5 using a table of n rows and different values of start and end is the following:

start	stop	Returned data
0	0	all rows 1
0	1	first row
0 < start <= n	stop = start	no row
0 < start <= n	0 < start < stop <= n	(stop - start) row(s)
0	n	all rows
0	n + 10	all rows 2
0	-1	n - 1 first rows 2
0	- n + 1	first row 2
-1	n	last row 2

Overall, when 0<=start<stop<=n, the API behaves as expected. There are two primary scenarios where either the behavior is undocumented or we have a mismatch between the documentation and the current implementation.

start=0, stop=0

The complexity here lies with the fact that the start/stop parameters of the OMERO.tables read API must be of long type. This prevents the ability to pass null/None. All of the options below effectively correspond to different interpretation of a value of 0.

Option 1: return the first row

This would require an update to OMERO.py to match the OMERO documentation as well as updates to the OMERO API documentation. Code-wise, this would be equivalent to translating start=0,stop=0 as start=0,stop=None in the PyTables call.

Option 2: return all rows

This would require no change to the current OMERO.py implementation and only updates to the OMERO documentation and OMERO API documentation. In OMERO.py, this would be equivalent to translating start=0,stop=0 as start=None,stop=None or not specifying start/stop in the PyTables call.

Option 3: return no row

This is a new behavior which would require a change in OMERO.py, the OMERO API documentation and the OMERO documentation. In PyTables this would be equivalent to passing start=0,stop=0 directly to the underlying PyTables.

start,end outside the [0 n] range

Both the PyTables and the OMERO documentation specify the semantics of start/end should be interpreted as per the built-in range function (or slice for the current PyTables documentation). However there are little specifics about whether any Python range/slice can be used to specify a range of rows.
By contrast some other methods like removeRows (now remove_rows) are being explicit about the support of whether negative index are supported.

Option 1: only support start and end values within [0 n] to specify a range of rows

This would require a change to OMERO.py to throw an ApiUsageException if either start or end is outside the range of rows.
The OMERO API documentation and the OMERO documentation would also need to be updated accordingly.

Option 2: formalize the support for any start and end values allowing to specify a range/slice

This would require a change to OMERO.py similar to #430 to fix the rowNumbers returned by arbitrary ranges. The OMERO API documentation and the OMERO documentation would also need to be updated accordingly.

/cc @chris-allan @jburel @joshmoore

Footnotes

1. this behavior was likely introduced in eba3ef7 ↩

2. the rowNumbers is incorrect by OMERO.py 5.19.5 ↩ ↩² ↩³ ↩⁴