Tar Filesystem¶
Manage the filesystem in a Tar archive.
- class fs.tarfs.TarFS(file: Union[Text, BinaryIO], write: bool = False, compression: Optional[Text] = None, encoding: Text = 'utf-8', temp_fs: Union[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
withwrite
set toFalse
(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 toTrue
, then theTarFS
will be a empty temporary filesystem. Any files / directories you create in theTarFS
will be written in to a tar file when theTarFS
is closed. The compression is set from the new file name but may be set manually with thecompression
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
, orNone
).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: Union[Text, BinaryIO], compression: Optional[Text] = None, encoding: Text = 'utf-8', temp_fs: Union[Text, FS] = 'temp://__tartemp__')[source]¶
A writable tar file.
- __init__(file: Union[Text, BinaryIO], compression: Optional[Text] = None, encoding: Text = 'utf-8', temp_fs: Union[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.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_tar(file: Union[Text, BinaryIO, None] = None, compression: Optional[Text] = None, encoding: Optional[Text] = 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: Union[Text, BinaryIO], encoding: Text = 'utf-8')[source]¶
A readable tar file.
- __init__(file: Union[Text, BinaryIO], 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.
- isdir(path)[source]¶
Check if a path maps to an existing directory.
- Parameters
path (str) – A path on the filesystem.
- Returns
True
ifpath
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
ifpath
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 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[T][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, **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 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.
- 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.