fs.base.FS¶
The filesystem base class is common to all filesystems. If you familiarize yourself with this (rather straightforward) API, you can work with any of the supported filesystems.
-
class
fs.base.
FS
¶ Base class for FS objects.
-
appendbytes
(path, data)¶ Append bytes to the end of a file. Creating the file if it doesn’t already exists.
Parameters: - path (str) – Path to a file.
- data (bytes) – Bytes to append.
Raises: - ValueError – if
data
is not bytes. - fs.errors.ResourceNotFound – if a parent directory of
path
does not exist.
-
appendtext
(path, text, encoding=u'utf-8', errors=None, newline=u'')¶ Append text to a file. Creating the file if it doesn’t already exists.
Parameters: - path (str) – Path to a file.
- text (str) – Text to append.
Raises: - ValueError – if
text
is not bytes. - fs.errors.ResourceNotFound – if a parent directory of
path
does not exist.
-
check
()¶ Check a filesystem may be used.
Will throw a
FilesystemClosed
if the filesystem is closed.Returns: None Raises: fs.errors.FilesystemClosed – if the filesystem is closed.
-
close
()¶ Close the filesystem and release any resources.
It is important to call this method when you have finished working with the filesystem. Some filesystems may not finalize changes until they are closed (archives for example). You may call this method explicitly (it is safe to call close multiple times), or you can use the filesystem as a context manager to automatically close.
Here’s an example of automatically closing a filesystem:
with OSFS('~/Desktop') as desktop_fs: desktop_fs.settext( 'note.txt', "Don't forget to tape Game of Thrones" )
If you attempt to use a filesystem that has been closed, a
FilesystemClosed
exception will be thrown.
-
copy
(src_path, dst_path, overwrite=False)¶ Copy file contents from
src_path
todst_path
.Parameters: - src_path (str) – Path of source file.
- dst_path (str) – Path to destination file.
Raises: - fs.errors.DestinationExists – If
dst_path
exists, and overwrite ==False
. - fs.errors.ResourceNotFound – If a parent directory of
dst_path
does not exist.
-
copydir
(src_path, dst_path, create=False)¶ Copy the contents of
src_path
todst_path
.Parameters: - src_path (str) – Source directory.
- dst_path (str) – Destination directory.
- create (bool) – If
True
thensrc_path
will be created if it doesn’t already exist.
Raises: fs.errors.ResourceNotFound – If the destination directory does not exist, and
create
is not True.
-
create
(path, wipe=False)¶ Create an empty file.
Parameters: - path (str) – Path to new file in filesystem.
- wipe (bool) – Truncate any existing file to 0 bytes.
Returns: True
if file was created,False
if it already existed.Return type: bool
The default behavior is to create a new file if one doesn’t already exist. If
wipe == True
an existing file will be truncated.
-
desc
(path)¶ Return a short descriptive text regarding a path.
Parameters: path (str) – A path to a resource on the filesystem. Return type: str
-
exists
(path)¶ Check if a path maps to a resource.
Parameters: path (str) – Path to a resource Return type: bool A
path
exists if it maps to any resource (including a directory).
-
filterdir
(path, files=None, dirs=None, exclude_dirs=None, exclude_files=None, namespaces=None, page=None)¶ Get an iterator of resource info, filtered by file patterns.
Parameters: - path (str) – A path to a directory on the filesystem.
- files (list) – A list of unix shell-style patterns to filter
file names, e.g.
['*.py']
. - dirs (list) – A list of unix shell-style wildcards to filter directory names.
- exclude_dirs (list) – An optional list of patterns used to exclude directories
- exclude_files (list) – An optional list of patterns used to exclude files.
- namespaces (list) – A list of namespaces to include in the resource information.
- page (tuple or None) – 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: iterator
This method enhances
scandir()
with additional filtering functionality.
-
getbasic
(path)¶ Get the basic resource info.
Parameters: path (str) – A path on the filesystem. Returns: Resource information object for path
.Return type: Info
This method is shorthand for the following:
fs.getinfo(path, namespaces=['basic'])
-
getbytes
(path)¶ Get the contents of a file as bytes.
Parameters: path (str) – A path to a readable file on the filesystem. Returns: file contents Return type: bytes Raises: fs.errors.ResourceNotFound – If path
does not exist.
-
getdetails
(path)¶ Get the details resource info.
Parameters: path (str) – A path on the filesystem. Returns: Resource information object for path
.Return type: Info
This method is shorthand for the following:
fs.getinfo(path, namespaces=['details'])
-
getinfo
(path, namespaces=None)¶ Get information regarding a resource (file or directory) on a filesystem.
Parameters: - path (str) – A path to a resource on the filesystem.
- namespaces (list or None) – Info namespaces to query (defaults to ‘basic’).
Returns: Resource information object.
Return type: For more information regarding resource information see Resource Info.
-
getmeta
(namespace=u'standard')¶ Get meta information regarding a filesystem.
Parameters: - keys (list or None) – A list of keys to retrieve, or None for all keys.
- namespace (str) – The meta namespace (default is “standard”).
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 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 an os.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.
-
getsize
(path)¶ Get the size (in bytes) of a resource.
Parameters: path (str) – A path to a resource. Return type: int The size of a file is the total number of readable bytes, which may not reflect the exact number of bytes of reserved disk space (or other storage medium).
The size of a directory is the number of bytes of overhead use to store the directory entry.
-
getsyspath
(path)¶ Get an system path to a resource.
Parameters: path (str) – A path on the filesystem. Return type: str Raises: fs.errors.NoSysPath – If there is no corresponding system path. A system path is one recognized by the OS, that may be used outside of PyFilesystem (in an application or a shell for example). This method will get the corresponding system path that would be referenced by
path
.Not all filesystems have associated system paths. Network and memory based filesystems, for example, may not physically store data anywhere the OS knows about. It is also possible for some paths to have a system path, whereas others don’t.
If
path
doesn’t have a system path, aNoSysPath
exception will be thrown.Note
A filesystem may return a system path even if no resource is referenced by that path – as long as it can be certain what that system path would be.
-
gettext
(path, encoding=None, errors=None, newline=u'')¶ Get the contents of a file as a string.
Parameters: - path (str) – A path to a readable file on the filesystem.
- encoding (str) – Encoding to use when reading contents in text mode.
- errors (str) – Unicode errors parameter.
- newline (str) – Newlines parameter.
Returns: file contents.
Raises: fs.errors.ResourceNotFound – If
path
does not exist.
-
gettype
(path)¶ Get the type of a resource.
Parameters: path – A path in the filesystem. Returns: ResourceType
A type of a resource is an integer that identifies the what the resource references. The standard type integers may be one of the values in the
ResourceType
enumerations.The most common resource types, supported by virtually all filesystems are
directory
(1) andfile
(2), but the following types are also possible:ResourceType value unknown 0 directory 1 file 2 character 3 block_special_file 4 fifo 5 socket 6 symlink 7 Standard resource types are positive integers, negative values are reserved for implementation specific resource types.
-
geturl
(path, purpose=u'download')¶ Get a URL to the given resource.
Parameters: - path (str) – A path on the filesystem
- purpose (str) – A short string that indicates which URL to
retrieve for the given path (if there is more than one). The
default is ‘download’, which should return a URL that
serves the file. Other filesystems may support other values
for
purpose
.
Returns: A URL.
Return type: str
Raises: fs.errors.NoURL – If the path does not map to a URL.
-
hassyspath
(path)¶ Check if a path maps to a system path.
Parameters: path (str) – A path on the filesystem Return type: bool
-
hasurl
(path, purpose=u'download')¶ Check if a path has a corresponding URL.
Parameters: - path (str) – A path on the filesystem
- purpose (str) – A purpose parameter, as given in
geturl()
.
Return type: bool
-
isclosed
()¶ Check if the filesystem is closed.
-
isdir
(path)¶ Check a path exists and is a directory.
-
isempty
(path)¶ Check if a directory is empty (contains no files or directories).
Parameters: path (str) – A directory path. Return type: bool
-
isfile
(path)¶ Check a path exists and is a file.
-
islink
(path)¶ Check if a path is a symlink.
Parameters: path (str) – A path on the filesystem. Return type: bool
-
listdir
(path)¶ Get a list of the resource names in a directory.
Parameters: path (str) – A path to a directory on the filesystem.
Returns: list of names, relative to
path
.Return type: list
Raises: - fs.errors.DirectoryExpected – If path is not a directory.
- fs.errors.ResourceNotFound – If path does not exist.
This method will return a list of the resources in a directory. A ‘resource’ is a file, directory, or one of the other types defined in
ResourceType
.
-
lock
()¶ Get a context manager that locks the filesystem.
Locking a filesystem gives a thread exclusive access to it. Other threads will block until the threads with the lock has left the context manager. Here’s how you would use it:
with my_fs.lock(): # May block # code here has exclusive access to the filesystem
It is a good idea to put a lock around any operations that you would like to be atomic. For instance if you are copying files, and you don’t want another thread to delete or modify anything while the copy is in progress.
Locking with this method is only required for code that calls multiple filesystem methods. Individual methods are thread safe already, and don’t need to be locked.
Note
This only locks at the Python level. There is nothing to prevent other processes from modifying the filesystem outside of the filesystem instance.
-
makedir
(path, permissions=None, recreate=False)¶ Make a directory, and return a
SubFS
for the new directory.Parameters: - path (str) – Path to directory from root.
- permissions (Permissions) –
Permissions
instance. - recreate (bool) – Do not raise an error if the directory exists.
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)¶ Make a directory, and any missing intermediate directories.
Parameters: - path (str) – Path to directory from root.
- recreate (bool) – If
False
(default), it is an error to attempt to create a directory that already exists. Set to True to allow directories to be re-created without errors. - permissions – Initial permissions.
Returns: A sub-directory filesystem.
Return type: Raises: - fs.errors.DirectoryExists – if the path is already
a directory, and
recreate
is False. - fs.errors.DirectoryExpected – if one of the ancestors in the path isn’t a directory.
-
match
(patterns, name)¶ Check if a name matches any of a list of wildcards.
Parameters: - patterns (list) – A list of patterns, e.g.
['*.py']
- name (str) – A file or directory name (not a path)
Return type: bool
If a filesystem is case insensitive (such as Windows) then this method will perform a case insensitive match (i.e.
*.py
will match the same names as*.PY
). Otherwise the match will be case sensitive (*.py
and*.PY
will match different names).>>> home_fs.match(['*.py'], '__init__.py') True >>> home_fs.match(['*.jpg', '*.png'], 'foo.gif') False
If
patterns
isNone
, or (['*']
), then this method will always return True.- patterns (list) – A list of patterns, e.g.
-
move
(src_path, dst_path, overwrite=False)¶ Move a file from src_path to dst_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.
Raises: - fs.errors.DestinationExists – If
dst_path
exists, and overwrite ==False
. - fs.errors.ResourceNotFound – If a parent directory of
dst_path
does not exist.
-
movedir
(src_path, dst_path, create=False)¶ Move contents of directory
src_path
todst_path
.Parameters: - src_path (str) – Path to source directory on the filesystem.
- dst_path (str) – Path to destination directory.
- create (bool) – If
True
, thendst_path
will be created if it doesn’t already exist.
-
open
(path, mode=u'r', buffering=-1, encoding=None, errors=None, newline=u'', **options)¶ Open a file.
Parameters: - path (str) – A path to a file on the filesystem.
- mode (str) – Mode to open file object.
- buffering (int) – Buffering policy:
0
to switch buffering off,1
to select line buffering,>1
to select a fixed-size buffer,-1
to auto-detect. - encoding (str) – Encoding for text files (defaults to
utf-8
) - errors (str) – What to do with unicode decode errors (see stdlib docs)
- newline (str) – New line parameter (See stdlib docs).
- options – Additional keyword parameters to set implementation specific options (if required). See implementation docs for details.
Return type: file object
-
openbin
(path, mode=u'r', buffering=-1, **options)¶ 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). 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 positive integer to indicate buffer size).
- options – Keyword parameters for any additional information required by the filesystem (if any).
Return type: file object
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 path does not exist.
-
opendir
(path, factory=None)¶ Get a filesystem object for a sub-directory.
Parameters: - path (str) – Path to a directory on the filesystem.
- factory – A callable that when invoked with an FS instance
and path will return a new FS object representing the sub-
directory contents. If no factory is supplied then
SubFS()
will be used.
Returns: A filesystem object representing a sub-directory.
Return type: Raises: fs.errors.DirectoryExpected – If
dst_path
does not exist or is not a directory.
-
remove
(path)¶ Remove a file.
Parameters: path (str) – Path to the file you want to remove.
Raises: - fs.errors.FileExpected – if the path is a directory.
- fs.errors.ResourceNotFound – if the path does not exist.
-
removedir
(path)¶ 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 (see
removetree()
if you want to remove the directory contents). - fs.errors.DirectoryExpected – If the path is not a directory.
- fs.errors.ResourceNotFound – If the path does not exist.
- fs.errors.RemoveRootError – If an attempt is made to remove the root directory (i.e. ‘/’).
- fs.errors.DirectoryNotEmpty – If the directory is not
empty (see
-
removetree
(dir_path)¶ Recursively remove the contents of a directory.
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.
-
scandir
(path, namespaces=None, page=None)¶ Get an iterator of resource info.
Parameters: - path (str) – A path on the filesystem
- namespaces (list) – A sequence of info namespaces.
- page (tuple or None) – May be a tuple of
(<start>, <end>)
indexes to return an iterator of a subset of the resource info, orNone
to iterator the entire directory. Paging a directory scan may be necessary for very large directories.
Return type: iterator
-
setbinfile
(path, file)¶ Set a file to the contents of a binary file object.
Parameters: - path (str) – A path on the filesystem.
- file (file object) – A file object open for reading in binary mode.
This method copies bytes from an open binary file to a file on the filesystem. If the destination exists, it will first be truncated.
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). For example:with open('myfile.bin') as read_file: my_fs.setbinfile('myfile.bin', read_file)
-
setbytes
(path, contents)¶ Copy (bytes) data to a file.
Parameters: - path (str) – Destination path on the filesystem.
- contents (bytes) – A bytes object with data to be written
-
setfile
(path, file, encoding=None, errors=None, newline=None)¶ Set a file to the contents of a file object.
Parameters: - path (str) – A path on the filesystem.
- file (file object) – A file object open for reading.
- encoding (str) – Encoding of destination file, or
None
for binary. - errors (str) – How encoding errors should be treated (same
as
io.open
). - newline (str) – Newline parameter (same is
io.open
).
This method will read the contents of a supplied file object, and write to a file on the filesystem. If the destination exists, it will first be truncated.
If encoding is supplied, the destination will be opened in text mode.
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). For example:with open('myfile.bin') as read_file: my_fs.setfile('myfile.bin', read_file)
-
setinfo
(path, info)¶ Set info on a resource.
Parameters: - path (str) – Path to a resource on the filesystem.
- info (dict) – Dict of resource info.
Raises: fs.errors.ResourceNotFound – If path does not exist on the filesystem.
This method is the compliment to
getinfo
and is used to set info values on a resource.The
info
dict should be in the same format as the raw info returned bygetinfo(file).raw
. Here’s an example:details_info = { "details": { "modified_time": time.time() } } my_fs.setinfo('file.txt', details_info)
-
settext
(path, contents, encoding=u'utf-8', errors=None, newline=u'')¶ Create or replace a file with text.
Parameters: - contents (str) – Path on the filesystem.
- encoding (str) – Encoding of destination file (default ‘UTF-8).
- errors (str) – Error parameter for encoding (same as
io.open
). - newline (str) – Newline parameter for encoding (same as
io.open
).
-
settimes
(path, accessed=None, modified=None)¶ Set the accessed and modified time on a resource.
Parameters: - accessed – The accessed time, as a datetime, or None to use the current rime.
- modified – The modified time, or
None
(the default) to use the same time asaccessed
parameter.
-
touch
(path)¶ Create 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.
-
tree
(**kwargs)¶ Render a tree view of the filesystem to stdout or a file.
The parameters are passed to
render()
.
-
validatepath
(path)¶ Check if a path is valid on this filesystem, and return a normalized absolute path.
Many filesystems have restrictions on the format of paths they support. This method will check that
path
is valid on the underlaying storage mechanism and throw aInvalidPath
exception if it is not.Parameters: path (str) – A path
Returns: A normalized, absolute path.
Return type: str
Raises: - fs.errors.InvalidPath – If the path is invalid.
- fs.errors.FilesystemClosed – if the filesystem is closed.
-
walk
¶ Get a
BoundWalker
object for this filesystem.
-