DOC: Confusion about Boolean dtype

[pauljurczak]

Issue with current documentation:

Page https://numpy.org/doc/stable/reference/arrays.dtypes.html recommends using ? to declare Boolean dtype and b for (signed) byte. Page https://numpy.org/doc/stable/reference/arrays.interface.html#arrays-interface recommends b for Boolean (integer type where all values are only True or False).

Idea or request for content:

Perhaps '?' boolean could be added to https://numpy.org/doc/stable/reference/arrays.interface.html#arrays-interface and meaning of b edited?

[seberg]

Its confusing, because 'b1' does denote boolean, because it is via the "kind" letters 'b', 'i', 'u', 'f', 'c', ... While ? is the single letter code where b would be byte (int8).

So the __array_interface__ is probably correct in that sense, but it seems all a bit unclear/managled up probably.

[pauljurczak]

@seberg I didn't know about b1. It is a well hidden secret. It doesn't appear on any of the pages I linked. Full documentation search leads to a different meaning of b1: https://numpy.org/doc/stable/reference/c-api/array.html#c.PyArray_EquivByteorders

[dvorst]

Does this mean that the documentation of https://numpy.org/doc/stable/reference/arrays.dtypes.html is incomplete? Since it specifies: "The first character specifies the kind of data and the remaining characters specify the number of bytes per item", which would mean b -> int8 and 1 -> 1 byte. But b1 indicates a bool, so this dtype is specified by both the first letter as well as the number.

>>> numpy.dtype('?')
dtype('bool')
>>> numpy.dtype('b')
dtype('int8')
>>> numpy.dtype('b1')
dtype('bool')

Making a PR for this.