southwark.targit
Archive where the changes to the contents are recorded using git.
Exceptions:
Exception to indicate an archive contains files utilising path traversal. |
Data:
Valid modes for opening |
Classes:
alias of |
|
|
A “TarGit” (pronounced “target”, /tɑːɡɪt/) is a |
|
Represents a save event in a |
Functions:
|
Checks the contents of an archive to ensure it does not contain any filenames with absolute paths or path traversal. |
-
exception
BadArchiveError[source] Bases:
OSErrorException to indicate an archive contains files utilising path traversal.
-
Modes Valid modes for opening
TarGitarchives in'r'– Read only access. The archive must exist.'w'– Read and write access. The archive must not exist.'a'– Read and write access to an existing archive.
Alias of
Literal['r','w','a']
-
Status alias of
southwark.StagedDict
-
class
TarGit(filename, mode='r')[source] Bases:
PathLikeA “TarGit” (pronounced “target”, /tɑːɡɪt/) is a
tar.gzarchive where the changes to the contents are recorded using git.- Parameters
- Raises
FileNotFoundError – If the file is opened in read or append mode, but it does not exist.
FileExistsError – If the file is opened in write mode, but it already exists.
ValueError – If an unknown value for
modeis given.
Methods:
save()Saves the contents of the archive.
status()Returns the status of the TarGit archive.
exists()Returns whether the
TarGitarchive exists.close()Closes the
TarGitarchive.__truediv__(filename)Returns a
PathPlusobject representing the given filename relative to the archive root.__repr__()Returns a string representation of the
TarGit.Returns the filename of the
TarGitarchive.__str__()Returns the filename of the
TarGitarchive.Attributes:
Returns whether the
TarGitarchive is closed.Returns the mode the
TarGitarchive was opened in.Returns an iterable over the historic save states of the
TarGit.-
save()[source] Saves the contents of the archive.
Does nothing if there are no changes to be saved.
-
status()[source] Returns the status of the TarGit archive.
The values in the dictionary are lists of filenames, relative to the TarGit root.
- Raises
IOError – If the file is closed.
- Return type
-
property
mode Returns the mode the
TarGitarchive was opened in.This defaults to
'r'. After the archive is closed this will show the last mode until the archive is opened again.- Return type
Literal['r','w','a']
-
check_archive_paths(archive)[source] Checks the contents of an archive to ensure it does not contain any filenames with absolute paths or path traversal.
For example, the following paths would raise an
BadArchiveError:/usr/bin/malware.sh– this is an absolute path.~/.local/bin/malware.sh– this tries to put the file in the user’s home directory.../.local/bin/malware.sh– this uses path traversal to try to get to a parent directory.
See also
The warning for
tarfile.TarFile.extractall()in the Python documentation.
-
namedtuple
SaveState(id, user, device, time, timezone)[source] Bases:
NamedTupleRepresents a save event in a
TarGitarchive’s history.- Fields
id (
str) – The SHA id of the underlying commit.user (
str) – The name of the user who made the changes.device (
str) – The hostname of the device the changes were made on.time (
float) – The time the changes were saved, in seconds from epoch.timezone (
int) – The timezone the changes were made in, as a GMT offset in seconds.