Merge pull request #467 from Blosc/arrayapi

Array-api 2

Author: lshaw8317

CMakeLists.txt

@@ -50,7 +50,7 @@ else()
     include(FetchContent)
     FetchContent_Declare(blosc2
         GIT_REPOSITORY https://github.com/Blosc/c-blosc2
-        GIT_TAG 82a85f9d285d7ae6d141c73e84c7574bfc24a134  # v2.21.2
+        GIT_TAG 0c853a639ba97997e33e29db9eed202459ebc6f0  # v2.21.3
     )
     FetchContent_MakeAvailable(blosc2)
     include_directories("${blosc2_SOURCE_DIR}/include")

doc/conf.py

@@ -1,9 +1,22 @@
 # -- Path setup --------------------------------------------------------------
+import inspect
 import os
 import sys
 
+import numpy as np
+
 import blosc2
 
+
+def genbody(f, func_list, lib="blosc2"):
+    for func in func_list:
+        f.write(f"    {func}\n")
+
+    f.write("\n\n\n")
+    for func in func_list:
+        f.write(f".. autofunction:: {lib}.{func}\n\n")
+
+
 sys.path.insert(0, os.path.abspath(os.path.dirname(blosc2.__file__)))
 
 project = "Python-Blosc2"
@@ -69,6 +82,120 @@
 html_show_sourcelink = False
 
 autosummary_generate_overwrite = False
+autosummary_generate = True
+
+# GENERATE ufuncs.rst
+blosc2_ufuncs = []
+for name, obj in vars(np).items():
+    if isinstance(obj, np.ufunc) and hasattr(blosc2, name):
+        blosc2_ufuncs.append(name)
+
+with open("reference/ufuncs.rst", "w") as f:
+    f.write(
+        """Universal Functions (`ufuncs`)
+------------------------------
+
+The following elementwise functions can be used for computing with any of :ref:`NDArray <NDArray>`, :ref:`C2Array <C2Array>`, :ref:`NDField <NDField>` and :ref:`LazyExpr <LazyExpr>`.
+
+Their result is always a :ref:`LazyExpr` instance, which can be evaluated (with ``compute`` or ``__getitem__``) to get the actual values of the computation.
+
+Note: The functions ``conj``, ``real``, ``imag``, ``contains``, ``where`` are not technically ufuncs.
+
+.. currentmodule:: blosc2
+
+.. autosummary::
+
+"""
+    )
+    genbody(f, blosc2_ufuncs)
+
+# GENERATE additional_funcs.rst
+blosc2_addfuncs = sorted(["conj", "real", "imag", "contains", "where", "clip", "round"])
+blosc2_dtypefuncs = sorted(["astype", "can_cast", "result_type", "isdtype"])
+
+with open("reference/additional_funcs.rst", "w") as f:
+    f.write(
+        """Additional Functions and Type Utilities
+=======================================
+
+Functions
+---------
+
+The following functions can also be used for computing with any of :ref:`NDArray <NDArray>`, :ref:`C2Array <C2Array>`, :ref:`NDField <NDField>` and :ref:`LazyExpr <LazyExpr>`.
+
+Their result is typically a :ref:`LazyExpr` instance, which can be evaluated (with ``compute`` or ``__getitem__``) to get the actual values of the computation.
+
+.. currentmodule:: blosc2
+
+.. autosummary::
+
+"""
+    )
+    genbody(f, blosc2_addfuncs)
+    f.write(
+        """Type Utilities
+--------------
+
+The following functions are useful for working with datatypes.
+
+.. currentmodule:: blosc2
+
+.. autosummary::
+
+"""
+    )
+    genbody(f, blosc2_dtypefuncs)
+
+# GENERATE index_funcs.rst
+blosc2_indexfuncs = sorted(
+    [
+        "count_nonzero",
+        "squeeze",
+        "expand_dims",
+        "sort",
+        "take",
+        "take_along_axis",
+        "broadcast_to",
+        "meshgrid",
+        "indices",
+    ]
+)
+
+with open("reference/index_funcs.rst", "w") as f:
+    f.write(
+        """Indexing Functions and Utilities
+=======================================
+
+The following functions are useful for performing indexing and oter associated operations.
+
+.. currentmodule:: blosc2
+
+.. autosummary::
+
+"""
+    )
+    genbody(f, blosc2_indexfuncs)
+
+# GENERATE linear_algebra.rst
+linalg_funcs = [
+    name
+    for name, obj in vars(blosc2.linalg).items()
+    if (inspect.isfunction(obj) and getattr(obj, "__doc__", None))
+]
+
+with open("reference/linalg.rst", "w") as f:
+    f.write(
+        """Linear Algebra
+-----------------
+The following functions can be used for computing linear algebra operations with :ref:`NDArray <NDArray>`.
+
+.. currentmodule:: blosc2.linalg
+
+.. autosummary::
+
+"""
+    )
+    genbody(f, linalg_funcs, "blosc2.linalg")
 
 hidden = "_ignore_multiple_size"
 

