| Date: | 2009-12-05 |
|---|---|
| Author: | Charles R. Harris |
| Author: | Pauli Virtanen |
If you work on Py3 transition, please try to keep this document up-to-date.
Information on porting to 3K:
- http://github.com/pv/numpy-work/commits/py3k
- http://github.com/cournape/numpy/commits/py3_bootstrap
- http://github.com/illume/numpy3k/commits/work
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.
- 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.
.. todo:: Check for any other changes ... This we want in the end to include in the release notes, and also in a "how to port" document.
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 most (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.
.. todo:: Should we be a good citizen and use ``lib2to3`` instead?
.. todo:: Do we want to get rid of this hack in the long run?
There are some utility functions needed for 3K compatibility in
numpy.compat.py3k -- they can be imported from numpy.compat:
- bytes: bytes constructor
- asbytes: convert string to bytes (no-op on Py2)
- getexception: get current exception (see below)
- isfileobj: detect Python file objects
More can be added as needed.
Syntax change: "except FooException, bar:" -> "except FooException as bar:"
Code that wants to cater both for Py2 and Py3 should do something like:
try: spam except SpamException: exc = getexception()
This is taken care also 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 hack, it takes care of most parts.
The Print statement changed to a builtin function in Py3.
Probably can generally be replaced by something like:
print("%s %s %s" % (a, b, c))
and in any case, there shouldn't be many print() statements in a library as low-level as Numpy is. When writing to a file, file.write should also be preferred to print.
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.
.. todo:: BufferType should probably be replaced with `memoryview` in most places. This was currently changed in a couple of places.
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_MAJOR_VERSION)?
Convenience macros for Python 3 support:
- PyInt -> PyLong on Py3
- PyString -> PyBytes on Py3
- PyUString -> PyUnicode on Py3 and PyString on Py2
- PyBytes on Py3
- Py_SIZE et al., for older Python versions
- PyFile compatibility on Py3
- PyObject_Cmp, convenience comparison function on Py3
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.
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*/
#if PY_VERSION_HEX >= 0x02050000
(unaryfunc)NULL, /*nb_index*/
#endif
};
.. todo:: Check if semantics of the methods have changed
.. todo:: We will also have to make sure the *_true_divide variants are defined. This should also be done for python < 3.x, but that introduces a requirement for the Py_TPFLAGS_HAVE_CLASS in the type flag.
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.
Currently, the format string and some of the memory is cached in the PyArrayObject structure. This is partly needed because of Python bug #7433.
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 contortions. But basically, since the strides and shape
of an array are locked when references to it are held, we can do with
a single allocated Py_ssize_t shape+strides buffer.
The buffer format string is currently cached in the dtype object.
Currently, there's a slight problem as dtypes are not immutable --
the names of the fields can be changed. Right now, this issue is
just ignored, and the field names in the buffer format string are
not updated.
From the consumer side, the new buffer protocol is mostly backward compatible with the old one, so little needs to be done here to retain basic functionality. However, we do want to make use of the new features, at least in multiarray.frombuffer and maybe in multiarray.array.
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 are a couple of places that need further attention:
VOID_getitem
In some cases, this returns a buffer object, built from scratch to point to a region of memory. However, in Py3 there is no stand-alone buffer object: the MemoryView always piggy-packs on some other object.
Should it actually return a Bytes object containing a copy of the data?
multiarray.int_asbuffer
Converts an integer to a void* pointer -- in Python.
Should we just remove this for Py3? It doesn't seem like it is used anywhere, and it doesn't sound very useful.
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:: Is there a cleaner way out of the ``bf_releasebuffer`` issue? It seems a bit that on Py2.6, the new buffer interface is a bit troublesome, as apparently Numpy will be the first piece of code exercising it more fully. It seems we should submit patches to Python on this. At least "s#" implementation on Py3 won't work at all, since the old buffer interface is no more present.
.. todo:: Find a way around the dtype mutability issue. Note that we cannot just realloc the format string when the names are changed: this would invalidate any existing buffer interfaces. And since we can't define ``bf_releasebuffer``, we don't know if there are any buffer interfaces present. One solution would be to alloc a "big enough" buffer at the beginning, and not change it after that. We could also make the strides etc. in the ``buffer_info`` structure static size. There's MAXDIMS present after all.
.. todo:: Take a second look at places that used PyBuffer_FromMemory and PyBuffer_FromReadWriteMemory -- what can be done with these?
.. todo:: Implement support for consuming new buffer objects. Probably in multiarray.frombuffer? Perhaps also in multiarray.array?
.. todo:: make ndarray shape and strides natively Py_ssize_t
.. todo:: Revise the decision on where to cache the format string -- dtype would be a better place for this.
.. todo:: There's some buffer code in numarray/_capi.c that needs to be addressed.
.. todo:: Does altering the PyArrayObject structure require bumping the ABI?
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
.. todo:: ufunc names -- again, what's the encoding?
.. todo:: Replace all occurrences of PyString by PyBytes, PyUnicode, or PyUString.
.. todo:: Finally, remove the convenience PyString #define from npy_3kcompat.h
.. 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.
"Strings" in Py3 are now Unicode, so it would make sense to re-associate Numpy's dtype letter 'S' with Unicode, and introduce a separate letter for Bytes.
The Bytes dtype can probably not be wholly dropped -- there may be some use for 1-byte character strings in e.g. genetics?
.. todo:: 'S' dtype should be aliased to 'U'. One of the two should be deprecated.
.. todo:: All dtype code should be checked for usage of *_STRINGLTR.
.. todo:: A new 'bytes' dtype? Should the type code be 'y'
.. todo:: Catch all worms that come out of the can because of this change. In any case, I guess many of the current failures in our test suite are because code 'S' does not correspond to the `str` type.
.. todo:: Currently, in parts of the code, both Bytes and Unicode strings are classified as "strings", and share some of the code paths. It should probably be checked if preferring Unicode for Py3 requires changing some of these parts.
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.
.. todo:: Decide on * what is: array([1]).dtype * what is: array([2**40]).dtype * what is: array([2**256]).dtype * what is: array([1]) + 2**40 * what is: array([1]) + 2**256 ie. dtype casting rules. It seems to <pv> that we will want to fix the dtype of Python 3 int to be the machine integer size, despite the fact that the actual Python 3 object is not fixed-size.
.. todo:: Audit the automatic dtype decision -- did I plug all the cases?
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.
.. todo:: Ensure that all types that had only tp_compare have also tp_richcompare.
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 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 compatibily 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 */
};
.. todo:: Check semantics of the PySequence methods.
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 */
};
.. todo:: Check semantics of the PyMapping methods.
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.
Temporary compatibility wrappers that return a fdopen file pointer are in private/npy_3kcompat.h. However, this is an unsatisfactory approach, since the FILE* pointer returned by fdopen cannot be freed as fclose on it would also close the underlying file.
.. todo:: 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.
This has vanished and is always on in Py3K.
It is currently #ifdef'd out for Py3.
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,
quite likely, not the correct thing to do.
.. todo:: Do the right thing for PyInstance checks.