polars-runtime-compat 1.34.0b2__cp39-abi3-win_amd64.whl

polars/_cpu_check.py

@@ -0,0 +1,265 @@
+# Vendored parts of the code from https://github.com/flababah/cpuid.py,
+# so we replicate its copyright license.
+
+# Copyright (c) 2014 Anders Høst
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy of
+# this software and associated documentation files (the "Software"), to deal in
+# the Software without restriction, including without limitation the rights to
+# use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+# the Software, and to permit persons to whom the Software is furnished to do so,
+# subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+# FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+# COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+# IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+# CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+
+from __future__ import annotations
+
+import ctypes
+import os
+from ctypes import CFUNCTYPE, POINTER, c_long, c_size_t, c_uint32, c_ulong, c_void_p
+from typing import ClassVar
+
+"""
+Determine whether Polars can be run on the current CPU.
+
+This must be done in pure Python, before the Polars binary is imported. If we
+were to try it on the Rust side the compiler could emit illegal instructions
+before/during the CPU feature check code.
+"""
+
+_IS_WINDOWS = os.name == "nt"
+_IS_64BIT = ctypes.sizeof(ctypes.c_void_p) == 8
+
+
+def get_runtime_repr() -> str:
+    import polars._plr as plr
+
+    return plr.RUNTIME_REPR
+
+
+def _open_posix_libc() -> ctypes.CDLL:
+    # Avoid importing ctypes.util if possible.
+    try:
+        if os.uname().sysname == "Darwin":
+            return ctypes.CDLL("libc.dylib", use_errno=True)
+        else:
+            return ctypes.CDLL("libc.so.6", use_errno=True)
+    except Exception:
+        from ctypes import util as ctutil
+
+        return ctypes.CDLL(ctutil.find_library("c"), use_errno=True)
+
+
+# Posix x86_64:
+# Three first call registers : RDI, RSI, RDX
+# Volatile registers         : RAX, RCX, RDX, RSI, RDI, R8-11
+
+# Windows x86_64:
+# Three first call registers : RCX, RDX, R8
+# Volatile registers         : RAX, RCX, RDX, R8-11
+
+# cdecl 32 bit:
+# Three first call registers : Stack (%esp)
+# Volatile registers         : EAX, ECX, EDX
+
+# fmt: off
+_POSIX_64_OPC = [
+        0x53,                    # push   %rbx
+        0x89, 0xf0,              # mov    %esi,%eax
+        0x89, 0xd1,              # mov    %edx,%ecx
+        0x0f, 0xa2,              # cpuid
+        0x89, 0x07,              # mov    %eax,(%rdi)
+        0x89, 0x5f, 0x04,        # mov    %ebx,0x4(%rdi)
+        0x89, 0x4f, 0x08,        # mov    %ecx,0x8(%rdi)
+        0x89, 0x57, 0x0c,        # mov    %edx,0xc(%rdi)
+        0x5b,                    # pop    %rbx
+        0xc3                     # retq
+]
+
+_WINDOWS_64_OPC = [
+        0x53,                    # push   %rbx
+        0x89, 0xd0,              # mov    %edx,%eax
+        0x49, 0x89, 0xc9,        # mov    %rcx,%r9
+        0x44, 0x89, 0xc1,        # mov    %r8d,%ecx
+        0x0f, 0xa2,              # cpuid
+        0x41, 0x89, 0x01,        # mov    %eax,(%r9)
+        0x41, 0x89, 0x59, 0x04,  # mov    %ebx,0x4(%r9)
+        0x41, 0x89, 0x49, 0x08,  # mov    %ecx,0x8(%r9)
+        0x41, 0x89, 0x51, 0x0c,  # mov    %edx,0xc(%r9)
+        0x5b,                    # pop    %rbx
+        0xc3                     # retq
+]
+
+_CDECL_32_OPC = [
+        0x53,                    # push   %ebx
+        0x57,                    # push   %edi
+        0x8b, 0x7c, 0x24, 0x0c,  # mov    0xc(%esp),%edi
+        0x8b, 0x44, 0x24, 0x10,  # mov    0x10(%esp),%eax
+        0x8b, 0x4c, 0x24, 0x14,  # mov    0x14(%esp),%ecx
+        0x0f, 0xa2,              # cpuid
+        0x89, 0x07,              # mov    %eax,(%edi)
+        0x89, 0x5f, 0x04,        # mov    %ebx,0x4(%edi)
+        0x89, 0x4f, 0x08,        # mov    %ecx,0x8(%edi)
+        0x89, 0x57, 0x0c,        # mov    %edx,0xc(%edi)
+        0x5f,                    # pop    %edi
+        0x5b,                    # pop    %ebx
+        0xc3                     # ret
+]
+# fmt: on
+
+# From memoryapi.h
+_MEM_COMMIT = 0x1000
+_MEM_RESERVE = 0x2000
+_MEM_RELEASE = 0x8000
+_PAGE_EXECUTE_READWRITE = 0x40
+
+
+class CPUID_struct(ctypes.Structure):
+    _fields_: ClassVar[list[tuple[str, type]]] = [
+        (r, c_uint32) for r in ("eax", "ebx", "ecx", "edx")
+    ]
+
+
+class CPUID:
+    def __init__(self) -> None:
+        if _IS_WINDOWS:
+            if _IS_64BIT:
+                # VirtualAlloc seems to fail under some weird
+                # circumstances when ctypes.windll.kernel32 is
+                # used under 64 bit Python. CDLL fixes this.
+                self.win = ctypes.CDLL("kernel32.dll")
+                opc = _WINDOWS_64_OPC
+            else:
+                # Here ctypes.windll.kernel32 is needed to get the
+                # right DLL. Otherwise it will fail when running
+                # 32 bit Python on 64 bit Windows.
+                self.win = ctypes.windll.kernel32  # type: ignore[attr-defined]
+                opc = _CDECL_32_OPC
+        else:
+            opc = _POSIX_64_OPC if _IS_64BIT else _CDECL_32_OPC
+
+        size = len(opc)
+        code = (ctypes.c_ubyte * size)(*opc)
+
+        if _IS_WINDOWS:
+            self.win.VirtualAlloc.restype = c_void_p
+            self.win.VirtualAlloc.argtypes = [
+                ctypes.c_void_p,
+                ctypes.c_size_t,
+                ctypes.c_ulong,
+                ctypes.c_ulong,
+            ]
+            self.addr = self.win.VirtualAlloc(
+                None, size, _MEM_COMMIT | _MEM_RESERVE, _PAGE_EXECUTE_READWRITE
+            )
+            if not self.addr:
+                msg = "could not allocate memory for CPUID check"
+                raise MemoryError(msg)
+            ctypes.memmove(self.addr, code, size)
+        else:
+            import mmap  # Only import if necessary.
+
+            # On some platforms PROT_WRITE + PROT_EXEC is forbidden, so we first
+            # only write and then mprotect into PROT_EXEC.
+            libc = _open_posix_libc()
+            mprotect = libc.mprotect
+            mprotect.argtypes = (ctypes.c_void_p, ctypes.c_size_t, ctypes.c_int)
+            mprotect.restype = ctypes.c_int
+
+            self.mmap = mmap.mmap(
+                -1,
+                size,
+                mmap.MAP_PRIVATE | mmap.MAP_ANONYMOUS,
+                mmap.PROT_READ | mmap.PROT_WRITE,
+            )
+            self.addr = ctypes.addressof(ctypes.c_void_p.from_buffer(self.mmap))
+            self.mmap.write(code)
+
+            if mprotect(self.addr, size, mmap.PROT_READ | mmap.PROT_EXEC) != 0:
+                msg = "could not execute mprotect for CPUID check"
+                raise RuntimeError(msg)
+
+        func_type = CFUNCTYPE(None, POINTER(CPUID_struct), c_uint32, c_uint32)
+        self.func_ptr = func_type(self.addr)
+
+    def __call__(self, eax: int, ecx: int = 0) -> CPUID_struct:
+        struct = CPUID_struct()
+        self.func_ptr(struct, eax, ecx)
+        return struct
+
+    def __del__(self) -> None:
+        if _IS_WINDOWS:
+            self.win.VirtualFree.restype = c_long
+            self.win.VirtualFree.argtypes = [c_void_p, c_size_t, c_ulong]
+            self.win.VirtualFree(self.addr, 0, _MEM_RELEASE)
+
+
+def _read_cpu_flags() -> dict[str, bool]:
+    # CPU flags from https://en.wikipedia.org/wiki/CPUID
+    cpuid = CPUID()
+    cpuid1 = cpuid(1, 0)
+    cpuid7 = cpuid(7, 0)
+    cpuid81h = cpuid(0x80000001, 0)
+
+    return {
+        "sse3": bool(cpuid1.ecx & (1 << 0)),
+        "ssse3": bool(cpuid1.ecx & (1 << 9)),
+        "fma": bool(cpuid1.ecx & (1 << 12)),
+        "cmpxchg16b": bool(cpuid1.ecx & (1 << 13)),
+        "sse4.1": bool(cpuid1.ecx & (1 << 19)),
+        "sse4.2": bool(cpuid1.ecx & (1 << 20)),
+        "movbe": bool(cpuid1.ecx & (1 << 22)),
+        "popcnt": bool(cpuid1.ecx & (1 << 23)),
+        "pclmulqdq": bool(cpuid1.ecx & (1 << 1)),
+        "avx": bool(cpuid1.ecx & (1 << 28)),
+        "bmi1": bool(cpuid7.ebx & (1 << 3)),
+        "bmi2": bool(cpuid7.ebx & (1 << 8)),
+        "avx2": bool(cpuid7.ebx & (1 << 5)),
+        "lzcnt": bool(cpuid81h.ecx & (1 << 5)),
+    }
+
+
+def check_cpu_flags(feature_flags: str) -> None:
+    if not feature_flags or os.environ.get("POLARS_SKIP_CPU_CHECK"):
+        return
+
+    expected_cpu_flags = [f.lstrip("+") for f in feature_flags.split(",")]
+    supported_cpu_flags = _read_cpu_flags()
+
+    missing_features = []
+    for f in expected_cpu_flags:
+        if f not in supported_cpu_flags:
+            msg = f"unknown feature flag: {f!r}"
+            raise RuntimeError(msg)
+
+        if not supported_cpu_flags[f]:
+            missing_features.append(f)
+
+    if missing_features:
+        import warnings  # Only import if necessary.
+
+        warnings.warn(
+            f"""Missing required CPU features.
+
+The following required CPU features were not detected:
+    {", ".join(missing_features)}
+Continuing to use this version of Polars on this processor will likely result in a crash.
+Install the `polars-lts-cpu` package instead of `polars` to run Polars with better compatibility.
+
+Hint: If you are on an Apple ARM machine (e.g. M1) this is likely due to running Python under Rosetta.
+It is recommended to install a native version of Python that does not run under Rosetta x86-64 emulation.
+
+If you believe this warning to be a false positive, you can set the `POLARS_SKIP_CPU_CHECK` environment variable to bypass this check.
+""",
+            RuntimeWarning,
+            stacklevel=1,
+        )

