child_pos_to_cell arguments are not consistent with C

[isaacbrodsky]

Compare

h3-py/src/h3/_cy/cells.pyx

Line 189 in 23bef19

cpdef H3int child_pos_to_cell(H3int parent, int child_res, int64_t child_pos) except 0:

to https://h3geo.org/docs/api/hierarchy#childpostocell

C has:
H3Error childPosToCell(int64_t childPos, H3Index parent, int childRes, H3Index *child);

Python has:
h3.child_pos_to_cell(parent, res_child, child_pos)

h3-duckdb matches the C library (which needs to be fixed in the docs uber/h3#1089)

[ajfriend]

It is documented correctly at https://uber.github.io/h3-py/api_verbose.html#h3.child_pos_to_cell and https://h3geo.org/docs/api/hierarchy#childpostocell

What other change would we make? I'm not sure if we'd want to do a breaking change in the Python API now that it's been like that for a while.

[isaacbrodsky]

Is it possible to fix it in a backwards compatible way? That is, accept either order of arguments?

Maybe we could add a more prominent note to the docs that this function differs from others, for those who are porting code in/out of Python?

[ajfriend]

I'm wary of adding multiple valid function signatures for a function, as I think that confusion from that will be worse than any we get from C and Python not matching.

We could definitely add a more obvious note in the docs about it.

Other things that might help: Adding type hints to the library (which is probably long-overdue) and/or some cheap validation checks on the inputs to raise errors early for users who might be expecting a different order.