Exceptions

This file contains the exception classes for the PyClasher package.

Authors

201st-Luka

MISSING = Missing() module-attribute

MISSING object

This Missing-instance is used as a reference in many parts of the package.

instance of the Missing class

AccessDenied

Bases: ApiException

Access denied, either because of missing/incorrect credentials or used API token does not grant access to the requested resource.

Source code in pyclasher/exceptions.py

class AccessDenied(ApiException):
    """
    Access denied, either because of missing/incorrect credentials or used API
    token does not grant access to the requested resource.
    """

    def __init__(self, client_error=None):
        """
        Args:
            client_error (ClientError): optional ``ClientError`` information
                                        that is provided by the request
        """
        super().__init__(403, client_error)
        return

    def __str__(self):
        return ("Access denied, either because of missing/incorrect "
                "credentials or used API token does not grant access to the "
                "requested resource.")

__init__(client_error=None)

Parameters:

Name	Type	Description	Default
client_error	ClientError	optional ClientError information that is provided by the request	None

Source code in pyclasher/exceptions.py

def __init__(self, client_error=None):
    """
    Args:
        client_error (ClientError): optional ``ClientError`` information
                                    that is provided by the request
    """
    super().__init__(403, client_error)
    return

ApiException

Bases: PyClasherException

Exception class that is subclassed by every API exception

Attributes:

Name	Type	Description
api_code	int	API status code of the request
client_error	ClientError	optional ClientError information that is provided by the request

Source code in pyclasher/exceptions.py

class ApiException(PyClasherException):
    """
    Exception class that is subclassed by every API exception

    Attributes:
        api_code (int):             API status code of the request
        client_error (ClientError): optional ``ClientError`` information that is
                                    provided by the request
    """

    def __init__(self, api_code, client_error=None):
        """
        Args:
            api_code (int):             API status code of the request
            client_error (ClientError): optional ``ClientError`` information
                                        that is provided by the request
        """
        self.api_code = api_code
        self.client_error = client_error
        super().__init__()
        return

    def __repr__(self):
        return f"{self.__class__.__name__}({self.api_code})"

    def __str__(self):
        return f"an API error occurred"

__init__(api_code, client_error=None)

Parameters:

Name	Type	Description	Default
api_code	int	API status code of the request	required
client_error	ClientError	optional ClientError information that is provided by the request	None

Source code in pyclasher/exceptions.py

def __init__(self, api_code, client_error=None):
    """
    Args:
        api_code (int):             API status code of the request
        client_error (ClientError): optional ``ClientError`` information
                                    that is provided by the request
    """
    self.api_code = api_code
    self.client_error = client_error
    super().__init__()
    return

ApiExceptions

Collection of the ApiExceptions

Attributes:

Name	Type	Description
BadRequest	BadRequest	BadRequest instance
AccessDenied	AccessDenied	AccessDenied instance
NotFound	NotFound	NotFound instance
Throttled	Throttled	Throttled instance
UnknownApiException	UnknownApiException	UnknownApiException instance
Maintenance	Maintenance	Maintenance instance

Source code in pyclasher/exceptions.py

