Proper way to declare custom exceptions in modern Python?

As of Python 3.8 (2018, https://docs.python.org/dev/whatsnew/3.8.html), the recommended method is still:

class CustomExceptionName(Exception):
    """Exception raised when very uncommon things happen"""
    pass

Please don't forget to document, why a custom exception is neccessary!

If you need to, this is the way to go for exceptions with more data:

class CustomExceptionName(Exception):
    """Still an exception raised when uncommon things happen"""
    def __init__(self, message, payload=None):
        self.message = message
        self.payload = payload # you could add more args
    def __str__(self):
        return str(self.message) # __str__() obviously expects a string to be returned, so make sure not to send any other data types

and fetch them like:

try:
    raise CustomExceptionName("Very bad mistake.", "Forgot upgrading from Python 1")
except CustomExceptionName as error:
    print(str(error)) # Very bad mistake
    print("Detail: {}".format(error.payload)) # Detail: Forgot upgrading from Python 1

payload=None is important to make it pickle-able. Before dumping it, you have to call error.__reduce__(). Loading will work as expected.

You maybe should investigate in finding a solution using pythons return statement if you need much data to be transferred to some outer structure. This seems to be clearer/more pythonic to me. Advanced exceptions are heavily used in Java, which can sometimes be annoying, when using a framework and having to catch all possible errors.

To define your own exceptions correctly, there are a few best practices that you should follow:

• Define a base class inheriting from Exception. This will allow to easily catch any exceptions related to the project:

  class MyProjectError(Exception):
      """A base class for MyProject exceptions."""
  

  Organizing the exception classes in a separate module (e.g. exceptions.py) is generally a good idea.

• To create a specific exception, subclass the base exception class.

  class CustomError(MyProjectError):
     """A custom exception class for MyProject."""
  

  You can subclass custom exception classes as well to create a hierarchy.

• To add support for extra argument(s) to a custom exception, define an __init__() method with a variable number of arguments. Call the base class's __init__(), passing any positional arguments to it (remember that BaseException/Exception expect any number of positional arguments). Store extra argument(s) to the instance, e.g.:

  class CustomError(MyProjectError):
      def __init__(self, *args, **kwargs):
          super().__init__(*args)
          self.foo = kwargs.get('foo')
  

  To raise such exception with an extra argument you can use:

   raise CustomError('Something bad happened', foo='foo')
  

This design adheres to the Liskov substitution principle, since you can replace an instance of a base exception class with an instance of a derived exception class. Also, it allows you to create an instance of a derived class with the same parameters as the parent.

See a very good article "The definitive guide to Python exceptions". The basic principles are:

• Always inherit from (at least) Exception.
• Always call BaseException.__init__ with only one argument.
• When building a library, define a base class inheriting from Exception.
• Provide details about the error.
• Inherit from builtin exceptions types when it makes sense.

There is also information on organizing (in modules) and wrapping exceptions, I recommend to read the guide.

Try this Example

class InvalidInputError(Exception):
    def __init__(self, msg):
        self.msg = msg
    def __str__(self):
        return repr(self.msg)

inp = int(input("Enter a number between 1 to 10:"))
try:
    if type(inp) != int or inp not in list(range(1,11)):
        raise InvalidInputError
except InvalidInputError:
    print("Invalid input entered")

A really simple approach:

class CustomError(Exception):
    pass

raise CustomError("Hmm, seems like this was custom coded...")

Or, have the error raise without printing __main__ (may look cleaner and neater):

class CustomError(Exception):
    __module__ = Exception.__module__

raise CustomError("Improved CustomError!")

I had issues with the above methods, as of Python 3.9.5. However, I found that this works for me:

class MyException(Exception):
    """Port Exception"""

And then it could be used in code like:

try:
    raise MyException('Message')

except MyException as err:
    print (err)

For maximum customisation, to define custom errors, you may want to define an intermediate class that inherits from Exception class as:

class BaseCustomException(Exception):
    def __init__(self, msg):
        self.msg = msg

    def __repr__(self):
        return self.msg


class MyCustomError(BaseCustomException):
    """raise my custom error"""

I came across this thread. This is how I do custom exceptions. While the Fault class is slightly complex, it makes declaring custom expressive exceptions with variable arguments trivial.

FinalViolation, SingletonViolation are both sub classes of TypeError so will be caught code below.

try:
    <do something>
except TypeError as ex:
    <handler>

That's why Fault doesn't inherit from Exception. To allow derivative exceptions to inherit from the exception of their choice.

class Fault:
    """Generic Exception base class. Note not descendant of Exception
Inheriting exceptions override formats"""
    formats = '' # to be overriden in descendant classes

    def __init__(self, *args):
        """Just save args for __str__"""
        self.args = args

    def __str__(self):
        """Use formats declared in descendant classes, and saved args to build exception text"""
        return self.formats.format(*self.args)

class TypeFault(Fault, TypeError):
    """Helper class mixing Fault and TypeError"""

class FinalViolation(TypeFault):
    """Custom exception raised if inheriting from 'final' class"""
    formats = "type {} is not an acceptable base type. It cannot be inherited from."

class SingletonViolation(TypeFault):     
    """Custom exception raised if instancing 'singleton' class a second time"""
    formats = "type {} is a singleton. It can only be instanced once."

FinalViolation, SingletonViolation unfortunately only accept 1 argument.

But one could easily create a multi arg error e.g.

class VesselLoadingError(Fault, BufferError):
    formats = "My {} is full of {}."

raise VesselLoadingError('hovercraft', 'eels')

__main__.VesselLoadingError: My hovercraft is full of eels.

For me it is just __init__ and variables but making sometimes testing.

My sample:

Error_codes = { 100: "Not enough parameters", 101: "Number of special characters more than limits", 102: "At least 18 alphanumeric characters and list of special chars !@#$&*" }

class localbreak( Exception ) :
    Message = ""
    
    def __init__(self, Message):
        self.Message = Message
        return
    def __str__(self):
        print(self.Message)
        return "False"

### When calling ...
raise localbreak(Error_codes[102])

Output:

Traceback (most recent call last):   File "ASCII.py", line 150, in <module>
    main(OldPassword, Newpassword)   File "ASCII.py", line 39, in main
    result = read_input("1", "2", Newpassword, "4")                                     
    File "ASCII.py", line 69, in read_input
    raise localbreak(Error_codes[102]) At least 18 alphanumeric characters and list of special chars !@#$&*
__main__.localbreak: False