jorisvandenbossche commented on code in PR #33698:
URL: https://github.com/apache/arrow/pull/33698#discussion_r1072066495
##########
python/pyarrow/io.pxi:
##########
@@ -851,6 +879,16 @@ cdef class MemoryMappedFile(NativeFile):
A stream that represents a memory-mapped file.
Supports 'r', 'r+', 'w' modes.
+
+ Examples
+ --------
+ Create a MemoryMappedFile:
Review Comment:
Maybe clarify here that this is creating a _new_ file, and not creating a
MemoryMappedFile object that is viewing an existing file? (if my understanding
about that is correct)
##########
python/pyarrow/io.pxi:
##########
@@ -1020,6 +1078,22 @@ cdef class OSFile(NativeFile):
cdef class FixedSizeBufferWriter(NativeFile):
"""
A stream writing to a Arrow buffer.
+
+ Examples
+ --------
+ >>> import pyarrow as pa
+ >>> buf = pa.allocate_buffer(5)
+ >>> bit = b'abcde'
+ >>> writer = pa.FixedSizeBufferWriter(buf)
+ >>> writer.write(bit)
Review Comment:
```suggestion
>>> writer = pa.FixedSizeBufferWriter(buf)
>>> writer.write(b'abcde')
```
(since `bit` is not used elsewhere, passing it directly avoids possible
confusion with variable names)
##########
python/pyarrow/io.pxi:
##########
@@ -978,6 +1016,26 @@ def create_memory_map(path, size):
cdef class OSFile(NativeFile):
"""
A stream backed by a regular file descriptor.
+
+ Examples
+ --------
+ >>> import pyarrow as pa
Review Comment:
Can you add some short descriptions of what is being done? ("Creating a new
file to write data to ..", "Opening a file to read..")
##########
python/pyarrow/io.pxi:
##########
@@ -1327,6 +1401,20 @@ def allocate_buffer(int64_t size, MemoryPool
memory_pool=None,
cdef class BufferOutputStream(NativeFile):
+ """
+ Examples
Review Comment:
Can you add a summary first line of the docstring? (before the "Examples"
section)
##########
python/pyarrow/io.pxi:
##########
@@ -851,6 +879,16 @@ cdef class MemoryMappedFile(NativeFile):
A stream that represents a memory-mapped file.
Supports 'r', 'r+', 'w' modes.
+
+ Examples
+ --------
+ Create a MemoryMappedFile:
Review Comment:
And actually, showing `pa.memory_map` to open an existing file with mmap
might be more useful to show here.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscr...@arrow.apache.org
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org
