René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Remove __eq__ and __hash__ in 2.0; compare names via explicit methods","articleBody":"## Summary\n\n2.0 will remove `HumanName.__eq__` and `HumanName.__hash__`. Instances revert to Python's default identity semantics (still safely usable in sets/dicts — see below). Value comparison moves to two explicit methods, shipped in 1.3.0 so the APIs overlap for a full minor release: `matches()` and `comparison_key()` (added in PR #247).\n\nFeedback welcome — this is a breaking change and the rationale is laid out in full below. The deprecation warnings shipped in 1.3.0 (#224, implemented in PR #247; released).\n\n## Why the current design can't be fixed in place\n\n`__eq__` currently compares `str(self).lower()` against `str(other).lower()`, and `__hash__` (added in 1.2.0, #138) hashes that string. This makes three promises:\n\n1. **Case-insensitive** equality\n2. **Cross-type** equality with plain strings (`hn == \"John Smith\"` → True)\n3. **Hashability** (usable in sets/dicts)\n\nThese are mathematically incompatible. If `hn == \"John Smith\"` and `hn == \"john smith\"` are both True, the hash invariant (`a == b` ⇒ `hash(a) == hash(b)`) requires `hash(hn)` to equal two different values. Consequence today: `{hn} | {\"John Smith\"}` is a two-element set whose elements compare equal — broken dedup, the very use case #138 added hashing for. No implementation can fix this; one of the three promises has to go.\n\n## Additional defects in the current design\n\n- **Mutation strands container entries.** `HumanName` is mutable; assigning any attribute changes the hash, so an instance already in a set/dict becomes unfindable. (Python nulls `__hash__` when a class defines `__eq__` for exactly this reason — #138 re-enabled what the language had disabled.)\n- **Equality depends on display config.** `str(self)` goes through `string_format`, so changing `CONSTANTS.string_format` retroactively changes whether two existing objects are equal. Same class of shared-mutable-state problem as #222.\n- **`maiden` is invisible to equality** — the default `string_format` has no `{maiden}` placeholder.\n- **`hn == 42` can be True** (if the name is \"42\"); `__eq__` stringifies any operand instead of returning `NotImplemented`.\n\n## Why removal rather than component-based `__eq__`/`__hash__`\n\nA component-based `==` was considered and is workable, but it still privileges one equality semantic for a domain that has none (is \"J. Smith\" equal to \"John Smith\"? \"Smith, John\"? every application answers differently), and still carries the mutate-while-hashed caveat. Removing both dunders is the only option with no footguns left: default identity hash is always stable and always consistent with identity equality, so sets/dicts of HumanName keep working — they just mean \"these objects\" rather than \"these name values\". Value semantics become explicit:\n\n- `hn.matches(other)` — parses a string operand, compares parsed components\n- `hn.comparison_key()` — hashable tuple of components, for dedup/dicts/groupby\n\n## Migration (from 1.3.0's deprecated `==`)\n\n| Before | After |\n|---|---|\n| `hn == x` | `hn.matches(x)` |\n| `\"john smith\" == hn` (reflected) | `hn.matches(\"john smith\")` — must flip operands |\n| `hn == maybe_none` | `maybe_none is not None and hn.matches(maybe_none)` — `matches()` raises `TypeError` on non-`str`/`HumanName` |\n| `hn in names`, `.index()`, `assertIn` | `any(hn.matches(n) for n in names)` or `comparison_key()` sets |\n| set/dict dedup via `hash(hn)` | `{n.comparison_key(): n for n in names}.values()` |\n\nUsers with a lossy custom `string_format` (e.g. `\"{first} {last}\"`) currently get projection equality; `matches()` compares all components and is stricter. Compare the specific attributes instead.\n\n## Checklist\n\n- [ ] Remove `__eq__` and `__hash__` from `HumanName`\n- [ ] Replace equality/hash tests with identity-semantics tests\n- [ ] Update the `docs/usage.rst` deprecation note (the equality example already uses `matches()` as of 1.3.0)\n- [ ] Migration section in docs + release log entry\n\n\n","author":{"url":"https://github.com/derek73","@type":"Person","name":"derek73"},"datePublished":"2026-07-05T20:56:11.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":0},"url":"https://github.com/223/python-nameparser/issues/223"}