fs.wrap¶
Collection of useful WrapFS
subclasses.
Here’s an example that opens a filesystem then makes it read only:
>>> home_fs = fs.open_fs('~')
>>> read_only_home_fs = fs.wrap.read_only(home_fs)
>>> read_only_home_fs.removedir('Desktop')
Traceback (most recent call last):
...
fs.errors.ResourceReadOnly: resource 'Desktop' is read only
-
class
fs.wrap.
WrapCachedDir
(wrap_fs)[source]¶ Caches filesystem directory information.
This filesystem caches directory information retrieved from a scandir call. This may speed up code that calls
isdir
,isfile
, orgettype
too frequently.Note
Using this wrap will prevent changes to directory information being visible to the filesystem object. Consequently it is best used only in a fairly limited scope where you don’t expected anything on the filesystem to change.
-
getinfo
(path, namespaces=None)[source]¶ Get information about a resource on a filesystem.
Parameters: Returns: resource information object.
Return type: Raises: fs.errors.ResourceNotFound
– Ifpath
does not exist.For more information regarding resource information, see Resource Info.
-
isdir
(path)[source]¶ Check if a path maps to an existing directory.
Parameters: path (str) – A path on the filesystem. Returns: True
ifpath
maps to a directory.Return type: bool
-
isfile
(path)[source]¶ Check if a path maps to an existing file.
Parameters: path (str) – A path on the filesystem. Returns: True
ifpath
maps to a file.Return type: bool
-
scandir
(path, namespaces=None, page=None)[source]¶ Get an iterator of resource info.
Parameters: - path (str) – A path to a directory on the filesystem.
- namespaces (list, optional) – A list of namespaces to include
in the resource information, e.g.
['basic', 'access']
. - page (tuple, optional) – May be a tuple of
(<start>, <end>)
indexes to return an iterator of a subset of the resource info, orNone
to iterate over the entire directory. Paging a directory scan may be necessary for very large directories.
Returns: an iterator of
Info
objects.Return type: Raises: fs.errors.DirectoryExpected
– Ifpath
is not a directory.fs.errors.ResourceNotFound
– Ifpath
does not exist.
-
-
class
fs.wrap.
WrapReadOnly
(wrap_fs)[source]¶ Makes a Filesystem read-only.
Any call that would would write data or modify the filesystem in any way will raise a
ResourceReadOnly
exception.-
appendbytes
(path, data)[source]¶ Append bytes to the end of a file, creating it if needed.
Parameters: Raises: TypeError
– Ifdata
is not abytes
instance.fs.errors.ResourceNotFound
– If a parent directory ofpath
does not exist.
-
appendtext
(path, text, encoding='utf-8', errors=None, newline='')[source]¶ Append text to the end of a file, creating it if needed.
Parameters: Raises: TypeError
– iftext
is not an unicode string.fs.errors.ResourceNotFound
– if a parent directory ofpath
does not exist.
-
copy
(src_path, dst_path, overwrite=False, preserve_time=False)[source]¶ Copy file contents from
src_path
todst_path
.Parameters: Raises: fs.errors.DestinationExists
– Ifdst_path
exists, andoverwrite
isFalse
.fs.errors.ResourceNotFound
– If a parent directory ofdst_path
does not exist.fs.errors.FileExpected
– Ifsrc_path
is not a file.
-
create
(path, wipe=False)[source]¶ Create an empty file.
The default behavior is to create a new file if one doesn’t already exist. If
wipe
isTrue
, any existing file will be truncated.Parameters: Returns: True
if a new file had to be created.Return type:
-
getmeta
(namespace='standard')[source]¶ Get meta information regarding a filesystem.
Parameters: namespace (str) – The meta namespace (defaults to "standard"
).Returns: the meta information. Return type: dict Meta information is associated with a namespace which may be specified with the
namespace
parameter. The default namespace,"standard"
, contains common information regarding the filesystem’s capabilities. Some filesystems may provide other namespaces which expose less common or implementation specific information. If a requested namespace is not supported by a filesystem, then an empty dictionary will be returned.The
"standard"
namespace supports the following keys:key Description case_insensitive True
if this filesystem is case insensitive.invalid_path_chars A string containing the characters that may not be used on this filesystem. max_path_length Maximum number of characters permitted in a path, or None
for no limit.max_sys_path_length Maximum number of characters permitted in a sys path, or None
for no limit.network True
if this filesystem requires a network.read_only True
if this filesystem is read only.supports_rename True
if this filesystem supports anos.rename
operation.Most builtin filesystems will provide all these keys, and third- party filesystems should do so whenever possible, but a key may not be present if there is no way to know the value.
Note
Meta information is constant for the lifetime of the filesystem, and may be cached.
-
makedir
(path, permissions=None, recreate=False)[source]¶ Make a directory.
Parameters: Returns: a filesystem whose root is the new directory.
Return type: Raises: fs.errors.DirectoryExists
– If the path already exists.fs.errors.ResourceNotFound
– If the path is not found.
-
makedirs
(path, permissions=None, recreate=False)[source]¶ Make a directory, and any missing intermediate directories.
Parameters: Returns: A sub-directory filesystem.
Return type: Raises: fs.errors.DirectoryExists
– if the path is already a directory, andrecreate
isFalse
.fs.errors.DirectoryExpected
– if one of the ancestors in the path is not a directory.
-
move
(src_path, dst_path, overwrite=False, preserve_time=False)[source]¶ Move a file from
src_path
todst_path
.Parameters: - src_path (str) – A path on the filesystem to move.
- dst_path (str) – A path on the filesystem where the source file will be written to.
- overwrite (bool) – If
True
, destination path will be overwritten if it exists. - preserve_time (bool) – If
True
, try to preserve mtime of the resources (defaults toFalse
).
Raises: fs.errors.FileExpected
– Ifsrc_path
maps to a directory instead of a file.fs.errors.DestinationExists
– Ifdst_path
exists, andoverwrite
isFalse
.fs.errors.ResourceNotFound
– If a parent directory ofdst_path
does not exist.
-
open
(path, mode='r', buffering=-1, encoding=None, errors=None, newline='', line_buffering=False, **options)[source]¶ Open a file.
Parameters: - path (str) – A path to a file on the filesystem.
- mode (str) – Mode to open the file object with (defaults to r).
- buffering (int) – Buffering policy (-1 to use default buffering, 0 to disable buffering, 1 to select line buffering, of any positive integer to indicate a buffer size).
- encoding (str) – Encoding for text files (defaults to
utf-8
) - errors (str, optional) – What to do with unicode decode errors
(see
codecs
module for more information). - newline (str) – Newline parameter.
- **options – keyword arguments for any additional information required by the filesystem (if any).
Returns: a file-like object.
Return type: Raises: fs.errors.FileExpected
– If the path is not a file.fs.errors.FileExists
– If the file exists, and exclusive mode is specified (x
in the mode).fs.errors.ResourceNotFound
– If the path does not exist.
-
openbin
(path, mode='r', buffering=-1, **options)[source]¶ Open a binary file-like object.
Parameters: - path (str) – A path on the filesystem.
- mode (str) – Mode to open file (must be a valid non-text mode,
defaults to r). Since this method only opens binary files,
the
b
in the mode string is implied. - buffering (int) – Buffering policy (-1 to use default buffering, 0 to disable buffering, or any positive integer to indicate a buffer size).
- **options – keyword arguments for any additional information required by the filesystem (if any).
Returns: a file-like object.
Return type: Raises: fs.errors.FileExpected
– Ifpath
exists and is not a file.fs.errors.FileExists
– If thepath
exists, and exclusive mode is specified (x
in the mode).fs.errors.ResourceNotFound
– Ifpath
does not exist andmode
does not imply creating the file, or if any ancestor ofpath
does not exist.
-
remove
(path)[source]¶ Remove a file from the filesystem.
Parameters: path (str) – Path of the file to remove.
Raises: fs.errors.FileExpected
– If the path is a directory.fs.errors.ResourceNotFound
– If the path does not exist.
-
removedir
(path)[source]¶ Remove a directory from the filesystem.
Parameters: path (str) – Path of the directory to remove.
Raises: fs.errors.DirectoryNotEmpty
– If the directory is not empty ( seeremovetree
for a way to remove the directory contents).fs.errors.DirectoryExpected
– If the path does not refer to a directory.fs.errors.ResourceNotFound
– If no resource exists at the given path.fs.errors.RemoveRootError
– If an attempt is made to remove the root directory (i.e.'/'
)
-
removetree
(path)[source]¶ Recursively remove a directory and all its contents.
This method is similar to
removedir
, but will remove the contents of the directory if it is not empty.Parameters: dir_path (str) – Path to a directory on the filesystem.
Raises: fs.errors.ResourceNotFound
– Ifdir_path
does not exist.fs.errors.DirectoryExpected
– Ifdir_path
is not a directory.
Caution
A filesystem should never delete its root folder, so
FS.removetree("/")
has different semantics: the contents of the root folder will be deleted, but the root will be untouched:>>> home_fs = fs.open_fs("~") >>> home_fs.removetree("/") >>> home_fs.exists("/") True >>> home_fs.isempty("/") True
Combined with
opendir
, this can be used to clear a directory without removing the directory itself:>>> home_fs = fs.open_fs("~") >>> home_fs.opendir("/Videos").removetree("/") >>> home_fs.exists("/Videos") True >>> home_fs.isempty("/Videos") True
-
setinfo
(path, info)[source]¶ Set info on a resource.
This method is the complement to
getinfo
and is used to set info values on a resource.Parameters: Raises: fs.errors.ResourceNotFound
– Ifpath
does not exist on the filesystemThe
info
dict should be in the same format as the raw info returned bygetinfo(file).raw
.Example
>>> details_info = {"details": { ... "modified": time.time() ... }} >>> my_fs.setinfo('file.txt', details_info)
-
settimes
(path, accessed=None, modified=None)[source]¶ Set the accessed and modified time on a resource.
Parameters:
-
touch
(path)[source]¶ Touch a file on the filesystem.
Touching a file means creating a new file if
path
doesn’t exist, or update accessed and modified times if the path does exist. This method is similar to the linux command of the same name.Parameters: path (str) – A path to a file on the filesystem.
-
upload
(path, file, chunk_size=None, **options)[source]¶ Set a file to the contents of a binary file object.
This method copies bytes from an open binary file to a file on the filesystem. If the destination exists, it will first be truncated.
Parameters: - path (str) – A path on the filesystem.
- file (io.IOBase) – a file object open for reading in binary mode.
- chunk_size (int, optional) – Number of bytes to read at a
time, if a simple copy is used, or
None
to use sensible default. - **options – Implementation specific options required to open the source file.
Raises: fs.errors.ResourceNotFound
– If a parent directory ofpath
does not exist.Note that the file object
file
will not be closed by this method. Take care to close it after this method completes (ideally with a context manager).Example
>>> with open('~/movies/starwars.mov', 'rb') as read_file: ... my_fs.upload('starwars.mov', read_file)
-
writebytes
(path, contents)[source]¶ Copy binary data to a file.
Parameters: Raises: TypeError
– if contents is not bytes.
-
writefile
(path, file, encoding=None, errors=None, newline='')[source]¶ Set a file to the contents of a file object.
Parameters: - path (str) – A path on the filesystem.
- file (io.IOBase) – A file object open for reading.
- encoding (str, optional) – Encoding of destination file,
defaults to
None
for binary. - errors (str, optional) – How encoding errors should be treated
(same as
io.open
). - newline (str) – Newline parameter (same as
io.open
).
This method is similar to
upload
, in that it copies data from a file-like object to a resource on the filesystem, but unlikeupload
, this method also supports creating files in text-mode (if theencoding
argument is supplied).Note that the file object
file
will not be closed by this method. Take care to close it after this method completes (ideally with a context manager).Example
>>> with open('myfile.txt') as read_file: ... my_fs.writefile('myfile.txt', read_file)
-