Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Making RFC 2119 usage clearer #801

Draft
wants to merge 3 commits into
base: main
Choose a base branch
from
Draft

Making RFC 2119 usage clearer #801

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
c4d90fe
Add a paragraph making it clearer that RFC 2119 is used
asmeurer Apr 30, 2024
08f12ce
Use a list-table instead of an rst table
asmeurer Apr 30, 2024
0d1999c
Add a sphinx extension to automatically bold RFC 2119 words
asmeurer Apr 30, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
61 changes: 32 additions & 29 deletions spec/2023.12/API_specification/data_types.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,35 +9,38 @@ A conforming implementation of the array API standard must provide and support
the following data types ("dtypes") in its array object, and as data type
objects in its main namespace under the specified names:

+--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| dtype object | description |
+==============+============================================================================================================================================================================================+
| bool | Boolean (``True`` or ``False``). |
+--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| int8 | An 8-bit signed integer whose values exist on the interval ``[-128, +127]``. |
+--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| int16 | A 16-bit signed integer whose values exist on the interval ``[−32,767, +32,767]``. |
+--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| int32 | A 32-bit signed integer whose values exist on the interval ``[−2,147,483,647, +2,147,483,647]``. |
+--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| int64 | A 64-bit signed integer whose values exist on the interval ``[−9,223,372,036,854,775,807, +9,223,372,036,854,775,807]``. |
+--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| uint8 | An 8-bit unsigned integer whose values exist on the interval ``[0, +255]``. |
+--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| uint16 | A 16-bit unsigned integer whose values exist on the interval ``[0, +65,535]``. |
+--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| uint32 | A 32-bit unsigned integer whose values exist on the interval ``[0, +4,294,967,295]``. |
+--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| uint64 | A 64-bit unsigned integer whose values exist on the interval ``[0, +18,446,744,073,709,551,615]``. |
+--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| float32 | IEEE 754 single-precision (32-bit) binary floating-point number (see IEEE 754-2019). |
+--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| float64 | IEEE 754 double-precision (64-bit) binary floating-point number (see IEEE 754-2019). |
+--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| complex64 | Single-precision (64-bit) complex floating-point number whose real and imaginary components must be IEEE 754 single-precision (32-bit) binary floating-point numbers (see IEEE 754-2019). |
+--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| complex128 | Double-precision (128-bit) complex floating-point number whose real and imaginary components must be IEEE 754 double-precision (64-bit) binary floating-point numbers (see IEEE 754-2019). |
+--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
.. list-table::
:widths: 20 80
:header-rows: 1

* - dtype object
- description
* - bool
- Boolean (``True`` or ``False``).
* - int8
- An 8-bit signed integer whose values exist on the interval ``[-128, +127]``.
* - int16
- A 16-bit signed integer whose values exist on the interval ``[−32,767, +32,767]``.
* - int32
- A 32-bit signed integer whose values exist on the interval ``[−2,147,483,647, +2,147,483,647]``.
* - int64
- A 64-bit signed integer whose values exist on the interval ``[−9,223,372,036,854,775,807, +9,223,372,036,854,775,807]``.
* - uint8
- An 8-bit unsigned integer whose values exist on the interval ``[0, +255]``.
* - uint16
- A 16-bit unsigned integer whose values exist on the interval ``[0, +65,535]``.
* - uint32
- A 32-bit unsigned integer whose values exist on the interval ``[0, +4,294,967,295]``.
* - uint64
- A 64-bit unsigned integer whose values exist on the interval ``[0, +18,446,744,073,709,551,615]``.
* - float32
- IEEE 754 single-precision (32-bit) binary floating-point number (see IEEE 754-2019).
* - float64
- IEEE 754 double-precision (64-bit) binary floating-point number (see IEEE 754-2019).
* - complex64
- Single-precision (64-bit) complex floating-point number whose real and imaginary components must be IEEE 754 single-precision (32-bit) binary floating-point numbers (see IEEE 754-2019).
* - complex128
- Double-precision (128-bit) complex floating-point number whose real and imaginary components must be IEEE 754 double-precision (64-bit) binary floating-point numbers (see IEEE 754-2019).

Data type objects must have the following methods (no attributes are required):

Expand Down
61 changes: 32 additions & 29 deletions spec/draft/API_specification/data_types.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,35 +9,38 @@ A conforming implementation of the array API standard must provide and support
the following data types ("dtypes") in its array object, and as data type
objects in its main namespace under the specified names:

