Remove empty_attribute_default; empty attributes always return ''

[derek73]

Summary

2.0 removes the empty_attribute_default config option entirely. Empty name attributes always return ''. Once None support goes (see below for why it must), the only legal value left is the default — a dial with one position isn't configuration.

History: why it exists

Added in v0.3.15 (2016, pre-1.0) for #44: a user wanted None instead of '' to store name components as database NULLs. The maintainer's first response was the one-liner that is now the migration path — "you could do it easily too with something like name.title or None" — and "I don't have a strong preference." Making None the universal return broke the formatting tests, so a config option was added as a compromise. The first consequence arrived in the same thread: str() produced 'None John None Doe None (None)', patched in PR #45 with a .replace(str(empty_attribute_default), '') scrub that is still in __str__ today.

What it has cost

• Every -> str annotation on the public API is false when the option is set to None; the attribute was deliberately left untyped in the mypy work (PR Add tests/ to mypy scope; fix real type gaps it surfaces #250) because typing it honestly cascades | None through everything
• The "J. None D." initials bug, fixed in 1.3.0 — same laundering class
• Live data corruption (str() strips literal "None" from real names when empty_attribute_default is None #254): the PR remove default attribute from formatted string (#44) #45 scrub can't distinguish an interpolated None from name text, so in None-mode str(HumanName("Nonez Smith")) returns 'z Smith' — the parse is correct and __str__ strips the literal None out of the person's name

What removal deletes

The or self.C.empty_attribute_default tail on all seven attribute properties plus surnames/given_names/last_base/last_prefixes and initials(); the __str__ scrub hack; the docs section; the test type: ignores.

Removal mechanics (both learned from the 1.3.0 guard work)

• Tombstone, not deletion: empty_attribute_default is a plain attribute, so naive removal makes CONSTANTS.empty_attribute_default = None a silent no-op — the accept-and-ignore failure family Non-descriptor Constants set attributes accept bare-string assignment; substring 'in' silently corrupts parsing #241 exterminated. 2.0 keeps a property whose setter raises with the migration hint.
• Readers exist, not just writers: the Option to get None instead of empty string #44 thread advised asserting against hn.C.empty_attribute_default in downstream tests. Reads break loudly with the tombstone; migration is "compare with '' or truthiness."

Migration

hn.first or None at the database boundary, or {k: v or None for k, v in name.as_dict().items()} for a whole record.

Bridge (1.4) — tracked in #263

• DeprecationWarning on any assignment to empty_attribute_default
• Ship the __str__ mangling fix (str() strips literal "None" from real names when empty_attribute_default is None #254) so None-mode users get correct output during their migration window

[derek73]

Note from the review of #277 (the 1.3.1 fix for #254): the fix changed str() behavior for custom truthy values of empty_attribute_default, an undocumented configuration (only '' and None are documented or tested).

With empty_attribute_default = 'N/A':

• before Fix str() scrubbing literal "None" from names when empty_attribute_default is None #277: str(HumanName('John Smith')) → 'John Smith' — the post-format scrub deleted the placeholder from empty slots, but also corrupted real name text containing it ('N/A Smith' → 'Smith', the same bug class as str() strips literal "None" from real names when empty_attribute_default is None #254)
• after Fix str() scrubbing literal "None" from names when empty_attribute_default is None #277: → 'N/A John N/A Smith N/A (N/A)' — the v or '' substitution only blanks falsy values, so a truthy default now renders literally in formatted output

Decision was to leave this as-is rather than complicate the deprecation-window code, since this option is removed entirely here in 2.0. If anyone reports depending on a truthy default before then, the fix would be to key the __str__ substitution off actual field emptiness (the _list attributes) instead of value falsiness.

🤖 Generated with Claude Code