Azure / Azure/azure-storage-python
API Documentation Should Include Expected Exceptions
- Langage dominant
- Python
- Étoiles
- 343
- Forks
- 243
- Métriques de merge des PR
- Aucune PR mergée en 30 j
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.
Guide de contribution
Ouvrir le guide de contribution
Piste de recherche
Commencez par la documentation de référence de BaseBlobService et les entrées de ses méthodes get_blob_to_*, puis exécutez get_blob_to_text sur un blob dont vous savez qu’il n’existe pas, comme indiqué. Documentez les exceptions attendues, notamment azure.common.AzureMissingResourceHttpError, pour les méthodes concernées et précisez ce qui se passe lorsque le blob n’existe pas.
Rédigé par le modèle d'indexation à partir du texte de l'issue.
Évaluation
- Stack technique
- python
- Domaine
- documentation
- Type d'issue
- Documentation
- Difficulté
- 3/5
- Temps estimé
- 1-2 jours
- Activité
- À l'abandon
- Clarté
- Plutôt claire
- Accessibilité débutants
- 38/100