OS Filesystem¶
Manage the filesystem provided by your OS.
In essence, an OSFS
is a thin layer over the io
and os
modules
of the Python standard library.
- class fs.osfs.OSFS(root_path: Text, create: bool = False, create_mode: SupportsInt = 511, expand_vars: bool = True)[source]¶
Create an OSFS.
Examples
>>> current_directory_fs = OSFS('.') >>> home_fs = OSFS('~/') >>> windows_system32_fs = OSFS('c://system32')
- __init__(root_path: Text, create: bool = False, create_mode: SupportsInt = 511, expand_vars: bool = True) None [source]¶
Create an OSFS instance.
- Parameters:
root_path (str or PathLike) – An OS path or path-like object to the location on your HD you wish to manage.
create (bool) – Set to
True
to create the root directory if it does not already exist, otherwise the directory should exist prior to creating theOSFS
instance (defaults toFalse
).create_mode (int) – The permissions that will be used to create the directory if
create
isTrue
and the path doesn’t exist, defaults to0o777
.expand_vars (bool) – If
True
(the default) environment variables of the form~
,$name
or${name}
will be expanded.
- Raises:
fs.errors.CreateFailed – If
root_path
does not exist, or could not be created.
- copy(src_path: Text, dst_path: Text, overwrite: bool = False, preserve_time: bool = False) None [source]¶
Copy file contents from
src_path
todst_path
.- Parameters:
- Raises:
fs.errors.DestinationExists – If
dst_path
exists, andoverwrite
isFalse
.fs.errors.ResourceNotFound – If a parent directory of
dst_path
does not exist.fs.errors.FileExpected – If
src_path
is not a file.
- getinfo(path: Text, namespaces: Optional[Collection[Text]] = None) Info [source]¶
Get information about a resource on a filesystem.
- Parameters:
- Returns:
resource information object.
- Return type:
- Raises:
fs.errors.ResourceNotFound – If
path
does not exist.
For more information regarding resource information, see Resource Info.
- getsyspath(path: Text) Text [source]¶
Get the system path of a resource.
- Parameters:
path (str) – A path on the filesystem.
- Returns:
the system path of the resource, if any.
- Return type:
- 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.
This method will always return a str on Py3.* and unicode on Py2.7. See
getospath
if you need to encode the path as bytes.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.
- gettype(path: Text) ResourceType [source]¶
Get the type of a resource.
- Parameters:
path (str) – A path on the filesystem.
- Returns:
the type of the resource.
- Return type:
- Raises:
fs.errors.ResourceNotFound – if
path
does not exist.
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: Text, purpose: Text = 'download') Text [source]¶
Get the URL to a 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 forpurpose
: for instance,OSFS
supports'fs'
, which returns a FS URL (see FS URLs).
- Returns:
a URL.
- Return type:
- Raises:
fs.errors.NoURL – If the path does not map to a URL.
- listdir(path: Text) List[Text] [source]¶
Get a list of the resource names in a directory.
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
.- Parameters:
path (str) – A path to a directory on the filesystem
- Returns:
list of names, relative to
path
.- Return type:
- Raises:
fs.errors.DirectoryExpected – If
path
is not a directory.fs.errors.ResourceNotFound – If
path
does not exist.
- makedir(path: Text, permissions: Optional[Permissions] = None, recreate: bool = False) SubFS[_O] [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.
- open(path: Text, mode: Text = 'r', buffering: int = - 1, encoding: Optional[Text] = None, errors: Optional[Text] = None, newline: Text = '', line_buffering: bool = False, **options: Any) IO [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: Text, mode: Text = 'r', buffering: int = - 1, **options: Any) BinaryIO [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
path
exists and is not a file.fs.errors.FileExists – If the
path
exists, and exclusive mode is specified (x
in the mode).fs.errors.ResourceNotFound – If
path
does not exist andmode
does not imply creating the file, or if any ancestor ofpath
does not exist.
- remove(path: Text) None [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: Text) None [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 ( see
removetree
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.
'/'
)
- scandir(path: Text, namespaces: Optional[Collection[Text]] = None, page: Optional[Tuple[int, int]] = None) Iterator[Info] [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 – If
path
is not a directory.fs.errors.ResourceNotFound – If
path
does not exist.
- setinfo(path: Text, info: RawInfo) None [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 – If
path
does not exist on the filesystem
The
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)