-
Notifications
You must be signed in to change notification settings - Fork 275
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add exceptions docs for __init__ and from_dict() #1820
Add exceptions docs for __init__ and from_dict() #1820
Conversation
Pull Request Test Coverage Report for Build 1794779858Warning: This coverage report may be inaccurate.This pull request's base commit is no longer the HEAD commit of its target branch. This means it includes changes from outside the original pull request, including, potentially, unrelated coverage changes.
Details
💛 - Coveralls |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I might leave this for lukas to handle, the only comment I have is that I have a strong sense that many docstrings claim things that we have not checked. An example I found inTargets.from_dict()
:
TypeError: Invalid type for a signed_dict value.
I'm pretty sure TypeError can also happen if "delegations" is not a dict. And if "targets" contains non-dict. And if if "delegations.roles" contains non-dicts. Maybe there are more cases? I don't think we should spend a lot of time figuring out the exact cases since no-one will care. If we are going to try and document this, let's try to make it non-specific enough that it may actually be correct and has a chance of staying correct
Would it be wrong to do something like this for each from_dict()
for example:
KeyError, TypeError, ValueError: Invalid arguments
Works for me. 👍 @MVrachev, mind updating the PR as Jussi said and then ping me for review? |
e7d69fb
to
dd59ada
Compare
@lukpueh you can review it now. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks for your diligence, @MVrachev! I found one small mistake (see comment inline) and raised another not immediately related concern. I think we only need to fix the former to land this PR.
@@ -402,6 +401,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: Invalid arguments. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Can you remind me, do we expect users to catch type errors by verifying our type annotations? If not, we'd also need to expect an AttributeError
here in case the spec_version
passed to the constructor does not have a split
method, which we call in:
python-tuf/tuf/api/metadata.py
Line 440 in dd59ada
spec_list = spec_version.split(".") |
OTOH, I noticed a few isinstance
-checks in other constructors in the module, that we probably wouldn't need if we relied on users running mypy, e.g.:
python-tuf/tuf/api/metadata.py
Lines 549 to 558 in dd59ada
keyid: str, | |
keytype: str, | |
scheme: str, | |
keyval: Dict[str, str], | |
unrecognized_fields: Optional[Mapping[str, Any]] = None, | |
): | |
if not all( | |
isinstance(at, str) for at in [keyid, keytype, scheme] | |
) or not isinstance(keyval, dict): | |
raise TypeError("Unexpected Key attributes types!") |
I guess the difference between those two example that in the former a user sees the issue right away, but not in the latter.
We don't have to solve this in this PR, I was just curious.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I don't think we have a strong stance on when should we check for types.
I think I agree that in the Key
example it's harder to notice that these fields are not strings.
I don't think we can rely on our users mypy
as it's not an official requirement to run python-tuf, but at the same time, we don't want to overdo it with the type checks as we are working with untyped language.
@jku any opinion on this?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I noticed a few isinstance-checks in other constructors in the module, that we probably wouldn't need if we relied on users running mypy
For deserialization code path (including constructors as that's how the code path is built, for better or worse) we can't tell users to rely on mypy: the input is after all just random objects coming from json.loads()
.
I think in these cases documenting TypeError is as useful as documenting ValueError and KeyError... That is "not very useful at all" but if we do it we should try to have full coverage.
dd59ada
to
0b04a5e
Compare
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I can't see any missing errors (apart from the suspicion in a code comment) but I imagine there may well be more: I'm fine with this PR otherwise though
Document ValueError, KeyError and TypeError exceptions for __init__ and from_dict() methods in Metadata API. Signed-off-by: Martin Vrachev <[email protected]>
0b04a5e
to
5b2290c
Compare
I approved this: I'm not entirely convinced that the coverage really is 100% complete but I also don't think it makes sense to put more effort into it. |
Fixes #1819
Description of the changes being introduced by the pull request:
Document
ValueError
,KeyError
andTypeError
exceptions for__init__
andfrom_dict()
methods in Metadata API.Please verify and check that the pull request fulfills the following
requirements: