✨: create HasArrayNamepace (#17)

Co-authored-by: Joren Hammudoglu <jhammudoglu@gmail.com>
Co-authored-by: Lucas Colley <lucas.colley8@gmail.com>

Author: 3 people

.gitignore

@@ -22,3 +22,6 @@ venv/
 
 # Build docs
 /src/array_api_typing/_version.py
+
+# Mac files
+.DS_Store

README.md

@@ -0,0 +1,52 @@
+<h1 align="center"> array-api-typing </h1>
+<h3 align="center">Type Annotations for the Python array API standard</h3>
+
+---
+
+## Installation
+
+```bash
+pip install array-api-typing
+```
+
+<details>
+  <summary>using <code>uv</code></summary>
+
+```bash
+uv add array-api-typing
+```
+
+</details>
+<details>
+  <summary>from source, using pip</summary>
+
+```bash
+pip install git+https://github.com/data-apis/array-api-typing.git
+```
+
+</details>
+<details>
+  <summary>building from source</summary>
+
+```bash
+cd /path/to/parent
+git clone https://github.com/data-apis/array-api-typing.git
+cd array-api-typing
+pip install -e .  # editable mode
+```
+
+</details>
+
+### Quick example
+
+```pycon
+>>> import array_api_typing as xpt
+>>> import numpy as np
+
+>>> def func(x: xpt.HasArrayNamespace) -> xpt.HasArrayNamespace:
+...    return x
+
+>>> func(np.array([1, 2, 3]))
+array([1, 2, 3])
+
+```

conftest.py

@@ -0,0 +1,16 @@
+"""Pytest configuration file."""
+
+from sybil import Sybil
+from sybil.parsers.doctest import DocTestParser
+
+readme_tester = Sybil(
+    parsers=[DocTestParser()],
+    pattern="README.md",
+)
+
+python_file_tester = Sybil(
+    parsers=[DocTestParser()],
+    pattern="src/**/*.py",
+)
+
+pytest_collect_file = (readme_tester + python_file_tester).pytest()

pyproject.toml

@@ -25,7 +25,9 @@
     "Topic :: Scientific/Engineering",
     "Typing :: Typed",
   ]
-  dependencies = []
+  dependencies = [
+    "typing-extensions>=4.14.0",
+  ]
 
   [project.urls]
     Repository = "https://github.com/data-apis/array-api-typing"
@@ -41,8 +43,9 @@
   dev = [
     { include-group = "test" },
     "lefthook>=1.11.13",
-]
+  ]
   test = [
+    "numpy>=1.25",
     "pytest>=8.3.3",
     "pytest-cov>=3",
     "pytest-github-actions-annotate-failures>=0.3.0",
@@ -83,6 +86,10 @@ version_tuple = {version_tuple!r}
   warn_unreachable = true
   warn_unused_configs = true
 
+  [[tool.mypy.overrides]]
+    module = "sybil.*"
+    ignore_missing_imports = true
+
 
 [tool.pytest.ini_options]
   addopts = [

src/array_api_typing/__init__.py

@@ -1,5 +1,6 @@
 """Static typing support for the array API standard."""
 
-__all__ = ()
+__all__ = ["HasArrayNamespace", "__version__", "__version_tuple__"]
 
-from ._version import version as __version__ , version_tuple as __version_tuple__
+from ._namespace import HasArrayNamespace
+from ._version import version as __version__, version_tuple as __version_tuple__

src/array_api_typing/_namespace.py

@@ -0,0 +1,31 @@
+"""Static typing support for the array API standard."""
+
+__all__ = ["HasArrayNamespace"]
+
+from types import ModuleType
+from typing import Protocol, final
+from typing_extensions import TypeVar
+
+T = TypeVar("T", bound=object, default=ModuleType)  # PEP 696 default
+
+
+@final
+class HasArrayNamespace(Protocol[T]):  # type: ignore[misc]  # see python/mypy#17288
+    """Protocol for classes that have an `__array_namespace__` method.
+
+    Example:
+    >>> import array_api_typing as xpt
+    >>>
+    >>> class MyArray:
+    ...     def __array_namespace__(self):
+    ...         return object()
+    >>>
+    >>> x = MyArray()
+    >>> def has_array_namespace(x: xpt.HasArrayNamespace) -> bool:
+    ...     return hasattr(x, "__array_namespace__")
+    >>> has_array_namespace(x)
+    True
+
+    """
+
+    def __array_namespace__(self, /, *, api_version: str | None = None) -> T: ...  # noqa: PLW3201