René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"SetManager inherits an API surface it doesn't want; decide its real interface","articleBody":"## Summary\n\n`SetManager` subclasses `collections.abc.Set`, and most of its sharp edges trace back to that choice. 1.3.0 made the inherited surface *safe* (#238, PR #240); 2.0 should decide whether it should *exist*.\n\n**Status after the 1.3.0 release:** the parts common to both options already shipped as deprecations — `__call__` and missing-member `remove()` emit `DeprecationWarning`, and `discard()` exists as the ignore-missing replacement (#253). The remaining decision here is only the option-A-vs-B question (the operator surface and the `Set` ABC), plus executing the removals.\n\n## Symptoms, all one root cause\n\n1. **Wrong ABC.** `collections.abc.Set` is the *immutable* set interface, yet the class exposes `add()`/`remove()`/`clear()`. The honest ABC for the current behavior is `MutableSet` — but see below for whether we want the ABC at all.\n2. **`remove()` has `discard()` semantics.** It silently ignores missing members, the opposite of what `set.remove` promises. `CONSTANTS.titles.remove('typo-entry')` reports nothing. *(1.3.0: now emits `DeprecationWarning`; `discard()` added.)*\n3. **`__call__` is an escape hatch.** `CONSTANTS.titles()` returns the raw underlying `set`, allowing mutation that bypasses both normalization and the `_on_change` cache-invalidation hook that `Constants` relies on. *(1.3.0: now emits `DeprecationWarning`.)*\n4. **The operator surface exists only by inheritance.** The `Set` mixins inject `|`/`\u0026`/`-`/`^` operators that accept arbitrary iterables and construct results outside the class's normalization invariant. Making them safe took six guarded, operand-normalizing overrides with ~10 `type: ignore` comments (PR #240) — when you fight both typeshed and the runtime ABC to guard methods you never designed, the supertype is wrong.\n\nRelated: the `__contains__` normalization asymmetry is now tracked separately as #244 (1.3.0); whichever option lands here, membership survives unchanged.\n\n## Options\n\n**A. Stop subclassing `Set`; compose over a plain `set` (recommended).**\nExpose exactly what the config use case needs: `add`, `remove`, `discard`, `clear`, `in`, iteration, `len`. The one internal set-algebra use, the `suffixes_prefixes_titles` union, works on the underlying sets directly.\n\n*Pros:*\n- Smallest honest surface — every method exists on purpose, and all mutation is forced through `add()`/`remove()`, so normalization and the `_on_change` cache-invalidation hook can never be bypassed\n- Deletes the six operator overrides and their ~10 `type: ignore` comments outright; nothing inherited is left to audit when Python's ABC mixins evolve\n- No future symptom 5: the class can't grow new behavior without someone deliberately adding it\n\n*Cons:*\n- `isinstance(x, collections.abc.Set)` stops passing; any downstream duck-typed set algebra on config sets breaks\n- `|`/`\u0026`/`-`/`^` on config sets stop working (mitigation: the operators only became *safe* in 1.3.0, so correct usage in the wild is necessarily rare)\n- Loses the ABC's free set-comparison semantics (`==`, `\u003c=` between managers); a deliberate two-line `__eq__` can be added back if wanted\n\n**B. Commit to the surface properly: switch to `MutableSet`.**\nKeep the normalized operators from PR #240, give `remove()` real `KeyError` semantics (`discard()` already shipped in 1.3.0), drop `__call__` (already deprecated).\n\n*Pros:*\n- Familiar set idioms keep working, including `isinstance` checks\n- `MutableSet`'s in-place mixins are a real fit: `__ior__` routes each element through `add()`, so `titles |= [...]` would normalize and fire `_on_change` for free — the inherited behavior finally *aligns* with the class invariant\n- Least migration for anyone using operators today\n\n*Cons:*\n- Keeps the root cause: a large inherited surface where every current and future mixin must be audited against the normalization invariant — `MutableSet` adds more, not less (`pop`, `__iand__`, `__ixor__`, `__isub__`, each of which mutates and must be verified to fire `_on_change`)\n- The typeshed-vs-runtime annotation friction from PR #240 remains and grows\n- Same breaking changes to `remove()`/`__call__` anyway, so B pays most of A's migration cost while keeping the maintenance tax\n\nOption A is preferred: no parser functionality needs set algebra on config sets, and every symptom above came from surface nobody designed. B's strongest point — `__ior__` normalizing for free — fixes one operator by accident of mixin implementation, which is the same coupling that produced the bugs.\n\n## Breaking changes (hence 2.0)\n\n- `isinstance(x, collections.abc.Set)` checks stop passing (option A)\n- `|`/`\u0026`/`-`/`^` on config sets stop working (option A) or keep 1.3.0 behavior (option B)\n- `remove()` of a missing member raises (`discard()`, shipped in 1.3.0, is the ignore-missing spelling)\n- `CONSTANTS.titles()` call syntax removed — iterate or copy instead\n\n\n","author":{"url":"https://github.com/derek73","@type":"Person","name":"derek73"},"datePublished":"2026-07-06T01:43:24.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":0},"url":"https://github.com/243/python-nameparser/issues/243"}