| Date: | 2010-07-11 |
|---|---|
| Author: | Charles R. Harris |
| Author: | Pauli Virtanen |
NumPy has now been ported to Python 3.
Some glitches may still be present; however, we are not aware of any significant ones, the test suite passes.
Information on porting to 3K:
The Nose test framework has currently (Nov 2009) no released Python 3 compatible version. Its 3K SVN branch, however, works quite well:
As a side effect, the Py3 adaptation has caused the following semantic changes that are visible on Py2.
- Objects (except bytes and str) that implement the PEP 3118 array interface
will behave as ndarrays in array(...) and asarray(...); the same way
as if they had
__array_interface__defined. - Otherwise, there are no known semantic changes.
The following semantic changes have been made on Py3:
Division: integer division is by default true_divide, also for arrays.
Dtype field names are Unicode.
Only unicode dtype field titles are included in fields dict.
PEP 3118 buffer objects will behave differently from Py2 buffer objects when used as an argument to array(...), asarray(...).
In Py2, they would cast to an object array.
In Py3, they cast similarly as objects having an
__array_interface__attribute, ie., they behave as if they were an ndarray view on the data.
Currently, setup.py calls 2to3 automatically to convert Python sources to Python 3 ones, and stores the results under:
build/py3k
Only changed files will be re-converted when setup.py is called a second time, making development much faster.
Currently, this seems to handle all of the necessary Python code conversion.
Not all of the 2to3 transformations are appropriate for all files.
Especially, 2to3 seems to be quite trigger-happy in replacing e.g.
unicode by str which causes problems in defchararray.py.
For files that need special handling, add entries to
tools/py3tool.py.
There are some utility functions needed for 3K compatibility in
numpy.compat.py3k -- they can be imported from numpy.compat:
- bytes, unicode: bytes and unicode constructors
- asbytes: convert string to bytes (no-op on Py2)
- asbytes_nested: convert strings in lists to Bytes
- asunicode: convert string to unicode
- asunicode_nested: convert strings in lists to Unicode
- asstr: convert item to the str type
- getexception: get current exception (see below)
- isfileobj: detect Python file objects
- strchar: character for Unicode (Py3) or Strings (Py2)
- open_latin1: open file in the latin1 text mode
More can be added as needed.
F2py is ported to Py3.
At many points in NumPy, bytes literals are needed. These can be created via numpy.compat.asbytes and asbytes_nested.
Syntax change: "except FooException, bar:" -> "except FooException as bar:"
This is taken care by 2to3, however.
The new relative import syntax,
from . import foo
is not available on Py2.4, so we can't simply use it.
Using absolute imports everywhere is probably OK, if they just happen to work.
2to3, however, converts the old syntax to new syntax, so as long as we use the converter, it takes care of most parts.
The Print statement changed to a builtin function in Py3.
Also this is taken care of by 2to3.
The following items were removed from types module in Py3:
- StringType (Py3: bytes is equivalent, to some degree)
- InstanceType (Py3: ???)
- IntType (Py3: no equivalent)
- LongType (Py3: equivalent long)
- FloatType (Py3: equivalent float)
- BooleanType (Py3: equivalent bool)
- ComplexType (Py3: equivalent complex)
- UnicodeType (Py3: equivalent str)
- BufferType (Py3: more-or-less equivalent memoryview)
In numerictypes.py, the "common" types were replaced by their
plain equivalents, and IntType was dropped.
In numerictypes, types on Python 3 were changed so that:
| Scalar type | Value |
|---|---|
| str_ | This is the basic Unicode string type on Py3 |
| bytes_ | This is the basic Byte-string type on Py3 |
| string_ | bytes_ alias |
| unicode_ | str_ alias |
These routines are difficult to duck-type to read both Unicode and Bytes input.
I assumed they are meant for reading Bytes streams -- this is probably the far more common use case with scientific data.
Python 3 is less forgiving about cyclic imports than Python 2. Cycles need to be broken to have the same code work both on Python 2 and 3.
A #define in config.h, defined when building for Py3.
.. todo:: Currently, this is generated as a part of the config. Is this sensible (we could also use Py_VERSION_HEX)?
Convenience macros for Python 3 support:
- PyInt -> PyLong on Py3
- PyString -> PyBytes on Py3
- PyUString -> PyUnicode on Py3 and PyString on Py2
- PyBytes on Py2
- PyUnicode_ConcatAndDel, PyUnicode_Concat2
- Py_SIZE et al., for older Python versions
- npy_PyFile_Dup, etc. to get FILE* from Py3 file objects
- PyObject_Cmp, convenience comparison function on Py3
- NpyCapsule_* helpers: PyCObject
Any new ones that need to be added should be added in this file.
.. todo:: Remove PyString_* eventually -- having a call to one of these in NumPy sources is a sign of an error...
These use Py_SIZE, etc. macros now. The macros are also defined in npy_3kcompat.h for the Python versions that don't have them natively.
Python 3 no longer supports type coercion in arithmetic.
Py_TPFLAGS_CHECKTYPES is now on by default, and so the C-level
interface, nb_* methods, still unconditionally receive whatever
types as their two arguments.
However, this will affect Python-level code: previously if you
inherited from a Py_TPFLAGS_CHECKTYPES enabled class that implemented
a __mul__ method, the same __mul__ method would still be
called also as when a __rmul__ was required, but with swapped
arguments (see Python/Objects/typeobject.c:wrap_binaryfunc_r).
However, on Python 3, arguments are swapped only if both are of same
(sub-)type, and otherwise things fail.
This means that ndarray-derived subclasses must now implement all
relevant __r*__ methods, since they cannot any more automatically
fall back to ndarray code.
The structures have been converted to the new format:
- number.c
- scalartypes.c.src
- scalarmathmodule.c.src
The slots np_divide, np_long, np_oct, np_hex, and np_inplace_divide have gone away. The slot np_int is what np_long used to be, tp_divide is now tp_floor_divide, and np_inplace_divide is now np_inplace_floor_divide.
These have simply been #ifdef'd out on Py3.
The Py2/Py3 compatible structure definition looks like:
static PyNumberMethods @name@_as_number = {
(binaryfunc)0, /*nb_add*/
(binaryfunc)0, /*nb_subtract*/
(binaryfunc)0, /*nb_multiply*/
#if defined(NPY_PY3K)
#else
(binaryfunc)0, /*nb_divide*/
#endif
(binaryfunc)0, /*nb_remainder*/
(binaryfunc)0, /*nb_divmod*/
(ternaryfunc)0, /*nb_power*/
(unaryfunc)0,
(unaryfunc)0, /*nb_pos*/
(unaryfunc)0, /*nb_abs*/
#if defined(NPY_PY3K)
(inquiry)0, /*nb_bool*/
#else
(inquiry)0, /*nb_nonzero*/
#endif
(unaryfunc)0, /*nb_invert*/
(binaryfunc)0, /*nb_lshift*/
(binaryfunc)0, /*nb_rshift*/
(binaryfunc)0, /*nb_and*/
(binaryfunc)0, /*nb_xor*/
(binaryfunc)0, /*nb_or*/
#if defined(NPY_PY3K)
#else
0, /*nb_coerce*/
#endif
(unaryfunc)0, /*nb_int*/
#if defined(NPY_PY3K)
(unaryfunc)0, /*nb_reserved*/
#else
(unaryfunc)0, /*nb_long*/
#endif
(unaryfunc)0, /*nb_float*/
#if defined(NPY_PY3K)
#else
(unaryfunc)0, /*nb_oct*/
(unaryfunc)0, /*nb_hex*/
#endif
0, /*inplace_add*/
0, /*inplace_subtract*/
0, /*inplace_multiply*/
#if defined(NPY_PY3K)
#else
0, /*inplace_divide*/
#endif
0, /*inplace_remainder*/
0, /*inplace_power*/
0, /*inplace_lshift*/
0, /*inplace_rshift*/
0, /*inplace_and*/
0, /*inplace_xor*/
0, /*inplace_or*/
(binaryfunc)0, /*nb_floor_divide*/
(binaryfunc)0, /*nb_true_divide*/
0, /*nb_inplace_floor_divide*/
0, /*nb_inplace_true_divide*/
(unaryfunc)NULL, /*nb_index*/
};
PyBuffer usage is widely spread in multiarray:
- The void scalar makes use of buffers
- Multiarray has methods for creating buffers etc. explicitly
- Arrays can be created from buffers etc.
- The .data attribute of an array is a buffer
Py3 introduces the PEP 3118 buffer protocol as the only protocol, so we must implement it.
The exporter parts of the PEP 3118 buffer protocol are currently
implemented in buffer.c for arrays, and in scalartypes.c.src
for generic array scalars. The generic array scalar exporter, however,
doesn't currently produce format strings, which needs to be fixed.
Also some code also stops working when bf_releasebuffer is
defined. Most importantly, PyArg_ParseTuple("s#", ...) refuses to
return a buffer if bf_releasebuffer is present. For this reason,
the buffer interface for arrays is implemented currently without
defining bf_releasebuffer at all. This forces us to go through
some additional work.
There are a couple of places that need further attention:
VOID_getitem
In some cases, this returns a buffer object on Python 2. On Python 3, there is no stand-alone buffer object, so we return a byte array instead.
The Py2/Py3 compatible PyBufferMethods definition looks like:
NPY_NO_EXPORT PyBufferProcs array_as_buffer = {
#if !defined(NPY_PY3K)
#if PY_VERSION_HEX >= 0x02050000
(readbufferproc)array_getreadbuf, /*bf_getreadbuffer*/
(writebufferproc)array_getwritebuf, /*bf_getwritebuffer*/
(segcountproc)array_getsegcount, /*bf_getsegcount*/
(charbufferproc)array_getcharbuf, /*bf_getcharbuffer*/
#else
(getreadbufferproc)array_getreadbuf, /*bf_getreadbuffer*/
(getwritebufferproc)array_getwritebuf, /*bf_getwritebuffer*/
(getsegcountproc)array_getsegcount, /*bf_getsegcount*/
(getcharbufferproc)array_getcharbuf, /*bf_getcharbuffer*/
#endif
#endif
#if PY_VERSION_HEX >= 0x02060000
(getbufferproc)array_getbuffer, /*bf_getbuffer*/
(releasebufferproc)array_releasebuffer, /*bf_releasebuffer*/
#endif
};
.. todo:: Produce PEP 3118 format strings for array scalar objects.
.. todo:: There's stuff to clean up in numarray/_capi.c
There are two places in which we may want to be able to consume buffer objects and cast them to ndarrays:
multiarray.frombuffer, ie.,
PyArray_FromAnyThe frombuffer returns only arrays of a fixed dtype. It does not make sense to support PEP 3118 at this location, since not much would be gained from that -- the backward compatibility functions using the old array interface still work.
So no changes needed here.
multiarray.array, ie.,
PyArray_FromAnyIn general, we would like to handle PEP 3118 buffers in the same way as
__array_interface__objects. Hence, we want to be able to cast them to arrays already inPyArray_FromAny.Hence,
PyArray_FromAnyneeds additions.
There are a few caveats in allowing PEP 3118 buffers in
PyArray_FromAny:
bytes (and str on Py2) objects offer a buffer interface that specifies them as 1-D array of bytes.
Previously
PyArray_FromAnyhas cast these to 'S#' dtypes. We don't want to change this, since will cause problems in many places.We do, however, want to allow other objects that provide 1-D byte arrays to be cast to 1-D ndarrays and not 'S#' arrays -- for instance, 'S#' arrays tend to strip trailing NUL characters.
So what is done in PyArray_FromAny currently is that:
Presence of PEP 3118 buffer interface is checked before checking for array interface. If it is present and the object is not bytes object, then it is used for creating a view on the buffer.
We also check in
discover_depthand_array_find_typefor the 3118 buffers, so that:array([some_3118_object])
will treat the object similarly as it would handle an ndarray.
However, again, bytes (and unicode) have priority and will not be handled as buffer objects.
This amounts to possible semantic changes:
array(buffer)will no longer create an object arrayarray([buffer], dtype='O'), but will instead expand to a view on the buffer.
.. todo:: Take a second look at places that used PyBuffer_FromMemory and PyBuffer_FromReadWriteMemory -- what can be done with these?
.. todo:: There's some buffer code in numarray/_capi.c that needs to be addressed.
Since there is a native buffer object in Py3, the memoryview, the newbuffer and getbuffer functions are removed from multiarray in Py3: their functionality is taken over by the new memoryview object.
There is no PyString in Py3, everything is either Bytes or Unicode. Unicode is also preferred in many places, e.g., in __dict__.
There are two issues related to the str/bytes change:
- Return values etc. should prefer unicode
- The 'S' dtype
This entry discusses return values etc. only, the 'S' dtype is a separate topic.
All uses of PyString in NumPy should be changed to one of
- PyBytes: one-byte character strings in Py2 and Py3
- PyUString (defined in npy_3kconfig.h): PyString in Py2, PyUnicode in Py3
- PyUnicode: UCS in Py2 and Py3
In many cases the conversion only entails replacing PyString with PyUString.
PyString is currently defined to PyBytes in npy_3kcompat.h, for making things to build. This definition will be removed when Py3 support is finished.
Where *_AsStringAndSize is used, more care needs to be taken, as
encoding Unicode to Bytes may needed. If this cannot be avoided, the
encoding should be ASCII, unless there is a very strong reason to do
otherwise. Especially, I don't believe we should silently fall back to
UTF-8 -- raising an exception may be a better choice.
Exceptions should use PyUnicode_AsUnicodeEscape -- this should result to an ASCII-clean string that is appropriate for the exception message.
Some specific decisions that have been made so far:
descriptor.c: dtype field names are UString
At some places in NumPy code, there are some guards for Unicode field names. However, the dtype constructor accepts only strings as field names, so we should assume field names are always UString.
descriptor.c: field titles can be arbitrary objects. If they are UString (or, on Py2, Bytes or Unicode), insert to fields dict.
descriptor.c: dtype strings are Unicode.
descriptor.c: datetime tuple contains Bytes only.
repr() and str() should return UString
comparison between Unicode and Bytes is not defined in Py3
Type codes in numerictypes.typeInfo dict are Unicode
Func name in errobj is Bytes (should be forced to ASCII)
.. todo:: tp_doc -- it's a char* pointer, but what is the encoding? Check esp. lib/src/_compiled_base Currently, UTF-8 is assumed.
.. todo:: ufunc names -- again, what's the encoding?
.. todo:: Cleanup to do later on: Replace all occurrences of PyString by PyBytes, PyUnicode, or PyUString.
.. todo:: Revise errobj decision?
.. todo:: Check that non-UString field names are not accepted anywhere.
PyUnicode in Py3 is pretty much as it was in Py2, except that it is now the only "real" string type.
In Py3, Unicode and Bytes are not comparable, ie., 'a' != b'a'. NumPy comparison routines were handled to act in the same way, leaving comparison between Unicode and Bytes undefined.
.. todo:: Check that indeed all comparison routines were changed.
On Python 3, the 'S' dtype will still be Bytes.
However,:
str, str_ == unicode_
There is no limited-range integer type any more in Py3. It makes no sense to inherit NumPy ints from Py3 ints.
Currently, the following is done:
- NumPy's integer types no longer inherit from Python integer.
- int is taken dtype-equivalent to NPY_LONG
- ints are converted to NPY_LONG
PyInt methods are currently replaced by PyLong, via macros in npy_3kcompat.h.
Dtype decision rules were changed accordingly, so that NumPy understands Py3 int translate to NPY_LONG as far as dtypes are concerned.
array([1]).dtype will be the default NPY_LONG integer.
.. todo::
Not inheriting from `int` on Python 3 makes the following not work:
``np.intp("0xff", 16)`` -- because the NumPy type does not take
the second argument. This could perhaps be fixed...
The Divide operation is no more.
Calls to PyNumber_Divide were replaced by FloorDivide or TrueDivide, as appropriate.
The PyNumberMethods entry is #ifdef'd out on Py3, see above.
The compare method has vanished, and is replaced with richcompare. We just #ifdef the compare methods out on Py3.
New richcompare methods were implemented for:
- flagsobject.c
On the consumer side, we have a convenience wrapper in npy_3kcompat.h providing PyObject_Cmp also on Py3.
The ndarray and dtype __setstate__ were modified to be backward-compatible with Py3: they need to accept a Unicode endian character, and Unicode data since that's what Py2 str is unpickled to in Py3.
An encoding assumption is required for backward compatibility: the user must do
loads(f, encoding='latin1')
to successfully read pickles created by Py2.
.. todo:: Forward compatibility? Is it even possible? For sure, we are not knowingly going to store data in PyUnicode, so probably the only way for forward compatibility is to implement a custom Unpickler for Py2?
.. todo:: If forward compatibility is not possible, aim to store also the endian character as Bytes...
The module initialization API changed in Python 3.1.
Most NumPy modules are now converted.
The PyTypeObject of py3k is binary compatible with the py2k version and the old initializers should work. However, there are several considerations to keep in mind.
- Because the first three slots are now part of a struct some compilers issue warnings if they are initialized in the old way.
- The compare slot has been made reserved in order to preserve binary compatibility while the tp_compare function went away. The tp_richcompare function has replaced it and we need to use that slot instead. This will likely require modifications in the searchsorted functions and generic sorts that currently use the compare function.
- The previous numpy practice of initializing the COUNT_ALLOCS slots was bogus. They are not supposed to be explicitly initialized and were out of place in any case because an extra base slot was added in python 2.6.
Because of these facts it is better to use #ifdefs to bring the old initializers up to py3k snuff rather than just fill the tp_richcompare slot. They also serve to mark the places where changes have been made. Note that explicit initialization can stop once none of the remaining entries are non-zero, because zero is the default value that variables with non-local linkage receive.
The Py2/Py3 compatible TypeObject definition looks like:
NPY_NO_EXPORT PyTypeObject Foo_Type = {
#if defined(NPY_PY3K)
PyVarObject_HEAD_INIT(0,0)
#else
PyObject_HEAD_INIT(0)
0, /* ob_size */
#endif
"numpy.foo" /* tp_name */
0, /* tp_basicsize */
0, /* tp_itemsize */
/* methods */
0, /* tp_dealloc */
0, /* tp_print */
0, /* tp_getattr */
0, /* tp_setattr */
#if defined(NPY_PY3K)
(void *)0, /* tp_reserved */
#else
0, /* tp_compare */
#endif
0, /* tp_repr */
0, /* tp_as_number */
0, /* tp_as_sequence */
0, /* tp_as_mapping */
0, /* tp_hash */
0, /* tp_call */
0, /* tp_str */
0, /* tp_getattro */
0, /* tp_setattro */
0, /* tp_as_buffer */
0, /* tp_flags */
0, /* tp_doc */
0, /* tp_traverse */
0, /* tp_clear */
0, /* tp_richcompare */
0, /* tp_weaklistoffset */
0, /* tp_iter */
0, /* tp_iternext */
0, /* tp_methods */
0, /* tp_members */
0, /* tp_getset */
0, /* tp_base */
0, /* tp_dict */
0, /* tp_descr_get */
0, /* tp_descr_set */
0, /* tp_dictoffset */
0, /* tp_init */
0, /* tp_alloc */
0, /* tp_new */
0, /* tp_free */
0, /* tp_is_gc */
0, /* tp_bases */
0, /* tp_mro */
0, /* tp_cache */
0, /* tp_subclasses */
0, /* tp_weaklist */
0, /* tp_del */
0 /* tp_version_tag (2.6) */
};
Types with tp_as_sequence defined
- multiarray/descriptor.c
- multiarray/scalartypes.c.src
- multiarray/arrayobject.c
PySequenceMethods in py3k are binary compatible with py2k, but some of the slots have gone away. I suspect this means some functions need redefining so the semantics of the slots needs to be checked:
PySequenceMethods foo_sequence_methods = {
(lenfunc)0, /* sq_length */
(binaryfunc)0, /* sq_concat */
(ssizeargfunc)0, /* sq_repeat */
(ssizeargfunc)0, /* sq_item */
(void *)0, /* nee sq_slice */
(ssizeobjargproc)0, /* sq_ass_item */
(void *)0, /* nee sq_ass_slice */
(objobjproc)0, /* sq_contains */
(binaryfunc)0, /* sq_inplace_concat */
(ssizeargfunc)0 /* sq_inplace_repeat */
};
Types with tp_as_mapping defined
- multiarray/descriptor.c
- multiarray/iterators.c
- multiarray/scalartypes.c.src
- multiarray/flagsobject.c
- multiarray/arrayobject.c
PyMappingMethods in py3k look to be the same as in py2k. The semantics of the slots needs to be checked:
PyMappingMethods foo_mapping_methods = {
(lenfunc)0, /* mp_length */
(binaryfunc)0, /* mp_subscript */
(objobjargproc)0 /* mp_ass_subscript */
};
Many of the PyFile items have disappeared:
- PyFile_Type
- PyFile_AsFile
- PyFile_FromString
Most importantly, in Py3 there is no way to extract a FILE* pointer from the Python file object. There are, however, new PyFile_* functions for writing and reading data from the file.
Compatibility wrappers that return a dup-ed fdopen file pointer are in private/npy_3kcompat.h. This causes more flushing to be necessary, but it appears there is no alternative solution. The FILE pointer so obtained must be closed with fclose after use.
.. todo:: Should probably be done much later on... Adapt all NumPy I/O to use the PyFile_* methods or the low-level IO routines. In any case, it's unlikely that C stdio can be used any more. Perhaps using PyFile_* makes numpy.tofile e.g. to a gzip to work?
The RO alias for READONLY is no more.
These were replaced, as READONLY is present also on Py2.
Deprecations:
- PyOS_ascii_strtod -> PyOS_double_from_string; curiously enough, PyOS_ascii_strtod is not only deprecated but also causes segfaults
There are some checks for PyInstance in common.c and ctors.c.
Currently, PyInstance_Check is just #ifdef'd out for Py3. This is,
possibly, not the correct thing to do.
.. todo:: Do the right thing for PyInstance checks.
The PyCObject API is removed in Python 3.2, so we need to rewrite it using PyCapsule.
NumPy was changed to use the Capsule API, using NpyCapsule* wrappers.