dirty-equals

What it is and what it does

dirty-equals is a testing library that overloads Python's `__eq__` method to create reusable matcher objects for assertions. Instead of manually checking individual fields or modifying data before comparison, you write assertions that read like specifications: a field must be a positive integer, match a regex, contain specific JSON, or fall within a time window. This makes test code more declarative and maintainable, especially when validating API responses or database records with many fields.

The library provides matchers for common patterns (type checks, regex matching, partial collections, JSON parsing, timestamp proximity) and supports combining conditions with boolean operators. It has no runtime dependencies, installs cleanly as a pure Python wheel, and is actively maintained with support for Python 3.9 through 3.14.

Use it for:

• Validate API response payloads without hardcoding exact values you don't control (timestamps, IDs, file paths).
• Compare database query results where you only care about certain fields or partial structure matches.
• Write readable assertions for JSON data by comparing the parsed structure rather than string matching.
• Test that response fields are the correct type without brittle exact-value checks.
• Combine multiple validation rules (e.g., 'must be a string AND match this pattern') in a single assertion.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Provides custom equality matchers that make unit test assertions more declarative by allowing flexible comparisons of complex data structures without modifying the values being tested.

Yes. dirty-equals is a low-friction, actively maintained testing utility with no dependencies that directly improves test readability and reduces boilerplate in assertion-heavy codebases. It is especially valuable for API and database testing where exact values are unknown or irrelevant. MIT license and broad Python version support make it safe to adopt.

Install

dirty-equals on PyPI

pip install dirty-equals

uv add dirty-equals

poetry add dirty-equals

Installing dirty-equals

Before you install

Low friction—pure Python wheel with no runtime dependencies. Actively maintained with recent releases and steady community adoption (top 5000 PyPI packages).

License in practice

MIT license permits unrestricted use, modification, and distribution in both open-source and proprietary projects.

Quickstart

pip install dirty-equals

from dirty_equals import IsPositiveInt, IsStr, IsJson

assert user_data == {
    'id': IsPositiveInt,
    'avatar_file': IsStr(regex=r'/[a-z0-9\-]{10}/example\.png'),
    'settings_json': IsJson({'theme': 'dark'}),
}

Requires Python 3.9 or later.

Verify before relying

• Whether performance overhead of custom equality checks is acceptable for large test suites.
• Compatibility with test frameworks beyond pytest (unittest, nose2, etc.).

Package facts

Evidence: dirty_equals-0.11-py3-none-any.whl

Tags

More Python Modules packages