summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorTravis E. Oliphant <teoliphant@gmail.com>2012-07-11 13:13:53 -0500
committerTravis E. Oliphant <teoliphant@gmail.com>2012-07-11 13:13:53 -0500
commit9a4ef177a17a3f41ba3456e9768317e1d6ccf81d (patch)
tree4e862e1fa55cb5f7bbaee7376a01e5c21224f759 /doc
parent1d4decdf49b26bab6889ed8ab2943558709567ca (diff)
downloadnumpy-9a4ef177a17a3f41ba3456e9768317e1d6ccf81d.tar.gz
Fix the deprecations language.
Diffstat (limited to 'doc')
-rw-r--r--doc/source/reference/c-api.deprecations.rst38
1 files changed, 19 insertions, 19 deletions
diff --git a/doc/source/reference/c-api.deprecations.rst b/doc/source/reference/c-api.deprecations.rst
index 3521dd2fd..4a5184ca7 100644
--- a/doc/source/reference/c-api.deprecations.rst
+++ b/doc/source/reference/c-api.deprecations.rst
@@ -6,18 +6,20 @@ Background
The API exposed by NumPy for third-party extensions has grown over
years of releases, and has allowed programmers to directly access
-NumPy functionality from C. This API was not originally designed to
-take into account best practices for C APIs, and was maintained by
-a small group of people with very little time to expend on improving
-it.
-
-Starting with NumPy 1.7, we are attempting to make a concerted effort to
-clean up the API. This includes fixing some grave sins, like removing
-the macro *fortran* (which was defined to *fortran_*) as well as
-clarifying some confusing choices caused by designing separate
-subsystems without noticing how they interacted. For example,
-NPY_DEFAULT was a flag controlling ndarray construction, while
-PyArray_DEFAULT was the default dtype enumeration value.
+NumPy functionality from C. This API can be best described as
+"organic". The core API originated with Numeric in 1995 and there are
+patterns such as the heavy use of macros written to mimic Python's
+C-API as well as account for compiler technology of the late 90's.
+There is only a small group of volunteers who have had very little
+time to spend on improving this API.
+
+There is an ongoing effort to improve the API to do things like remove
+a "fortran" macro and ensure that the NPY_ prefixes don't collide with
+names from the PyArray_ prefixes. It is important in this effort,
+however, to ensure that code that compiles for NumPy 1.X continues to
+compile for NumPy 1.X. At the same, time certain API's will be marked
+as deprecated so that future-looking code can avoid these API's and
+follow better practices.
Another important role played by deprecations in the C API is to move
towards hiding internal details of the NumPy implementation. For those
@@ -25,19 +27,17 @@ needing direct, easy, access to the data of ndarrays, this will not
remove this ability. Rather, there are many potential performance
optimizations which require changing the implementation details, and
NumPy developers have been unable to try them because of the high
-value of preserving ABI compatibility. By deprecating this direct access
-over the course of several releases, we will in the future be able to
-improve NumPy's performance in ways we cannot presently.
+value of preserving ABI compatibility. By deprecating this direct
+access, we will in the future be able to improve NumPy's performance
+in ways we cannot presently.
Deprecation Mechanism NPY_NO_DEPRECATED_API
-------------------------------------------
In C, there is no equivalent to the deprecation warnings that Python
supports. One way to do deprecations is to flag them in the documentation
-and release notes, then remove or change the deprecated features in the
-next version. We intend to do this, but also have created a mechanism to help
-third-party developers test that their code does not use any of the
-deprecated features.
+and release notes, then remove or change the deprecated features in a
+future version (NumPy 2.0 and beyond).
To use the NPY_NO_DEPRECATED_API mechanism, you need to #define it to
the target API version of NumPy before #including any NumPy headers.