Update docs framework & exception docs (#1145)

Author: ikonst

.readthedocs.yaml

@@ -0,0 +1,19 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+   configuration: docs/conf.py
+
+# Optionally declare the Python requirements required to build your docs
+python:
+   install:
+   - requirements: docs/requirements.txt

docs/api.rst

@@ -28,6 +28,7 @@ Low Level API
 Exceptions
 ----------
 
+.. autoexception:: pynamodb.exceptions.PynamoDBException
 .. autoexception:: pynamodb.exceptions.PynamoDBConnectionError
 .. autoexception:: pynamodb.exceptions.DeleteError
 .. autoexception:: pynamodb.exceptions.QueryError
@@ -38,4 +39,8 @@ Exceptions
 .. autoexception:: pynamodb.exceptions.TableError
 .. autoexception:: pynamodb.exceptions.TableDoesNotExist
 .. autoexception:: pynamodb.exceptions.DoesNotExist
-
+.. autoexception:: pynamodb.exceptions.TransactWriteError
+.. autoexception:: pynamodb.exceptions.TransactGetError
+.. autoexception:: pynamodb.exceptions.InvalidStateError
+.. autoexception:: pynamodb.exceptions.AttributeDeserializationError
+.. autoexception:: pynamodb.exceptions.AttributeNullError

docs/conf.py

@@ -267,3 +267,7 @@
 
 # If true, do not generate a @detailmenu in the "Top" node's menu.
 #texinfo_no_detailmenu = False
+
+autodoc_default_options = {
+    'members': True,
+}

docs/requirements.txt

@@ -1,2 +1,3 @@
 .[signals]
-sphinx-rtd-theme==0.4.3
+sphinx>=5
+sphinx-rtd-theme==1.1.1

pynamodb/exceptions.py

@@ -8,22 +8,35 @@
 
 
 class PynamoDBException(Exception):
-    msg: str
-
     """
-    A common exception class
+    Base class for all PynamoDB exceptions.
     """
+
+    msg: str
+
     def __init__(self, msg: Optional[str] = None, cause: Optional[Exception] = None) -> None:
         self.msg = msg if msg is not None else self.msg
         self.cause = cause
         super(PynamoDBException, self).__init__(self.msg)
 
     @property
     def cause_response_code(self) -> Optional[str]:
+        """
+        The DynamoDB response code such as:
+
+        - ``ConditionalCheckFailedException``
+        - ``ProvisionedThroughputExceededException``
+        - ``TransactionCanceledException``
+
+        Inspect this value to determine the cause of the error and handle it.
+        """
         return getattr(self.cause, 'response', {}).get('Error', {}).get('Code')
 
     @property
     def cause_response_message(self) -> Optional[str]:
+        """
+        The human-readable description of the error returned by DynamoDB.
+        """
         return getattr(self.cause, 'response', {}).get('Error', {}).get('Message')
 
 
@@ -101,35 +114,37 @@ def __init__(self, table_name: str) -> None:
 
 class TransactWriteError(PynamoDBException):
     """
-    Raised when a TransactWrite operation fails
+    Raised when a :class:`~pynamodb.transactions.TransactWrite` operation fails.
     """
-    pass
 
 
 class TransactGetError(PynamoDBException):
     """
-    Raised when a TransactGet operation fails
+    Raised when a :class:`~pynamodb.transactions.TransactGet` operation fails.
     """
-    pass
 
 
 class InvalidStateError(PynamoDBException):
     """
-    Raises when the internal state of an operation context is invalid
+    Raises when the internal state of an operation context is invalid.
     """
     msg = "Operation in invalid state"
 
 
 class AttributeDeserializationError(TypeError):
     """
-    Raised when attribute type is invalid
+    Raised when attribute type is invalid during deserialization.
     """
     def __init__(self, attr_name: str, attr_type: str):
         msg = "Cannot deserialize '{}' attribute from type: {}".format(attr_name, attr_type)
         super(AttributeDeserializationError, self).__init__(msg)
 
 
 class AttributeNullError(ValueError):
+    """
+    Raised when an attribute which is not nullable (:code:`null=False`) is unset during serialization.
+    """
+
     def __init__(self, attr_name: str) -> None:
         self.attr_path = attr_name
 
@@ -141,8 +156,14 @@ def prepend_path(self, attr_name: str) -> None:
 
 
 class VerboseClientError(botocore.exceptions.ClientError):
-    def __init__(self, error_response: Any, operation_name: str, verbose_properties: Optional[Any] = None):
-        """ Modify the message template to include the desired verbose properties """
+    def __init__(self, error_response: Any, operation_name: str, verbose_properties: Optional[Any] = None) -> None:
+        """
+        Like ClientError, but with a verbose message.
+
+        :param error_response: Error response in shape expected by ClientError.
+        :param operation_name: The name of the operation that failed.
+        :param verbose_properties: A dict of properties to include in the verbose message.
+        """
         if not verbose_properties:
             verbose_properties = {}