Skip to content

Commit

Permalink
Exceptions docs for __init__ and from_dict()
Browse files Browse the repository at this point in the history 
Document ValueError, KeyError and TypeError exceptions for __init__ and
from_dict() methods in Metadata API.

Signed-off-by: Martin Vrachev <[email protected]>
  • Loading branch information
@MVrachev
MVrachev committed Feb 3, 2022
1 parent 6c1dfce commit e7d69fb
Showing 1 changed file with 100 additions and 12 deletions.
112 changes: 100 additions & 12 deletions tuf/api/metadata.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -124,8 +124,8 @@ def from_dict(cls, metadata: Dict[str, Any]) -> "Metadata[T]":
metadata: TUF metadata in dict representation.
Raises:
KeyError: The metadata dict format is invalid.
ValueError: The metadata has an unrecognized signed._type field.
KeyError: Metadata dict misses a certain key.
ValueError: Metadata dict values are somehow invalid.
Side Effect:
Destroys the metadata dict passed by reference.
Expand Down Expand Up @@ -402,6 +402,9 @@ class Signed(metaclass=abc.ABCMeta):
spec_version: The supported TUF specification version number.
expires: The metadata expiry date.
unrecognized_fields: Dictionary of all unrecognized fields.
Raises:
ValueError: Attributes are somehow invalid.
"""

# type is required for static reference without changing the API
Expand Down Expand Up @@ -537,6 +540,9 @@ class Key:
"rsassa-pss-sha256", "ed25519", and "ecdsa-sha2-nistp256".
keyval: Opaque key content
unrecognized_fields: Dictionary of all unrecognized fields.
Raises:
TypeError: Invalid type for an argument.
"""

