Azure / Azure/azure-storage-python
API Documentation Should Include Expected Exceptions
- Ngôn ngữ chính
- Python
- Star
- 343
- Fork
- 243
- Chỉ số merge pull request
- Không có pull request nào được merge trong 30 ngày
Mô tả
### 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.
Hướng dẫn đóng góp
Hướng nghiên cứu
Bắt đầu với tài liệu tham chiếu của BaseBlobService và các mục về các phương thức get_blob_to_*, sau đó chạy get_blob_to_text với một blob được biết là không tồn tại như đã mô tả. Ghi lại các ngoại lệ dự kiến, bao gồm azure.common.AzureMissingResourceHttpError, đối với các phương thức liên quan và làm rõ điều gì xảy ra khi blob không tồn tại.
Do mô hình lập chỉ mục viết ra từ nội dung của issue.
Đánh giá
- Công nghệ
- python
- Lĩnh vực
- documentation
- Loại issue
- Tài liệu
- Độ khó
- 3/5
- Thời gian dự kiến
- 1-2 ngày
- Mức độ hoạt động
- Đình trệ
- Độ rõ ràng
- Khá rõ ràng
- Mức phù hợp với người mới
- 38/100