Merge branch 'main' of github.com:Blosc/python-blosc2

Author: lshaw8317

.pre-commit-config.yaml

@@ -16,15 +16,15 @@ repos:
       - id: trailing-whitespace
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.13.0
+    rev: v0.13.3
     hooks:
       - id: ruff-check
         args: ["--fix", "--show-fixes"]
       - id: ruff-format
         exclude: ^bench/
 
   - repo: https://github.com/adamchainz/blacken-docs
-    rev: 1.19.1
+    rev: 1.20.0
     hooks:
       - id: blacken-docs
         additional_dependencies: [black==24.*]

ANNOUNCE.rst

@@ -10,12 +10,14 @@ which matches NumPy behaviour.
 
 You can think of Python-Blosc2 3.x as an extension of NumPy/numexpr that:
 
-- Can deal with ndarrays compressed using first-class codecs & filters.
+- Can deal with NDArray compressed objects using first-class codecs & filters.
 - Performs many kind of math expressions, including reductions, indexing...
+- Supports multi-threading and SIMD acceleration (via numexpr).
+- Can operate with data from other libraries (like PyTables, h5py, Zarr, Dask, etc).
 - Supports NumPy ufunc mechanism: mix and match NumPy and Blosc2 computations.
 - Integrates with Numba and Cython via UDFs (User Defined Functions).
 - Adheres to modern NumPy casting rules way better than numexpr.
-- Performs linear algebra operations (like ``blosc2.matmul()``).
+- Performs linear algebra operations (like ``blosc2.tensordot()``).
 
 Install it with::
 

examples/ndarray/xarray-expression.py

@@ -0,0 +1,54 @@
+#######################################################################
+# Copyright (c) 2019-present, Blosc Development Team <[email protected]>
+# All rights reserved.
+#
+# This source code is licensed under a BSD-style license (found in the
+# LICENSE file in the root directory of this source tree)
+#######################################################################
+
+# Example on how to use xarray containers as operands in Blosc2 expressions
+# Note that there is no special support for xarray in Blosc2; the techniques
+# below works for any object that implements the Array protocol (i.e. having
+# a shape and dtype attributes, and a __getitem__ method and a __len__ method.
+
+import numpy as np
+import xarray
+
+import blosc2
+
+
+class NewObj(blosc2.Array):
+    def __init__(self, a):
+        self.a = a
+
+    @property
+    def shape(self):
+        return self.a.shape
+
+    @property
+    def dtype(self):
+        return self.a.dtype
+
+    def __getitem__(self, key):
+        return self.a[key]
+
+    def __len__(self):
+        return len(self.a)
+
+
+a = np.arange(100, dtype=np.int64).reshape(10, 10)
+res = a + np.sin(a) + np.hypot(a, a) + 1
+
+a = xarray.DataArray(a)  # supported natively by blosc2; no copies
+b = NewObj(a)  #  minimal Array protocol implementation; no copies
+assert isinstance(b, blosc2.Array)  # any Array compliant object works
+c = blosc2.asarray(a)  # convert into a blosc2.NDArray; data is copied
+d = blosc2.SimpleProxy(a)  # SimpleProxy conversion; no copies
+# Define a lazy expression (defer computation until needed)
+lb = blosc2.lazyexpr("a + sin(b) + hypot(c, d) + 1")
+
+# Check!
+np.testing.assert_array_equal(lb[:], res)
+# One can also evaluate the expression directly (eager computation)
+resb2 = blosc2.evaluate("a + sin(b) + hypot(c, d) + 1")
+np.testing.assert_array_equal(resb2, res)

src/blosc2/core.py

@@ -920,6 +920,13 @@ def set_nthreads(nthreads: int) -> int:
 
     Notes
     -----
+    The number of threads can also be set via the ``BLOSC_NTHREADS`` environment
+    variable (e.g., ``export BLOSC_NTHREADS=1``). Additionally, you may want to set
+    ``NUMEXPR_NUM_THREADS`` (e.g., ``export NUMEXPR_NUM_THREADS=1``) as well since
+    numexpr is used under the hood when performing some operations.  Note that
+    this function only sets the number of threads used by Blosc, not the number
+    of threads used by numexpr.
+
     The maximum number of threads for Blosc is :math:`2^{31} - 1`. In some
     cases, Blosc gets better results if you set the number of threads
     to a value slightly below your number of cores