+--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| dtype object | description |
+==============+============================================================================================================================================================================================+
| bool | Boolean (``True`` or ``False``). |
+--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| int8 | An 8-bit signed integer whose values exist on the interval ``[-128, +127]``. |
+--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| int16 | A 16-bit signed integer whose values exist on the interval ``[−32,767, +32,767]``. |
+--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| int32 | A 32-bit signed integer whose values exist on the interval ``[−2,147,483,647, +2,147,483,647]``. |
+--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| int64 | A 64-bit signed integer whose values exist on the interval ``[−9,223,372,036,854,775,807, +9,223,372,036,854,775,807]``. |
+--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| uint8 | An 8-bit unsigned integer whose values exist on the interval ``[0, +255]``. |
+--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| uint16 | A 16-bit unsigned integer whose values exist on the interval ``[0, +65,535]``. |
+--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| uint32 | A 32-bit unsigned integer whose values exist on the interval ``[0, +4,294,967,295]``. |
+--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| uint64 | A 64-bit unsigned integer whose values exist on the interval ``[0, +18,446,744,073,709,551,615]``. |
+--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| float32 | IEEE 754 single-precision (32-bit) binary floating-point number (see IEEE 754-2019). |
+--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| float64 | IEEE 754 double-precision (64-bit) binary floating-point number (see IEEE 754-2019). |
+--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| complex64 | Single-precision (64-bit) complex floating-point number whose real and imaginary components must be IEEE 754 single-precision (32-bit) binary floating-point numbers (see IEEE 754-2019). |
+--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| complex128 | Double-precision (128-bit) complex floating-point number whose real and imaginary components must be IEEE 754 double-precision (64-bit) binary floating-point numbers (see IEEE 754-2019). |
+--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
.. list-table::
:widths: 20 80
:header-rows: 1

* - dtype object
- description
* - bool
- Boolean (``True`` or ``False``).
* - int8
- An 8-bit signed integer whose values exist on the interval ``[-128, +127]``.
* - int16
- A 16-bit signed integer whose values exist on the interval ``[−32,767, +32,767]``.
* - int32
- A 32-bit signed integer whose values exist on the interval ``[−2,147,483,647, +2,147,483,647]``.
* - int64
- A 64-bit signed integer whose values exist on the interval ``[−9,223,372,036,854,775,807, +9,223,372,036,854,775,807]``.
* - uint8
- An 8-bit unsigned integer whose values exist on the interval ``[0, +255]``.
* - uint16
- A 16-bit unsigned integer whose values exist on the interval ``[0, +65,535]``.
* - uint32
- A 32-bit unsigned integer whose values exist on the interval ``[0, +4,294,967,295]``.
* - uint64
- A 64-bit unsigned integer whose values exist on the interval ``[0, +18,446,744,073,709,551,615]``.
* - float32
- IEEE 754 single-precision (32-bit) binary floating-point number (see IEEE 754-2019).
* - float64
- IEEE 754 double-precision (64-bit) binary floating-point number (see IEEE 754-2019).
* - complex64
- Single-precision (64-bit) complex floating-point number whose real and imaginary components must be IEEE 754 single-precision (32-bit) binary floating-point numbers (see IEEE 754-2019).
* - complex128
- Double-precision (128-bit) complex floating-point number whose real and imaginary components must be IEEE 754 double-precision (64-bit) binary floating-point numbers (see IEEE 754-2019).

Data type objects must have the following methods (no attributes are required):

Expand Down
2 changes: 2 additions & 0 deletions spec/draft/purpose_and_scope.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -460,6 +460,8 @@ a dimension whose size is one.
**vector**:
a one-dimensional array.

In addition to the above terms, the key words "**must**", "**must not**", "**required**", "**shall**", "**shall not**", "**should**", "**should not**", "**recommended**", "**may**", and "**optional**" in this specification are to be interpreted as described in [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119).

* * *

## Normative References
Expand Down
1 change: 1 addition & 0 deletions src/_array_api_conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,7 @@
"sphinx_favicon",
"sphinx_markdown_tables",
"sphinxcontrib.jquery",
"autobold_rfc2119",
]

autosummary_generate = True
Expand Down
30 changes: 30 additions & 0 deletions src/autobold_rfc2119.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
from sphinx.application import Sphinx
import re

rfc_2119_words = [
'must',
'must not',
'required',
'shall',
'shall not',
'should',
'should not',
'recommended',
'not recommended',
'may',
'optional',
]

def bold_terms(source):
return re.sub(rf'\b({"|".join(rfc_2119_words)})\b(?!\[)', r'**\1**', source, flags=re.IGNORECASE)

def bold_terms_source_read(app, docname, source):
source[0] = bold_terms(source[0])

def bold_terms_autodoc(app, what, name, obj, options, lines):
for i in range(len(lines)):
lines[i] = bold_terms(lines[i])

def setup(app: Sphinx):
app.connect('source-read', bold_terms_source_read)
app.connect('autodoc-process-docstring', bold_terms_autodoc)
Loading