From 8adab689ffb78cdff92d980347a2da93f2250222 Mon Sep 17 00:00:00 2001 From: Sebastien Awwad Date: Mon, 14 Mar 2016 12:40:06 -0400 Subject: [PATCH] Expanding and clarifying docstring for tuf.client.updater::refresh() --- tuf/client/updater.py | 30 ++++++++++++++++++++---------- 1 file changed, 20 insertions(+), 10 deletions(-) diff --git a/tuf/client/updater.py b/tuf/client/updater.py index 99e2de9a..22753749 100755 --- a/tuf/client/updater.py +++ b/tuf/client/updater.py @@ -563,15 +563,23 @@ def _import_delegations(self, parent_role): def refresh(self, unsafely_update_root_if_necessary=True): """ - 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. 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). Updates the metadata files of the top-level roles with the latest