Doc for spi readinto() ambiguous

[solarjoe]

https://circuitpython.readthedocs.io/en/latest/shared-bindings/busio/#busio.SPI.readinto

readinto(self, buffer: _typing.WriteableBuffer, *, start: int = 0, end: int = sys.maxsize, write_value: int = 0)

Keyword states
end: int = sys.maxsize

Docstring states
end (int) – end of buffer slice; if not specified, use len(buffer)

[ladyada]

@solarjoe moving this to circuitpython, please submit a PR for dis-ambiguating documentation!

[dhalbert]

@solarjoe: I wrote it this way because end: int = len(buffer) cannot be used to specify the default arg, since it's not a constant. The calculation internally is basically min(end, len(buffer)). How do you think this might be rephrased to be clearer?

[solarjoe]

Good question, the keyword is None by default, right?

I found this and it seems to be a common workaround for computed keyword arguments to use None and
calculate later.
https://stackoverflow.com/a/21804648/7919597

You could use the Optional type hint like

readinto(self, buffer: _typing.WriteableBuffer, *, start: int = 0, end: typing.Optional[int]=None, write_value: int = 0)

and

end (int) – end of buffer slice; if None use len(buffer)

[dhalbert]

Good question, the keyword is None by default, right?

In this case and in similar methods, it's not None, it's actually what the signature says: sys.maxsize. We do use None sometimes, but not here. Here it's less code internally to use only an integer in the readinto() and similar cases. And here if you gave, say, 10000 as the arg, and the buffer is smaller than that, it would use len(buffer).