dirty-equals

When comparing datetime objects using IsDatetime, you can control how timezone awareness and offsets are handled using the enforce_tz parameter.

enforce_tz=True (Default)

Strict matching of timezone status and offsets:

• If the reference datetime is naive, the compared value must also be naive.
• If the reference datetime is aware, the compared value must be aware and have the same offset.

enforce_tz=False

More flexible matching:

• If the reference datetime is naive, the compared value can be either naive or aware, as long as the datetime values match.
• If the reference datetime is aware, the compared value must represent the same point in time (it must be aware).

from datetime import datetime
from zoneinfo import ZoneInfo
from dirty_equals import IsDatetime

tz_london = ZoneInfo('Europe/London')
new_year_london = datetime(2000, 1, 1, tzinfo=tz_london)

tz_nyc = ZoneInfo('America/New_York')
new_year_eve_nyc = datetime(1999, 12, 31, 19, 0, 0, tzinfo=tz_nyc)

# Matches because they represent the same point in time, despite different offsets
assert new_year_eve_nyc == IsDatetime(approx=new_year_london, enforce_tz=False)

# Fails because offsets do not match
assert new_year_eve_nyc != IsDatetime(approx=new_year_london, enforce_tz=True)

new_year_naive = datetime(2000, 1, 1)

# Fails because naive vs aware comparison with enforce_tz=False requires value match
assert new_year_naive != IsDatetime(approx=new_year_london, enforce_tz=False)

# Matches because values match and enforce_tz=False allows naive/aware mix for naive references
assert new_year_london == IsDatetime(approx=new_year_naive, enforce_tz=False)

The __repr__ method of dirty-equals types is designed to provide clean, readable diffs in pytest when assertions fail.

Standard Behavior

By default, repr() returns a string describing the type, similar to how it was created:

• repr(IsInt) -> 'IsInt'
• repr(IsInt()) -> 'IsInt()'
• repr(IsApprox(42)) -> 'IsApprox(approx=42)'

Comparison Behavior (The 'Black Magic')

When a dirty-equals type is used in an equality (==) operation and the comparison returns True, the __repr__ of the type changes to return the repr() of the actual value being compared.

This ensures that when pytest compares two large dictionaries and finds them equal, the diff doesn't show the dirty-equals type names, but rather the actual values, making the output much easier to read.

Important: To get the cleanest pytest output, always use initialised types (e.g., IsPositiveInt() instead of IsPositiveInt).

from dirty_equals import IsInt

v = IsInt()
assert 42 == v
assert repr(v) == '42'

You can define custom matching logic by creating a class that inherits from DirtyEquals. This is more robust than implementing a standard __eq__ method because:

1. Error Handling: TypeError and ValueError raised within the equals method are caught and treated as a False (not-equals) result instead of crashing.
2. Representation: A useful __repr__ is automatically generated. If the equality check returns True, the representation is modified for better debugging.
3. Boolean Logic: Support for boolean operators (like | for OR) works out of the box.
4. Uninitialised Usage: You can use the class itself (e.g., IsEven) in comparisons rather than needing to instantiate it (e.g., IsEven()).

To implement a custom type, inherit from DirtyEquals[T] (where T is the type of the value you are comparing against) and implement the equals(self, other: Any) -> bool method.

from decimal import Decimal
from typing import Any, Union

from dirty_equals import DirtyEquals, IsOneOf


class IsEven(DirtyEquals[Union[int, float, Decimal]]):
    def equals(self, other: Any) -> bool:
        return other % 2 == 0


assert 2 == IsEven
assert 3 != IsEven
assert 'foobar' != IsEven
assert 3 == IsEven | IsOneOf(3)

The dirty-equals library allows you to perform declarative assertions by using special objects that override the __eq__ method. Instead of checking exact values, you can check for properties like being a positive integer, matching a regex, or being close to the current time. This is particularly useful when testing API responses or database records where some fields (like IDs, timestamps, or generated strings) are non-deterministic.

from dirty_equals import IsJson, IsNow, IsPositiveInt, IsStr

def test_user_endpoint(client: 'HttpClient', db_conn: 'Database'):
    client.post('/users/create/', data=...)

    user_data = db_conn.fetchrow('select * from users')
    assert user_data == {
        'id': IsPositiveInt,  # Checks if id is a positive integer
        'username': 'samuelcolvin',  # Standard equality check
        'avatar_file': IsStr(regex=r'/[a-z0-9\-]{10}/example\.png'),  # Matches a regex pattern
        'settings_json': IsJson({'theme': 'dark', 'language': 'en'}),  # Validates JSON content against a dict
        'created_ts': IsNow(delta=3),  # Checks if datetime is within 3 seconds of now
    }

You can use dirty-equals to validate complex dictionaries by replacing specific values with constraint objects. This allows you to verify the structure and certain properties of a dictionary without needing to know the exact values of every field.

Commonly used constraints include:

• IsPositiveInt: Validates that a value is a positive integer.
• IsStr(regex=...): Validates that a string matches a specific regular expression.
• IsJson(dict): Validates that a value is a JSON string that, when decoded, matches the provided dictionary.
• IsNow(delta=...): Validates that a datetime is close to the current time within a certain number of seconds.

from dirty_equals import IsJson, IsNow, IsPositiveInt, IsStr

# user_data is a dict returned from a database or API which we want to test
assert user_data == {
    # we want to check that id is a positive int
    'id': IsPositiveInt,
    # we know avatar_file should be a string, but we need a regex as we don't know whole value
    'avatar_file': IsStr(regex=r'/[a-z0-9\-]{10}/example\.png'),
    # settings_json is JSON, but it's more robust to compare the value it encodes, not strings
    'settings_json': IsJson({'theme': 'dark', 'language': 'en'}),
    # created_ts is datetime, we don't know the exact value, but we know it should be close to now
    'created_ts': IsNow(delta=3),
}