class ApiExceptions:
    """
    Collection of the ApiExceptions

    Attributes:
        BadRequest (BadRequest):                    ``BadRequest`` instance
        AccessDenied (AccessDenied):                ``AccessDenied`` instance
        NotFound (NotFound):                        ``NotFound`` instance
        Throttled (Throttled):                      ``Throttled`` instance
        UnknownApiException (UnknownApiException):  ``UnknownApiException``
                                                    instance
        Maintenance (Maintenance):                  ``Maintenance`` instance
    """

    BadRequest = BadRequest()
    AccessDenied = AccessDenied()
    NotFound = NotFound()
    Throttled = Throttled()
    UnknownApiException = UnknownApiException()
    Maintenance = Maintenance()

    @classmethod
    def from_api_code(cls, api_code, client_error=None):
        """
        Class method to create a subclass of ``ApiException`` using the API
        code and the optional client error information that is provided by the
        request itself.

        Args:
            api_code (int):             API status code of the request
            client_error (ClientError): optional ``ClientError`` information
                                        that is provided by the request

        Returns:
            returns a subclass of ``ApiException``

        Raises:
            PyClasherException: ``api_code`` is not 400, 403, 404, 429,
                                500, 503
        """

        # cannot use a `match ...: case ...:` here because it is not
        # supported for Python version 3.9 and below
        if api_code == 400:
            return BadRequest(client_error)
        elif api_code == 403:
            return AccessDenied(client_error)
        elif api_code == 404:
            return NotFound(client_error)
        elif api_code == 429:
            return Throttled(client_error)
        elif api_code == 500:
            return UnknownApiException(client_error)
        elif api_code == 503:
            return Maintenance(client_error)
        else:
            PyClasherException(f"could not find {api_code} in the API "
                               f"exceptions")

from_api_code(api_code, client_error=None) classmethod

Class method to create a subclass of ApiException using the API code and the optional client error information that is provided by the request itself.

Parameters:

Name	Type	Description	Default
api_code	int	API status code of the request	required
client_error	ClientError	optional ClientError information that is provided by the request	None

Returns:

Type	Description
ApiException	returns a subclass of ApiException

Raises:

Type	Description
PyClasherException	api_code is not 400, 403, 404, 429, 500, 503

Source code in pyclasher/exceptions.py

@classmethod
def from_api_code(cls, api_code, client_error=None):
    """
    Class method to create a subclass of ``ApiException`` using the API
    code and the optional client error information that is provided by the
    request itself.

    Args:
        api_code (int):             API status code of the request
        client_error (ClientError): optional ``ClientError`` information
                                    that is provided by the request

    Returns:
        returns a subclass of ``ApiException``

    Raises:
        PyClasherException: ``api_code`` is not 400, 403, 404, 429,
                            500, 503
    """

    # cannot use a `match ...: case ...:` here because it is not
    # supported for Python version 3.9 and below
    if api_code == 400:
        return BadRequest(client_error)
    elif api_code == 403:
        return AccessDenied(client_error)
    elif api_code == 404:
        return NotFound(client_error)
    elif api_code == 429:
        return Throttled(client_error)
    elif api_code == 500:
        return UnknownApiException(client_error)
    elif api_code == 503:
        return Maintenance(client_error)
    else:
        PyClasherException(f"could not find {api_code} in the API "
                           f"exceptions")

BadRequest

Bases: ApiException

Client provided incorrect parameters for the request.

Source code in pyclasher/exceptions.py

class BadRequest(ApiException):
    """
    Client provided incorrect parameters for the request.
    """

    def __init__(self, client_error=None):
        """
        Args:
            client_error (ClientError): optional ``ClientError`` information
                                        that is provided by the request
        """
        super().__init__(400, client_error)
        return

    def __str__(self):
        return "Client provided incorrect parameters for the request."

__init__(client_error=None)

Parameters:

Name	Type	Description	Default
client_error	ClientError	optional ClientError information that is provided by the request	None

Source code in pyclasher/exceptions.py

def __init__(self, client_error=None):
    """
    Args:
        client_error (ClientError): optional ``ClientError`` information
                                    that is provided by the request
    """
    super().__init__(400, client_error)
    return

ClientAlreadyInitialised

Bases: PyClasherException

Exception that is raised if a new client was created but there is another client that has at least one equal token.

Source code in pyclasher/exceptions.py

class ClientAlreadyInitialised(PyClasherException):
    """
    Exception that is raised if a new client was created but there is another
    client that has at least one equal token.
    """

    def __str__(self):
        return ("It is not possible to create multiple clients with the same "
                "tokens.")

ClientIsNotRunning

Bases: PyClasherException

Exception that is raised if the client is not running but an action that requires the client to run was done.

Source code in pyclasher/exceptions.py

