Package zeroinstall :: Package zerostore :: Module manifest

Module manifest

Processing of implementation manifests.

A manifest is a string representing a directory tree, with the property that two trees will generate identical manifest strings if and only if:

They have extactly the same set of files, directories and symlinks.
For each pair of corresponding directories in the two sets:
- The mtimes are the same (OldSHA1 only).
For each pair of corresponding files in the two sets:
- The size, executable flag and mtime are the same.
- The contents have matching secure hash values.
For each pair of corresponding symlinks in the two sets:
- The mtime and size are the same.
- The targets have matching secure hash values.

The manifest is typically processed with a secure hash itself. So, the idea is that any significant change to the contents of the tree will change the secure hash value of the manifest.

A top-level ".manifest" file is ignored.

Classes
	Algorithm Abstract base class for algorithms.
	OldSHA1
	HashLibAlgorithm

Functions

Algorithm

get_algorithm(name)
Look-up an Algorithm by name.

source code

generate_manifest(root, alg='sha1')

source code

add_manifest_file(dir, digest_or_alg)
Writes a .manifest file into 'dir', and returns the digest.

source code

(Algorithm, str)

splitID(id)
Take an ID in the form 'alg=value' and return a tuple (alg, value).

source code

copy_with_verify(src, dest, mode, alg, required_digest)
Copy path src to dest, checking that the contents give the right digest.

source code

verify(root, required_digest=None)
Ensure that directory 'dir' generates the given digest.

source code

copy_tree_with_verify(source, target, manifest_data, required_digest)
Copy directory source to be a subdirectory of target if it matches the required_digest.

source code

fixup_permissions(root)
Set permissions recursively for children of root:

source code

Variables
	sha1_new = `hashlib.sha1`
	algorithms = `{'sha1': OldSHA1(), 'sha1new': HashLibAlgorithm('...`

Function Details

get_algorithm(name)

source code

Look-up an Algorithm by name.

Parameters:

name (str)

Returns: Algorithm

Raises:

BadDigest - if the name is unknown.

generate_manifest(root, alg='sha1')

source code

Parameters:

alg (str)
root (str)

Deprecated: use get_algorithm and Algorithm.generate_manifest instead.

add_manifest_file(dir, digest_or_alg)

source code

Writes a .manifest file into 'dir', and returns the digest. You should call fixup_permissions before this to ensure that the permissions are correct. On exit, dir itself has mode 555. Subdirectories are not changed.

Parameters:

dir (str) - root of the implementation
digest_or_alg (Algorithm) - should be an instance of Algorithm. Passing a digest here is deprecated.

splitID(id)

source code

Take an ID in the form 'alg=value' and return a tuple (alg, value).

Parameters:

id (str)

Returns: (Algorithm, str)

Raises:

BadDigest - if the algorithm isn't known or the ID has the wrong format.

copy_with_verify(src, dest, mode, alg, required_digest)

source code

Copy path src to dest, checking that the contents give the right digest. dest must not exist. New file is created with a mode of 'mode & umask'.

Parameters:

src (str) - source filename
dest (str) - target filename
mode (int) - target mode
alg (Algorithm) - algorithm to generate digest
required_digest (str) - expected digest value

Raises:

BadDigest - the contents of the file don't match required_digest

verify(root, required_digest=None)

source code

Ensure that directory 'dir' generates the given digest. For a non-error return:

Dir's name must be a digest (in the form "alg=value")
The calculated digest of the contents must match this name.
If there is a .manifest file, then its digest must also match.

Parameters:

required_digest (str | None)
root (str)

Raises:

BadDigest - if verification fails.

copy_tree_with_verify(source, target, manifest_data, required_digest)

source code

Copy directory source to be a subdirectory of target if it matches the required_digest. manifest_data is normally source/.manifest. source and manifest_data are not trusted (will typically be under the control of another user). The copy is first done to a temporary directory in target, then renamed to the final name only if correct. Therefore, an invalid 'target/required_digest' will never exist. A successful return means than target/required_digest now exists (whether we created it or not).

Parameters:

source (str)
required_digest (str)
target (str)
manifest_data (str)

fixup_permissions(root)

source code

Set permissions recursively for children of root:

If any X bit is set, they all must be.
World readable, non-writable.

Parameters:

root (str)

Raises:

Exception - if there are unsafe special bits set (setuid, etc).

Variables Details

algorithms

Value:

{'sha1': OldSHA1(), 'sha1new': HashLibAlgorithm('sha1new', 50, 'sha1')
, 'sha256': HashLibAlgorithm('sha256', 80), 'sha256new': HashLibAlgori
thm('sha256new', 90, 'sha256'),}