python-tuf icon indicating copy to clipboard operation
python-tuf copied to clipboard

Improve docstrings on exceptions

Open MVrachev opened this issue 3 years ago • 3 comments

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

MVrachev avatar Dec 17 '21 16:12 MVrachev

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
"""
...

MVrachev avatar Dec 17 '21 16:12 MVrachev

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.

jku avatar Dec 20 '21 08:12 jku

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)

jku avatar Apr 04 '22 12:04 jku