Deprecate PyOS_ascii_strtod and PyOS_ascii_atof, and document the replacement functio...

diff --git a/Doc/c-api/conversion.rst b/Doc/c-api/conversion.rst
index fc42508ede4a424a70e12edee756e528c9982174..b32100b82bfdb676a13666ece3c87dd1d02d14fb 100644 (file)
--- a/Doc/c-api/conversion.rst
+++ b/Doc/c-api/conversion.rst
@@ -51,6 +51,40 @@ The return value (*rv*) for these functions should be interpreted as follows:
 The following functions provide locale-independent string to number conversions.
 
 
+.. cfunction:: double PyOS_string_to_double(const char *s, char **endptr, PyObject *overflow_exception)
+
+   Convert a string ``s`` to a :ctype:`double`, raising a Python
+   exception on failure.  The set of accepted strings corresponds to
+   the set of strings accepted by Python's :func:`float` constructor,
+   except that ``s`` must not have leading or trailing whitespace.
+   The conversion is independent of the current locale.
+
+   If ``endptr`` is ``NULL``, convert the whole string.  Raise
+   ValueError and return ``-1.0`` if the string is not a valid
+   representation of a floating-point number.
+
+   If endptr is not ``NULL``, convert as much of the string as
+   possible and set ``*endptr`` to point to the first unconverted
+   character.  If no initial segment of the string is the valid
+   representation of a floating-point number, set ``*endptr`` to point
+   to the beginning of the string, raise ValueError, and return
+   ``-1.0``.
+
+   If ``s`` represents a value that is too large to store in a float
+   (for example, ``"1e500"`` is such a string on many platforms) then
+   if ``overflow_exception`` is ``NULL`` return ``Py_HUGE_VAL`` (with
+   an appropriate sign) and don't set any exception.  Otherwise,
+   ``overflow_exception`` must point to a Python exception object;
+   raise that exception and return ``-1.0``.  In both cases, set
+   ``*endptr`` to point to the first character after the converted value.
+
+   If any other error occurs during the conversion (for example an
+   out-of-memory error), set the appropriate Python exception and
+   return ``-1.0``.
+
+   .. versionadded:: 2.7
+
+
 .. cfunction:: double PyOS_ascii_strtod(const char *nptr, char **endptr)
 
    Convert a string to a :ctype:`double`. This function behaves like the Standard C
@@ -60,9 +94,13 @@ The following functions provide locale-independent string to number conversions.
    :cfunc:`PyOS_ascii_strtod` should typically be used for reading configuration
    files or other non-user input that should be locale independent.
 
+   See the Unix man page :manpage:`strtod(2)` for details.
+
    .. versionadded:: 2.4
 
-   See the Unix man page :manpage:`strtod(2)` for details.
+   .. deprecated:: 2.7
+      Use :cfunc:`PyOS_string_to_double` instead.
+
 
 
 .. cfunction:: char* PyOS_ascii_formatd(char *buffer, size_t buf_len, const char *format, double d)
@@ -119,9 +157,12 @@ The following functions provide locale-independent string to number conversions.
 
    Convert a string to a :ctype:`double` in a locale-independent way.
 
+   See the Unix man page :manpage:`atof(2)` for details.
+
    .. versionadded:: 2.4
 
-   See the Unix man page :manpage:`atof(2)` for details.
+   .. deprecated:: 3.1
+      Use :cfunc:`PyOS_string_to_double` instead.
 
 
 .. cfunction:: char* PyOS_stricmp(char *s1, char *s2)

diff --git a/Misc/NEWS b/Misc/NEWS
index 8fcef1d662f7a75984503757f618a867fb254476..e2695053427982d372ac4b0d88f651dea3311339 100644 (file)
--- a/Misc/NEWS
+++ b/Misc/NEWS
@@ -1414,6 +1414,9 @@ Documentation
 C-API
 -----
 
+- Add new C-API function PyOS_string_to_double, and deprecated
+  PyOS_ascii_atof and PyOS_ascii_strtod.
+
 - Removed _PyOS_double_to_string. Use PyOS_double_to_string
   instead. This is in preparation for (but not strictly related to)
   issue #7117, short float repr.

diff --git a/Python/pystrtod.c b/Python/pystrtod.c
index 64bf73daecdb61513ae9cf482cac067465341721..27ddc941c2dd1cd8f2e7fa07cd3384628c3eb253 100644 (file)
--- a/Python/pystrtod.c
+++ b/Python/pystrtod.c
@@ -270,6 +270,8 @@ _PyOS_ascii_strtod(const char *nptr, char **endptr)
 
 #endif
 
+/* PyOS_ascii_strtod is DEPRECATED in Python 2.7 and 3.1 */
+
 double
 PyOS_ascii_strtod(const char *nptr, char **endptr)
 {
@@ -277,6 +279,12 @@ PyOS_ascii_strtod(const char *nptr, char **endptr)
        const char *p;
        double x;
 
+       if (PyErr_WarnEx(PyExc_DeprecationWarning,
+                        "PyOS_ascii_strtod and PyOS_ascii_atof are "
+                        "deprecated.  Use PyOS_string_to_double "
+                        "instead.", 1) < 0)
+               return -1.0;
+
        /* _PyOS_ascii_strtod already does everything that we want,
           except that it doesn't parse leading whitespace */
        p = nptr;
@@ -290,13 +298,15 @@ PyOS_ascii_strtod(const char *nptr, char **endptr)
        return x;
 }
 
+/* PyOS_ascii_strtod is DEPRECATED in Python 2.7 and 3.1 */
+
 double
 PyOS_ascii_atof(const char *nptr)
 {
        return PyOS_ascii_strtod(nptr, NULL);
 }
 
-/* PyOS_string_to_double is the recommended replacement for the
+/* PyOS_string_to_double is the recommended replacement for the deprecated
    PyOS_ascii_strtod and PyOS_ascii_atof functions.  It converts a
    null-terminated byte string s (interpreted as a string of ASCII characters)
    to a float.  The string should not have leading or trailing whitespace (in
@@ -332,7 +342,7 @@ PyOS_string_to_double(const char *s,
 
        errno = 0;
        PyFPE_START_PROTECT("PyOS_string_to_double", return -1.0)
-       x = PyOS_ascii_strtod(s, &fail_pos);
+       x = _PyOS_ascii_strtod(s, &fail_pos);
        PyFPE_END_PROTECT(x)
 
        if (errno == ENOMEM) {