{ "__type": "IngestedDoc", "__tag": 4010, "_content": {}, "_ordered_sections": [], "item_file": null, "item_line": null, "item_type": null, "aliases": [], "example_section_data": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "see_also": [], "signature": null, "references": null, "qa": "numpy_2_0_migration_guide", "arbitrary": [ { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This document contains a set of instructions on how to update your code to work with NumPy 2.0. It covers changes in NumPy's Python and C APIs." } ] }, { "__type": "Admonition", "__tag": 4056, "kind": "note", "base_type": "note", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "note " } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Note that NumPy 2.0 also breaks binary compatibility - if you are distributing binaries for a Python package that depends on NumPy's C API, please see " }, { "__type": "CrossRef", "__tag": 4002, "value": "numpy-2-abi-handling", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "docs", "path": "dev:depending_on_numpy" }, "kind": "exists" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "NumPy 2.0 migration guide" } ], "level": 0, "target": "numpy-2-migration-guide" }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Many of the changes covered in the 2.0 release notes and in this migration guide can be automatically adapted in downstream code with a dedicated " }, { "__type": "Link", "__tag": 4049, "children": [ { "__type": "Text", "__tag": 4046, "value": "Ruff" } ], "url": "https://docs.astral.sh/ruff/", "title": "" }, { "__type": "Text", "__tag": 4046, "value": " rule, namely rule " }, { "__type": "Link", "__tag": 4049, "children": [ { "__type": "Text", "__tag": 4046, "value": "NPY201" } ], "url": "https://docs.astral.sh/ruff/rules/numpy2-deprecation/", "title": "" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "You should install " }, { "__type": "InlineCode", "__tag": 4051, "value": "ruff>=0.4.8" }, { "__type": "Text", "__tag": 4046, "value": " and add the " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY201" }, { "__type": "Text", "__tag": 4046, "value": " rule to your " }, { "__type": "InlineCode", "__tag": 4051, "value": "pyproject.toml" }, { "__type": "Text", "__tag": 4046, "value": " " } ] }, { "__type": "Code", "__tag": 4050, "value": "[tool.ruff.lint]\nselect = [\"NPY201\"]", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "You can also apply the NumPy 2.0 rule directly from the command line " } ] }, { "__type": "Code", "__tag": 4050, "value": "$ ruff check path/to/code/ --select NPY201", "execution_status": null } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Ruff plugin" } ], "level": 1, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "NumPy 2.0 changes promotion (the result of combining dissimilar data types) as per " }, { "__type": "InlineRole", "__tag": 4003, "value": "NEP 50 ", "domain": null, "role": "ref", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": ". Please see the NEP for details on this change. It includes a table of example changes and a backwards compatibility section." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The largest backwards compatibility change is that the precision of scalars is now preserved consistently. Two examples are:" } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "np.float32(3) + 3." }, { "__type": "Text", "__tag": 4046, "value": " now returns a float32 when it previously returned a float64." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "np.array([3], dtype=np.float32) + np.float64(3)" }, { "__type": "Text", "__tag": 4046, "value": " will now return a float64 array. (The higher precision of the scalar is not ignored.)" } ] } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "For floating point values, this can lead to lower precision results when working with scalars. For integers, errors or overflows are possible." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "To solve this, you may cast explicitly. Very often, it may also be a good solution to ensure you are working with Python scalars via " }, { "__type": "InlineCode", "__tag": 4051, "value": "int()" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "float()" }, { "__type": "Text", "__tag": 4046, "value": ", or " }, { "__type": "InlineCode", "__tag": 4051, "value": "numpy_scalar.item()" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "To track down changes, you can enable emitting warnings for changed behavior (use " }, { "__type": "InlineCode", "__tag": 4051, "value": "warnings.simplefilter" }, { "__type": "Text", "__tag": 4046, "value": " to raise it as an error for a traceback) " } ] }, { "__type": "Code", "__tag": 4050, "value": "np._set_promotion_state(\"weak_and_warn\")", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "which is useful during testing. Unfortunately, running this may flag many changes that are irrelevant in practice." } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Changes to NumPy data type promotion" } ], "level": 1, "target": "migration_promotion_changes" }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The default integer used by NumPy is now 64bit on all 64bit systems (and 32bit on 32bit system). For historic reasons related to Python 2 it was previously equivalent to the C " }, { "__type": "InlineCode", "__tag": 4051, "value": "long" }, { "__type": "Text", "__tag": 4046, "value": " type. The default integer is now equivalent to " }, { "__type": "InlineCode", "__tag": 4051, "value": "np.intp" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Most end-users should not be affected by this change. Some operations will use more memory, but some operations may actually become faster. If you experience issues due to calling a library written in a compiled language it may help to explicitly cast to a " }, { "__type": "InlineCode", "__tag": 4051, "value": "long" }, { "__type": "Text", "__tag": 4046, "value": ", for example with: " }, { "__type": "InlineCode", "__tag": 4051, "value": "arr = arr.astype(\"long\", copy=False)" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Libraries interfacing with compiled code that are written in C, Cython, or a similar language may require updating to accommodate user input if they are using the " }, { "__type": "InlineCode", "__tag": 4051, "value": "long" }, { "__type": "Text", "__tag": 4046, "value": " or equivalent type on the C-side. In this case, you may wish to use " }, { "__type": "InlineCode", "__tag": 4051, "value": "intp" }, { "__type": "Text", "__tag": 4046, "value": " and cast user input or support both " }, { "__type": "InlineCode", "__tag": 4051, "value": "long" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineCode", "__tag": 4051, "value": "intp" }, { "__type": "Text", "__tag": 4046, "value": " (to better support NumPy 1.x as well). When creating a new integer array in C or Cython, the new " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_DEFAULT_INT" }, { "__type": "Text", "__tag": 4046, "value": " macro will evaluate to either " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_LONG" }, { "__type": "Text", "__tag": 4046, "value": " or " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_INTP" }, { "__type": "Text", "__tag": 4046, "value": " depending on the NumPy version." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Note that the NumPy random API is not affected by this change." } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Windows default integer" } ], "level": 1, "target": "migration_windows_int64" }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Some definitions were removed or replaced due to being outdated or unmaintainable. Some new API definitions will evaluate differently at runtime between NumPy 2.0 and NumPy 1.x. Some are defined in " }, { "__type": "InlineCode", "__tag": 4051, "value": "numpy/_core/include/numpy/npy_2_compat.h" }, { "__type": "Text", "__tag": 4046, "value": " (for example " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_DEFAULT_INT" }, { "__type": "Text", "__tag": 4046, "value": ") which can be vendored in full or part to have the definitions available when compiling against NumPy 1.x." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If necessary, " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyArray_RUNTIME_VERSION >= NPY_2_0_API_VERSION" }, { "__type": "Text", "__tag": 4046, "value": " can be used to explicitly implement different behavior on NumPy 1.x and 2.0. (The compat header defines it in a way compatible with such use.)" } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Please let us know if you require additional workarounds here." } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "C-API Changes" } ], "level": 1, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "One of the most impactful C-API changes is that the " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyArray_Descr" }, { "__type": "Text", "__tag": 4046, "value": " struct is now more opaque to allow us to add additional flags and have itemsizes not limited by the size of " }, { "__type": "InlineCode", "__tag": 4051, "value": "int" }, { "__type": "Text", "__tag": 4046, "value": " as well as allow improving structured dtypes in the future and not burden new dtypes with their fields." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Code which only uses the type number and other initial fields is unaffected. Most code will hopefully mainly access the " }, { "__type": "InlineCode", "__tag": 4051, "value": "->elsize" }, { "__type": "Text", "__tag": 4046, "value": " field, when the dtype/descriptor itself is attached to an array (e.g. " }, { "__type": "InlineCode", "__tag": 4051, "value": "arr->descr->elsize" }, { "__type": "Text", "__tag": 4046, "value": ") this is best replaced with " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyArray_ITEMSIZE(arr)" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Where not possible, new accessor functions are required:" } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "PyDataType_ELSIZE" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyDataType_SET_ELSIZE" }, { "__type": "Text", "__tag": 4046, "value": " (note that the result is now " }, { "__type": "InlineCode", "__tag": 4051, "value": "npy_intp" }, { "__type": "Text", "__tag": 4046, "value": " and not " }, { "__type": "InlineCode", "__tag": 4051, "value": "int" }, { "__type": "Text", "__tag": 4046, "value": ")." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "PyDataType_ALIGNMENT" } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "PyDataType_FIELDS" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyDataType_NAMES" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyDataType_SUBARRAY" } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "PyDataType_C_METADATA" } ] } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Cython code should use Cython 3, in which case the change is transparent. (Struct access is available for elsize and alignment when compiling only for NumPy 2.)" } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "For compiling with both 1.x and 2.x if you use these new accessors it is unfortunately necessary to either define them locally via a macro like " } ] }, { "__type": "Code", "__tag": 4050, "value": "#if NPY_ABI_VERSION < 0x02000000\n #define PyDataType_ELSIZE(descr) ((descr)->elsize)\n#endif", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "or adding " }, { "__type": "InlineCode", "__tag": 4051, "value": "npy2_compat.h" }, { "__type": "Text", "__tag": 4046, "value": " into your code base and explicitly include it when compiling with NumPy 1.x (as they are new API). Including the file has no effect on NumPy 2." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Please do not hesitate to open a NumPy issue, if you require assistance or the provided functions are not sufficient." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Strong", "__tag": 4048, "children": [ { "__type": "Text", "__tag": 4046, "value": "Custom User DTypes:" } ] }, { "__type": "Text", "__tag": 4046, "value": " Existing user dtypes must now use " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyArray_DescrProto" }, { "__type": "Text", "__tag": 4046, "value": " to define their dtype and slightly modify the code. See note in " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyArray_RegisterDataType" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "The " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyArray_Descr" }, { "__type": "Text", "__tag": 4046, "value": " struct has been changed" } ], "level": 2, "target": "migration_c_descr" }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If you previously included only " }, { "__type": "InlineCode", "__tag": 4051, "value": "ndarraytypes.h" }, { "__type": "Text", "__tag": 4046, "value": " you may find that some functionality is not available anymore and requires the inclusion of " }, { "__type": "InlineCode", "__tag": 4051, "value": "ndarrayobject.h" }, { "__type": "Text", "__tag": 4046, "value": " or similar. This include is also needed when vendoring " }, { "__type": "InlineCode", "__tag": 4051, "value": "npy_2_compat.h" }, { "__type": "Text", "__tag": 4046, "value": " into your own codebase to allow use of the new definitions when compiling with NumPy 1.x." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Functionality which previously did not require import includes:" } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Functions to access dtype flags: " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyDataType_FLAGCHK" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyDataType_REFCHK" }, { "__type": "Text", "__tag": 4046, "value": ", and the related " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_BEGIN_THREADS_DESCR" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "PyArray_GETITEM" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyArray_SETITEM" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] } ] }, { "__type": "Admonition", "__tag": 4056, "kind": "warning", "base_type": "warning", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "warning " } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "It is important that the " }, { "__type": "InlineCode", "__tag": 4051, "value": "import_array()" }, { "__type": "Text", "__tag": 4046, "value": " mechanism is used to ensure that the full NumPy API is accessible when using the " }, { "__type": "InlineCode", "__tag": 4051, "value": "npy_2_compat.h" }, { "__type": "Text", "__tag": 4046, "value": " header. In most cases your extension module probably already calls it. However, if not we have added " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyArray_ImportNumPyAPI()" }, { "__type": "Text", "__tag": 4046, "value": " as a preferable way to ensure the NumPy API is imported. This function is light-weight when called multiple times so that you may insert it wherever it may be needed (if you wish to avoid setting it up at module import)." } ] } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Functionality moved to headers requiring " }, { "__type": "InlineCode", "__tag": 4051, "value": "import_array()" } ], "level": 2, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The maximum number of dimensions (and arguments) was increased to 64. This affects the " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_MAXDIMS" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_MAXARGS" }, { "__type": "Text", "__tag": 4046, "value": " macros. It may be good to review their use, and we generally encourage you to not use these macros (especially " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_MAXARGS" }, { "__type": "Text", "__tag": 4046, "value": "), so that a future version of NumPy can remove this limitation on the number of dimensions." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "NPY_MAXDIMS" }, { "__type": "Text", "__tag": 4046, "value": " was also used to signal " }, { "__type": "InlineCode", "__tag": 4051, "value": "axis=None" }, { "__type": "Text", "__tag": 4046, "value": " in the C-API, including the " }, { "__type": "InlineCode", "__tag": 4051, "value": "PyArray_AxisConverter" }, { "__type": "Text", "__tag": 4046, "value": ". The latter will return " }, { "__type": "InlineCode", "__tag": 4051, "value": "-2147483648" }, { "__type": "Text", "__tag": 4046, "value": " as an axis (the smallest integer value). Other functions may error with " }, { "__type": "InlineCode", "__tag": 4051, "value": "AxisError: axis 64 is out of bounds for array of dimension" }, { "__type": "Text", "__tag": 4046, "value": " in which case you need to pass " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_RAVEL_AXIS" }, { "__type": "Text", "__tag": 4046, "value": " instead of " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_MAXDIMS" }, { "__type": "Text", "__tag": 4046, "value": ". " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_RAVEL_AXIS" }, { "__type": "Text", "__tag": 4046, "value": " is defined in the " }, { "__type": "InlineCode", "__tag": 4051, "value": "npy_2_compat.h" }, { "__type": "Text", "__tag": 4046, "value": " header and runtime dependent (mapping to 32 on NumPy 1.x and " }, { "__type": "InlineCode", "__tag": 4051, "value": "-2147483648" }, { "__type": "Text", "__tag": 4046, "value": " on NumPy 2.x)." } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Increased maximum number of dimensions" } ], "level": 2, "target": "migration_maxdims" }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The underlying C types for all of the complex types have been changed to use native C99 types. While the memory layout of those types remains identical to the types used in NumPy 1.x, the API is slightly different, since direct field access (like " }, { "__type": "InlineCode", "__tag": 4051, "value": "c.real" }, { "__type": "Text", "__tag": 4046, "value": " or " }, { "__type": "InlineCode", "__tag": 4051, "value": "c.imag" }, { "__type": "Text", "__tag": 4046, "value": ") is no longer possible." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "It is recommended to use the functions " }, { "__type": "InlineCode", "__tag": 4051, "value": "npy_creal" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineCode", "__tag": 4051, "value": "npy_cimag" }, { "__type": "Text", "__tag": 4046, "value": " (and the corresponding float and long double variants) to retrieve the real or imaginary part of a complex number, as these will work with both NumPy 1.x and with NumPy 2.x. New functions " }, { "__type": "InlineCode", "__tag": 4051, "value": "npy_csetreal" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineCode", "__tag": 4051, "value": "npy_csetimag" }, { "__type": "Text", "__tag": 4046, "value": ", along with compatibility macros " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_CSETREAL" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineCode", "__tag": 4051, "value": "NPY_CSETIMAG" }, { "__type": "Text", "__tag": 4046, "value": " (and the corresponding float and long double variants), have been added for setting the real or imaginary part." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The underlying type remains a struct under C++ (all of the above still remains valid)." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This has implications for Cython. It is recommended to always use the native typedefs " }, { "__type": "InlineCode", "__tag": 4051, "value": "cfloat_t" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "cdouble_t" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "clongdouble_t" }, { "__type": "Text", "__tag": 4046, "value": " rather than the NumPy types " }, { "__type": "InlineCode", "__tag": 4051, "value": "npy_cfloat" }, { "__type": "Text", "__tag": 4046, "value": ", etc, unless you have to interface with C code written using the NumPy types. You can still write cython code using the " }, { "__type": "InlineCode", "__tag": 4051, "value": "c.real" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineCode", "__tag": 4051, "value": "c.imag" }, { "__type": "Text", "__tag": 4046, "value": " attributes (using the native typedefs), but you can no longer use in-place operators " }, { "__type": "InlineCode", "__tag": 4051, "value": "c.imag += 1" }, { "__type": "Text", "__tag": 4046, "value": " in Cython's c++ mode." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Because NumPy 2 now includes " }, { "__type": "InlineCode", "__tag": 4051, "value": "complex.h" }, { "__type": "Text", "__tag": 4046, "value": " code that uses a variable named " }, { "__type": "InlineCode", "__tag": 4051, "value": "I" }, { "__type": "Text", "__tag": 4046, "value": " may see an error such as" } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "to use the name " }, { "__type": "InlineCode", "__tag": 4051, "value": "I" }, { "__type": "Text", "__tag": 4046, "value": " requires an " }, { "__type": "InlineCode", "__tag": 4051, "value": "#undef I" }, { "__type": "Text", "__tag": 4046, "value": " now." } ] }, { "__type": "Admonition", "__tag": 4056, "kind": "note", "base_type": "note", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "note " } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "NumPy 2.0.1 briefly included the " }, { "__type": "InlineCode", "__tag": 4051, "value": "#undef I" }, { "__type": "Text", "__tag": 4046, "value": " to help users not already including " }, { "__type": "InlineCode", "__tag": 4051, "value": "complex.h" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Complex types - Underlying type changes" } ], "level": 2, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "In NumPy 2.0 certain functions, modules, and constants were moved or removed to make the NumPy namespace more user-friendly by removing unnecessary or outdated functionality and clarifying which parts of NumPy are considered private. Please see the tables below for guidance on migration. For most changes this means replacing it with a backwards compatible alternative." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Please refer to " }, { "__type": "InlineRole", "__tag": 4003, "value": "NEP52", "domain": null, "role": "ref", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " for more details." } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Changes to namespaces" } ], "level": 1, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "About 100 members of the main " }, { "__type": "InlineCode", "__tag": 4051, "value": "np" }, { "__type": "Text", "__tag": 4046, "value": " namespace have been deprecated, removed, or moved to a new place. It was done to reduce clutter and establish only one way to access a given attribute. The table below shows members that have been removed:" } ] }, { "__type": "Code", "__tag": 4050, "value": "====================== =================================================================\nremoved member migration guideline\n====================== =================================================================\nadd_docstring It's still available as ``np.lib.add_docstring``.\nadd_newdoc It's still available as ``np.lib.add_newdoc``.\nadd_newdoc_ufunc It's an internal function and doesn't have a replacement.\nalltrue Use ``np.all`` instead.\nasfarray Use ``np.asarray`` with a float dtype instead.\nbyte_bounds Now it's available under ``np.lib.array_utils.byte_bounds``\ncast Use ``np.asarray(arr, dtype=dtype)`` instead.\ncfloat Use ``np.complex128`` instead.\ncharrarray It's still available as ``np.char.chararray``.\nclongfloat Use ``np.clongdouble`` instead.\ncompare_chararrays It's still available as ``np.char.compare_chararrays``.\ncompat There's no replacement, as Python 2 is no longer supported.\ncomplex\\_ Use ``np.complex128`` instead.\ncumproduct Use ``np.cumprod`` instead.\nDataSource It's still available as ``np.lib.npyio.DataSource``.\ndeprecate Emit ``DeprecationWarning`` with ``warnings.warn`` directly,\n or use ``typing.deprecated``.\ndeprecate_with_doc Emit ``DeprecationWarning`` with ``warnings.warn`` directly,\n or use ``typing.deprecated``.\ndisp Use your own printing function instead.\nfastCopyAndTranspose Use ``arr.T.copy()`` instead.\nfind_common_type Use ``numpy.promote_types`` or ``numpy.result_type`` instead. \n To achieve semantics for the ``scalar_types`` argument, \n use ``numpy.result_type`` and pass the Python values ``0``, \n ``0.0``, or ``0j``.\nformat_parser It's still available as ``np.rec.format_parser``.\nget_array_wrap\nfloat\\_ Use ``np.float64`` instead.\ngeterrobj Use the np.errstate context manager instead.\nInf Use ``np.inf`` instead.\nInfinity Use ``np.inf`` instead.\ninfty Use ``np.inf`` instead.\nissctype Use ``issubclass(rep, np.generic)`` instead.\nissubclass\\_ Use ``issubclass`` builtin instead.\nissubsctype Use ``np.issubdtype`` instead.\nmat Use ``np.asmatrix`` instead.\nmaximum_sctype Use a specific dtype instead. You should avoid relying\n on any implicit mechanism and select the largest dtype of\n a kind explicitly in the code.\nNaN Use ``np.nan`` instead.\nnbytes Use ``np.dtype().itemsize`` instead.\nNINF Use ``-np.inf`` instead.\nNZERO Use ``-0.0`` instead.\nlongcomplex Use ``np.clongdouble`` instead.\nlongfloat Use ``np.longdouble`` instead.\nlookfor Search NumPy's documentation directly.\nobj2sctype Use ``np.dtype(obj).type`` instead.\nPINF Use ``np.inf`` instead.\nproduct Use ``np.prod`` instead.\nPZERO Use ``0.0`` instead.\nrecfromcsv Use ``np.genfromtxt`` with comma delimiter instead.\nrecfromtxt Use ``np.genfromtxt`` instead.\nround\\_ Use ``np.round`` instead.\nsafe_eval Use ``ast.literal_eval`` instead.\nsctype2char Use ``np.dtype(obj).char`` instead.\nsctypes Access dtypes explicitly instead.\nseterrobj Use the np.errstate context manager instead.\nset_numeric_ops For the general case, use ``PyUFunc_ReplaceLoopBySignature``. \n For ndarray subclasses, define the ``__array_ufunc__`` method \n and override the relevant ufunc.\nset_string_function Use ``np.set_printoptions`` instead with a formatter \n for custom printing of NumPy objects.\nsinglecomplex Use ``np.complex64`` instead.\nstring\\_ Use ``np.bytes_`` instead.\nsometrue Use ``np.any`` instead.\nsource Use ``inspect.getsource`` instead.\ntracemalloc_domain It's now available from ``np.lib``.\nunicode\\_ Use ``np.str_`` instead.\nwho Use an IDE variable explorer or ``locals()`` instead.\n====================== =================================================================", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If the table doesn't contain an item that you were using but was removed in " }, { "__type": "InlineCode", "__tag": 4051, "value": "2.0" }, { "__type": "Text", "__tag": 4046, "value": ", then it means it was a private member. You should either use the existing API or, in case it's infeasible, reach out to us with a request to restore the removed entry." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The next table presents deprecated members, which will be removed in a release after " }, { "__type": "InlineCode", "__tag": 4051, "value": "2.0" }, { "__type": "Text", "__tag": 4046, "value": ":" } ] }, { "__type": "Code", "__tag": 4050, "value": "================= =======================================================================\ndeprecated member migration guideline\n================= =======================================================================\nin1d Use ``np.isin`` instead.\nrow_stack Use ``np.vstack`` instead (``row_stack`` was an alias for ``vstack``).\ntrapz Use ``np.trapezoid`` or a ``scipy.integrate`` function instead.\n================= =======================================================================", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Finally, a set of internal enums has been removed. As they weren't used in downstream libraries we don't provide any information on how to replace them:" } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "[" }, { "__type": "InlineCode", "__tag": 4051, "value": "FLOATING_POINT_SUPPORT" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "FPE_DIVIDEBYZERO" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "FPE_INVALID" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "FPE_OVERFLOW" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "FPE_UNDERFLOW" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "UFUNC_BUFSIZE_DEFAULT" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "UFUNC_PYVALS_NAME" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "CLIP" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "WRAP" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "RAISE" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "BUFSIZE" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "ALLOW_THREADS" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "MAXDIMS" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "MAY_SHARE_EXACT" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "MAY_SHARE_BOUNDS" }, { "__type": "Text", "__tag": 4046, "value": "]" } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Main namespace" } ], "level": 2, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Most of the functions available within " }, { "__type": "InlineCode", "__tag": 4051, "value": "np.lib" }, { "__type": "Text", "__tag": 4046, "value": " are also present in the main namespace, which is their primary location. To make it unambiguous how to access each public function, " }, { "__type": "InlineCode", "__tag": 4051, "value": "np.lib" }, { "__type": "Text", "__tag": 4046, "value": " is now empty and contains only a handful of specialized submodules, classes and functions:" } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "array_utils" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "format" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "introspect" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "mixins" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "npyio" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "scimath" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineCode", "__tag": 4051, "value": "stride_tricks" }, { "__type": "Text", "__tag": 4046, "value": " submodules," } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "Arrayterator" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineCode", "__tag": 4051, "value": "NumpyVersion" }, { "__type": "Text", "__tag": 4046, "value": " classes," } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "add_docstring" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineCode", "__tag": 4051, "value": "add_newdoc" }, { "__type": "Text", "__tag": 4046, "value": " functions," } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "tracemalloc_domain" }, { "__type": "Text", "__tag": 4046, "value": " constant." } ] } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If you get an " }, { "__type": "InlineCode", "__tag": 4051, "value": "AttributeError" }, { "__type": "Text", "__tag": 4046, "value": " when accessing an attribute from " }, { "__type": "InlineCode", "__tag": 4051, "value": "np.lib" }, { "__type": "Text", "__tag": 4046, "value": " you should try accessing it from the main " }, { "__type": "InlineCode", "__tag": 4051, "value": "np" }, { "__type": "Text", "__tag": 4046, "value": " namespace then. If an item is also missing from the main namespace, then you're using a private member. You should either use the existing API or, in case it's infeasible, reach out to us with a request to restore the removed entry." } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "numpy.lib namespace" } ], "level": 2, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The " }, { "__type": "InlineCode", "__tag": 4051, "value": "np.core" }, { "__type": "Text", "__tag": 4046, "value": " namespace is now officially private and has been renamed to " }, { "__type": "InlineCode", "__tag": 4051, "value": "np._core" }, { "__type": "Text", "__tag": 4046, "value": ". The user should never fetch members from the " }, { "__type": "InlineCode", "__tag": 4051, "value": "_core" }, { "__type": "Text", "__tag": 4046, "value": " directly - instead the main namespace should be used to access the attribute in question. The layout of the " }, { "__type": "InlineCode", "__tag": 4051, "value": "_core" }, { "__type": "Text", "__tag": 4046, "value": " module might change in the future without notice, contrary to public modules which adhere to the deprecation period policy. If an item is also missing from the main namespace, then you should either use the existing API or, in case it's infeasible, reach out to us with a request to restore the removed entry." } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "numpy.core namespace" } ], "level": 2, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "A few methods from " }, { "__type": "InlineCode", "__tag": 4051, "value": "np.ndarray" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineCode", "__tag": 4051, "value": "np.generic" }, { "__type": "Text", "__tag": 4046, "value": " scalar classes have been removed. The table below provides replacements for the removed members:" } ] }, { "__type": "Code", "__tag": 4050, "value": "====================== ========================================================\nexpired member migration guideline\n====================== ========================================================\nnewbyteorder Use ``arr.view(arr.dtype.newbyteorder(order))`` instead.\nptp Use ``np.ptp(arr, ...)`` instead.\nsetitem Use ``arr[index] = value`` instead.\n====================== ========================================================", "execution_status": null } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "ndarray and scalar methods" } ], "level": 2, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "A new " }, { "__type": "CrossRef", "__tag": 4002, "value": "numpy.strings", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "numpy", "version": "*", "kind": "api", "path": "numpy.strings" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " namespace has been created, where most of the string operations are implemented as ufuncs. The old " }, { "__type": "CrossRef", "__tag": 4002, "value": "numpy.char", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "numpy", "version": "*", "kind": "api", "path": "numpy.char" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " namespace still is available, and, wherever possible, uses the new ufuncs for greater performance. We recommend using the " }, { "__type": "CrossRef", "__tag": 4002, "value": "strings", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "numpy", "version": "*", "kind": "api", "path": "numpy.strings" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " functions going forward. The " }, { "__type": "CrossRef", "__tag": 4002, "value": "char", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "numpy", "version": "*", "kind": "api", "path": "numpy.char" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " namespace may be deprecated in the future." } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "numpy.strings namespace" } ], "level": 2, "target": null }, { "__type": "Section", "__tag": 4015, "children": [], "title": [ { "__type": "Text", "__tag": 4046, "value": "Other changes" } ], "level": 1, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "NumPy 2.0 is designed to load pickle files created with NumPy 1.26, and vice versa. For versions 1.25 and earlier loading NumPy 2.0 pickle file will throw an exception." } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Note about pickled files" } ], "level": 2, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The " }, { "__type": "CrossRef", "__tag": 4002, "value": "copy keyword behavior changes", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "docs", "path": "release:2.0.0-notes" }, "kind": "exists" }, { "__type": "Text", "__tag": 4046, "value": " in " }, { "__type": "CrossRef", "__tag": 4002, "value": "asarray", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "numpy", "version": "*", "kind": "api", "path": "numpy:asarray" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "CrossRef", "__tag": 4002, "value": "array", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "numpy", "version": "*", "kind": "api", "path": "numpy:array" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineRole", "__tag": 4003, "value": "ndarray.__array__ ", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " may require these changes:" } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Code using " }, { "__type": "InlineCode", "__tag": 4051, "value": "np.array(..., copy=False)" }, { "__type": "Text", "__tag": 4046, "value": " can in most cases be changed to " }, { "__type": "InlineCode", "__tag": 4051, "value": "np.asarray(...)" }, { "__type": "Text", "__tag": 4046, "value": ". Older code tended to use " }, { "__type": "InlineCode", "__tag": 4051, "value": "np.array" }, { "__type": "Text", "__tag": 4046, "value": " like this because it had less overhead than the default " }, { "__type": "InlineCode", "__tag": 4051, "value": "np.asarray" }, { "__type": "Text", "__tag": 4046, "value": " copy-if-needed behavior. This is no longer true, and " }, { "__type": "InlineCode", "__tag": 4051, "value": "np.asarray" }, { "__type": "Text", "__tag": 4046, "value": " is the preferred function." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "For code that explicitly needs to pass " }, { "__type": "InlineCode", "__tag": 4051, "value": "None" }, { "__type": "Text", "__tag": 4046, "value": "/" }, { "__type": "InlineCode", "__tag": 4051, "value": "False" }, { "__type": "Text", "__tag": 4046, "value": " meaning \"copy if needed\" in a way that's compatible with NumPy 1.x and 2.x, see " }, { "__type": "Link", "__tag": 4049, "children": [ { "__type": "Text", "__tag": 4046, "value": "scipy#20172" } ], "url": "https://github.com/scipy/scipy/pull/20172", "title": "" }, { "__type": "Text", "__tag": 4046, "value": " for an example of how to do so." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "For any " }, { "__type": "InlineCode", "__tag": 4051, "value": "__array__" }, { "__type": "Text", "__tag": 4046, "value": " method on a non-NumPy array-like object, " }, { "__type": "InlineCode", "__tag": 4051, "value": "dtype=None" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineCode", "__tag": 4051, "value": "copy=None" }, { "__type": "Text", "__tag": 4046, "value": " keywords must be added to the signature - this will work with older NumPy versions as well (although older numpy versions will never pass in " }, { "__type": "InlineCode", "__tag": 4051, "value": "copy" }, { "__type": "Text", "__tag": 4046, "value": " keyword). If the keywords are added to the " }, { "__type": "InlineCode", "__tag": 4051, "value": "__array__" }, { "__type": "Text", "__tag": 4046, "value": " signature, then for:" } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "copy=True" }, { "__type": "Text", "__tag": 4046, "value": " and any " }, { "__type": "InlineCode", "__tag": 4051, "value": "dtype" }, { "__type": "Text", "__tag": 4046, "value": " value always return a new copy," } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "copy=None" }, { "__type": "Text", "__tag": 4046, "value": " create a copy if required (for example by " }, { "__type": "InlineCode", "__tag": 4051, "value": "dtype" }, { "__type": "Text", "__tag": 4046, "value": ")," } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "copy=False" }, { "__type": "Text", "__tag": 4046, "value": " a copy must never be made. If a copy is needed to return a numpy array or satisfy " }, { "__type": "InlineCode", "__tag": 4051, "value": "dtype" }, { "__type": "Text", "__tag": 4046, "value": ", then raise an exception (" }, { "__type": "InlineCode", "__tag": 4051, "value": "ValueError" }, { "__type": "Text", "__tag": 4046, "value": ")." } ] } ] } ] } ] } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Adapting to changes in the " }, { "__type": "InlineCode", "__tag": 4051, "value": "copy" }, { "__type": "Text", "__tag": 4046, "value": " keyword" } ], "level": 2, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "It should be fairly rare to have to write code that explicitly branches on the " }, { "__type": "InlineCode", "__tag": 4051, "value": "numpy" }, { "__type": "Text", "__tag": 4046, "value": " version - in most cases, code can be rewritten to be compatible with 1.x and 2.0 at the same time. However, if it is necessary, here is a suggested code pattern to use, using " }, { "__type": "CrossRef", "__tag": 4002, "value": "numpy.lib.NumpyVersion", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "numpy", "version": "*", "kind": "api", "path": "numpy.lib:NumpyVersion" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": ": " } ] }, { "__type": "Code", "__tag": 4050, "value": "# example with AxisError, which is no longer available in\n# the main namespace in 2.0, and not available in the\n# `exceptions` namespace in <1.25.0 (example uses <2.0.0b1\n# for illustrative purposes):\nif np.lib.NumpyVersion(np.__version__) >= '2.0.0b1':\n from numpy.exceptions import AxisError\nelse:\n from numpy import AxisError", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This pattern will work correctly including with NumPy release candidates, which is important during the 2.0.0 release period." } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Writing numpy-version-dependent code" } ], "level": 2, "target": null } ], "local_refs": [] }