Rename file and fix rendering issues

Author: kgryte

spec/draft/API_specification/inspection.rst

@@ -3,21 +3,36 @@ Inspection
 
     Array API specification for namespace inspection utilities.
 
-A conforming implementation of the array API standard must provide and support the following functions and objects.
+A conforming implementation of the array API standard must provide and support the following functions and associated inspection APIs.
 
 
 Objects in API
 --------------
 
-.. currentmodule:: array_api
+.. currentmodule:: array_api.info
 
 ..
   NOTE: please keep the functions in alphabetical order
 
 .. autosummary::
    :toctree: generated
-   :template: attribute.rst
-   :nosignatures:
+   :template: method.rst
 
    __array_namespace_info__
-   Info
+
+
+Inspection APIs
+---------------
+..
+  NOTE: please keep the methods in alphabetical order
+
+
+.. autosummary::
+   :toctree: generated
+   :template: method.rst
+
+   capabilities
+   default_device
+   default_dtypes
+   devices
+   dtypes

src/array_api_stubs/_draft/__init__.py

@@ -7,7 +7,6 @@
 from . import data_types as dtype
 from .elementwise_functions import *
 from .indexing_functions import *
-from .inspection import *
 from .linear_algebra_functions import *
 from .manipulation_functions import *
 from .searching_functions import *
@@ -17,6 +16,7 @@
 from .utility_functions import *
 from . import linalg
 from . import fft
+from . import info
 
 
 __array_api_version__: str = "YYYY.MM"

src/array_api_stubs/_draft/_types.py

@@ -25,6 +25,10 @@
     "finfo_object",
     "iinfo_object",
     "Enum",
+    "DefaultDataTypes",
+    "DataTypes",
+    "Capabilities",
+    "Info",
 ]
 
 from dataclasses import dataclass
@@ -85,6 +89,28 @@
 )
 
 
+@dataclass
+class Info:
+    """Namespace returned by `__array_namespace_info__`."""
+
+    def capabilities() -> Capabilities:
+        ...
+
+    def default_device() -> device:
+        ...
+
+    def default_dtypes(*, device: Optional[device]) -> DefaultDataTypes:
+        ...
+
+    def devices() -> List[device]:
+        ...
+
+    def dtypes(
+        *, device: Optional[device], kind: Optional[Union[str, Tuple[str, ...]]]
+    ) -> DataTypes:
+        ...
+
+
 @dataclass
 class finfo_object:
     """Dataclass returned by `finfo`."""

src/array_api_stubs/_draft/info.py

@@ -0,0 +1,143 @@
+__all__ = [
+    "__array_namespace_info__",
+    "capabilities",
+    "default_device",
+    "default_dtypes",
+    "devices",
+    "dtypes",
+]
+
+from ._types import (
+    Optional,
+    Union,
+    Tuple,
+    List,
+    device,
+    dtype,
+    DefaultDataTypes,
+    DataTypes,
+    Capabilities,
+    Info,
+)
+
+
+def __array_namespace_info__() -> Info:
+    """
+    Returns a namespace with Array API namespace inspection utilities.
+
+    Returns
+    -------
+    out: Info
+        Namespace with Array API namespace inspection utilities.
+    """
+
+
+def capabilities() -> Capabilities:
+    """
+    Returns a dictionary of array library capabilities.
+
+    The dictionary should contain the following keys:
+
+    -   **boolean_indexing**: boolean indicating whether an array library supports boolean indexing.
+    -   **data_dependent_shapes**: boolean indicating whether an array library supports data-dependent output shapes.
+
+    Returns
+    -------
+    out: Capabilities
+        a dictionary of array library capabilities.
+    """
+
+
+def default_device() -> device:
+    """
+    Returns an object for the default device.
+
+    Returns
+    -------
+    out: device
+        an object corresponding to the default device.
+    """
+
+
+def default_dtypes(
+    *,
+    device: Optional[device] = None,
+) -> DefaultDataTypes:
+    """
+    Returns a dictionary containing default data types.
+
+    The dictionary should have the following keys:
+
+    -   **real floating**: default real floating-point data type.
+    -   **complex floating**: default complex floating-point data type.
+    -   **integral**: default integral data type.
+    -   **indexing**: default index data type.
+
+    Parameters
+    ----------
+    device: Optional[device]
+        device for which to return default data types. If ``device`` is ``None``, the returned data types must be the default data types for the current device. If ``device`` is not ``None``, the returned data types must be default data types specific to the specified device. Default: ``None``.
+
+        .. note::
+           Some array libraries have the concept of a device context manager, allowing library consumers to manage the current device context. When ``device`` is ``None``, libraries supporting a device context should return the default data types for the current device. For libraries without a context manager or supporting only a single device, those libraries should return the default data types for the default device.
+
+    Returns
+    -------
+    out: DefaultDataTypes
+        a dictionary containing the default data type for respective data type kinds.
+    """
+
+
+def dtypes(
+    *,
+    device: Optional[device] = None,
+    kind: Optional[Union[str, Tuple[str, ...]]] = None,
+) -> DataTypes:
+    """
+    Returns a dictionary of supported *Array API* data types.
+
+    .. note::
+       While specification-conforming array libraries may support additional data types which are not present in this specification, data types which are not present in this specification should not be included in the returned dictionary.
+
+    Parameters
+    ----------
+    kind: Optional[Union[str, Tuple[str, ...]]]
+        data type kind.
+
+        -   If ``kind`` is ``None``, the function must return a dictionary containing all supported Array API data types.
+
+        -   If ``kind`` is a string, the function must return a dictionary containing the data types belonging to the specified data type kind. The following data type kinds must be supported:
+
+            -   ``'bool'``: boolean data types (e.g., ``bool``).
+            -   ``'signed integer'``: signed integer data types (e.g., ``int8``, ``int16``, ``int32``, ``int64``).
+            -   ``'unsigned integer'``: unsigned integer data types (e.g., ``uint8``, ``uint16``, ``uint32``, ``uint64``).
+            -   ``'integral'``: integer data types. Shorthand for ``('signed integer', 'unsigned integer')``.
+            -   ``'real floating'``: real-valued floating-point data types (e.g., ``float32``, ``float64``).
+            -   ``'complex floating'``: complex floating-point data types (e.g., ``complex64``, ``complex128``).
+            -   ``'numeric'``: numeric data types. Shorthand for ``('integral', 'real floating', 'complex floating')``.
+
+        -   If ``kind`` is a tuple, the tuple specifies a union of data type kinds, and the function must return a dictionary containing the data types belonging to at least one of the specified data type kinds.
+
+        Default: ``None``.
+    device: Optional[device]
+        device for which to return supported data types. If ``device`` is ``None``, the returned data types must be the supported data types for the current device; otherwise, the returned data types must be supported data types specific to the specified device. Default: ``None``.
+
+        .. note::
+           Some array libraries have the concept of a device context manager, allowing library consumers to manage the current device context. When ``device`` is ``None``, libraries supporting a device context should return the supported data types for the current device. For libraries without a context manager or supporting only a single device, those libraries should return the supported data types for the default device.
+
+    Returns
+    -------
+    out: DataTypes
+        a dictionary containing supported data types.
+    """
+
+
+def devices() -> List[device]:
+    """
+    Returns a list of supported devices.
+
+    Returns
+    -------
+    out: List[device]
+        a list of supported devices.
+    """