René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Drop bytes input in 2.0; require str","articleBody":"## Summary\n\n2.0 should stop accepting `bytes` anywhere and require `str`, making decoding the caller's job. The bytes tolerance is a Python 2 legacy, and — verified below — it is already inconsistent to the point of being half-broken: bytes input currently gets a different behavior depending on which door it walks through.\n\n## Current state (verified)\n\n| Entry point | Behavior with bytes |\n|---|---|\n| `HumanName(b'John Smith')` | works — decoded with the `encoding` kwarg; emits `DeprecationWarning` since 1.3.0 |\n| `hn.first = b'Jane'` / `HumanName(first=b'Jane')` | **crashes** — `_set_list` explicitly accepts bytes, then `parse_pieces` fails deep inside with the confusing inverse error `TypeError: a bytes-like object is required, not 'str'` (`bytes.split(' ')`) |\n| `SetManager.add(b'esq')` | works — decoded, but see the stdin sniffing below; emits `DeprecationWarning` since 1.3.0 |\n| `SetManager(b'esq')` / `SetManager([b'esq'])` | already rejected loudly with a decode hint (1.3.0: #238, PR #240) |\n\nSo the \"feature\" is: two paths that decode, one that crashes confusingly despite an isinstance check that promises support, and one that's already banned. Nobody can be relying on the full surface, because part of it doesn't function.\n\n## Additional defect: environment-dependent decoding\n\n`SetManager.add_with_encoding` resolves the encoding as `encoding or sys.stdin.encoding or DEFAULT_ENCODING`. The encoding of the process's stdin has no relationship to an arbitrary `bytes` argument, so the same call can decode differently depending on how the process was launched (terminal vs. pipe vs. embedded with `sys.stdin = None`). Library behavior should not vary with the runtime environment.\n\n## What's removed in 2.0\n\n- `full_name: str | bytes` and `original: str | bytes` become `str`\n- The `encoding` constructor kwarg and `self.encoding` attribute\n- The bytes branch in `_set_list` and the bytes tolerance in `parse_pieces` (accepting what later crashes)\n- `add_with_encoding()` — `add()` becomes str-only, raising the same decode-hint `TypeError` the constructor already raises; the stdin sniffing goes with it\n\n## Migration\n\nOne line at the boundary: `HumanName(raw.decode('utf-8'))` — the caller knows the real encoding; the library never did. Everything else is the same call with `str`.\n\n## Bridge\n\n- [x] `DeprecationWarning` when bytes reaches `full_name` or `SetManager.add()`, naming the decode-first replacement — shipped in 1.3.0 (#253)\n\n\n- [ ] 1.4: `DeprecationWarning` on every `add_with_encoding()` call regardless of argument type, naming `add()` as the replacement — the str path is silent today, so the method's removal is otherwise unwarned (bytes callers additionally get the existing decode-first warning; two distinct migrations). Tracked in #263.\n","author":{"url":"https://github.com/derek73","@type":"Person","name":"derek73"},"datePublished":"2026-07-06T01:56:33.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":0},"url":"https://github.com/245/python-nameparser/issues/245"}