Document exceptions raised by functions in packaging.utils

[pradyunsg]

Functions like parse_wheel_filename and parse_sdist_filename can raise exceptions, but this is not a documented detail. We should document the exceptions and add a Raises to the relevant functions.

[MrMino]

I'm happy to PR this, I'm familiar with that part.

Let me know if I'm mistaken in any / missing something:

• canonicalize_name - doesn't raise
• canonicalize_version - doesn't raise
• parse_wheel_filename - raises InvalidWheelFilename when:
  • given filename does not end with ".whl"
  • the number of dashes (parts) in the filename is different from 4 or 5
  • the distribution name contains unescaped non-alphanumerical characters (PEP427 escaping and unicode).
  • the build number doesn't start with a digit
• parse_sdist_filename - raises InvalidSdistFilename when:
  • given filename does not end with a sdist-appropriate extension (.zip or .tar.gz)
  • if the distribution name and version are not separated by a - (dash).

Is there anything else? How detailed does this description need to be?

For convenience: https://packaging.pypa.io/en/latest/utils.html