Merge pull request #3065 from honno/honno/array-api

AUTHORS.rst

@@ -8,6 +8,7 @@ their individual contributions.
 
 .. NOTE - this list is in alphabetical order by first name (or handle).
 
+* `Aaron Meurer <https://github.com/asmeurer>`_
 * `Adam Johnson <https://github.com/adamchainz>`_
 * `Adam Sven Johnson <https://www.github.com/pkqk>`_
 * `Afrida Tabassum <https://github.com/oxfordhalfblood>`_ (afrida@gmail.com)
@@ -93,6 +94,7 @@ their individual contributions.
 * `Markus Unterwaditzer <https://github.com/untitaker>`_ (markus@unterwaditzer.net)
 * `Mathieu Paturel <https://github.com/math2001>`_ (mathieu.paturel@gmail.com)
 * `Matt Bachmann <https://www.github.com/bachmann1234>`_ (bachmann.matt@gmail.com)
+* `Matthew Barber <https://www.github.com/honno>`_ (quitesimplymatt@gmail.com)
 * `Max Nordlund <https://www.github.com/maxnordlund>`_ (max.nordlund@gmail.com)
 * `Maxim Kulkin <https://www.github.com/maximkulkin>`_ (maxim.kulkin@gmail.com)
 * `Michel Alexandre Salim <https://github.com/michel-slm>`_ (michel@michel-slm.name)

hypothesis-python/RELEASE.rst

@@ -0,0 +1,6 @@
+RELEASE_TYPE: minor
+
+This release introduces strategies for array/tensor libraries adopting the
+`Array API standard <https://data-apis.org/>`__ (:issue:`3037`).
+They are available in :ref:`the hypothesis.extra.array_api extra <array-api>`,
+and work much like the existing :doc:`strategies for NumPy <numpy>`.

hypothesis-python/docs/conf.py

@@ -16,6 +16,7 @@
 import datetime
 import os
 import sys
+import types
 
 import sphinx_rtd_theme
 
@@ -59,6 +60,14 @@ def setup(app):
     if os.path.isfile(os.path.join(os.path.dirname(__file__), "..", "RELEASE.rst")):
         app.tags.add("has_release_file")
 
+    # patch in mock array_api namespace so we can autodoc it
+    from hypothesis.extra.array_api import make_strategies_namespace, mock_xp
+
+    mod = types.ModuleType("xps")
+    mod.__dict__.update(make_strategies_namespace(mock_xp).__dict__)
+    assert "xps" not in sys.modules
+    sys.modules["xps"] = mod
+
 
 language = None
 
@@ -98,6 +107,7 @@ def setup(app):
     "pypi": ("https://pypi.org/project/%s/", ""),
     "bpo": ("https://bugs.python.org/issue%s", "bpo-"),
     "np-ref": ("https://numpy.org/doc/stable/reference/%s", ""),
+    "xp-ref": ("https://data-apis.org/array-api/latest/API_specification/%s", ""),
     "wikipedia": ("https://en.wikipedia.org/wiki/%s", ""),
 }
 

hypothesis-python/docs/numpy.rst

@@ -52,3 +52,41 @@ and confirmed working with every Pandas minor version from 0.25 through to 1.1.
 Releases that are not the latest patch release of their minor version are not
 tested or officially supported, but will probably also work unless you hit a
 pandas bug.
+
+.. _array-api:
+
+---------
+Array API
+---------
+
+.. tip::
+   The Array API standard is not yet finalised, so this module will make breaking
+   changes if necessary to support newer versions of the standard.
+
+Hypothesis offers strategies for `Array API <https://data-apis.org/>`_ adopting
+libraries in the ``hypothesis.extra.array_api`` package. See :issue:`3037` for
+more details.  If you want to test with :pypi:`CuPy`, :pypi:`Dask`, :pypi:`JAX`,
+:pypi:`MXNet`, :pypi:`PyTorch <torch>`, :pypi:`TensorFlow`, or :pypi:`Xarray` -
+or just ``numpy.array_api`` - this is the extension for you!
+
+.. autofunction:: hypothesis.extra.array_api.make_strategies_namespace
+
+The resulting namespace contains all our familiar strategies like
+:func:`~xps.arrays` and :func:`~xps.from_dtype`, but based on the array-API
+standard semantics and returning objects from the ``xp`` module:
+
+.. automodule:: xps
+   :members:
+        from_dtype,
+        arrays,
+        array_shapes,
+        scalar_dtypes,
+        boolean_dtypes,
+        numeric_dtypes,
+        integer_dtypes,
+        unsigned_integer_dtypes,
+        floating_dtypes,
+        valid_tuple_axes,
+        broadcastable_shapes,
+        mutually_broadcastable_shapes,
+        indices,