Skip to content

Add specification for isdtype - #503

Merged
rgommers merged 11 commits into
mainfrom
add-is-dtype
Nov 28, 2022
Merged

Add specification for isdtype#503
rgommers merged 11 commits into
mainfrom
add-is-dtype

Conversation

@kgryte

@kgrytekgryte commented Nov 3, 2022

Copy link
Copy Markdown
Contributor

This PR

  • resolvesRFC: add data type inspection utilities to the array API specification #425 by adding an API for testing whether a provided dtype is of a specified data type kind.
  • specifies that the function name is is_type (rather than is_dtype) in order to match result_type. Another possibility is istype in order to match astype.Update: based on feedback, the function name is specified as isdtype. The functions astype and result_type are now considered ill-named (e.g., as_dtype/asdtype and result_dtype/common_dtype are considered better based on present naming conventions, but are named as such due to historical reasons). The choice of isdtype is considered preferable over is_dtype in order to be consistent with isfinite, isinf, and isnan, which already exist in the specification. One should note that this does not follow strict PEP8 guidance; however, consistency within specification was considered preferable over PEP8 purity.
  • follows the API design proposed and voted on in RFC: add data type inspection utilities to the array API specification #425 (comment) and supports providing a dtype, a str, and a tuple of dtype and str.
  • supports the following dtype kinds: 'bool', 'signed integer', 'unsigned integer', 'integral', 'real floating','complex floating', and 'numeric'.
  • does not include the kind "floating" (as described in the specification data type categories). This kind would be achieved via a tuple: ('real floating', 'complex floating').

@kgrytekgryte added the API extension Adds new functions or objects to the API. label Nov 3, 2022
@kgrytekgryte added this to the v2022 milestone Nov 3, 2022
@kgryte

Copy link
Copy Markdown
ContributorAuthor

Based on the 3 November 2022 meeting, a few changes should be made to this PR:

  1. change integer to integral (in order to avoid ambiguity with integer referring to signed integer dtypes).
  2. change real to real floating (due to ambiguity of what is meant by "real").
  3. change complex to complex floating (in order to mirror real floating).
  4. add a note explaining that array API implementors are not limited to including only dtypes as described in the spec in particular categories. E.g., float16 and bfloat16 can be included in real floating.

Comment threadspec/API_specification/array_api/data_type_functions.py Outdated
@rgommers

Copy link
Copy Markdown
Member

Based on the 3 November 2022 meeting, a few changes should be made to this PR:

(1) and (4) are more clear cut than (2) and (3), which make things more verbose. But I'm fine with all four of those.

I do really want to see the name change to either is_dtype or isdtype. Then, with those five changes made, I think this is good to go.

@kgrytekgryte changed the title Add specification for is_typeAdd specification for is_dtypeNov 21, 2022
@kgrytekgryte changed the title Add specification for is_dtypeAdd specification for isdtypeNov 21, 2022
@kgryte

Copy link
Copy Markdown
ContributorAuthor

I've updated the PR to incorporate the proposed changes 1-4, and I've renamed the API to isdtype to be consistent with isfinite, isinf, and isnan. Both isdtype and is_dtype were considered acceptable based on feedback here and in consortium meetings; the former was chosen for consistency with existing specification APIs.

This PR should be ready for another round of review.

@rgommersrgommers left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Okay, it looks like this is ready. There was a very long and lively debate on gh-425 around the design options here. It looks like we ended up with something that is clean, and that fairly takes into account everyone's comments.

In it goes, thanks @kgryte & everyone else!

@rgommers
rgommers merged commit 19ef830 into mainNov 28, 2022
@rgommers
rgommers deleted the add-is-dtype branch November 28, 2022 15:19
Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Labels

API extensionAdds new functions or objects to the API.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

RFC: add data type inspection utilities to the array API specification

4 participants

@kgryte@rgommers@seberg@agoose77