class ClientIsNotRunning(PyClasherException):
    """
    Exception that is raised if the client is not running but an action that
    requires the client to run was done.
    """

    def __str__(self):
        return "The client is not running."

ClientIsRunning

Bases: PyClasherException

Exception that is raised if the client is started multiple times without stopping the client between those calls.

Source code in pyclasher/exceptions.py

class ClientIsRunning(PyClasherException):
    """
    Exception that is raised if the client is started multiple times without
    stopping the client between those calls.
    """

    def __str__(self):
        return ("The client is already running. Stop it first before starting "
                "again.")

ClientRunningOverwrite

Bases: PyClasherException

Exception that is raised if the client is running but a client parameter was tried to edit but requires a client that is not running.

Source code in pyclasher/exceptions.py

class ClientRunningOverwrite(PyClasherException):
    """
    Exception that is raised if the client is running but a client parameter
    was tried to edit but requires a client that is not running.
    """

    def __str__(self):
        return "You cannot overwrite the parameter of a running client."

InvalidClientId

Bases: PyClasherException

Exception that is raised if a client ID is not valid. It can already been taken, or it can be equal to an ID that is in the range of 0 to global_client_id.

Source code in pyclasher/exceptions.py

class InvalidClientId(PyClasherException):
    """
    Exception that is raised if a client ID is not valid. It can already been
    taken, or it can be equal to an ID that is in the range of 0 to
    ``global_client_id``.
    """
    pass

InvalidLoginData

Bases: PyClasherException

Exception that is raised if the provided login data using Client.from_login(..., ...) is not valid.

Source code in pyclasher/exceptions.py

class InvalidLoginData(PyClasherException):
    """
    Exception that is raised if the provided login data using
    `Client.from_login(..., ...)` is not valid.
    """

    def __str__(self):
        return "The login data is invalid."

InvalidSeasonFormat

Bases: PyClasherException

Exception that is raised if the season format is not valid.

Source code in pyclasher/exceptions.py

class InvalidSeasonFormat(PyClasherException):
    """
    Exception that is raised if the season format is not valid.
    """

    def __str__(self):
        return ("The season string is not valid. It must be follow the "
                "following format: <yyyy-mm> where <yyyy> is the year"
                " and <mm> is the month.")

InvalidTimeFormat

Bases: PyClasherException

Exception that is raised if the provided time format is not recognized by the API.

Attributes:

Name	Type	Description
value	str	value string of the invalid time
time_format	str	format of a valid time string

Source code in pyclasher/exceptions.py

class InvalidTimeFormat(PyClasherException):
    """
    Exception that is raised if the provided time format is not recognized by
    the API.

    Attributes:
        value (str):        value string of the invalid time
        time_format (str):  format of a valid time string
    """

    def __init__(self, value, time_format):
        """
        Args:
            value (str):        value string of the invalid time
            time_format (str):  format of a valid time string
        """
        self.value = value
        self.time_format = time_format
        super().__init__()
        return

    def __str__(self):
        return (f"The time {self.value} does not match the format "
                f"'{self.time_format}'.")

__init__(value, time_format)

Parameters:

Name	Type	Description	Default
value	str	value string of the invalid time	required
time_format	str	format of a valid time string	required

Source code in pyclasher/exceptions.py

def __init__(self, value, time_format):
    """
    Args:
        value (str):        value string of the invalid time
        time_format (str):  format of a valid time string
    """
    self.value = value
    self.time_format = time_format
    super().__init__()
    return

InvalidType

Bases: PyClasherException

Exception that is raised if a type is incorrect (similar to TypeError)

Attributes:

