René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Add matches() and comparison_key(); deprecate __eq__/__hash__","articleBody":"Bridge work for #223 (removal of `__eq__`/`__hash__` in 2.0). Shipping the replacements in 1.3.0 means there is one release where old and new APIs coexist: downstream code can adopt `matches()` while `==` still works, and libraries supporting both 1.3+ and 2.x need no version sniffing.\n\n## New API (deliberately minimal — the signature is a commitment that survives 2.0)\n\n- `matches(other: str | HumanName) -\u003e bool` — exact, case-insensitive comparison of parsed components. String operands are parsed with `self.C`, so `hn.matches(\"Smith, John\")` and `hn.matches(\"John Smith\")` both match — unlike `==`, which only matches strings that render exactly like `str(hn)`. Raises `TypeError` for other types. Docstring notes: parses on every call — pre-parse or use `comparison_key()` when matching against many rows.\n- `comparison_key() -\u003e tuple[str, ...]` — the seven members (title/first/middle/last/suffix/nickname/maiden), each `\" \".join(...__list).lower()`. Built from the `*_list` attributes, so it is independent of `string_format` and `empty_attribute_default`. Includes `maiden` from day one (new in this release).\n\nNo leniency options (initials matching, nickname equivalence) — that's record linkage territory and out of scope; `matches()` is exact-components by design.\n\n## Deprecation\n\n- `DeprecationWarning` in `__eq__` and `__hash__` naming the replacement\n- Docstring note on where `==` and `matches()` disagree during the overlap: maiden-bearing names vs their own `str()` output, and lossy custom `string_format`s (`matches()` compares all components; that's the fix, not a bug)\n\n## Checklist\n\n- [ ] `matches()` + `comparison_key()` + tests (incl. `TypeError`, comma-form equivalence, case-folding, maiden participation)\n- [ ] Deprecation warnings + tests that they fire\n- [ ] Docs + release log entries referencing #223\n","author":{"url":"https://github.com/derek73","@type":"Person","name":"derek73"},"datePublished":"2026-07-05T20:56:31.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":0},"url":"https://github.com/224/python-nameparser/issues/224"}