Author: Armin Rigo <[email protected]>
Branch:
Changeset: r1613:758533c5b7f8
Date: 2014-12-30 04:17 +0100
http://bitbucket.org/cffi/cffi/changeset/758533c5b7f8/
Log: Document ffi.from_buffer()
diff --git a/cffi/api.py b/cffi/api.py
--- a/cffi/api.py
+++ b/cffi/api.py
@@ -267,9 +267,9 @@
return self._backend.buffer(cdata, size)
def from_buffer(self, python_buffer):
- """Return a <cdata 'void *'> that points to the data of the
- given object, which must support the buffer interface. Note
- that this is not meant to be used on the built-in types str,
+ """Return a <cdata 'char[]'> that points to the data of the
+ given Python object, which must support the buffer interface.
+ Note that this is not meant to be used on the built-in types str,
unicode, or bytearray (you can build 'char[]' arrays explicitly)
but only on objects containing large quantities of raw data
in some other format, like 'array.array' or numpy arrays.
diff --git a/doc/source/index.rst b/doc/source/index.rst
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -1230,6 +1230,20 @@
gives inconsistent results on regular byte strings). Use ``buf[:]``
instead.
+``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 (read-write) reference to the existing data, not a copy; for this
+reason, and for PyPy compatibility, it does not work with the built-in
+types str or unicode or bytearray. It is meant to be used on objects
+containing large quantities of raw data, like ``array.array`` or numpy
+arrays. It supports both the old buffer API (in Python 2.x) and the
+new memoryview API. 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. *New in version 0.9.*
+
+.. "versionadded:: 0.9" --- inlined in the previous paragraph
+
``ffi.typeof("C type" or cdata object)``: return an object of type
``<ctype>`` corresponding to the parsed string, or to the C type of the
@@ -1264,10 +1278,9 @@
``ffi.offsetof("C struct type", "fieldname")``: return the offset within
the struct of the given field. Corresponds to ``offsetof()`` in C.
-*New in version 0.9:* ``"fieldname"`` can be ``"x.y"`` in case of nested
-structures.
-.. "versionadded:: 0.9" --- inlined in the previous paragraph
+.. versionchanged:: 0.9
+ ``"fieldname"`` can be ``"x.y"`` in case of nested structures.
``ffi.getctype("C type" or <ctype>, extra="")``: return the string
representation of the given C type. If non-empty, the "extra" string is
@@ -1333,11 +1346,10 @@
sure to keep it alive if it was obtained directly from ``ffi.new()``.
*New in version 0.4.*
-*New in version 0.9:* ``"field"`` can be ``"x.y"`` in case of nested
-structures.
+.. versionchanged:: 0.9
+ ``"field"`` can be ``"x.y"`` in case of nested structures.
.. "versionadded:: 0.4" --- inlined in the previous paragraph
-.. "versionadded:: 0.9" --- inlined in the previous paragraph
Unimplemented features
_______________________________________________
pypy-commit mailing list
[email protected]
https://mail.python.org/mailman/listinfo/pypy-commit
