Author: Armin Rigo <[email protected]> Branch: Changeset: r2856:3234afed406d Date: 2017-01-04 18:44 +0100 http://bitbucket.org/cffi/cffi/changeset/3234afed406d/
Log: Tweaks the docs diff --git a/doc/source/ref.rst b/doc/source/ref.rst --- a/doc/source/ref.rst +++ b/doc/source/ref.rst @@ -175,15 +175,16 @@ **ffi.from_buffer(python_buffer)**: return a ``<cdata 'char[]'>`` that points to the data of the given Python object, which must support the buffer interface. This is the opposite of ``ffi.buffer()``. It gives -a reference to the existing data, not a copy; It does not work with the built-in -type unicode. +a reference to the existing data, not a copy. It is meant to be used on objects containing large quantities of raw data, like bytearrays or ``array.array`` or numpy -arrays. It supports both the old buffer API (in Python 2.x) and the -new memoryview API. Note that if you pass a read-only buffer object, +arrays. It supports both the old *buffer* API (in Python 2.x) and the +new *memoryview* API. Note that if you pass a read-only buffer object, you still get a regular ``<cdata 'char[]'>``; it is your responsibility not to write there if the original buffer doesn't expect you to. +*In particular, never modify byte strings!* + The original object is kept alive (and, in case of memoryview, locked) as long as the cdata object returned by ``ffi.from_buffer()`` is alive. @@ -193,13 +194,11 @@ can directly pass ``ffi.from_buffer(python_buffer)`` as argument to the call. -*New in version 1.7:* the python_buffer can be a bytearray object. -Be careful: if the bytearray gets resized (e.g. its ``.append()`` -method is called), then the ``<cdata>`` object will point to freed -memory and must not be used any more. - -*New in version 1.8:* the python_buffer can be a byte string (but still -not a buffer/memoryview on a string). Never modify a byte string! +*New in version 1.10:* the ``python_buffer`` can be anything supporting +the buffer/memoryview interface (except unicode strings). Previously, +bytearray objects were supported in version 1.7 onwards (careful, if you +resize the bytearray, the ``<cdata>`` object will point to freed +memory); and byte strings were supported in version 1.8 onwards. ffi.memmove() @@ -211,8 +210,7 @@ areas can overlap. Each of ``dest`` and ``src`` can be either a cdata pointer or a Python object supporting the buffer/memoryview interface. In the case of ``dest``, the buffer/memoryview must be writable. -Unlike ``ffi.from_buffer()``, there are no restrictions on the type of -buffer. *New in version 1.3.* Examples: +*New in version 1.3.* Examples: * ``ffi.memmove(myptr, b"hello", 5)`` copies the 5 bytes of ``b"hello"`` to the area that ``myptr`` points to. @@ -223,6 +221,8 @@ * ``ffi.memmove(myptr + 1, myptr, 100)`` shifts 100 bytes from the memory at ``myptr`` to the memory at ``myptr + 1``. +In versions before 1.10, ``ffi.from_buffer()`` had restrictions on the +type of buffer, which made ``ffi.memmove()`` more general. .. _ffi-typeof: .. _ffi-sizeof: diff --git a/doc/source/whatsnew.rst b/doc/source/whatsnew.rst --- a/doc/source/whatsnew.rst +++ b/doc/source/whatsnew.rst @@ -3,8 +3,8 @@ ====================== -v1.9.2 -====== +v1.10 +===== * Issue #295: use calloc() directly instead of PyObject_Malloc()+memset() to handle ffi.new() with a default @@ -23,8 +23,13 @@ * Add support for some obscure compilers (non-msvc, non-gcc, non-icc, non-clang) -* ``ffi.from_buffer`` allows Python 2 strings and Python 3 bytes to be - passed. Unicode is the only type disallowed. +* Implemented the remaining cases for ``ffi.from_buffer``. Now all + buffer/memoryview objects can be passed. The one remaining check is + against passing unicode strings in Python 2. (They support the buffer + interface, but that gives the raw bytes behind the UTF16/UCS4 storage, + which is most of the times not what you expect. In Python 3 this has + been fixed and the unicode strings don't support the memoryview + interface any more.) v1.9 ==== _______________________________________________ pypy-commit mailing list [email protected] https://mail.python.org/mailman/listinfo/pypy-commit
