Tar Filesystem¶

Manage the filesystem in a Tar archive.

class fs.tarfs.TarFS(file: Text | BinaryIO, write: bool = False, compression: Text | None = None, encoding: Text = 'utf-8', temp_fs: Text | FS = 'temp://__tartemp__')[source]¶

Read and write tar files.

There are two ways to open a TarFS for the use cases of reading a tar file, and creating a new one.

If you open the TarFS with write set to False (the default), then the filesystem will be a read only filesystem which maps to the files and directories within the tar file. Files are decompressed on the fly when you open them.

Here’s how you might extract and print a readme from a tar file:

with TarFS('foo.tar.gz') as tar_fs:
    readme = tar_fs.readtext('readme.txt')

If you open the TarFS with write set to True, then the TarFS will be a empty temporary filesystem. Any files / directories you create in the TarFS will be written in to a tar file when the TarFS is closed. The compression is set from the new file name but may be set manually with the compression argument.

Here’s how you might write a new tar file containing a readme.txt file:

with TarFS('foo.tar.xz', write=True) as new_tar:
    new_tar.writetext(
        'readme.txt',
        'This tar file was written by PyFilesystem'
    )

Parameters:

file (str or io.IOBase) – An OS filename, or an open file handle.
write (bool) – Set to True to write a new tar file, or use default (False) to read an existing tar file.
compression (str, optional) – Compression to use (one of the formats supported by tarfile: xz, gz, bz2, or None).
temp_fs (str) – An FS URL or an FS instance to use to store data prior to tarring. Defaults to creating a new TempFS.

class fs.tarfs.WriteTarFS(file: Text | BinaryIO, compression: Text | None = None, encoding: Text = 'utf-8', temp_fs: Text | FS = 'temp://__tartemp__')[source]¶

A writable tar file.

__init__(file: Text | BinaryIO, compression: Text | None = None, encoding: Text = 'utf-8', temp_fs: Text | FS = 'temp://__tartemp__') → None[source]¶: Create a filesystem. See help(type(self)) for accurate signature.

delegate_path(path: Text) → Tuple[FS, Text][source]¶

Encode a path for proxied filesystem.

Parameters:: path (str) – A path on the filesystem.
Returns:: a tuple of (<filesystem>, <new_path>)
Return type:: (FS, str)

delegate_fs() → FS[source]¶

Get the proxied filesystem.

This method should return a filesystem for methods not associated with a path, e.g. getmeta.

close() → None[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.

write_tar(file: Text | BinaryIO | None = None, compression: Text | None = None, encoding: Text | None = None) → None[source]¶

Write tar to a file.

Parameters:

file (str or io.IOBase, optional) – Destination file, may be a file name or an open file object.
compression (str, optional) – Compression to use (one of the constants defined in tarfile in the stdlib).
encoding (str, optional) – The character encoding to use (default uses the encoding defined in __init__).

Note

This is called automatically when the TarFS is closed.

class fs.tarfs.ReadTarFS(file: Text | BinaryIO, encoding: Text = 'utf-8')[source]¶

A readable tar file.

__init__(file: Text | BinaryIO, encoding: Text = 'utf-8') → None[source]¶: Create a filesystem. See help(type(self)) for accurate signature.

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.

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

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

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)

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[T][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.

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

close() → None[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.

isclosed() → bool[source]¶: Check if the filesystem is closed.

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.