Basic question: What's the most Pythonic/logical way to make my own, custom warning classes? What are the correct warning and exception classes that I should be subclassing?

Motivation: The requirements for the library I'm writing specify that if a MyContainer object c contains an item x and the caller of the library tries to place a "duplicate" of x -- call it y -- into c, a warning is issued to the caller and the return value of c.my_transformation_method(x, y) is placed into c to replace x. In other words, MyContainers will replace elements with their duplicates, but must warn the user when doing so.

Based on my reading, the most flexible way to warn the caller of a library about a nonfatal action is with the warnings standard module. It allows the caller to handle the warning as it sees fit, doing anything from ignoring warnings to treating them as errors. (Note that I'm using Python 3, but I don't think that's essential to the question here.)

Example: What I've done is defined the following warning subclass:

class DuplicateItemWarning(UserWarning, ValueError):
    pass

Then the add() method of MyContainer calls warnings.warn('detected duplicate', DuplicateItemWarning) when it detects an attempt to insert a duplicate item.

Specific questions:

  1. Should I be subclassing UserWarning as above, or just sublcassing Warning?

  2. It seems semantically sensible to subclass ValueError (which, in the above example, merely inserts ValueError in the MRO between Warning and Ex

Edit
Report