polars/_dependencies.py

@@ -0,0 +1,355 @@
+from __future__ import annotations
+
+import re
+import sys
+from collections.abc import Hashable
+from functools import cache
+from importlib import import_module
+from importlib.util import find_spec
+from types import ModuleType
+from typing import TYPE_CHECKING, Any, ClassVar, cast
+
+_ALTAIR_AVAILABLE = True
+_DELTALAKE_AVAILABLE = True
+_FSSPEC_AVAILABLE = True
+_GEVENT_AVAILABLE = True
+_GREAT_TABLES_AVAILABLE = True
+_HYPOTHESIS_AVAILABLE = True
+_NUMPY_AVAILABLE = True
+_PANDAS_AVAILABLE = True
+_POLARS_CLOUD_AVAILABLE = True
+_PYARROW_AVAILABLE = True
+_PYDANTIC_AVAILABLE = True
+_PYICEBERG_AVAILABLE = True
+_TORCH_AVAILABLE = True
+_PYTZ_AVAILABLE = True
+
+
+class _LazyModule(ModuleType):
+    """
+    Module that can act both as a lazy-loader and as a proxy.
+
+    Notes
+    -----
+    We do NOT register this module with `sys.modules` so as not to cause
+    confusion in the global environment. This way we have a valid proxy
+    module for our own use, but it lives *exclusively* within polars.
+    """
+
+    __lazy__ = True
+
+    _mod_pfx: ClassVar[dict[str, str]] = {
+        "numpy": "np.",
+        "pandas": "pd.",
+        "pyarrow": "pa.",
+        "polars_cloud": "pc.",
+    }
+
+    def __init__(
+        self,
+        module_name: str,
+        *,
+        module_available: bool,
+    ) -> None:
+        """
+        Initialise lazy-loading proxy module.
+
+        Parameters
+        ----------
+        module_name : str
+            the name of the module to lazy-load (if available).
+
+        module_available : bool
+            indicate if the referenced module is actually available (we will proxy it
+            in both cases, but raise a helpful error when invoked if it doesn't exist).
+        """
+        self._module_available = module_available
+        self._module_name = module_name
+        self._globals = globals()
+        super().__init__(module_name)
+
+    def _import(self) -> ModuleType:
+        # import the referenced module, replacing the proxy in this module's globals
+        module = import_module(self.__name__)
+        self._globals[self._module_name] = module
+        self.__dict__.update(module.__dict__)
+        return module
+
+    def __getattr__(self, name: str) -> Any:
+        # have "hasattr('__wrapped__')" return False without triggering import
+        # (it's for decorators, not modules, but keeps "make doctest" happy)
+        if name == "__wrapped__":
+            msg = f"{self._module_name!r} object has no attribute {name!r}"
+            raise AttributeError(msg)
+
+        # accessing the proxy module's attributes triggers import of the real thing
+        if self._module_available:
+            # import the module and return the requested attribute
+            module = self._import()
+            return getattr(module, name)
+
+        # user has not installed the proxied/lazy module
+        elif name == "__name__":
+            return self._module_name
+        elif re.match(r"^__\w+__$", name) and name != "__version__":
+            # allow some minimal introspection on private module
+            # attrs to avoid unnecessary error-handling elsewhere
+            return None
+        else:
+            # all other attribute access raises a helpful exception
+            pfx = self._mod_pfx.get(self._module_name, "")
+            msg = f"{pfx}{name} requires {self._module_name!r} module to be installed"
+            raise ModuleNotFoundError(msg) from None
+
+
+def _lazy_import(module_name: str) -> tuple[ModuleType, bool]:
+    """
+    Lazy import the given module; avoids up-front import costs.
+
+    Parameters
+    ----------
+    module_name : str
+        name of the module to import, eg: "pyarrow".
+
+    Notes
+    -----
+    If the requested module is not available (eg: has not been installed), a proxy
+    module is created in its place, which raises an exception on any attribute
+    access. This allows for import and use as normal, without requiring explicit
+    guard conditions - if the module is never used, no exception occurs; if it
+    is, then a helpful exception is raised.
+
+    Returns
+    -------
+    tuple of (Module, bool)
+        A lazy-loading module and a boolean indicating if the requested/underlying
+        module exists (if not, the returned module is a proxy).
+    """
+    # check if module is LOADED
+    if module_name in sys.modules:
+        return sys.modules[module_name], True
+
+    # check if module is AVAILABLE
+    try:
+        module_spec = find_spec(module_name)
+        module_available = not (module_spec is None or module_spec.loader is None)
+    except ModuleNotFoundError:
+        module_available = False
+
+    # create lazy/proxy module that imports the real one on first use
+    # (or raises an explanatory ModuleNotFoundError if not available)
+    return (
+        _LazyModule(
+            module_name=module_name,
+            module_available=module_available,
+        ),
+        module_available,
+    )
+
+
+if TYPE_CHECKING:
+    import dataclasses
+    import html
+    import json
+    import pickle
+    import subprocess
+
+    import altair
+    import boto3
+    import deltalake
+    import fsspec
+    import gevent
+    import great_tables
+    import hypothesis
+    import numpy
+    import pandas
+    import polars_cloud
+    import pyarrow
+    import pydantic
+    import pyiceberg
+    import pyiceberg.schema
+    import pytz
+    import torch
+
+else:
+    # infrequently-used builtins
+    dataclasses, _ = _lazy_import("dataclasses")
+    html, _ = _lazy_import("html")
+    json, _ = _lazy_import("json")
+    pickle, _ = _lazy_import("pickle")
+    subprocess, _ = _lazy_import("subprocess")
+
+    # heavy/optional third party libs
+    altair, _ALTAIR_AVAILABLE = _lazy_import("altair")
+    boto3, _BOTO3_AVAILABLE = _lazy_import("boto3")
+    deltalake, _DELTALAKE_AVAILABLE = _lazy_import("deltalake")
+    fsspec, _FSSPEC_AVAILABLE = _lazy_import("fsspec")
+    gevent, _GEVENT_AVAILABLE = _lazy_import("gevent")
+    great_tables, _GREAT_TABLES_AVAILABLE = _lazy_import("great_tables")
+    hypothesis, _HYPOTHESIS_AVAILABLE = _lazy_import("hypothesis")
+    numpy, _NUMPY_AVAILABLE = _lazy_import("numpy")
+    pandas, _PANDAS_AVAILABLE = _lazy_import("pandas")
+    polars_cloud, _POLARS_CLOUD_AVAILABLE = _lazy_import("polars_cloud")
+    pyarrow, _PYARROW_AVAILABLE = _lazy_import("pyarrow")
+    pydantic, _PYDANTIC_AVAILABLE = _lazy_import("pydantic")
+    pyiceberg, _PYICEBERG_AVAILABLE = _lazy_import("pyiceberg")
+    torch, _TORCH_AVAILABLE = _lazy_import("torch")
+    pytz, _PYTZ_AVAILABLE = _lazy_import("pytz")
+
+
+@cache
+def _might_be(cls: type, type_: str) -> bool:
+    # infer whether the given class "might" be associated with the given
+    # module (in which case it's reasonable to do a real isinstance check;
+    # we defer that so as not to unnecessarily trigger module import)
+    try:
+        return any(f"{type_}." in str(o) for o in cls.mro())
+    except TypeError:
+        return False
+
+
+def _check_for_numpy(obj: Any, *, check_type: bool = True) -> bool:
+    return _NUMPY_AVAILABLE and _might_be(
+        cast(Hashable, type(obj) if check_type else obj), "numpy"
+    )
+
+
+def _check_for_pandas(obj: Any, *, check_type: bool = True) -> bool:
+    return _PANDAS_AVAILABLE and _might_be(
+        cast(Hashable, type(obj) if check_type else obj), "pandas"
+    )
+
+
+def _check_for_pyarrow(obj: Any, *, check_type: bool = True) -> bool:
+    return _PYARROW_AVAILABLE and _might_be(
+        cast(Hashable, type(obj) if check_type else obj), "pyarrow"
+    )
+
+
+def _check_for_pydantic(obj: Any, *, check_type: bool = True) -> bool:
+    return _PYDANTIC_AVAILABLE and _might_be(
+        cast(Hashable, type(obj) if check_type else obj), "pydantic"
+    )
+
+
+def _check_for_torch(obj: Any, *, check_type: bool = True) -> bool:
+    return _TORCH_AVAILABLE and _might_be(
+        cast(Hashable, type(obj) if check_type else obj), "torch"
+    )
+
+
+def _check_for_pytz(obj: Any, *, check_type: bool = True) -> bool:
+    return _PYTZ_AVAILABLE and _might_be(
+        cast(Hashable, type(obj) if check_type else obj), "pytz"
+    )
+
+
+def import_optional(
+    module_name: str,
+    err_prefix: str = "required package",
+    err_suffix: str = "not found",
+    min_version: str | tuple[int, ...] | None = None,
+    min_err_prefix: str = "requires",
+    install_message: str | None = None,
+) -> Any:
+    """
+    Import an optional dependency, returning the module.
+
+    Parameters
+    ----------
+    module_name : str
+        Name of the dependency to import.
+    err_prefix : str, optional
+        Error prefix to use in the raised exception (appears before the module name).
+    err_suffix: str, optional
+        Error suffix to use in the raised exception (follows the module name).
+    min_version : {str, tuple[int]}, optional
+        If a minimum module version is required, specify it here.
+    min_err_prefix : str, optional
+        Override the standard "requires" prefix for the minimum version error message.
+    install_message : str, optional
+        Override the standard "Please install it using..." exception message fragment.
+
+    Examples
+    --------
+    >>> from polars._dependencies import import_optional
+    >>> import_optional(
+    ...     "definitely_a_real_module",
+    ...     err_prefix="super-important package",
+    ... )  # doctest: +SKIP
+    ImportError: super-important package 'definitely_a_real_module' not installed.
+    Please install it using the command `pip install definitely_a_real_module`.
+    """
+    from polars._utils.various import parse_version
+    from polars.exceptions import ModuleUpgradeRequiredError
+
+    module_root = module_name.split(".", 1)[0]
+    try:
+        module = import_module(module_name)
+    except ImportError:
+        prefix = f"{err_prefix.strip(' ')} " if err_prefix else ""
+        suffix = f" {err_suffix.strip(' ')}" if err_suffix else ""
+        err_message = f"{prefix}'{module_name}'{suffix}.\n" + (
+            install_message
+            or f"Please install using the command `pip install {module_root}`."
+        )
+        raise ModuleNotFoundError(err_message) from None
+
+    if min_version:
+        min_version = parse_version(min_version)
+        mod_version = parse_version(module.__version__)
+        if mod_version < min_version:
+            msg = (
+                f"{min_err_prefix} {module_root} "
+                f"{'.'.join(str(v) for v in min_version)} or higher"
+                f" (found {'.'.join(str(v) for v in mod_version)})"
+            )
+            raise ModuleUpgradeRequiredError(msg)
+
+    return module
+
+
+__all__ = [
+    # lazy-load rarely-used/heavy builtins (for fast startup)
+    "dataclasses",
+    "html",
+    "json",
+    "pickle",
+    "subprocess",
+    # lazy-load third party libs
+    "altair",
+    "boto3",
+    "deltalake",
+    "fsspec",
+    "gevent",
+    "great_tables",
+    "numpy",
+    "pandas",
+    "polars_cloud",
+    "pydantic",
+    "pyiceberg",
+    "pyarrow",
+    "torch",
+    "pytz",
+    # lazy utilities
+    "_check_for_numpy",
+    "_check_for_pandas",
+    "_check_for_pyarrow",
+    "_check_for_pydantic",
+    "_check_for_torch",
+    "_check_for_pytz",
+    # exported flags/guards
+    "_ALTAIR_AVAILABLE",
+    "_DELTALAKE_AVAILABLE",
+    "_FSSPEC_AVAILABLE",
+    "_GEVENT_AVAILABLE",
+    "_GREAT_TABLES_AVAILABLE",
+    "_HYPOTHESIS_AVAILABLE",
+    "_NUMPY_AVAILABLE",
+    "_PANDAS_AVAILABLE",
+    "_POLARS_CLOUD_AVAILABLE",
+    "_PYARROW_AVAILABLE",
+    "_PYDANTIC_AVAILABLE",
+    "_PYICEBERG_AVAILABLE",
+    "_TORCH_AVAILABLE",
+]