[arrow] branch master updated: ARROW-3727: [Python] Document use of foreign_buffer()

[we...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

wesm pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/arrow.git


The following commit(s) were added to refs/heads/master by this push:
     new e4761e0  ARROW-3727: [Python] Document use of foreign_buffer()
e4761e0 is described below

commit e4761e07d6d32e8c3fddac20f0abca0bb89543ad
Author: Antoine Pitrou <an...@python.org>
AuthorDate: Mon Dec 10 09:12:40 2018 -0600

    ARROW-3727: [Python] Document use of foreign_buffer()
    
    Author: Antoine Pitrou <an...@python.org>
    
    Closes #3146 from pitrou/ARROW-3727-foreign-buffer-doc and squashes the following commits:
    
    e81a5f0cf <Antoine Pitrou> ARROW-3727:  Document use of foreign_buffer()
---
 docs/source/python/memory.rst | 23 ++++++++++++++---------
 python/pyarrow/io.pxi         |  8 ++++++--
 2 files changed, 20 insertions(+), 11 deletions(-)

diff --git a/docs/source/python/memory.rst b/docs/source/python/memory.rst
index 1ee81e7..0d30866 100644
--- a/docs/source/python/memory.rst
+++ b/docs/source/python/memory.rst
@@ -35,8 +35,8 @@ Referencing and Allocating Memory
 pyarrow.Buffer
 --------------
 
-The :class:`~pyarrow.Buffer` object wraps the C++ ``arrow::Buffer`` type and is
-the primary tool for memory management in Apache Arrow in C++. It permits
+The :class:`Buffer` object wraps the C++ :cpp:class:`arrow::Buffer` type
+which is the primary tool for memory management in Apache Arrow in C++. It permits
 higher-level array classes to safely interact with memory which they may or may
 not own. ``arrow::Buffer`` can be zero-copy sliced to permit Buffers to cheaply
 reference other Buffers, while preserving memory lifetime and clean
@@ -46,8 +46,9 @@ There are many implementations of ``arrow::Buffer``, but they all provide a
 standard interface: a data pointer and length. This is similar to Python's
 built-in `buffer protocol` and ``memoryview`` objects.
 
-A :class:`~pyarrow.Buffer` can be created from any Python object which
-implements the buffer protocol. Let's consider a bytes object:
+A :class:`Buffer` can be created from any Python object implementing
+the buffer protocol by calling the :func:`py_buffer` function. Let's consider
+a bytes object:
 
 .. ipython:: python
 
@@ -61,18 +62,22 @@ implements the buffer protocol. Let's consider a bytes object:
 Creating a Buffer in this way does not allocate any memory; it is a zero-copy
 view on the memory exported from the ``data`` bytes object.
 
-The Buffer's ``to_pybytes`` method can convert to a Python byte string:
+External memory, under the form of a raw pointer and size, can also be
+referenced using the :func:`foreign_buffer` function.
+
+Buffers can be used in circumstances where a Python buffer or memoryview is
+required, and such conversions are zero-copy:
 
 .. ipython:: python
 
-   buf.to_pybytes()
+   memoryview(buf)
 
-Buffers can be used in circumstances where a Python buffer or memoryview is
-required, and such conversions are also zero-copy:
+The Buffer's :meth:`~Buffer.to_pybytes` method converts the Buffer's data to a
+Python bytestring (thus making a copy of the data):
 
 .. ipython:: python
 
-   memoryview(buf)
+   buf.to_pybytes()
 
 Memory Pools
 ------------
diff --git a/python/pyarrow/io.pxi b/python/pyarrow/io.pxi
index 9f7dc7b..97abde8 100644
--- a/python/pyarrow/io.pxi
+++ b/python/pyarrow/io.pxi
@@ -1173,10 +1173,14 @@ def py_buffer(object obj):
     return pyarrow_wrap_buffer(buf)
 
 
-def foreign_buffer(address, size, base):
+def foreign_buffer(address, size, base=None):
     """
     Construct an Arrow buffer with the given *address* and *size*,
-    backed by the Python *base* object.
+    optionally backed by the Python *base* object.
+
+    The *base* object, if given, will be kept alive as long as this buffer
+    is alive, including accross language boundaries (for example if the
+    buffer is referenced by C++ code).
     """
     cdef:
         intptr_t c_addr = address