repository: Address review comments

This is a collection of comment, documentation and logging fixes.

The noteworthy part is making it clear that repository is not stable
API yet: I think this is a good idea.

Signed-off-by: Jussi Kukkonen <jkukkonen@google.com>

Author: jku

examples/client_example/README.md

@@ -32,7 +32,7 @@ In another terminal, run the client:
 
 Note that unlike normal repositories, the example repository only exists in
 memory and is re-generated from scratch at every startup: This means your
-client needs to run `tofu` everytime you restart the repository application.
+client needs to run `tofu` every time you restart the repository application.
 
 
 ### Example with a repository on the internet

examples/repository/README.md

@@ -1,23 +1,21 @@
 # TUF Repository Application Example
 
+:warning: This example uses the repository module which is not considered
+part of the python-tuf stable API quite yet.
 
-This TUF Repository Application Example has following features:
+This TUF Repository Application Example has the following features:
 - Initializes a completely new repository on startup
 - Stores everything (metadata, targets, signing keys) in-memory
 - Serves metadata and targets on localhost (default port 8001)
 - Simulates a live repository by automatically adding a new target
   file every 10 seconds.
 
 
-### Example with the repository example
+### Usage
 
 ```console
 ./repo
 ```
 Your repository is now running and is accessible on localhost, See e.g.
-http://127.0.0.1:8001/metadata/1.root.json
-
-Note that because the example generates a new repository at startup,
-clients need to also re-initialize their trust root when the repository
-application is restarted. With the example client this is done with
-`./client tofu`.
+http://127.0.0.1:8001/metadata/1.root.json. The
+[client example](../client_example/README.md) uses this address by default.

examples/repository/_simplerepo.py

@@ -42,12 +42,12 @@ class SimpleRepository(Repository):
 
 
     Attributes:
-        role_cache: Contains every historical metadata version of every role in
-            this repositorys. Keys are rolenames and values are lists of
-            Metadata
-        signer_cache: Contains all signers available to the repository. Keys
-            are rolenames, values are lists of signers
-        target_cache:
+        role_cache: Every historical metadata version of every role in this
+            repositorys. Keys are role names and values are lists of Metadata
+        signer_cache: All signers available to the repository. Keys are role
+            names, values are lists of signers
+        target_cache: All target files served by the repository. Keys are
+            target paths and values are file contents as bytes.
     """
 
     expiry_period = timedelta(days=1)

tuf/repository/__init__.py

@@ -1,6 +1,13 @@
 # Copyright 2021-2022 python-tuf contributors
 # SPDX-License-Identifier: MIT OR Apache-2.0
 
-"""Repository API: A library to help repository implementations"""
+"""Repository API: A helper library for repository implementations
+
+This module is intended to make any "metadata editing" applications easier to
+implement: this includes repository applications, CI integration components as
+well as developer and signing tools.
+
+The repository module is not considered part of the stable python-tuf API yet.
+"""
 
 from tuf.repository._repository import AbortEdit, Repository

tuf/repository/_repository.py

@@ -21,6 +21,9 @@ class AbortEdit(Exception):
 class Repository(ABC):
     """Abstract class for metadata modifying implementations
 
+    NOTE: The repository module is not considered part of the python-tuf
+    stable API yet.
+
     This class is intended to be a base class used in any metadata editing
     application, whether it is a real repository server or a developer tool.
 
@@ -95,15 +98,15 @@ def snapshot(self, force: bool = False) -> Tuple[bool, Dict[str, MetaFile]]:
         """Update snapshot meta information
 
         Updates the snapshot meta information according to current targets
-        metadata state and the current current snapshot meta information.
+        metadata state and the current snapshot meta information.
 
         Arguments:
             force: should new snapshot version be created even if meta
                 information would not change?
 
         Returns: Tuple of
             - True if snapshot was created, False if not
-            - Meta information for targets metadata was removed from snapshot
+            - Meta information for targets metadata that was removed from snapshot
         """
 
         # Snapshot update is needed if
@@ -135,9 +138,7 @@ def snapshot(self, force: bool = False) -> Tuple[bool, Dict[str, MetaFile]]:
             # this is reachable as edit() handles AbortEdit
             logger.debug("Snapshot update not needed")  # type: ignore[unreachable]
         else:
-            logger.debug(
-                "Snapshot v%d, %d targets", snapshot.version, len(snapshot.meta)
-            )
+            logger.debug("Snapshot v%d", snapshot.version)
 
         return update_version, removed