NumPy数组中数值类型提示的最佳实践

# 摘自 NumPy 核心库中 np.ndarray 的 __add__ 方法定义（简化版）
from typing import Union
import numpy as np

# 概念性展示：np.ndarray 的 __add__ 方法签名
# def __add__(self: np.ndarray, other: Union[int, float, np.ndarray], /) -> np.ndarray:
#     # ... 实际的加法逻辑 ...
#     pass

# 摘自 NumPy 核心库中 numpy.arange 函数定义（简化版）
from typing import Union, Optional
import numpy as np

def arange(
    start: Union[int, float],
    /, # 表示此参数为仅限位置参数
    stop: Optional[Union[int, float]] = None,
    step: Union[int, float] = 1,
    *, # 表示后续参数为仅限关键字参数
    dtype: Optional[np.dtype] = None,
    # ... 其他参数 ...
) -> np.ndarray:
    """
    Return evenly spaced values within a given interval.
    """
    return np.arange(start, stop, step, dtype=dtype)

# 示例调用
arr1 = arange(0, 10, 1) # 使用 Python int
arr2 = arange(0.0, 5.0, 0.5) # 使用 Python float
arr3 = arange(np.float64(0), np.int32(5), np.float32(0.5)) # 使用 NumPy 标量

from typing import Union
import numpy as np

def process_value_with_array(
    data_array: np.ndarray,
    value: Union[int, float]
) -> np.ndarray:
    """
    处理一个NumPy数组和一个数值。
    该数值可以是Python的int/float，也可以是NumPy的标量类型。

    Args:
        data_array: 输入的NumPy数组。
        value: 要处理的数值，可以是整数或浮点数（包括NumPy标量）。

    Returns:
        经过数值处理后的新NumPy数组。
    """
    # 示例操作：将数组中所有大于 'value' 的元素设为 'value'
    return np.where(data_array > value, value, data_array)

# 测试不同类型的输入
my_array = np.array([[1.5, 2.7, 3.1], [4.0, 0.9, 2.2]], dtype=np.float64)

# 1. 使用 Python 内置 float
result1 = process_value_with_array(my_array, 2.5)
print("使用 Python float:", result1)
# 预期输出: [[1.5 2.5 2.5] [2.5 0.9 2.2]]

# 2. 使用 Python 内置 int
result2 = process_value_with_array(my_array, 2)
print("使用 Python int:", result2)
# 预期输出: [[1.5 2.  2. ] [2.  0.9 2.2]]

# 3. 使用 NumPy float64 标量
numpy_float_scalar = my_array[0, 1] # np.float64(2.7)
result3 = process_value_with_array(my_array, numpy_float_scalar)
print("使用 NumPy float64:", result3)
# 预期输出: [[1.5 2.7 2.7] [2.7 0.9 2.2]]

# 4. 使用 NumPy int32 标量（假设有一个整数数组）
int_array = np.array([[10, 20], [30, 40]], dtype=np.int32)
numpy_int_scalar = int_array[0, 0] # np.int32(10)
result4 = process_value_with_array(int_array, numpy_int_scalar)
print("使用 NumPy int32:", result4)
# 预期输出: [[10 10] [10 10]]