pyopencl 2024.2.7__cp310-cp310-macosx_11_0_arm64.whl → 2025.1__cp310-cp310-macosx_11_0_arm64.whl

pyopencl/__init__.py

@@ -1,3 +1,6 @@
+from __future__ import annotations
+
+
 __copyright__ = "Copyright (C) 2009-15 Andreas Kloeckner"
 
 __license__ = """
@@ -22,11 +25,11 @@ THE SOFTWARE.
 
 import logging
 from sys import intern
-from typing import Any, Dict, List, Optional, Sequence, Tuple, Union
+from typing import Any, Sequence
 from warnings import warn
 
 # must import, otherwise dtype registry will not be fully populated
-import pyopencl.cltypes  # noqa: F401
+import pyopencl.cltypes
 from pyopencl.version import VERSION, VERSION_STATUS, VERSION_TEXT  # noqa: F401
 
 
@@ -54,7 +57,7 @@ except ImportError:
             stacklevel=2)
     raise
 
-import numpy as np  # noqa: I003
+import numpy as np
 
 import sys
 
@@ -187,14 +190,14 @@ if not _PYPY:
 if get_cl_header_version() >= (1, 1):
     from pyopencl._cl import UserEvent  # noqa: F401
 if get_cl_header_version() >= (1, 2):
-    from pyopencl._cl import ImageDescriptor  # noqa: F401
+    from pyopencl._cl import ImageDescriptor
     from pyopencl._cl import (  # noqa: F401
         _enqueue_barrier_with_wait_list, _enqueue_fill_buffer,
         _enqueue_marker_with_wait_list, enqueue_fill_image,
         enqueue_migrate_mem_objects, unload_platform_compiler)
 
 if get_cl_header_version() >= (2, 0):
-    from pyopencl._cl import SVM, SVMAllocation, SVMPointer  # noqa: F401
+    from pyopencl._cl import SVM, SVMAllocation, SVMPointer
 
 if _cl.have_gl():
     from pyopencl._cl import (  # noqa: F401
@@ -272,7 +275,7 @@ def _find_pyopencl_include_path() -> str:
             # NOTE: only available in Python >=3.9
             from importlib.resources import files
         except ImportError:
-            from importlib_resources import files
+            from importlib_resources import files  # type: ignore[no-redef]
 
         include_path = str(files("pyopencl") / "cl")
         if not exists(include_path):
@@ -347,11 +350,11 @@ from pytools import strtobool
 
 _PYOPENCL_NO_CACHE = strtobool(os.environ.get("PYOPENCL_NO_CACHE", "false"))
 
-_DEFAULT_BUILD_OPTIONS: List[str] = []
-_DEFAULT_INCLUDE_OPTIONS: List[str] = ["-I", _find_pyopencl_include_path()]
+_DEFAULT_BUILD_OPTIONS: list[str] = []
+_DEFAULT_INCLUDE_OPTIONS: list[str] = ["-I", _find_pyopencl_include_path()]
 
 # map of platform.name to build options list
-_PLAT_BUILD_OPTIONS: Dict[str, List[str]] = {
+_PLAT_BUILD_OPTIONS: dict[str, list[str]] = {
         "Oclgrind": ["-D", "PYOPENCL_USING_OCLGRIND"],
         }
 
@@ -423,10 +426,7 @@ class Program:
         return self._get_prg().get_build_info(*args, **kwargs)
 
     def all_kernels(self):
-        result = self._get_prg().all_kernels()
-        for knl in result:
-            knl._setup(self)
-        return result
+        return self._get_prg().all_kernels()
 
     @property
     def int_ptr(self):
@@ -443,22 +443,22 @@ class Program:
             knl = Kernel(self, attr)
             # Nvidia does not raise errors even for invalid names,
             # but this will give an error if the kernel is invalid.
-            knl.num_args
-            knl._source = getattr(self, "_source", None)
+            knl.num_args  # noqa: B018
 
             if self._build_duration_info is not None:
-                build_descr, was_cached, duration = self._build_duration_info
+                build_descr, _was_cached, duration = self._build_duration_info
                 if duration > 0.2:
-                    logger.info("build program: kernel '%s' was part of a "
-                            "lengthy %s (%.2f s)" % (attr, build_descr, duration))
+                    logger.info(
+                        "build program: kernel '%s' was part of a "
+                        "lengthy %s (%.2f s)", attr, build_descr, duration)
 
                 # don't whine about build times more than once.
                 self._build_duration_info = None
 
             return knl
-        except LogicError:
+        except LogicError as err:
             raise AttributeError("'%s' was not found as a program "
-                    "info attribute or as a kernel name" % attr)
+                    "info attribute or as a kernel name" % attr) from err
 
     # {{{ build
 
@@ -666,18 +666,6 @@ def _add_functionality():
 
     # {{{ Context
 
-    context_old_init = Context.__init__
-
-    def context_init(self, devices, properties, dev_type, cache_dir=None):
-        if cache_dir is not None:
-            warn("The 'cache_dir' argument to the Context constructor "
-                "is deprecated and no longer has an effect. "
-                "It was removed because it only applied to the wrapper "
-                "object and not the context itself, leading to inconsistencies.",
-                DeprecationWarning, stacklevel=2)
-
-        context_old_init(self, devices, properties, dev_type)
-
     def context_repr(self):
         return "<pyopencl.Context at 0x{:x} on {}>".format(self.int_ptr,
                 ", ".join(repr(dev) for dev in self.devices))
@@ -780,9 +768,9 @@ def _add_functionality():
 
             try:
                 inf_attr = getattr(info_cls, name.upper())
-            except AttributeError:
+            except AttributeError as err:
                 raise AttributeError("%s has no attribute '%s'"
-                        % (type(self), name))
+                        % (type(self), name)) from err
             else:
                 return self.event.get_profiling_info(inf_attr)
 
@@ -792,31 +780,9 @@ def _add_functionality():
 
     # {{{ Kernel
 
-    kernel_old_init = Kernel.__init__
     kernel_old_get_info = Kernel.get_info
     kernel_old_get_work_group_info = Kernel.get_work_group_info
 
-    def kernel_init(self, prg, name):
-        if not isinstance(prg, _cl._Program):
-            prg = prg._get_prg()
-
-        kernel_old_init(self, prg, name)
-
-        self._setup(prg)
-
-    def kernel__setup(self, prg):
-        self._source = getattr(prg, "_source", None)
-
-        from pyopencl.invoker import generate_enqueue_and_set_args
-        self._enqueue, self._set_args = generate_enqueue_and_set_args(
-                self.function_name, self.num_args, self.num_args,
-                None,
-                warn_about_arg_count_bug=None,
-                work_around_arg_count_bug=None, devs=self.context.devices)
-
-        self._wg_info_cache = {}
-        return self
-
     def kernel_set_arg_types(self, arg_types):
         arg_types = tuple(arg_types)
 
@@ -845,38 +811,31 @@ def _add_functionality():
         # }}}
 
         from pyopencl.invoker import generate_enqueue_and_set_args
-        self._enqueue, self.set_args = \
-                generate_enqueue_and_set_args(
+        self._set_enqueue_and_set_args(
+                *generate_enqueue_and_set_args(
                         self.function_name,
                         len(arg_types), self.num_args,
                         arg_types,
                         warn_about_arg_count_bug=warn_about_arg_count_bug,
                         work_around_arg_count_bug=work_around_arg_count_bug,
-                        devs=self.context.devices)
+                        devs=self.context.devices))
 
     def kernel_get_work_group_info(self, param, device):
+        try:
+            wg_info_cache = self._wg_info_cache
+        except AttributeError:
+            wg_info_cache = self._wg_info_cache = {}
+
         cache_key = (param, device.int_ptr)
         try:
-            return self._wg_info_cache[cache_key]
+            return wg_info_cache[cache_key]
         except KeyError:
             pass
 
         result = kernel_old_get_work_group_info(self, param, device)
-        self._wg_info_cache[cache_key] = result
+        wg_info_cache[cache_key] = result
         return result
 
-    def kernel_set_args(self, *args, **kwargs):
-        # Need to duplicate the 'self' argument for dynamically generated  method
-        return self._set_args(self, *args, **kwargs)
-
-    def kernel_call(self, queue, global_size, local_size, *args, **kwargs):
-        # __call__ can't be overridden directly, so we need this
-        # trampoline hack.
-
-        # Note: This is only used for the generic __call__, before
-        # kernel_set_scalar_arg_dtypes is called.
-        return self._enqueue(self, queue, global_size, local_size, *args, **kwargs)
-
     def kernel_capture_call(self, output_file, queue, global_size, local_size,
             *args, **kwargs):
         from pyopencl.capture_call import capture_kernel_call
@@ -891,16 +850,12 @@ def _add_functionality():
         else:
             return val
 
-    Kernel.__init__ = kernel_init
-    Kernel._setup = kernel__setup
     Kernel.get_work_group_info = kernel_get_work_group_info
 
     # FIXME: Possibly deprecate this version
     Kernel.set_scalar_arg_dtypes = kernel_set_arg_types
     Kernel.set_arg_types = kernel_set_arg_types
 
-    Kernel.set_args = kernel_set_args
-    Kernel.__call__ = kernel_call
     Kernel.capture_call = kernel_capture_call
     Kernel.get_info = kernel_get_info
 
@@ -934,10 +889,30 @@ def _add_functionality():
 
     # {{{ Image
 
-    image_old_init = Image.__init__
+    def image_init(
+                self, context, flags, format, shape=None, pitches=None,
+                hostbuf=None, is_array=False, buffer=None, *,
+                desc: ImageDescriptor | None = None,
+                _through_create_image: bool = False,
+            ) -> None:
+        if hostbuf is not None and not \
+                (flags & (mem_flags.USE_HOST_PTR | mem_flags.COPY_HOST_PTR)):
+            warn("'hostbuf' was passed, but no memory flags to make use of it.",
+                 stacklevel=2)
+
+        if desc is not None:
+            if shape is not None:
+                raise TypeError("shape may not be passed when using descriptor")
+            if pitches is not None:
+                raise TypeError("pitches may not be passed when using descriptor")
+            if is_array:
+                raise TypeError("is_array may not be passed when using descriptor")
+            if buffer is not None:
+                raise TypeError("is_array may not be passed when using descriptor")
 
-    def image_init(self, context, flags, format, shape=None, pitches=None,
-            hostbuf=None, is_array=False, buffer=None):
+            Image._custom_init(self, context, flags, format, desc, hostbuf)
+
+            return
 
         if shape is None and hostbuf is None:
             raise Error("'shape' must be passed if 'hostbuf' is not given")
@@ -945,15 +920,16 @@ def _add_functionality():
         if shape is None and hostbuf is not None:
             shape = hostbuf.shape
 
-        if hostbuf is not None and not \
-                (flags & (mem_flags.USE_HOST_PTR | mem_flags.COPY_HOST_PTR)):
-            warn("'hostbuf' was passed, but no memory flags to make use of it.",
-                 stacklevel=2)
-
         if hostbuf is None and pitches is not None:
             raise Error("'pitches' may only be given if 'hostbuf' is given")
 
         if context._get_cl_version() >= (1, 2) and get_cl_header_version() >= (1, 2):
+            if not _through_create_image:
+                warn("Non-descriptor Image constructor called. "
+                     "This will stop working in 2026. "
+                     "Use create_image instead (with the same arguments).",
+                     DeprecationWarning, stacklevel=2)
+
             if buffer is not None and is_array:
                 raise ValueError(
                         "'buffer' and 'is_array' are mutually exclusive")
@@ -1002,7 +978,7 @@ def _add_functionality():
             desc.num_samples = 0  # per CL 1.2 spec
             desc.buffer = buffer
 
-            image_old_init(self, context, flags, format, desc, hostbuf)
+            Image._custom_init(self, context, flags, format, desc, hostbuf)
         else:
             # legacy init for CL 1.1 and older
             if is_array:
@@ -1016,7 +992,7 @@ def _add_functionality():
             if buffer is not None:
                 raise TypeError("'buffer' argument is not supported for CL < 1.2")
 
-            image_old_init(self, context, flags, format, shape,
+            Image._custom_init(self, context, flags, format, shape,
                     pitches, hostbuf)
 
     class _ImageInfoGetter:
@@ -1030,9 +1006,9 @@ def _add_functionality():
         def __getattr__(self, name):
             try:
                 inf_attr = getattr(_cl.image_info, name.upper())
-            except AttributeError:
+            except AttributeError as err:
                 raise AttributeError("%s has no attribute '%s'"
-                        % (type(self), name))
+                        % (type(self), name)) from err
             else:
                 return self.event.get_image_info(inf_attr)
 
@@ -1055,7 +1031,7 @@ def _add_functionality():
     def error_str(self):
         val = self.what
         try:
-            val.routine
+            val.routine  # noqa: B018
         except AttributeError:
             return str(val)
         else:
@@ -1151,8 +1127,8 @@ def _add_functionality():
             """
 
     def svmptr_map(self, queue: CommandQueue, *, flags: int, is_blocking: bool =
-                   True, wait_for: Optional[Sequence[Event]] = None,
-                   size: Optional[Event] = None) -> "SVMMap":
+                   True, wait_for: Sequence[Event] | None = None,
+                   size: Event | None = None) -> SVMMap:
         """
         :arg is_blocking: If *False*, subsequent code must wait on
             :attr:`SVMMap.event` in the returned object before accessing the
@@ -1170,8 +1146,8 @@ def _add_functionality():
                                     size=size))
 
     def svmptr_map_ro(self, queue: CommandQueue, *, is_blocking: bool = True,
-                      wait_for: Optional[Sequence[Event]] = None,
-                      size: Optional[int] = None) -> "SVMMap":
+                      wait_for: Sequence[Event] | None = None,
+                      size: int | None = None) -> SVMMap:
         """Like :meth:`map`, but with *flags* set for a read-only map.
         """
 
@@ -1179,8 +1155,8 @@ def _add_functionality():
                 is_blocking=is_blocking, wait_for=wait_for, size=size)
 
     def svmptr_map_rw(self, queue: CommandQueue, *, is_blocking: bool = True,
-                      wait_for: Optional[Sequence[Event]] = None,
-                      size: Optional[int] = None) -> "SVMMap":
+                      wait_for: Sequence[Event] | None = None,
+                      size: int | None = None) -> SVMMap:
         """Like :meth:`map`, but with *flags* set for a read-only map.
         """
 
@@ -1190,8 +1166,8 @@ def _add_functionality():
     def svmptr__enqueue_unmap(self, queue, wait_for=None):
         return _cl._enqueue_svm_unmap(queue, self, wait_for)
 
-    def svmptr_as_buffer(self, ctx: Context, *, flags: Optional[int] = None,
-                         size: Optional[int] = None) -> Buffer:
+    def svmptr_as_buffer(self, ctx: Context, *, flags: int | None = None,
+                         size: int | None = None) -> Buffer:
         """
         :arg ctx: a :class:`Context`
         :arg flags: a combination of :class:`pyopencl.map_flags`, defaults to
