Implementaion of #29499

Description

This PR introduces a new parameter, ndmax, to the np.array function. This parameter allows users to explicitly limit the maximum number of dimensions that NumPy will create when converting nested sequences (like lists of lists) into an array.

To ensure backward compatibility, the default behavior remains unchanged. When ndmax is not specified, the function falls back to its current heuristic. This means it will create as many dimensions as possible from nested sequences, up to the compile-time limit defined by NPY_MAXDIMS.

Motivation and Context

As discussed in issue #29499, the current behavior of np.array can lead to unexpected results when dtype=object is specified. For example:

• A list of lists with non-uniform lengths correctly creates a 1D array of list objects.
• A list of lists with uniform lengths is implicitly promoted to a 2D ndarray, even with dtype=object.

This inconsistency arises because, as @rkern explained, NumPy has a strong heuristic that assumes uniformly nested sequences are intended to be multi-dimensional arrays. While this is often the desired outcome, it overrides the user's explicit intent in cases where a 1D array of list objects is needed, regardless of their shape. This can cause subtle bugs, particularly in data processing pipelines for machine learning.

The existing workarounds, such as pre-allocating with np.empty and then assigning or using np.fromiter, are effective but less intuitive than a direct parameter. The addition of ndmax provides a clear and explicit way to control this behavior directly within the most commonly used array creation function.

How to use ndmax

The ndmax parameter provides fine-grained control over the array creation process.

• Current Behavior (Unexpected Promotion):

# Even with dtype=object, this creates a 2D NumPy array
b = np.array([[1, 2, 3], [4, 5, 6]], dtype=object)
print(b.shape)      # (2, 3)
print(type(b[0]))   # <class 'numpy.ndarray'>

• New Behavior with ndmax=1 (Desired Outcome):

# With ndmax=1, NumPy stops at 1 dimension, preserving inner lists
b_new = np.array([[1, 2, 3], [4, 5, 6]], dtype=object, ndmax=1)
print(b_new.shape)      # (2,)
print(type(b_new[0]))   # <class 'list'>

This aligns the behavior for uniform lists with that of non-uniform lists when the user's intent is to create an array of objects.

Implementation Details

The implementation was made straightforward by leveraging the pre-existing max_depth parameter in the core C-API function, PyArray_FromAny_int. The new Python-level ndmax argument is passed directly to this internal parameter.

This approach ensures that the new feature is built upon NumPy's established and tested array creation logic, minimizing risk and maintaining internal consistency.