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 the OSFS instance (defaults to False).
create_mode (int) – The permissions that will be used to create the directory if create is True and the path doesn’t exist, defaults to 0o777.
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 to dst_path.

Parameters:

src_path (str) – Path of source file.
dst_path (str) – Path to destination file.
overwrite (bool) – If True, overwrite the destination file if it exists (defaults to False).
preserve_time (bool) – If True, try to preserve mtime of the resource (defaults to False).

Raises:

fs.errors.DestinationExists – If dst_path exists, and overwrite is False.
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: Collection[Text] | None = None) → Info[source]¶

Get information about a resource on a filesystem.

Parameters:

path (str) – A path to a resource on the filesystem.
namespaces (list, optional) – Info namespaces to query. The "basic" namespace is alway included in the returned info, whatever the value of namespaces may be.

Returns:

resource information object.

Return type:

Info

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:: 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.

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, a NoSysPath 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:: ResourceType
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) and file (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 for purpose: for instance, OSFS supports 'fs', which returns a FS URL (see FS URLs).

Returns:

a URL.

Return type:

str

Raises:

fs.errors.NoURL – If the path does not map to a URL.

islink(path: Text) → bool[source]¶

Check if a path maps to a symlink.

Parameters:: path (str) – A path on the filesystem.
Returns:: True if path maps to a symlink.
Return type:: bool

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:

list

Raises:

fs.errors.DirectoryExpected – If path is not a directory.
fs.errors.ResourceNotFound – If path does not exist.

makedir(path: Text, permissions: Permissions | None = None, recreate: bool = False) → SubFS[_O][source]¶

Make a directory.

Parameters:

path (str) – Path to directory from root.
permissions (Permissions, optional) – a Permissions instance, or None to use default.
recreate (bool) – Set to True to avoid raising an error if the directory already exists (defaults to False).

Returns:

a filesystem whose root is the new directory.

Return type:

SubFS

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: Text | None = None, errors: Text | None = 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:

io.IOBase

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:

io.IOBase

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 and mode does not imply creating the file, or if any ancestor of path 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: Collection[Text] | None = None, page: Tuple[int, int] | None = 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, or None 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

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:

path (str) – Path to a resource on the filesystem.
info (dict) – Dictionary of resource info.

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 by getinfo(file).raw.

Example

>>> details_info = {"details": {
...     "modified": time.time()
... }}
>>> my_fs.setinfo('file.txt', details_info)

validatepath(path: Text) → Text[source]¶: Check path may be encoded, in addition to usual checks.