@@ -1359,15 +1335,6 @@ def _add_functionality():
 
     # }}}
 
-    if get_cl_header_version() >= (2, 0):
-        svm_old_init = SVM.__init__
-
-    def svm_init(self, mem):
-        if get_cl_header_version() >= (2, 0):
-            svm_old_init(self, mem)
-
-        self.mem = mem
-
     def svm_map(self, queue, flags, is_blocking=True, wait_for=None):
         """
         :arg is_blocking: If *False*, subsequent code must wait on
@@ -1404,7 +1371,6 @@ def _add_functionality():
         return _cl._enqueue_svm_unmap(queue, self, wait_for)
 
     if get_cl_header_version() >= (2, 0):
-        SVM.__init__ = svm_init
         SVM.map = svm_map
         SVM.map_ro = svm_map_ro
         SVM.map_rw = svm_map_rw
@@ -1532,10 +1498,48 @@ if get_cl_header_version() >= (2, 0):
 # }}}
 
 
+# {{{ create_image
+
+def create_image(context, flags, format, shape=None, pitches=None,
+        hostbuf=None, is_array=False, buffer=None) -> Image:
+    """
+    See :class:`mem_flags` for values of *flags*.
+    *shape* is a 2- or 3-tuple. *format* is an instance of :class:`ImageFormat`.
+    *pitches* is a 1-tuple for 2D images and a 2-tuple for 3D images, indicating
+    the distance in bytes from one scan line to the next, and from one 2D image
+    slice to the next.
+
+    If *hostbuf* is given and *shape* is *None*, then *hostbuf.shape* is
+    used as the *shape* parameter.
+
+    :class:`Image` inherits from :class:`MemoryObject`.
+
+    .. note::
+
+        If you want to load images from :class:`numpy.ndarray` instances or read images
+        back into them, be aware that OpenCL images expect the *x* dimension to vary
+        fastest, whereas in the default (C) order of :mod:`numpy` arrays, the last index
+        varies fastest. If your array is arranged in the wrong order in memory,
+        there are two possible fixes for this:
+
+        * Convert the array to Fortran (column-major) order using :func:`numpy.asarray`.
+
+        * Pass *ary.T.copy()* to the image creation function.
+
+    .. versionadded:: 2024.3
+    """
+
+    return Image(context, flags, format, shape=shape, pitches=pitches,
+        hostbuf=hostbuf, is_array=is_array, buffer=buffer,
+        _through_create_image=True)
+
+# }}}
+
+
 # {{{ create_some_context
 
-def choose_devices(interactive: Optional[bool] = None,
-                   answers: Optional[List[str]] = None) -> List[Device]:
+def choose_devices(interactive: bool | None = None,
+                   answers: list[str] | None = None) -> list[Device]:
     """
     Choose :class:`Device` instances 'somehow'.
 
