Skip to content

Sequence Types

IsListOrTuple

IsListOrTuple(
    *items: Any,
    positions: Optional[Dict[int, Any]] = None,
    check_order: bool = True,
    length: "LengthType" = None
)

Bases: DirtyEquals[T]

Check that some object is a list or tuple and optionally its values match some constraints.

IsListOrTuple and its subclasses can be initialised in two ways:

Parameters:

Name Type Description Default
*items Any

Positional members of an object to check. These must start from the zeroth position, but (depending on the value of length) may not include all values of the list/tuple being checked.

()
check_order bool

Whether to enforce the order of the items.

True
length Union[int, Tuple[int, Union[int, Any]]]

length constraints, int or tuple matching the arguments of HasLen.

None

or,

Parameters:

Name Type Description Default
positions Dict[int, Any]

Instead of *items, a dictionary of positions and values to check and be provided.

None
length Union[int, Tuple[int, Union[int, Any]]]

length constraints, int or tuple matching the arguments of HasLen.

None
IsListOrTuple
from dirty_equals import IsListOrTuple, AnyThing

assert [1, 2, 3] == IsListOrTuple(1, 2, 3)
assert (1, 3, 2) == IsListOrTuple(1, 2, 3, check_order=False)
assert [{'a': 1}, {'a': 2}] == (
    IsListOrTuple({'a': 2}, {'a': 1}, check_order=False) #(1)!
)
assert [1, 2, 3, 3] != IsListOrTuple(1, 2, 3, check_order=False) #(2)!

assert [1, 2, 3, 4, 5] == IsListOrTuple(1, 2, 3, length=...) #(3)!
assert [1, 2, 3, 4, 5] != IsListOrTuple(1, 2, 3, length=(8, 10)) #(4)!

assert ['a', 'b', 'c', 'd'] == (
    IsListOrTuple(positions={2: 'c', 3: 'd'}) #(5)!
)
assert ['a', 'b', 'c', 'd'] == (
    IsListOrTuple(positions={2: 'c', 3: 'd'}, length=4) #(6)!
)

assert [1, 2, 3, 4] == IsListOrTuple(3, check_order=False, length=(0, ...)) #(7)!

assert [1, 2, 3] == IsListOrTuple(AnyThing, AnyThing, 3) #(8)!
  1. Unlike using sets for comparison, we can do order-insensitive comparisons on objects that are not hashable.
  2. And we won't get caught out by duplicate values
  3. Here we're just checking the first 3 items, the compared list or tuple can be of any length
  4. Compared list is not long enough
  5. Compare using positions, here no length if enforced
  6. Compare using positions but with a length constraint
  7. Here we're just confirming that the value 3 is in the list
  8. If you don't care about the first few values of a list or tuple, you can use AnyThing in your arguments.

IsList

Bases: IsListOrTuple[List[Any]]

All the same functionality as IsListOrTuple, but the compared value must be a list.

IsList
from dirty_equals import IsList

assert [1, 2, 3] == IsList(1, 2, 3)
assert [1, 2, 3] == IsList(positions={2: 3})
assert [1, 2, 3] == IsList(1, 2, 3, check_order=False)
assert [1, 2, 3, 4] == IsList(1, 2, 3, length=4)
assert [1, 2, 3, 4] == IsList(1, 2, 3, length=(4, 5))
assert [1, 2, 3, 4] == IsList(1, 2, 3, length=...)

assert (1, 2, 3) != IsList(1, 2, 3)

IsTuple

Bases: IsListOrTuple[Tuple[Any, ...]]

All the same functionality as IsListOrTuple, but the compared value must be a tuple.

IsTuple
from dirty_equals import IsTuple

assert (1, 2, 3) == IsTuple(1, 2, 3)
assert (1, 2, 3) == IsTuple(positions={2: 3})
assert (1, 2, 3) == IsTuple(1, 2, 3, check_order=False)
assert (1, 2, 3, 4) == IsTuple(1, 2, 3, length=4)
assert (1, 2, 3, 4) == IsTuple(1, 2, 3, length=(4, 5))
assert (1, 2, 3, 4) == IsTuple(1, 2, 3, length=...)

assert [1, 2, 3] != IsTuple(1, 2, 3)

HasLen

HasLen(
    min_length: int,
    max_length: Union[None, int, Any] = None,
)

Bases: DirtyEquals[Sized]

Check that some has a given length, or length in a given range.

Parameters:

Name Type Description Default
min_length int

Expected length if max_length is not given, else minimum length.

required
max_length Union[None, int, Any]

Expected maximum length, use an ellipsis ... to indicate that there's no maximum.

None
HasLen
from dirty_equals import HasLen

assert [1, 2, 3] == HasLen(3) #(1)!
assert '123' == HasLen(3, ...) #(2)!
assert (1, 2, 3) == HasLen(3, 5) #(3)!
assert (1, 2, 3) == HasLen(0, ...) #(4)!
  1. Length must be 3.
  2. Length must be 3 or higher.
  3. Length must be between 3 and 5 inclusive.
  4. Length is required but can take any value.

Contains

Contains(contained_value: Any, *more_contained_values: Any)

Bases: DirtyEquals[Container[Any]]

Check that an object contains one or more values.

Parameters:

Name Type Description Default
contained_value Any

value that must be contained in the compared object.

required
*more_contained_values Any

more values that must be contained in the compared object.

()
Contains
from dirty_equals import Contains

assert [1, 2, 3] == Contains(1)
assert [1, 2, 3] == Contains(1, 2)
assert (1, 2, 3) == Contains(1)
assert 'abc' == Contains('b')
assert {'a': 1, 'b': 2} == Contains('a')
assert [1, 2, 3] != Contains(10)