Responses & Errors

googleSheetsLib.models.Response dataclass

Bases: Generic[T]

Universal response wrapper for all library operations.

This class uses Generics (T) to allow type checkers to understand the structure of the returned data.

Attributes:

Name	Type	Description
data	T	The payload returned by the operation (e.g., a Sheet object, a dictionary of values, or a list). Is None if the operation failed or the the request doesn't expect a data response.
error	SheetsError	An error object containing details if the operation failed.
ok	bool	Success flag. Returns True if the operation succeeded, False otherwise.
date	datetime	Timestamp of when the response object was created.
details	Any	Extra metadata or debugging info regarding the request execution. Generally structured like a dcitionary with the request's information.

Source code in src/googleSheetsLib/models.py

@dataclass
class Response(Generic[T]):
    """
    Universal response wrapper for all library operations.

    This class uses Generics (`T`) to allow type checkers to understand the 
    structure of the returned data.

    Attributes:
        data (T, optional): The payload returned by the operation (e.g., a Sheet object, 
            a dictionary of values, or a list). Is `None` if the operation failed or the the request
            doesn't expect a data response.
        error (SheetsError, optional): An error object containing details if the operation failed.
        ok (bool): Success flag. Returns `True` if the operation succeeded, `False` otherwise.
        date (datetime): Timestamp of when the response object was created.
        details (Any, optional): Extra metadata or debugging info regarding the request execution.
            Generally structured like a dcitionary with the request's information.
    """

    data: Optional[T] = None
    error: Optional[SheetsError] = None
    ok: bool = False
    date: datetime = field(default_factory=datetime.now)
    details: Optional[Any] = None

    @classmethod
    def success(cls, data: T = None, details = None) -> "Response[T]":
        """
        Factory method to create a successful response.

        Args:
            data (T, optional): The result of the operation.
            details (Any, optional): Additional metadata.

        Returns:
            Response[T]: A response object with `ok=True` and populated data.
        """
        return cls(ok=True, data=data, error=None, details = details)

    @classmethod
    def fail(cls, message: str, 
             code: Optional[int] = None, 
             function_name: Optional[str] = None,
             details: Optional[Any] = None) -> "Response[Any]":
        """
        Factory method to create a failure response.

        Args:
            message (str): Description of what went wrong.
            code (int, optional): Error code associated with the failure.
            function_name (str, optional): Context of where the error originated.
            details (Any, optional): Raw exception or error data.

        Returns:
            Response[Any]: A response object with `ok=False` and a populated `SheetsError`.
        """
        return cls(ok=False, data=None, error=SheetsError(message=message, code=code, function_name=function_name, details=details))

fail(message, code=None, function_name=None, details=None) classmethod

Factory method to create a failure response.

Parameters:

Name	Type	Description	Default
message	str	Description of what went wrong.	required
code	int	Error code associated with the failure.	None
function_name	str	Context of where the error originated.	None
details	Any	Raw exception or error data.	None

Returns:

Type	Description
Response[Any]	Response[Any]: A response object with ok=False and a populated SheetsError.

Source code in src/googleSheetsLib/models.py

@classmethod
def fail(cls, message: str, 
         code: Optional[int] = None, 
         function_name: Optional[str] = None,
         details: Optional[Any] = None) -> "Response[Any]":
    """
    Factory method to create a failure response.

    Args:
        message (str): Description of what went wrong.
        code (int, optional): Error code associated with the failure.
        function_name (str, optional): Context of where the error originated.
        details (Any, optional): Raw exception or error data.

    Returns:
        Response[Any]: A response object with `ok=False` and a populated `SheetsError`.
    """
    return cls(ok=False, data=None, error=SheetsError(message=message, code=code, function_name=function_name, details=details))

success(data=None, details=None) classmethod

Factory method to create a successful response.

Parameters:

Name	Type	Description	Default
data	T	The result of the operation.	None
details	Any	Additional metadata.	None

Returns:

Type	Description
Response[T]	Response[T]: A response object with ok=True and populated data.

Source code in src/googleSheetsLib/models.py

@classmethod
def success(cls, data: T = None, details = None) -> "Response[T]":
    """
    Factory method to create a successful response.

    Args:
        data (T, optional): The result of the operation.
        details (Any, optional): Additional metadata.

    Returns:
        Response[T]: A response object with `ok=True` and populated data.
    """
    return cls(ok=True, data=data, error=None, details = details)

googleSheetsLib.models.SheetsError dataclass

Standardized error container for API or library exceptions.

This class encapsulates error details to provide a consistent error handling experience across the library.

Attributes:

Name	Type	Description
message	str	A human-readable description of the error.
code	int	The HTTP status code (e.g., 404, 500) or internal error code.
reason	str	The API error reason (e.g., 'invalid_grant', 'notFound').
function_name	str	The name of the method/function where the error occurred. Useful for debugging the call stack.
details	Any	Raw error payload or traceback information.

Source code in src/googleSheetsLib/models.py

@dataclass
class SheetsError:
    """
    Standardized error container for API or library exceptions.

    This class encapsulates error details to provide a consistent error handling 
    experience across the library.

    Attributes:
        message (str): A human-readable description of the error.
        code (int, optional): The HTTP status code (e.g., 404, 500) or internal error code.
        reason (str, optional): The API error reason (e.g., 'invalid_grant', 'notFound').
        function_name (str, optional): The name of the method/function where the error occurred.
            Useful for debugging the call stack.
        details (Any, optional): Raw error payload or traceback information.
    """
    message: str
    code: Optional[int] = None
    reason: Optional[str] = None
    function_name: Optional[str] = None
    details: Any = None