@@ -1647,7 +1651,8 @@ def choose_devices(interactive: Optional[bool] = None,
 
     if not devices:
         raise Error("no devices found")
-    elif len(devices) == 1:
+    elif len(devices) == 1 and not answers:
+        cc_print(f"Choosing only available device: {devices[0]}")
         pass
     else:
         if not answers:
@@ -1671,13 +1676,13 @@ def choose_devices(interactive: Optional[bool] = None,
 
     if answers:
         raise RuntimeError("not all provided choices were used by "
-                "choose_device. (left over: '%s')" % ":".join(answers))
+                "choose_devices. (left over: '%s')" % ":".join(answers))
 
     return devices
 
 
-def create_some_context(interactive: Optional[bool] = None,
-                        answers: Optional[List[str]] = None) -> Context:
+def create_some_context(interactive: bool | None = None,
+                        answers: list[str] | None = None) -> Context:
     """
     Create a :class:`Context` 'somehow'.
 
@@ -2066,9 +2071,9 @@ def enqueue_copy(queue, dest, src, **kwargs):
 # {{{ enqueue_fill
 
 def enqueue_fill(queue: CommandQueue,
-        dest: "Union[MemoryObject, SVMPointer]",
+        dest: MemoryObject | SVMPointer,
         pattern: Any, size: int, *, offset: int = 0,
-        wait_for: Optional[Sequence[Event]] = None) -> Event:
+        wait_for: Sequence[Event] | None = None) -> Event:
     """
     .. versionadded:: 2022.2
     """
@@ -2097,7 +2102,7 @@ DTYPE_TO_CHANNEL_TYPE = {
     np.dtype(np.uint8): channel_type.UNSIGNED_INT8,
     }
 try:
-    np.float16
+    np.float16  # noqa: B018
 except Exception:
     pass
 else:
@@ -2159,7 +2164,7 @@ def image_from_array(ctx, ary, num_channels=None, mode="r", norm_int=False):
     else:
         channel_type = DTYPE_TO_CHANNEL_TYPE[dtype]
 
-    return Image(ctx, mode_flags | mem_flags.COPY_HOST_PTR,
+    return create_image(ctx, mode_flags | mem_flags.COPY_HOST_PTR,
             ImageFormat(img_format, channel_type),
             shape=shape[::-1], pitches=strides[::-1][1:],
             hostbuf=ary)
@@ -2272,12 +2277,12 @@ def svm_empty(ctx, flags, shape, dtype, order="C", alignment=None, queue=None):
         s = 1
         for dim in shape:
             s *= dim
-    except TypeError:
+    except TypeError as err:
         admissible_types = (int, np.integer)
 
         if not isinstance(shape, admissible_types):
             raise TypeError("shape must either be iterable or "
-                    "castable to an integer")
+                    "castable to an integer") from err
         s = shape
         shape = (shape,)
 
@@ -2392,14 +2397,14 @@ def fsvm_empty_like(ctx, ary, alignment=None):
 # }}}
 
 
-_KERNEL_ARG_CLASSES: Tuple[type, ...] = (
+_KERNEL_ARG_CLASSES: tuple[type, ...] = (
         MemoryObjectHolder,
         Sampler,
         CommandQueue,
         LocalMemory,
         )
 if get_cl_header_version() >= (2, 0):
-    _KERNEL_ARG_CLASSES = _KERNEL_ARG_CLASSES + (SVM,)
+    _KERNEL_ARG_CLASSES = (*_KERNEL_ARG_CLASSES, SVM)
 
 
 # vim: foldmethod=marker

pyopencl/_mymako.py

@@ -1,6 +1,6 @@
 try:
     import mako.template  # noqa: F401
-except ImportError:
+except ImportError as err:
     raise ImportError(
             "Some of PyOpenCL's facilities require the Mako templating engine.\n"
             "You or a piece of software you have used has tried to call such a\n"
@@ -9,6 +9,6 @@ except ImportError:
             "- easy_install Mako\n"
             "- pip install Mako\n"
             "- aptitude install python-mako\n"
-            "\nor whatever else is appropriate for your system.")
+            "\nor whatever else is appropriate for your system.") from err
 
-from mako import *  # noqa: F401, F403
+from mako import *  # noqa: F403

pyopencl/algorithm.py

@@ -34,6 +34,7 @@ from typing import Optional
 
 import numpy as np
 from mako.template import Template
+
 from pytools import memoize, memoize_method
 
 import pyopencl as cl
@@ -976,8 +977,10 @@ class ListOfListsBuilder:
         knl = getattr(prg, kernel_name)
 
         from pyopencl.tools import get_arg_list_scalar_arg_dtypes
-        knl.set_scalar_arg_dtypes(get_arg_list_scalar_arg_dtypes(
-            kernel_list_args+self.arg_decls) + [index_dtype])
+        knl.set_scalar_arg_dtypes([
+            *get_arg_list_scalar_arg_dtypes([*kernel_list_args, *self.arg_decls]),
+            index_dtype
+            ])
 
         return knl
 
@@ -1049,8 +1052,9 @@ class ListOfListsBuilder:
         knl = getattr(prg, kernel_name)
 
         from pyopencl.tools import get_arg_list_scalar_arg_dtypes
-        knl.set_scalar_arg_dtypes(get_arg_list_scalar_arg_dtypes(
-            kernel_list_args+self.arg_decls) + [index_dtype])
+        knl.set_scalar_arg_dtypes([
+            *get_arg_list_scalar_arg_dtypes(kernel_list_args + self.arg_decls),
+            index_dtype])
 
         return knl
 
@@ -1226,14 +1230,13 @@ class ListOfListsBuilder:
                 queue, (n_objects + 1,), index_dtype, allocator=allocator)
             info_record.compressed_indices[0] = 0
 
-            compress_events[name] = compress_kernel( \
-                # pylint: disable=possibly-used-before-assignment
+            compress_events[name] = compress_kernel(  # pylint: disable=possibly-used-before-assignment
                 info_record.starts,
                 compressed_counts,
                 info_record.nonempty_indices,
                 info_record.compressed_indices,
                 info_record.num_nonempty_lists,
-                wait_for=[count_event] + info_record.compressed_indices.events)
+                wait_for=[count_event, *info_record.compressed_indices.events])
 
             info_record.starts = compressed_counts