python-tuf
python-tuf copied to clipboard
Improve docstrings on exceptions
Current behavior:
Currently, in tuf/api/metadata.py we are using multiple ways to document our custom TUF exceptions.
There are two main ways of how we handle exceptions:
- there are places where we define an exception with the full module name: https://github.com/theupdateframework/python-tuf/blob/0f1fc6e33cbc4d4c6b502b9f8c64b119d1a4ad2f/tuf/api/metadata.py#L185
- and in other cases, we document only the name of the exception: https://github.com/theupdateframework/python-tuf/blob/0f1fc6e33cbc4d4c6b502b9f8c64b119d1a4ad2f/tuf/api/metadata.py#L346
Expected behavior: Decide how we want to document our exceptions and stick to that. Document how we should write docstrings about exceptions somewhere. I didn't find any mentions about the exception docstrings in the Google Python guidelines
One solution I am proposing is using a hybrid of the two ways we document them now: document exception as
module_name.exception_name where module_name is the name we have given during import.
Example:
import tuf.api.exceptions as exceptions
...
def f():
"""
Raises:
exceptions.UnsignedMetadataError: unsigned metadata
"""
...
I would prefer no module path and just using the class name (this is what we do for other things -- see e.g. how we refer to TargetFile and not tuf.api.metadata.TargetFile in the ngclient documentation).
However, we probably should start publishing the exceptions documention on RTD so that there is a reference to look them up.
I'll add the backlog tag with the hope that it leads to figuring out some better solution than the current worst-of-all-options (quite wordy in docstring, yet no linked docs on readthedocs)