API Documentation Should Include Expected Exceptions

Which service(blob, file, queue) does this issue concern?

Blob

Which version of the SDK was used? Please provide the output of pip freeze.

azure-storage-blob v1.4.0

What problem was encountered?

The documentation for BaseBlobService does not include Exceptions that can be expected. For example, the get_blob_to_* methods simply state that they return a blob. But what happens if that Blob doesn’t exist? This can theoretically happen even if you first verify that the blob in question exists.

Have you found a mitigation/solution?

Run functions locally to see what exceptions are produced. [This is not very comprehensive.] In a simple test that consisted of calling get_blob_to_text with a known non-existent file, I found that it raises the azure.common.AzureMissingResourceHttpError exception (which is also not documented…?).

This is important because Python tends to be EAFP rather than LBYL and having well-documented exceptions helps enable a EAFP development approach.

[dsgon]

Hi. I’m working with this library and I detect that it is the same for cosmosdb.table.tableservice TableService (TableStorage) Any update about this?

[zezha-msft]

Hi @ericdrobinson, thanks for reaching out and providing us feedbacks!

I’ve logged an item to improve the documentation.