ENH: core: Start converting ufunc to new iterator, add PyArray_PromoteTypes

1 files changed, 40 insertions, 0 deletions

diff --git a/numpy/add_newdocs.py b/numpy/add_newdocs.py
index 5e6a07bb0..92e438249 100644
--- a/numpy/add_newdocs.py
+++ b/numpy/add_newdocs.py
@@ -1178,6 +1178,46 @@ add_newdoc('numpy.core.multiarray', 'can_cast',
 
     """)
 
+add_newdoc('numpy.core.multiarray', 'promote_types',
+    """
+    promote_types(type1, type2)
+
+    Returns the data type with the smallest size and smallest scalar
+    kind to which both ``type1`` and ``type2`` may be safely cast.
+    The returned data type is always in native byte order.  Promotion of
+    string, unicode and void with numbers is disallowed.
+
+    Parameters
+    ----------
+    type1 : dtype or dtype specifier
+        First data type.
+    type2 : dtype or dtype specifier
+        Second data type.
+
+    Returns
+    -------
+    out : dtype
+        The promoted data type.
+
+    Examples
+    --------
+    >>> np.promote_types('f4', 'f8')
+    dtype('float64')
+
+    >>> np.promote_types('i8', 'f4')
+    dtype('float64')
+
+    >>> np.promote_types('>i8', '<c8')
+    dtype('complex128')
+
+    >>> np.promote_types('i1', 'S8')
+    Traceback (most recent call last):
+      File "<stdin>", line 1, in <module>
+    TypeError: invalid type promotion
+
+
+    """)
+
 add_newdoc('numpy.core.multiarray','newbuffer',
     """newbuffer(size)