fs.base

PyFilesystem base class.

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[source]

Base class for FS objects.

__del__()[source]

Auto-close the filesystem on exit.

__enter__()[source]

Allow use of filesystem as a context manager.

__exit__(exc_type, exc_value, traceback)[source]

Close filesystem on exit.

__init__()[source]

Create a filesystem. See help(type(self)) for accurate signature.

appendbytes(path, data)[source]

Append bytes to the end of a file, creating it if needed.

Parameters:
  • path (str) – Path to a file.
  • data (bytes) – Bytes to append.
Raises:
appendtext(path, text, encoding='utf-8', errors=None, newline='')[source]

Append text to the end of a file, creating it if needed.

Parameters:
  • path (str) – Path to a file.
  • text (str) – Text to append.
  • 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.
Raises:
check()[source]

Check if a filesystem may be used.

Raises:fs.errors.FilesystemClosed – if the filesystem is closed.
close()[source]

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.

Example

>>> with OSFS('~/Desktop') as desktop_fs:
...    desktop_fs.writetext(
...        '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, preserve_time=False)[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:
copydir(src_path, dst_path, create=False, preserve_time=False)[source]

Copy the contents of src_path to dst_path.

Parameters:
  • src_path (str) – Path of source directory.
  • dst_path (str) – Path to destination directory.
  • create (bool) – If True, then dst_path will be created if it doesn’t exist already (defaults to False).
  • preserve_time (bool) – If True, try to preserve mtime of the resource (defaults to False).
Raises:
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 is True, any existing file will be truncated.

Parameters:
  • path (str) – Path to a new file in the filesystem.
  • wipe (bool) – If True, truncate any existing file to 0 bytes (defaults to False).
Returns:

True if a new file had to be created.

Return type:

bool

desc(path)[source]

Return a short descriptive text regarding a path.

Parameters:path (str) – A path to a resource on the filesystem.
Returns:a short description of the path.
Return type:str
Raises:fs.errors.ResourceNotFound – If path does not exist.
download(path, file, chunk_size=None, **options)[source]

Copy a file from the filesystem to a file-like object.

This may be more efficient that opening and copying files manually if the filesystem supplies an optimized method.

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

Parameters:
  • path (str) – Path to a resource.
  • file (file-like) – A file-like object open for writing 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.

Example

>>> with open('starwars.mov', 'wb') as write_file:
...     my_fs.download('/Videos/starwars.mov', write_file)
Raises:fs.errors.ResourceNotFound – if path does not exist.
exists(path)[source]

Check if a path maps to a resource.

Parameters:path (str) – Path to a resource.
Returns:True if a resource exists at the given path.
Return type:bool
filterdir(path, files=None, dirs=None, exclude_dirs=None, exclude_files=None, namespaces=None, page=None)[source]

Get an iterator of resource info, filtered by patterns.

This method enhances scandir with additional filtering functionality.

Parameters:
  • path (str) – A path to a directory on the filesystem.
  • files (list, optional) – A list of UNIX shell-style patterns to filter file names, e.g. ['*.py'].
  • dirs (list, optional) – A list of UNIX shell-style patterns to filter directory names.
  • exclude_dirs (list, optional) – A list of patterns used to exclude directories.
  • exclude_files (list, optional) – A list of patterns used to exclude files.
  • 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

getbasic(path)[source]

Get the basic resource info.

This method is shorthand for the following:

fs.getinfo(path, namespaces=['basic'])
Parameters:path (str) – A path on the filesystem.
Returns:Resource information object for path.
Return type:Info

Note

Deprecated since version 2.4.13: Please use getinfo directly, which is required to always return the basic namespace.

getbytes(path)

Get the contents of a file as bytes.

Parameters:

path (str) – A path to a readable file on the filesystem.

Returns:

the file contents.

Return type:

bytes

Raises:

Note

Deprecated since version 2.2.0: Please use readbytes

getdetails(path)[source]

Get the details resource info.

This method is shorthand for the following:

fs.getinfo(path, namespaces=['details'])
Parameters:path (str) – A path on the filesystem.
Returns:Resource information object for path.
Return type:Info
getfile(path, file, chunk_size=None, **options)

Copy a file from the filesystem to a file-like object.

This may be more efficient that opening and copying files manually if the filesystem supplies an optimized method.

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

Parameters:
  • path (str) – Path to a resource.
  • file (file-like) – A file-like object open for writing 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.

Example

>>> with open('starwars.mov', 'wb') as write_file:
...     my_fs.download('/Videos/starwars.mov', write_file)
Raises:fs.errors.ResourceNotFound – if path does not exist.

Note

Deprecated since version 2.2.0: Please use download

getinfo(path, namespaces=None)[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.

getmeta(namespace='standard')[source]

Get meta information regarding a filesystem.

Parameters:namespace (str) – The meta namespace (defaults to "standard").
Returns:the meta information.
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 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.

getmodified(path)[source]

Get the timestamp of the last modifying access of a resource.

Parameters:path (str) – A path to a resource.
Returns:The timestamp of the last modification.
Return type:datetime

The modified timestamp of a file is the point in time that the file was last changed. Depending on the file system, it might only have limited accuracy.

getospath(path)[source]

Get the system path to a resource, in the OS’ prefered encoding.

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.

This method takes the output of getsyspath and encodes it to the filesystem’s prefered encoding. In Python3 this step is not required, as the os module will do it automatically. In Python2.7, the encoding step is required to support filenames on the filesystem that don’t encode correctly.

Note

If you want your code to work in Python2.7 and Python3 then use this method if you want to work with the OS filesystem outside of the OSFS interface.

getsize(path)[source]

Get the size (in bytes) of a resource.

Parameters:path (str) – A path to a resource.
Returns:the size of the resource.
Return type:int
Raises:fs.errors.ResourceNotFound – if path does not exist.

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

gettext(path, encoding=None, errors=None, newline='')

Get the contents of a file as a string.

Parameters:
  • path (str) – A path to a readable file on the filesystem.
  • encoding (str, optional) – Encoding to use when reading contents in text mode (defaults to None, reading in binary mode).
  • errors (str, optional) – Unicode errors parameter.
  • newline (str) – Newlines parameter.
Returns:

file contents.

Return type:

str

Raises:

fs.errors.ResourceNotFound – If path does not exist.

Note

Deprecated since version 2.2.0: Please use readtext

gettype(path)[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, purpose='download')[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.

glob

a globber object..

Type:BoundGlobber
hash(path, name)[source]

Get the hash of a file’s contents.

Parameters:
  • path (str) – A path on the filesystem.
  • name (str) – One of the algorithms supported by the hashlib module, e.g. "md5" or "sha256".
Returns:

The hex digest of the hash.

Return type:

str

Raises:
hassyspath(path)[source]

Check if a path maps to a system path.

Parameters:path (str) – A path on the filesystem.
Returns:True if the resource at path has a syspath.
Return type:bool
hasurl(path, purpose='download')[source]

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

True if an URL for the given purpose exists.

Return type:

bool

isclosed()[source]

Check if the filesystem is closed.

isdir(path)[source]

Check if a path maps to an existing directory.

Parameters:path (str) – A path on the filesystem.
Returns:True if path maps to a directory.
Return type:bool
isempty(path)[source]

Check if a directory is empty.

A directory is considered empty when it does not contain any file or any directory.

Parameters:

path (str) – A path to a directory on the filesystem.

Returns:

True if the directory is empty.

Return type:

bool

Raises:
  • errors.DirectoryExpected – If path is not a directory.
  • errors.ResourceNotFound – If path does not exist.
isfile(path)[source]

Check if a path maps to an existing file.

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

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)[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:
lock()[source]

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.

Returns:a lock specific to the filesystem instance.
Return type:threading.RLock

Example

>>> with my_fs.lock():  # May block
...    # code here has exclusive access to the filesystem
...    pass

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)[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:
makedirs(path, permissions=None, recreate=False)[source]

Make a directory, and any missing intermediate directories.

Parameters:
  • path (str) – Path to directory from root.
  • permissions (Permissions, optional) – Initial permissions, or None to use defaults.
  • recreate (bool) – If False (the default), attempting to create an existing directory will raise an error. Set to True to ignore existing directories.
Returns:

A sub-directory filesystem.

Return type:

SubFS

Raises:
match(patterns, name)[source]

Check if a name matches any of a list of wildcards.

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

Parameters:
  • patterns (list, optional) – A list of patterns, e.g. ['*.py'], or None to match everything.
  • name (str) – A file or directory name (not a path)
Returns:

True if name matches any of the patterns.

Return type:

bool

Raises:

TypeError – If patterns is a single string instead of a list (or None).

Example

>>> my_fs.match(['*.py'], '__init__.py')
True
>>> my_fs.match(['*.jpg', '*.png'], 'foo.gif')
False

Note

If patterns is None (or ['*']), then this method will always return True.

match_glob(patterns, path, accept_prefix=False)[source]

Check if a path matches any of a list of glob patterns.

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

Parameters:
  • patterns (list, optional) – A list of patterns, e.g. ['*.py'], or None to match everything.
  • path (str) – A resource path, starting with “/”.
  • accept_prefix (bool) – If True, the path is not required to match the patterns themselves but only need to be a prefix of a string that does.
Returns:

True if path matches any of the patterns.

Return type:

bool

Raises:
  • TypeError – If patterns is a single string instead of a list (or None).
  • ValueError – If path is not a string starting with “/”.

Example

>>> my_fs.match_glob(['*.py'], '/__init__.py')
True
>>> my_fs.match_glob(['*.jpg', '*.png'], '/foo.gif')
False
>>> my_fs.match_glob(['dir/file.txt'], '/dir/', accept_prefix=True)
True
>>> my_fs.match_glob(['dir/file.txt'], '/dir/', accept_prefix=False)
False
>>> my_fs.match_glob(['dir/file.txt'], '/dir/gile.txt', accept_prefix=True)
False

Note

If patterns is None (or ['*']), then this method will always return True.

move(src_path, dst_path, overwrite=False, preserve_time=False)[source]

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.
  • preserve_time (bool) – If True, try to preserve mtime of the resources (defaults to False).
Raises:
movedir(src_path, dst_path, create=False, preserve_time=False)[source]

Move directory src_path to dst_path.

Parameters:
  • src_path (str) – Path of source directory on the filesystem.
  • dst_path (str) – Path to destination directory.
  • create (bool) – If True, then dst_path will be created if it doesn’t exist already (defaults to False).
  • preserve_time (bool) – If True, try to preserve mtime of the resources (defaults to False).
Raises:
open(path, mode='r', buffering=-1, encoding=None, errors=None, newline='', **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:

io.IOBase

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

io.IOBase

Raises:
opendir(path, factory=None)[source]

Get a filesystem object for a sub-directory.

Parameters:
  • path (str) – Path to a directory on the filesystem.
  • factory (callable, optional) – 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_class will be used.
Returns:

A filesystem representing a sub-directory.

Return type:

SubFS

Raises:
readbytes(path)[source]

Get the contents of a file as bytes.

Parameters:

path (str) – A path to a readable file on the filesystem.

Returns:

the file contents.

Return type:

bytes

Raises:
readtext(path, encoding=None, errors=None, newline='')[source]

Get the contents of a file as a string.

Parameters:
  • path (str) – A path to a readable file on the filesystem.
  • encoding (str, optional) – Encoding to use when reading contents in text mode (defaults to None, reading in binary mode).
  • errors (str, optional) – Unicode errors parameter.
  • newline (str) – Newlines parameter.
Returns:

file contents.

Return type:

str

Raises:

fs.errors.ResourceNotFound – If path does not exist.

remove(path)[source]

Remove a file from the filesystem.

Parameters:

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

Raises:
removedir(path)[source]

Remove a directory from the filesystem.

Parameters:

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

Raises:
removetree(dir_path)[source]

Recursively remove a directory and all its contents.

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.

Raises:

Caution

A filesystem should never delete its root folder, so FS.removetree("/") has different semantics: the contents of the root folder will be deleted, but the root will be untouched:

>>> home_fs = fs.open_fs("~")
>>> home_fs.removetree("/")
>>> home_fs.exists("/")
True
>>> home_fs.isempty("/")
True

Combined with opendir, this can be used to clear a directory without removing the directory itself:

>>> home_fs = fs.open_fs("~")
>>> home_fs.opendir("/Videos").removetree("/")
>>> home_fs.exists("/Videos")
True
>>> home_fs.isempty("/Videos")
True
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, 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:
setbinfile(path, file, chunk_size=None, **options)

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

fs.errors.ResourceNotFound – If a parent directory of path does not exist.

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)

Note

Deprecated since version 2.2.0: Please use upload

setbytes(path, contents)

Copy binary data to a file.

Parameters:
  • path (str) – Destination path on the filesystem.
  • contents (bytes) – Data to be written.
Raises:

TypeError – if contents is not bytes.

Note

Deprecated since version 2.2.0: Please use writebytes

setfile(path, file, encoding=None, errors=None, newline='')

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 unlike upload, this method also supports creating files in text-mode (if the encoding 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)

Note

Deprecated since version 2.2.0: Please use writefile

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:
  • 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)
settext(path, contents, encoding='utf-8', errors=None, newline='')

Create or replace a file with text.

Parameters:
  • path (str) – Destination path on the filesystem.
  • contents (str) – Text to be written.
  • encoding (str, optional) – Encoding of destination file (defaults to 'utf-8').
  • errors (str, optional) – How encoding errors should be treated (same as io.open).
  • newline (str) – Newline parameter (same as io.open).
Raises:

TypeError – if contents is not a unicode string.

Note

Deprecated since version 2.2.0: Please use writetext

settimes(path, accessed=None, modified=None)[source]

Set the accessed and modified time on a resource.

Parameters:
  • path – A path to a resource on the filesystem.
  • accessed (datetime, optional) – The accessed time, or None (the default) to use the current time.
  • modified (datetime, optional) – The modified time, or None (the default) to use the same time as the accessed parameter.
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.
tree(**kwargs)[source]

Render a tree view of the filesystem to stdout or a file.

The parameters are passed to render().

Keyword Arguments:
 
  • path (str) – The path of the directory to start rendering from (defaults to root folder, i.e. '/').
  • file (io.IOBase) – An open file-like object to render the tree, or None for stdout.
  • encoding (str) – Unicode encoding, or None to auto-detect.
  • max_levels (int) – Maximum number of levels to display, or None for no maximum.
  • with_color (bool) – Enable terminal color output, or None to auto-detect terminal.
  • dirs_first (bool) – Show directories first.
  • exclude (list) – Option list of directory patterns to exclude from the tree render.
  • filter (list) – Optional list of files patterns to match in the tree render.
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.
Raises:

fs.errors.ResourceNotFound – If a parent directory of path does not exist.

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)
validatepath(path)[source]

Validate a path, returning a normalized absolute path on sucess.

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 a InvalidPath exception if it is not.

Parameters:

path (str) – A path.

Returns:

A normalized, absolute path.

Return type:

str

Raises:
walk

a walker bound to this filesystem.

Type:BoundWalker
walker_class

alias of fs.walk.Walker

writebytes(path, contents)[source]

Copy binary data to a file.

Parameters:
  • path (str) – Destination path on the filesystem.
  • contents (bytes) – Data to be written.
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 unlike upload, this method also supports creating files in text-mode (if the encoding 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)
writetext(path, contents, encoding='utf-8', errors=None, newline='')[source]

Create or replace a file with text.

Parameters:
  • path (str) – Destination path on the filesystem.
  • contents (str) – Text to be written.
  • encoding (str, optional) – Encoding of destination file (defaults to 'utf-8').
  • errors (str, optional) – How encoding errors should be treated (same as io.open).
  • newline (str) – Newline parameter (same as io.open).
Raises:

TypeError – if contents is not a unicode string.