fs.wrap¶
Collection of useful WrapFS
subclasses.
Here’s an example that opens a filesystem then makes it read only:
>>> from fs import open_fs
>>> from fs.wrap import read_only
>>> projects_fs = open_fs('~/projects')
>>> read_only_projects_fs = read_only(projects_fs)
>>> read_only_projects_fs.remove('__init__.py')
Traceback (most recent call last):
...
fs.errors.ResourceReadOnly: resource '__init__.py' 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: 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)[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.
-
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:
-
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)[source]¶ Move a file from
src_path
todst_path
.Parameters: 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
– 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.
-
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.'/'
)
-
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.
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)
-