Zip Filesystem¶
Manage the filesystem in a Zip archive.
- class fs.zipfs.ZipFS(file: Union[Text, BinaryIO], write: bool = False, compression: int = 8, encoding: Text = 'utf-8', temp_fs: Union[Text, FS] = 'temp://__ziptemp__')[source]¶
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
withwrite
set toFalse
(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
withwrite
set toTrue
, then theZipFS
will be an empty temporary filesystem. Any files / directories you create in theZipFS
will be written in to a zip file when theZipFS
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, orFalse
(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: Union[Text, BinaryIO], compression: int = 8, encoding: Text = 'utf-8', temp_fs: Union[Text, FS] = 'temp://__ziptemp__')[source]¶
A writable zip file.
- __init__(file: Union[Text, BinaryIO], compression: int = 8, encoding: Text = 'utf-8', temp_fs: Union[Text, FS] = 'temp://__ziptemp__') → 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.base.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_zip(file: Union[Text, BinaryIO, None] = None, compression: Optional[int] = None, encoding: Optional[Text] = None) → None[source]¶
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: Union[BinaryIO, Text], encoding: Text = 'utf-8')[source]¶
A readable zip file.
- __init__(file: Union[BinaryIO, Text], encoding: Text = 'utf-8') → None[source]¶
Create a filesystem. See help(type(self)) for accurate signature.
- 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 ofnamespaces
may be.
- Returns
resource information object.
- Return type
- Raises
fs.errors.ResourceNotFound – If
path
does not exist.
For more information regarding resource information, see Resource Info.
- 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 bygetinfo(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: Optional[Permissions] = None, recreate: bool = False) → SubFS[R][source]¶
Make a directory.
- Parameters
path (str) – Path to directory from root.
permissions (Permissions, optional) – a
Permissions
instance, orNone
to use default.recreate (bool) – Set to
True
to avoid raising an error if the directory already exists (defaults toFalse
).
- Returns
a filesystem whose root is the new directory.
- Return type
- 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, **kwargs: 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 andmode
does not imply creating the file, or if any ancestor ofpath
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.
- readbytes(path: Text) → bytes[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
fs.errors.FileExpected – if
path
exists but is not a file.fs.errors.ResourceNotFound – if
path
does not exist.
- 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 forpurpose
: 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.