From d84495279d1bc88d7221e22902513fe48625bdbc Mon Sep 17 00:00:00 2001
From: Stephen Finucane <stephenfin@redhat.com>
Date: Thu, 17 Aug 2023 11:01:13 +0100
Subject: [PATCH] docs: Add exception documentation

Provide a list of available exceptions and stress that callers must
handle these themselves.

Change-Id: If3f56524a4642e0e147305758a8c5a4cc88c94bd
Signed-off-by: Stephen Finucane <stephenfin@redhat.com>
---
 doc/source/user/exceptions.rst | 15 +++++++++++++++
 doc/source/user/index.rst      | 13 +++++++++++++
 openstack/exceptions.py        | 22 +++-------------------
 3 files changed, 31 insertions(+), 19 deletions(-)
 create mode 100644 doc/source/user/exceptions.rst

diff --git a/doc/source/user/exceptions.rst b/doc/source/user/exceptions.rst
new file mode 100644
index 000000000..3e85f6f98
--- /dev/null
+++ b/doc/source/user/exceptions.rst
@@ -0,0 +1,15 @@
+Exceptions
+==========
+
+openstacksdk provides a number of `exceptions`__ for commonly encountered
+issues, such as missing API endpoints, various HTTP error codes, timeouts and
+so forth. It is the responsibility of the calling application to handle these
+exceptions appropriately.
+
+Available exceptions
+--------------------
+
+.. automodule:: openstack.exceptions
+   :members:
+
+.. __: https://docs.python.org/3/library/exceptions.html
diff --git a/doc/source/user/index.rst b/doc/source/user/index.rst
index f9e49fcf6..7522e7116 100644
--- a/doc/source/user/index.rst
+++ b/doc/source/user/index.rst
@@ -171,6 +171,19 @@ can be customized.
    resource
    service_description
    utils
+
+Errors and warnings
+~~~~~~~~~~~~~~~~~~~
+
+The SDK attempts to provide detailed errors and warnings for things like failed
+requests, deprecated APIs, and invalid configurations. Application developers
+are responsible for handling these errors and can opt into warnings to ensure
+their applications stay up-to-date.
+
+.. toctree::
+   :maxdepth: 1
+
+   exceptions
    warnings
 
 Presentations
diff --git a/openstack/exceptions.py b/openstack/exceptions.py
index 93a4b9d06..8c14f9d0b 100644
--- a/openstack/exceptions.py
+++ b/openstack/exceptions.py
@@ -57,6 +57,8 @@ class InvalidRequest(SDKException):
 
 
 class HttpException(SDKException, _rex.HTTPError):
+    """The base exception for all HTTP error responses."""
+
     def __init__(
         self,
         message='Error',
@@ -119,26 +121,18 @@ class HttpException(SDKException, _rex.HTTPError):
 class BadRequestException(HttpException):
     """HTTP 400 Bad Request."""
 
-    pass
-
 
 class ForbiddenException(HttpException):
     """HTTP 403 Forbidden Request."""
 
-    pass
-
 
 class ConflictException(HttpException):
     """HTTP 409 Conflict."""
 
-    pass
-
 
 class PreconditionFailedException(HttpException):
     """HTTP 412 Precondition Failed."""
 
-    pass
-
 
 class MethodNotSupported(SDKException):
     """The resource does not support this operation type."""
@@ -161,13 +155,9 @@ class MethodNotSupported(SDKException):
 class DuplicateResource(SDKException):
     """More than one resource exists with that name."""
 
-    pass
-
 
 class ResourceNotFound(HttpException):
-    """No resource exists with that name or id."""
-
-    pass
+    """No resource exists with that name or ID."""
 
 
 NotFoundException = ResourceNotFound
@@ -176,20 +166,14 @@ NotFoundException = ResourceNotFound
 class ResourceTimeout(SDKException):
     """Timeout waiting for resource."""
 
-    pass
-
 
 class ResourceFailure(SDKException):
     """General resource failure."""
 
-    pass
-
 
 class InvalidResourceQuery(SDKException):
     """Invalid query params for resource."""
 
-    pass
-
 
 def _extract_message(obj):
     if isinstance(obj, dict):