=========================
NumPy 2.0.0 Release Notes
=========================

[Possibly 1.7.0 release notes, as ABI compatibility is still being maintained]

Highlights
==========


New features
============


Mask-based NA missing values
----------------------------

Support for NA missing values similar to those in R has been implemented.
This was done by adding optional NA masks to the core array object.

While a significant amount of the NumPy functionality has been extended to
support NA masks, not everything is yet supported. Here is a list of things
that do and do not work with NA values:

What works with NA:
    * Basic indexing and slicing, as well as full boolean mask indexing.
    * All element-wise ufuncs.
    * UFunc.reduce methods, with a new skipna parameter.
    * The nditer object.
    * Array methods:
       + ndarray.clip, ndarray.min, ndarray.max, ndarray.sum, ndarray.prod,
         ndarray.conjugate, ndarray.diagonal, ndarray.flatten
       + numpy.concatenate, numpy.column_stack, numpy.hstack,
         numpy.vstack, numpy.dstack

What doesn't work with NA:
    * Fancy indexing, such as with lists and partial boolean masks.
    * ndarray.flat and any other methods that use the old iterator
      mechanism instead of the newer nditer.
    * Struct dtypes, which will have corresponding struct masks with
      one mask value per primitive field of the struct dtype.
    * UFunc.reduce of multi-dimensional arrays, with skipna=True and a ufunc
      that doesn't have an identity.
    * UFunc.accumulate, UFunc.reduceat.
    * np.logical_and, np.logical_or, np.all, and np.any don't satisfy the
      rules NA | True == True and NA & False == False yet.
    * Array methods:
       + ndarray.argmax, ndarray.argmin,
       + numpy.repeat, numpy.delete (relies on fancy indexing),
         numpy.append, numpy.insert (relies on fancy indexing),
         numpy.where,



Custom formatter for printing arrays
------------------------------------



Changes
=======

The default casting rule for UFunc out= parameters has been changed from
'unsafe' to 'same_kind'.  Most usages which violate the 'same_kind'
rule are likely bugs, so this change may expose previously undetected
errors in projects that depend on NumPy.

The functions np.diag, np.diagonal, and <ndarray>.diagonal now return a
view into the original array instead of making a copy. This makes these
functions more consistent with NumPy's general approach of taking views
where possible, and performs much faster as well.

The function np.concatenate tries to match the layout of its input
arrays. Previously, the layout did not follow any particular reason,
and depended in an undesirable way on the particular axis chosen for
concatenation. A bug was also fixed which silently allowed out of bounds
axis arguments.


Deprecations
============

Specifying a custom string formatter with a `_format` array attribute is
deprecated. The new `formatter` keyword in ``numpy.set_printoptions`` or
``numpy.array2string`` can be used instead.

In the C API, direct access to the fields of PyArrayObject* has been
deprecated. Direct access has been recommended against for many releases, but
now you can test your code against the deprecated C API by #defining
NPY_NO_DEPRECATED_API before including any NumPy headers. Expect
something similar for PyArray_Descr* and other core objects in the
future as preparation for NumPy 2.0.