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) → 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).

Raises
getinfo(path: Text, namespaces: Optional[Collection[Text]] = 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.

Returns

a URL.

Return type

str

Raises

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

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
makedir(path: Text, permissions: Optional[Permissions] = 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
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

io.IOBase

Raises
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
remove(path: Text) → None[source]

Remove a file from the filesystem.

Parameters

path (str) – Path of the file to remove.

Raises
removedir(path: Text) → None[source]

Remove a directory from the filesystem.

Parameters

path (str) – Path of the directory to remove.

Raises
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, 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
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.