---
id: dirty-equals
version: "0.11"
license: MIT
license_treatment: permissive
maintenance: active
---

# dirty-equals — Doing dirty (but extremely useful) things with equals.

License: permissive · Maintenance: active · Downloads: 3.0M/mo

## 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 above — 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

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

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 3.0M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

flexible test assertions, declarative equality matching, api response testing, partial dict comparison, unit test helpers, json assertion testing, database result validation, test-assertion, api-testing, declarative

[View on SkillFed](https://skillfed.io/packages/dirty-equals) · [View on PyPI](https://pypi.org/project/dirty-equals/)