Zip Filesystem

Manage the filesystem in a Zip archive.

class fs.zipfs.ZipFS(wrap_fs)

Read and write zip files.

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

If you open the ZipFS 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 zip file. Files are decompressed on the fly when you open them.

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

with ZipFS('foo.zip') as zip_fs:
    readme = zip_fs.readtext('readme.txt')

If you open the ZipFS with write set to True, then the ZipFS will be an empty temporary filesystem. Any files / directories you create in the ZipFS will be written in to a zip file when the ZipFS is closed.

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

with ZipFS('foo.zip', write=True) as new_zip:
    new_zip.writetext(
        'readme.txt',
        'This zip file was written by PyFilesystem'
    )

Parameters:

• file (str or io.IOBase) – An OS filename, or an open file object.
• write (bool) – Set to True to write a new zip file, or False (default) to read an existing zip file.
• compression (int) – Compression to use (one of the constants defined in the zipfile module in the stdlib).
• temp_fs (str or FS) – An FS URL or an FS instance to use to store data prior to zipping. Defaults to creating a new TempFS.

class fs.zipfs.WriteZipFS(file, compression=8, encoding='utf-8', temp_fs='temp://__ziptemp__')

A writable zip file.

__init__(file, compression=8, encoding='utf-8', temp_fs='temp://__ziptemp__')

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

delegate_path(path)

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

Get the proxied filesystem.

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

close()

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_zip(file=None, compression=None, encoding=None)

Write zip to a file.

Parameters:

• file (str or io.IOBase, optional) – Destination file, may be a file name or an open file handle.
• compression (int, optional) – Compression to use (one of the constants defined in the zipfile module 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 ZipFS is closed.

class fs.zipfs.ReadZipFS(file, encoding='utf-8')

A readable zip file.

__init__(file, encoding='utf-8')

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

getinfo(path, namespaces=None)

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.

setinfo(path, info)

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)

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, permissions=None, recreate=False)

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, mode='r', buffering=-1, **kwargs)

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)

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)

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

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.

readbytes(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:

• fs.errors.FileExpected – if path exists but is not a file.
• fs.errors.ResourceNotFound – if path does not exist.

geturl(path, purpose='download')

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.