def __init__(
Expand All @@ -559,7 +565,12 @@ def __init__(

@classmethod
def from_dict(cls, keyid: str, key_dict: Dict[str, Any]) -> "Key":
"""Creates Key object from its dict representation."""
"""Creates Key object from its dict representation.
Raises:
KeyError: Missing key inside key_dict.
TypeError: Invalid type for keyid or any of key_dict values.
"""
keytype = key_dict.pop("keytype")
scheme = key_dict.pop("scheme")
keyval = key_dict.pop("keyval")
Expand Down Expand Up @@ -666,6 +677,9 @@ class Role:
keyids: The roles signing key identifiers.
threshold: Number of keys required to sign this role's metadata.
unrecognized_fields: Dictionary of all unrecognized fields.
Raises:
ValueError: Attributes are somehow invalid.
"""

def __init__(
Expand All @@ -684,7 +698,12 @@ def __init__(

@classmethod
def from_dict(cls, role_dict: Dict[str, Any]) -> "Role":
"""Creates Role object from its dict representation."""
"""Creates Role object from its dict representation.
Raises:
KeyError: Missing key inside role_dict.
ValueError: Invalid values inside role_dict.
"""
keyids = role_dict.pop("keyids")
threshold = role_dict.pop("threshold")
# All fields left in the role_dict are unrecognized.
Expand Down Expand Up @@ -713,6 +732,9 @@ class Root(Signed):
required to sign the metadata for a specific role.
consistent_snapshot: Does repository support consistent snapshots.
unrecognized_fields: Dictionary of all unrecognized fields.
Raises:
ValueError: Attributes are somehow invalid.
"""

type = _ROOT
Expand All @@ -739,7 +761,13 @@ def __init__(

@classmethod
def from_dict(cls, signed_dict: Dict[str, Any]) -> "Root":
"""Creates Root object from its dict representation."""
"""Creates Root object from its dict representation.
Raises:
ValueError: The signed_dict values are somehow invalid.
KeyError: Missing key inside signed_dict.
TypeError: Invalid type for a signed_dict value.
"""
common_args = cls._common_fields_from_dict(signed_dict)
consistent_snapshot = signed_dict.pop("consistent_snapshot", None)
keys = signed_dict.pop("keys")
Expand Down Expand Up @@ -889,6 +917,9 @@ class MetaFile(BaseFile):
hashes: Dictionary of hash algorithm names to hashes of the metadata
file content.
unrecognized_fields: Dictionary of all unrecognized fields.
Raises:
ValueError: Attributes are somehow invalid.
"""

def __init__(
Expand All @@ -913,7 +944,12 @@ def __init__(

@classmethod
def from_dict(cls, meta_dict: Dict[str, Any]) -> "MetaFile":
"""Creates MetaFile object from its dict representation."""
"""Creates MetaFile object from its dict representation.
Raises:
ValueError: Invalid meta_dict values.
KeyError: Missing key inside meta_dict.
"""
version = meta_dict.pop("version")
length = meta_dict.pop("length", None)
hashes = meta_dict.pop("hashes", None)
Expand Down Expand Up @@ -968,6 +1004,9 @@ class Timestamp(Signed):
expires: The metadata expiry date.
unrecognized_fields: Dictionary of all unrecognized fields.
snapshot_meta: Meta information for snapshot metadata.
Raises:
ValueError: Attributes are somehow invalid.
"""

type = _TIMESTAMP
Expand All @@ -985,7 +1024,12 @@ def __init__(

@classmethod
def from_dict(cls, signed_dict: Dict[str, Any]) -> "Timestamp":
"""Creates Timestamp object from its dict representation."""
"""Creates Timestamp object from its dict representation.
Raises:
ValueError: Invalid signed_dict values.
KeyError: Missing key inside signed_dict.
"""
common_args = cls._common_fields_from_dict(signed_dict)
meta_dict = signed_dict.pop("meta")
snapshot_meta = MetaFile.from_dict(meta_dict["snapshot.json"])
Expand Down Expand Up @@ -1013,6 +1057,9 @@ class Snapshot(Signed):
expires: The metadata expiry date.
unrecognized_fields: Dictionary of all unrecognized fields.
meta: A dictionary of target metadata filenames to MetaFile objects.
Raises:
ValueError: Attributes are somehow invalid.
"""

type = _SNAPSHOT
Expand All @@ -1030,7 +1077,12 @@ def __init__(

@classmethod
def from_dict(cls, signed_dict: Dict[str, Any]) -> "Snapshot":
"""Creates Snapshot object from its dict representation."""
"""Creates Snapshot object from its dict representation.
Raises:
ValueError: Invalid signed_dict values.
KeyError: Missing key inside signed_dict.
"""
common_args = cls._common_fields_from_dict(signed_dict)
meta_dicts = signed_dict.pop("meta")
meta = {}
Expand Down Expand Up @@ -1073,6 +1125,9 @@ class DelegatedRole(Role):
paths: Path patterns. See note above.
path_hash_prefixes: Hash prefixes. See note above.
unrecognized_fields: Attributes not managed by TUF Metadata API.
Raises:
ValueError: Attributes are somehow invalid.
"""

def __init__(
Expand Down Expand Up @@ -1106,7 +1161,12 @@ def __init__(

@classmethod
def from_dict(cls, role_dict: Dict[str, Any]) -> "DelegatedRole":
"""Creates DelegatedRole object from its dict representation."""
"""Creates DelegatedRole object from its dict representation.
Raises:
ValueError: Invalid role_dict values.
KeyError: Missing key inside role_dict.
"""
name = role_dict.pop("name")
keyids = role_dict.pop("keyids")
threshold = role_dict.pop("threshold")
Expand Down Expand Up @@ -1205,6 +1265,9 @@ class Delegations:
role. The roles order also defines the order that role delegations
are considered during target searches.
unrecognized_fields: Dictionary of all unrecognized fields.
Raises:
ValueError: Attributes are somehow invalid.
"""

def __init__(
Expand All @@ -1226,7 +1289,13 @@ def __init__(

@classmethod
def from_dict(cls, delegations_dict: Dict[str, Any]) -> "Delegations":
"""Creates Delegations object from its dict representation."""
"""Creates Delegations object from its dict representation.
Raises:
ValueError: Invalid delegations_dict values.
KeyError: Missing key inside delegations_dict.
TypeError: Invalid type for an argument.
"""
keys = delegations_dict.pop("keys")
keys_res = {}
for keyid, key_dict in keys.items():
Expand Down Expand Up @@ -1264,6 +1333,10 @@ class TargetFile(BaseFile):
file content.
path: URL path to a target file, relative to a base targets URL.
unrecognized_fields: Dictionary of all unrecognized fields.
Raises:
ValueError: Attributes are somehow invalid.
TypeError: Invalid type for an argument.
"""

def __init__(
Expand All @@ -1290,7 +1363,13 @@ def custom(self) -> Any:

@classmethod
def from_dict(cls, target_dict: Dict[str, Any], path: str) -> "TargetFile":
"""Creates TargetFile object from its dict representation."""
"""Creates TargetFile object from its dict representation.
Raises:
ValueError: The target_dict values are somehow invalid.
KeyError: Missing key inside target_dict.
TypeError: Invalid type for a target_dict value.
"""
length = target_dict.pop("length")
hashes = target_dict.pop("hashes")

Expand Down Expand Up @@ -1409,6 +1488,9 @@ class Targets(Signed):
delegations: Defines how this Targets delegates responsibility to other
Targets Metadata files.
unrecognized_fields: Dictionary of all unrecognized fields.
Raises:
ValueError: Attributes are somehow invalid.
"""

type = _TARGETS
Expand All @@ -1430,7 +1512,13 @@ def __init__(

@classmethod
def from_dict(cls, signed_dict: Dict[str, Any]) -> "Targets":
"""Creates Targets object from its dict representation."""
"""Creates Targets object from its dict representation.
Raises:
ValueError: Invalid signed_dict values.
KeyError: Missing key inside signed_dict.
TypeError: Invalid type for a signed_dict value.
"""
common_args = cls._common_fields_from_dict(signed_dict)
targets = signed_dict.pop(_TARGETS)
try:
Expand Down

0 comments on commit e7d69fb

Please sign in to comment.