Azure / Azure/azure-storage-python

API Documentation Should Include Expected Exceptions

Offen
#542 5 Kommentare 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen
Vorherrschende Sprache
Python
Sterne
343
Forks
243
PR-Merge-Kennzahlen
Keine gemergten PRs in 30 T.

Beschreibung

### 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.

Beitragsleitfaden

Beitragsleitfaden öffnen

Rechercherichtung

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.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Bewertung

Tech-Stack
python
Bereich
documentation
Issue-Typ
Dokumentation
Schwierigkeit
3/5
Geschätzter Aufwand
1-2 Tage
Aktivitätsstatus
Veraltet
Klarheit
Größtenteils klar
Anfängerfreundlichkeit
38/100

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.