Name	Type	Description
element	Any	the element whose type is not correct
types	type, tuple[type, ...	correct type or types

Source code in pyclasher/exceptions.py

class InvalidType(PyClasherException):
    """
    Exception that is raised if a type is incorrect (similar to `TypeError`)

    Attributes:
        element (Any):                  the element whose type is not correct
        types (type, tuple[type, ...):  correct type or types
    """

    def __init__(self, element, allowed_types):
        """
        Args:
            element (Any):                          the element whose type is
                                                    not correct
            allowed_types (type, tuple[type, ...):  correct type or types
        """
        super().__init__()
        self.element = element
        self.types = allowed_types
        return

    def __str__(self):
        return (f"{self.element} is of invalid type, allowed types are "
                f"{self.types}.")

__init__(element, allowed_types)

Parameters:

Name	Type	Description	Default
element	Any	the element whose type is not correct	required
allowed_types	type, tuple[type, ...	correct type or types	required

Source code in pyclasher/exceptions.py

def __init__(self, element, allowed_types):
    """
    Args:
        element (Any):                          the element whose type is
                                                not correct
        allowed_types (type, tuple[type, ...):  correct type or types
    """
    super().__init__()
    self.element = element
    self.types = allowed_types
    return

LoginNotDone

Bases: PyClasherException

Exception that is raised of raised if the login is not done but tokens were tried to retrieve. (similar to RequestNotDone)

Source code in pyclasher/exceptions.py

class LoginNotDone(PyClasherException):
    """
    Exception that is raised of raised if the login is not done but tokens
    were tried to retrieve. (similar to ``RequestNotDone``)
    """

    def __str__(self):
        return "The login was not done. You need to login first."

Maintenance

Bases: ApiException

Service is temporarily unavailable because of maintenance.

Source code in pyclasher/exceptions.py

class Maintenance(ApiException):
    """
    Service is temporarily unavailable because of maintenance.
    """

    def __init__(self, client_error=None):
        """
        Args:
            client_error (ClientError): optional ``ClientError`` information
                                        that is provided by the request
        """
        super().__init__(503, client_error)
        return

    def __str__(self):
        return "Service is temporarily unavailable because of maintenance."

__init__(client_error=None)

Parameters:

Name	Type	Description	Default
client_error	ClientError	optional ClientError information that is provided by the request	None

Source code in pyclasher/exceptions.py

def __init__(self, client_error=None):
    """
    Args:
        client_error (ClientError): optional ``ClientError`` information
                                    that is provided by the request
    """
    super().__init__(503, client_error)
    return

Missing

Class of the MISSING object

Notes

This class always returns itself. One time received in a response there is no way back to an object different from MISSING.

Attributes:

Name	Type	Description
return_string	str	the string that is returned using str(MISSING)

Source code in pyclasher/exceptions.py

class Missing:
    """
    Class of the ``MISSING`` object

    Notes:
        This class always returns itself. One time received in a response there
        is no way back to an object different from ``MISSING``.

    Attributes:
        return_string (str):    the string that is returned using
                                ``str(MISSING)``
    """

    return_string = "MISSING"

    def __call__(self, *args, **kwargs):
        return self

    def __getitem__(self, item):
        return self

    def __getattr__(self, item):
        return self

    def __add__(self, other):
        if isinstance(other, Missing):
            return 0
        return other

    def __str__(self):
        return self.return_string

    def __repr__(self):
        return "Missing()"

NoClient

Bases: PyClasherException

Exception that is raised if a request was started but there is no client that can execute the request.

Source code in pyclasher/exceptions.py

class NoClient(PyClasherException):
    """
    Exception that is raised if a request was started but there is no client
    that can execute the request.
    """

    def __str__(self):
        return "No client has been initialised."

NoneToken

Bases: PyClasherException

Exception that is raised if a client is started without any tokens.

Source code in pyclasher/exceptions.py

class NoneToken(PyClasherException):
    """
    Exception that is raised if a client is started without any tokens.
    """

    def __str__(self):
        return ("The token must be passed to the client. "
                "You can do this in the initialisation process"
                " or pass the tokens to the start function.")

NotFound

Bases: ApiException

Resource was not found.

Source code in pyclasher/exceptions.py

class NotFound(ApiException):
    """
    Resource was not found.
    """

    def __init__(self, client_error=None):
        """
        Args:
            client_error (ClientError): optional ``ClientError`` information
                                        that is provided by the request
        """
        super().__init__(404, client_error)
        return

    def __str__(self):
        return "Resource was not found."

__init__(client_error=None)

Parameters:

Name	Type	Description	Default
client_error	ClientError	optional ClientError information that is provided by the request	None

Source code in pyclasher/exceptions.py

def __init__(self, client_error=None):
    """
    Args:
        client_error (ClientError): optional ``ClientError`` information
                                    that is provided by the request
    """
    super().__init__(404, client_error)
    return

PyClasherException

Bases: Exception

Exception class that is subclassed by every exception to the pyclasher package

Source code in pyclasher/exceptions.py

class PyClasherException(Exception):
    """
    Exception class that is subclassed by every exception to the ``pyclasher``
    package
    """
    pass

RequestNotDone

Bases: PyClasherException

Exception that is raised if a request attribute, property, ... was accessed but could not be loaded because the request was not done.

Source code in pyclasher/exceptions.py

class RequestNotDone(PyClasherException):
    """
    Exception that is raised if a request attribute, property, ... was
    accessed but could not be loaded because the request was not done.
    """

    def __str__(self):
        return "The request was not done."

RequestTimeout

Bases: PyClasherException

Exception that is raised if a request takes longer than allowed.

Attributes:

Name	Type	Description
allowed_time	float	maximal time a request is allowed to take

Source code in pyclasher/exceptions.py

class RequestTimeout(PyClasherException):
    """
    Exception that is raised if a request takes longer than allowed.

    Attributes:
        allowed_time (float):   maximal time a request is allowed to take
    """

    def __init__(self, allowed_time):
        """
        Args:
            allowed_time (float):   maximal time a request is allowed to take
        """
        self.allowed_time = allowed_time
        super().__init__()
        return

    def __str__(self):
        return (f"The request took longer than {self.allowed_time}s and was "
                f"cancelled.")

__init__(allowed_time)

Parameters:

Name	Type	Description	Default
allowed_time	float	maximal time a request is allowed to take	required

Source code in pyclasher/exceptions.py

def __init__(self, allowed_time):
    """
    Args:
        allowed_time (float):   maximal time a request is allowed to take
    """
    self.allowed_time = allowed_time
    super().__init__()
    return

Throttled

Bases: ApiException

Request was throttled, because amount of requests was above the threshold defined for the used API token.

Source code in pyclasher/exceptions.py

class Throttled(ApiException):
    """
    Request was throttled, because amount of requests was above the threshold
    defined for the used API token.
    """

    def __init__(self, client_error=None):
        """
        Args:
            client_error (ClientError): optional ``ClientError`` information
                                        that is provided by the request
        """
        super().__init__(429, client_error)
        return

    def __str__(self):
        return ("Request was throttled, because amount of requests was above "
                "the threshold defined for the used API token.")

__init__(client_error=None)

Parameters:

Name	Type	Description	Default
client_error	ClientError	optional ClientError information that is provided by the request	None

Source code in pyclasher/exceptions.py

def __init__(self, client_error=None):
    """
    Args:
        client_error (ClientError): optional ``ClientError`` information
                                    that is provided by the request
    """
    super().__init__(429, client_error)
    return

UnknownApiException

Bases: ApiException

Unknown error happened when handling the request.

Source code in pyclasher/exceptions.py

class UnknownApiException(ApiException):
    """
    Unknown error happened when handling the request.
    """

    def __init__(self, client_error=None):
        """
        Args:
            client_error (ClientError): optional ``ClientError`` information
                                        that is provided by the request
        """
        super().__init__(500, client_error)
        return

    def __str__(self):
        return "Unknown error happened when handling the request."

__init__(client_error=None)

Parameters:

Name	Type	Description	Default
client_error	ClientError	optional ClientError information that is provided by the request	None

Source code in pyclasher/exceptions.py

def __init__(self, client_error=None):
    """
    Args:
        client_error (ClientError): optional ``ClientError`` information
                                    that is provided by the request
    """
    super().__init__(500, client_error)
    return