From b964d80823b41dc94db7544ca325fc4cdcdd7b97 Mon Sep 17 00:00:00 2001
From: Fridolin Pokorny <fridolin.pokorny@datadoghq.com>
Date: Sun, 18 Dec 2022 14:32:04 +0100
Subject: [PATCH] Document public API for tuf.api and tuf.ngclient

Signed-off-by: Fridolin Pokorny <fridolin.pokorny@datadoghq.com>
---
 tuf/__init__.py                   |  7 ++++
 tuf/api/__init__.py               | 67 +++++++++++++++++++++++++++++++
 tuf/api/exceptions.py             |  7 +++-
 tuf/api/serialization/__init__.py | 12 ++++++
 tuf/ngclient/__init__.py          |  7 ++++
 5 files changed, 98 insertions(+), 2 deletions(-)

diff --git a/tuf/__init__.py b/tuf/__init__.py
index e416974c8e..4a05c9b7d7 100755
--- a/tuf/__init__.py
+++ b/tuf/__init__.py
@@ -4,5 +4,12 @@
 """TUF
 """
 
+import tuf.api
+import tuf.ngclient
+
 # This value is used in the requests user agent.
 __version__ = "2.0.0"
+__all__ = [
+    tuf.api.__name__,
+    tuf.ngclient.__name__,
+]
diff --git a/tuf/api/__init__.py b/tuf/api/__init__.py
index e69de29bb2..3db2843301 100644
--- a/tuf/api/__init__.py
+++ b/tuf/api/__init__.py
@@ -0,0 +1,67 @@
+# Copyright New York University and the TUF contributors
+# SPDX-License-Identifier: MIT OR Apache-2.0
+
+"""Public API for ``tuf.api``."""
+
+from .metadata import (
+    BaseFile,
+    DelegatedRole,
+    Delegations,
+    Key,
+    MetaFile,
+    Metadata,
+    Role,
+    Root,
+    SPECIFICATION_VERSION,
+    Signed,
+    Snapshot,
+    SuccinctRoles,
+    TOP_LEVEL_ROLE_NAMES,
+    TargetFile,
+    Targets,
+    Timestamp,
+)
+
+from .exceptions import (
+    BadVersionNumberError,
+    DownloadError,
+    DownloadHTTPError,
+    DownloadLengthMismatchError,
+    EqualVersionNumberError,
+    ExpiredMetadataError,
+    LengthOrHashMismatchError,
+    RepositoryError,
+    SlowRetrievalError,
+    StorageError,
+    UnsignedMetadataError,
+)
+
+__all__ = [
+    "SPECIFICATION_VERSION",
+    "TOP_LEVEL_ROLE_NAMES",
+    BadVersionNumberError.__name__,
+    BaseFile.__name__,
+    DelegatedRole.__name__,
+    Delegations.__name__,
+    DownloadError.__name__,
+    DownloadHTTPError.__name__,
+    DownloadLengthMismatchError.__name__,
+    EqualVersionNumberError.__name__,
+    ExpiredMetadataError.__name__,
+    Key.__name__,
+    LengthOrHashMismatchError.__name__,
+    MetaFile.__name__,
+    Metadata.__name__,
+    RepositoryError.__name__,
+    Role.__name__,
+    Root.__name__,
+    Signed.__name__,
+    SlowRetrievalError.__name__,
+    Snapshot.__name__,
+    StorageError.__name__,
+    SuccinctRoles.__name__,
+    TargetFile.__name__,
+    Targets.__name__,
+    Timestamp.__name__,
+    UnsignedMetadataError.__name__,
+]
diff --git a/tuf/api/exceptions.py b/tuf/api/exceptions.py
index a2a889b079..f23f65902c 100644
--- a/tuf/api/exceptions.py
+++ b/tuf/api/exceptions.py
@@ -10,8 +10,7 @@
 
 #### Repository errors ####
 
-# pylint: disable=unused-import
-from securesystemslib.exceptions import StorageError
+from securesystemslib.exceptions import StorageError as _SecureSystemsLibStorageError
 
 
 class RepositoryError(Exception):
@@ -41,6 +40,10 @@ class LengthOrHashMismatchError(RepositoryError):
     """An error while checking the length and hash values of an object."""
 
 
+class StorageError(_SecureSystemsLibStorageError, RepositoryError):
+    """An error raised when a file cannot be read or written."""
+
+
 #### Download Errors ####
 
 
diff --git a/tuf/api/serialization/__init__.py b/tuf/api/serialization/__init__.py
index 7aef8b9884..aba08fea56 100644
--- a/tuf/api/serialization/__init__.py
+++ b/tuf/api/serialization/__init__.py
@@ -18,6 +18,7 @@
 from typing import TYPE_CHECKING
 
 from tuf.api.exceptions import RepositoryError
+from .json import CanonicalJSONSerializer
 
 if TYPE_CHECKING:
     # pylint: disable=cyclic-import
@@ -57,3 +58,14 @@ class SignedSerializer(metaclass=abc.ABCMeta):
     def serialize(self, signed_obj: "Signed") -> bytes:
         """Serialize Signed object to bytes."""
         raise NotImplementedError
+
+
+__all__ = [
+    CanonicalJSONSerializer.__name__,
+    DeserializationError.__name__,
+    MetadataDeserializer.__name__,
+    MetadataSerializer.__name__,
+    RepositoryError.__name__,
+    SerializationError.__name__,
+    SignedSerializer.__name__,
+]
diff --git a/tuf/ngclient/__init__.py b/tuf/ngclient/__init__.py
index 371954a991..83dfbba7a8 100644
--- a/tuf/ngclient/__init__.py
+++ b/tuf/ngclient/__init__.py
@@ -7,3 +7,10 @@
 from tuf.ngclient.config import UpdaterConfig
 from tuf.ngclient.fetcher import FetcherInterface
 from tuf.ngclient.updater import Updater
+
+
+__all__ = [
+    FetcherInterface.__name__,
+    Updater.__name__,
+    UpdaterConfig.__name__,
+]