jorisvandenbossche commented on code in PR #13564:
URL: https://github.com/apache/arrow/pull/13564#discussion_r918636552
##########
python/pyarrow/_fs.pyx:
##########
@@ -100,6 +100,53 @@ cdef class FileInfo(_Weakrefable):
If given, the filesystem entry size in bytes. This should only
be given if `type` is `FileType.File`.
+ Examples
+ --------
+ Generate a file:
+
+ >>> from pyarrow import fs
+ >>> local = fs.LocalFileSystem()
+ >>> with local.open_output_stream('/tmp/fileinfo.dat') as stream:
+ ... stream.write(b'data')
+ ...
+ 4
+
+ Get FileInfo object using `get_file_info()`:
Review Comment:
```suggestion
Get FileInfo object using ``get_file_info()``:
```
(inline code needs a double quote for rst, in contrast to markdown ..)
##########
python/pyarrow/_fs.pyx:
##########
@@ -100,6 +100,53 @@ cdef class FileInfo(_Weakrefable):
If given, the filesystem entry size in bytes. This should only
be given if `type` is `FileType.File`.
+ Examples
+ --------
+ Generate a file:
+
+ >>> from pyarrow import fs
+ >>> local = fs.LocalFileSystem()
+ >>> with local.open_output_stream('/tmp/fileinfo.dat') as stream:
+ ... stream.write(b'data')
+ ...
Review Comment:
You can also leave out this additional `...` line without further content
(you typically get this when trying it interactively in a python console, as
you need an extra enter to start executing it, but for the docstring that only
gives additional vertical space)
##########
python/pyarrow/_fs.pyx:
##########
@@ -260,6 +354,44 @@ cdef class FileSelector(_Weakrefable):
If true, an empty selection is returned.
recursive : bool, default False
Whether to recurse into subdirectories.
+
+ Examples
+ --------
+ Generate a file:
+
+ >>> from pyarrow import fs
+ >>> local = fs.LocalFileSystem()
+ >>> with local.open_output_stream('/tmp/fileinfo.dat') as stream:
+ ... stream.write(b'data')
+ ...
+ 4
Review Comment:
same here
##########
python/pyarrow/_fs.pyx:
##########
@@ -260,6 +354,44 @@ cdef class FileSelector(_Weakrefable):
If true, an empty selection is returned.
recursive : bool, default False
Whether to recurse into subdirectories.
+
+ Examples
+ --------
+ Generate a file:
+
+ >>> from pyarrow import fs
+ >>> local = fs.LocalFileSystem()
+ >>> with local.open_output_stream('/tmp/fileinfo.dat') as stream:
+ ... stream.write(b'data')
+ ...
+ 4
+
+ Create new directory and subdirectory with copied data:
+
+ >>> # directory
+ >>> local.create_dir('/tmp/alphabet')
+ >>> local.copy_file('/tmp/fileinfo.dat', '/tmp/alphabet/fileinfo.dat')
+ >>> # subdirectory
+ >>> local.create_dir('/tmp/alphabet/aeiou')
Review Comment:
I understand that "aeiou" are the vowels of the alphabet ;) But the first
time I read it I found it a bit hard to read (before realizing that it were
just all vowels), so maybe something more boring like "subdir" can make it
easier to read?
##########
python/pyarrow/_fs.pyx:
##########
@@ -100,6 +100,53 @@ cdef class FileInfo(_Weakrefable):
If given, the filesystem entry size in bytes. This should only
be given if `type` is `FileType.File`.
+ Examples
+ --------
+ Generate a file:
+
+ >>> from pyarrow import fs
+ >>> local = fs.LocalFileSystem()
+ >>> with local.open_output_stream('/tmp/fileinfo.dat') as stream:
+ ... stream.write(b'data')
+ ...
+ 4
Review Comment:
This "4" is a left-over? (or at least for me, it doesn't print the size of
what gets written)
##########
python/pyarrow/_fs.pyx:
##########
@@ -541,6 +754,12 @@ cdef class FileSystem(_Weakrefable):
The path of the file to be copied from.
dest : str
The destination path where the file is copied to.
+
+ Examples
+ --------
+ >>> local.copy_file('/tmp/fileinfo.dat', '/tmp/fileinfo_copy.dat')
+ >>> local.get_file_info('/tmp/fileinfo_copy.dat')
+ <FileInfo for '/tmp/fileinfo_copy.dat': type=FileType.File, size=4>
Review Comment:
Maybe show here that the original file also still exists? (since that is
what is different compared to `move`)
##########
python/pyarrow/_fs.pyx:
##########
@@ -335,6 +467,21 @@ cdef class FileSystem(_Weakrefable):
tuple of (FileSystem, str path)
With (filesystem, path) tuple where path is the abstract path
inside the FileSystem instance.
+
+ Examples
+ --------
+ Create a new FileSystem subclass from path:
+
+ >>> local_new, path =
fs.LocalFileSystem().from_uri('file:///tmp/fileinfo.dat')
Review Comment:
And actually it's maybe also better (or at least shorter) to use
`FileSystem.from_uri` instead of `LocalFileSystem.from_uri`.
There is nothing about this method that is specific to a FileSystem
subclass, and so it is not because you call it from `LocalFileSystem` that it
is guaranteed to return a local filesystem (eg if you would pass a S3 URI to
the LocalFileSystem, it would (somewhat confusingly) also work fine)
##########
python/pyarrow/_fs.pyx:
##########
@@ -100,6 +100,53 @@ cdef class FileInfo(_Weakrefable):
If given, the filesystem entry size in bytes. This should only
be given if `type` is `FileType.File`.
+ Examples
+ --------
+ Generate a file:
+
+ >>> from pyarrow import fs
+ >>> local = fs.LocalFileSystem()
+ >>> with local.open_output_stream('/tmp/fileinfo.dat') as stream:
+ ... stream.write(b'data')
+ ...
+ 4
+
+ Get FileInfo object using `get_file_info()`:
+
+ >>> local.get_file_info('/tmp/fileinfo.dat')
+ <FileInfo for '/tmp/fileinfo.dat': type=FileType.File, size=4>
+
+ or FileInfo constructor:
+
+ >>> fs.FileInfo('/tmp/fileinfo.dat', type=fs.FileType.File)
+ <FileInfo for '/tmp/fileinfo.dat': type=FileType.File, size=None>
Review Comment:
I am not fully sure we should show the constructor (I don't know of a reason
that someone would want to create one manually?)
##########
python/pyarrow/_fs.pyx:
##########
@@ -335,6 +467,21 @@ cdef class FileSystem(_Weakrefable):
tuple of (FileSystem, str path)
With (filesystem, path) tuple where path is the abstract path
inside the FileSystem instance.
+
+ Examples
+ --------
+ Create a new FileSystem subclass from path:
Review Comment:
```suggestion
Create a new FileSystem subclass from a URI:
```
##########
python/pyarrow/_fs.pyx:
##########
@@ -335,6 +467,21 @@ cdef class FileSystem(_Weakrefable):
tuple of (FileSystem, str path)
With (filesystem, path) tuple where path is the abstract path
inside the FileSystem instance.
+
+ Examples
+ --------
+ Create a new FileSystem subclass from path:
+
+ >>> local_new, path =
fs.LocalFileSystem().from_uri('file:///tmp/fileinfo.dat')
Review Comment:
```suggestion
>>> local_new, path =
fs.LocalFileSystem.from_uri('file:///tmp/fileinfo.dat')
```
Since this is a staticmethod, you actually don't need to call it from an
instance (as you already did for the S3 example below).
##########
python/pyarrow/_fs.pyx:
##########
@@ -422,6 +575,13 @@ cdef class FileSystem(_Weakrefable):
FileInfo or list of FileInfo
Single FileInfo object is returned for a single path, otherwise
a list of FileInfo objects is returned.
+
+ Examples
+ --------
+ >>> local
+ <pyarrow._fs.LocalFileSystem object at ...>
+ >>> local.get_file_info("local.get_file_info(/tmp/fileinfo.dat)")
Review Comment:
The `"local.get_file_info"` inside the path might be a copy-paste mistake?
--
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
