Azure / Azure/azure-storage-python

API Documentation Should Include Expected Exceptions

オープン
#542 コメント 5 件 リアクション 0 件 担当者 0 名 GitHub で見る
主要言語
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

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。