Elgato_dark/python-tuf
1
0
Fork 0
mirror of https://github.com/theupdateframework/python-tuf synced 2026-05-24 10:08:28 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Expanding and clarifying docstring for tuf.client.updater::refresh()

Browse source
This commit is contained in:
Sebastien Awwad 2016-03-14 12:40:06 -04:00
parent 0fa4518929
commit 8adab689ff
No known key found for this signature in database
GPG key ID: BC0C6DEDD5E5CC03
1 changed files with 20 additions and 10 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

30
tuf/client/updater.py
View file

@ -563,15 +563,23 @@ def _import_delegations(self, parent_role):
def refresh(self, unsafely_update_root_if_necessary=True):
"""
<Purpose>
Update the latest copies of the metadata for the top-level roles.
The update request process follows a specific order to ensure the
metadata files are securely updated.
The client would call refresh() prior to requesting target file
information. Calling refresh() ensures target methods, like
all_targets() and target(), refer to the latest available content.
The latest copies, according to the currently trusted top-level metadata,
of delegated metadata are downloaded and updated by the target methods.
Update the latest copies of the metadata for the top-level roles. The
update request process follows a specific order to ensure the metadata
files are securely updated: timestamp -> snapshot -> root -> targets.
Delegated metadata is not refreshed by this method. After this method is
called, the use of target methods (e.g., all_targets(), targets_of_role(),
or target()) will update delegated metadata.
Calling refresh() ensures that top-level metadata is up-to-date, so that
the target methods can refer to the latest available content. Thus,
refresh() should always be called by the client before any requests of
target file information.
The expiration time for downloaded metadata is also verified.
If the refresh fails for any reason, it will be retried once after first
attempting to update the root metadata file. Only then will the exceptions
listed here potentially be raised.
<Arguments>
unsafely_update_root_if_necessary:
@ -584,7 +592,9 @@ def refresh(self, unsafely_update_root_if_necessary=True):
If the metadata for any of the top-level roles cannot be updated.
tuf.ExpiredMetadataError:
If any metadata has expired.
If any of the top-level metadata is expired (whether a new version was
downloaded expired or no new version was found and the existing
version is now expired).
<Side Effects>
Updates the metadata files of the top-level roles with the latest