Azure / Azure/azure-storage-python
API Documentation Should Include Expected Exceptions
- 主要言語
- Python
- スター
- 343
- フォーク
- 243
- PR マージ指標
- 30日以内にマージされた PR はありません
説明
### 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.
コントリビューションガイド
調査の方向性
まず BaseBlobService のリファレンスドキュメントと、その get_blob_to_* メソッドのエントリを確認し、次に説明どおり、存在しないことが分かっている blob に対して get_blob_to_text を実行します。関連するメソッドについて、azure.common.AzureMissingResourceHttpError を含む予想される例外を文書化し、blob が存在しない場合に何が起こるかを明確にしてください。
索引モデルが issue の本文から書いたものです。
評価
- 技術スタック
- python
- 領域
- documentation
- issue の種類
- ドキュメント
- 難易度
- 3/5
- 見積もり時間
- 1〜2日
- 活発さ
- 停滞
- 明瞭さ
- おおむね明確
- 初心者へのやさしさ
- 38/100