doc/reference/additional_funcs.rst

@@ -0,0 +1,61 @@
+Additional Functions and Type Utilities
+=======================================
+
+Functions
+---------
+
+The following functions can also be used for computing with any of :ref:`NDArray <NDArray>`, :ref:`C2Array <C2Array>`, :ref:`NDField <NDField>` and :ref:`LazyExpr <LazyExpr>`.
+
+Their result is typically a :ref:`LazyExpr` instance, which can be evaluated (with ``compute`` or ``__getitem__``) to get the actual values of the computation.
+
+.. currentmodule:: blosc2
+
+.. autosummary::
+
+    clip
+    conj
+    contains
+    imag
+    real
+    round
+    where
+
+
+
+.. autofunction:: blosc2.clip
+
+.. autofunction:: blosc2.conj
+
+.. autofunction:: blosc2.contains
+
+.. autofunction:: blosc2.imag
+
+.. autofunction:: blosc2.real
+
+.. autofunction:: blosc2.round
+
+.. autofunction:: blosc2.where
+
+Type Utilities
+--------------
+
+The following functions are useful for working with datatypes.
+
+.. currentmodule:: blosc2
+
+.. autosummary::
+
+    astype
+    can_cast
+    isdtype
+    result_type
+
+
+
+.. autofunction:: blosc2.astype
+
+.. autofunction:: blosc2.can_cast
+
+.. autofunction:: blosc2.isdtype
+
+.. autofunction:: blosc2.result_type

doc/reference/array_operations.rst

@@ -4,6 +4,8 @@ Operations with arrays
 .. toctree::
     :maxdepth: 1
 
-    lazy_functions
+    ufuncs
     reduction_functions
-    linear_algebra
+    linalg
+    additional_funcs
+    index_funcs

doc/reference/index_funcs.rst

@@ -0,0 +1,38 @@
+Indexing Functions and Utilities
+=======================================
+
+The following functions are useful for performing indexing and oter associated operations.
+
+.. currentmodule:: blosc2
+
+.. autosummary::
+
+    broadcast_to
+    count_nonzero
+    expand_dims
+    indices
+    meshgrid
+    sort
+    squeeze
+    take
+    take_along_axis
+
+
+
+.. autofunction:: blosc2.broadcast_to
+
+.. autofunction:: blosc2.count_nonzero
+
+.. autofunction:: blosc2.expand_dims
+
+.. autofunction:: blosc2.indices
+
+.. autofunction:: blosc2.meshgrid
+
+.. autofunction:: blosc2.sort
+
+.. autofunction:: blosc2.squeeze
+
+.. autofunction:: blosc2.take
+
+.. autofunction:: blosc2.take_along_axis

doc/reference/lazy_functions.rst

@@ -0,0 +1,34 @@
+Linear Algebra
+-----------------
+The following functions can be used for computing linear algebra operations with :ref:`NDArray <NDArray>`.
+
+.. currentmodule:: blosc2.linalg
+
+.. autosummary::
+
+    matmul
+    tensordot
+    vecdot
+    permute_dims
+    transpose
+    matrix_transpose
+    diagonal
+    outer
+
+
+
+.. autofunction:: blosc2.linalg.matmul
+
+.. autofunction:: blosc2.linalg.tensordot
+
+.. autofunction:: blosc2.linalg.vecdot
+
+.. autofunction:: blosc2.linalg.permute_dims
+
+.. autofunction:: blosc2.linalg.transpose
+
+.. autofunction:: blosc2.linalg.matrix_transpose
+
+.. autofunction:: blosc2.linalg.diagonal
+
+.. autofunction:: blosc2.linalg.outer