Azure / Azure/azure-storage-python

API Documentation Should Include Expected Exceptions

Open
#542 5 comments 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
343
Forks
243
PR merge metrics
No merged PRs in 30d

Description

### 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](https://azure-storage.readthedocs.io/ref/azure.storage.blob.baseblobservice.html) does not include Exceptions that can be expected. For example, the [`get_blob_to_*` methods](https://azure-storage.readthedocs.io/ref/azure.storage.blob.baseblobservice.html#azure.storage.blob.baseblobservice.BaseBlobService.get_blob_to_bytes) 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`](https://azure-storage.readthedocs.io/ref/azure.storage.blob.baseblobservice.html#azure.storage.blob.baseblobservice.BaseBlobService.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...?](https://github.com/Azure/azure-sdk-for-python/blob/b7301923a50fcf36a134c9d7fb6b5e88af9e4256/azure-common/azure/common/__init__.py#L35)).

This is important because Python tends to be [EAFP rather than LBYL](https://blogs.msdn.microsoft.com/pythonengineering/2016/06/29/idiomatic-python-eafp-versus-lbyl/) and having well-documented exceptions helps enable a EAFP development approach.

Contributor guide

Open the contributing guide

Research direction

Start with the BaseBlobService reference documentation and its get_blob_to_* method entries, then run get_blob_to_text against a known nonexistent blob as described. Document the expected exceptions, including azure.common.AzureMissingResourceHttpError, for the relevant methods and clarify what happens when the blob does not exist.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
38/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.