Utility Classes :: IsOneOf

Overview

The IsOneOf class is used to specify that the object must be an instance of any number of types or user-defined classes, or be validated by other extension classes [1].

The IsOneOf() constructor must be passed at least two ([2]) distinct ([3]) types, user-defined classes or registered extension classes. For example:

IsOneOf(int, FooClass, IsAllof(ClassA, ClassB))

Where FooClass is either a old- or new-style class, and IsAllOf is the IsAllOf() utility class.

The requirement that there are two distinct conditions stems from the fact that the following call is almost certainly an error:

IsOneOf(int, int)

Details

• If the object being checked by the IsOneOf instance does not match any of the provided conditions, a _TC_TypeError will be raised; the right attribute will be the IsOneOf instance, and the wrong attribute will be the type of the object. [4]

  This exception is to be caught and converted to a TypeCheckError before it reaches the level of the user.

• IsOneOf objects will only compare equal (i.e., ==) if all the conditions in the left-hand side are found in the right-hand side, and vice versa [5].

  All IsOneOf instances that compare equal with == will produce the same value when run through the built-in hash() function [6].

• The IsOneOf class has been given some intelligence about boolean equality, meaning that it will optimise the creation of certain instances. For instance:

  IsOneOf(IsOneOf(int, float), IsOneOf(str, set))

  is equivalent to

  IsOneOf(int, float, str, set)

  In fact, the first will be coerced into the second, meaning that the two will compare and hash as equals [5, 6].

• Another coercion-related intelligence is this:

  IsOneOf(int, int, float, float)

  will be simplified to

  IsOneOf(int, float)

  Again, these two will compare and hash as equals [5, 6].

• The order in which the IsOneOf instance's conditions will be checked is undefined.

References

1. test_utility_classes.py: Test_Or.test_success
2. test_utility_classes.py: Test_Or.test_constructor
3. test_utility_classes.py: Test_Or.test_distinct_parameters
4. test_utility_classes.py: Test_Or.test_failure
5. test_utility_classes.py: Test_Or.test_equality
6. test_utility_classes.py: Test_Or.test_hash