Review follow-ups: class-not-instance hint, stale doc sweep

The likeliest wrong constants argument is the Constants class itself
(forgotten parentheses), which the TypeError reported as an unhelpful
"got type"; special-case classes with a did-you-mean hint, test-driven
with pytest.raises match patterns (also tightened the existing bare
TypeError check, which any TypeError in __init__ would have satisfied).

Sweep prose left stale by this fix: the config module "Potential
Gotcha" docstring had the same only-None phrasing corrected in
customize.rst; the AGENTS.md mypy note attributed most test-suite
errors to the constants=None pattern, an error class the Constants|None
annotation eliminated; and the :param constants: docstring now
documents the TypeError and drops its malformed type spec.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: derek73

AGENTS.md

@@ -160,7 +160,7 @@ Don't use the bare `python3 -m doctest <file>.rst` CLI (no `optionflags`) to che
 
 `Constants` class attributes (e.g. `patronymic_name_order`, `middle_name_as_last`) document behavior with a bare string literal placed right after the assignment — Sphinx's attribute-docstring convention. That string never becomes a real `__doc__`, so `--doctest-modules` (which walks `__doc__` attributes) never sees any `.. doctest::` examples inside it — this let a stale example slip through CI once (`middle_name_as_last`, #133). `tests/test_config_attribute_docstrings.py` (#195) closes that gap: it parses `nameparser/config/__init__.py` with `ast` to recover those literals and runs any doctest examples through `doctest.DocTestParser`/`DocTestRunner` explicitly, so `pytest -q` now exercises them too. When adding or editing a `.. doctest::` example in a `Constants` attribute's bare-string docstring, this is the mechanism that actually runs it — don't assume `--doctest-modules` covers it.
 
-**`uv run mypy nameparser/` intentionally excludes `tests/`** (`pyproject.toml`'s `[tool.mypy] packages = ["nameparser"]`) — if you run mypy against `tests/` too you'll see ~40 pre-existing errors; don't treat them as a regression. Most are tests deliberately passing `constants=None` (a documented runtime pattern the `Constants` type hint doesn't capture) or intentionally wrong-typed inputs verifying the code rejects them.
+**`uv run mypy nameparser/` intentionally excludes `tests/`** (`pyproject.toml`'s `[tool.mypy] packages = ["nameparser"]`) — if you run mypy against `tests/` too you'll see ~30 pre-existing errors; don't treat them as a regression. Most are intentionally wrong-typed inputs verifying the code rejects them, or `Constants` attribute assignments the config type hints don't capture.
 
 **`initials_separator` is intra-group only** — it controls the joiner between consecutive initials *within* a name group (e.g. two middle names in `middle_list`). Spaces *between* groups come from `initials_format`. To fully concatenate initials you need both `initials_separator=""` and `initials_format="{first}{middle}{last}"`.
 

nameparser/config/__init__.py

@@ -21,9 +21,10 @@
     >>> hn.C.titles.add('dean') # doctest: +SKIP
     >>> hn.parse_full_name() # need to run this again after config changes
 
-**Potential Gotcha**: If you do not pass ``None`` as the second argument,
-``hn.C`` will be a reference to the module config, possibly yielding 
-unexpected results. See `Customizing the Parser <customize.html>`_.
+**Potential Gotcha**: If you do not pass ``None`` (or your own
+:py:class:`Constants` instance) as the second argument, ``hn.C`` will be a
+reference to the module config, possibly yielding unexpected results. See
+`Customizing the Parser <customize.html>`_.
 """
 import re
 import sys

nameparser/parser.py

@@ -48,9 +48,10 @@ class HumanName:
     * :py:attr:`given_names`
 
     :param str full_name: The name string to be parsed.
-    :param constants constants:
-        a :py:class:`~nameparser.config.Constants` instance. Pass ``None`` for
-        `per-instance config <customize.html>`_.
+    :param constants:
+        a :py:class:`~nameparser.config.Constants` instance (subclasses are
+        honored). Pass ``None`` for `per-instance config <customize.html>`_.
+        Anything else raises ``TypeError``.
     :param str encoding: string representing the encoding of your input
     :param str string_format: python string formatting
     :param str initials_format: python initials string formatting
@@ -113,9 +114,13 @@ def __init__(
         if constants is None:
             constants = Constants()
         elif not isinstance(constants, Constants):
+            # passing the class itself is the likeliest mistake, and
+            # reporting it as "got type" would only add confusion
+            hint = (" (a class was passed; did you mean Constants()?)"
+                    if isinstance(constants, type) else "")
             raise TypeError(
                 "constants must be a Constants instance or None, "
-                f"got {type(constants).__name__}"
+                f"got {type(constants).__name__}{hint}"
             )
         self.C = constants
 

tests/test_constants.py

@@ -38,9 +38,13 @@ class CustomConstants(Constants):
         self.m(hn.last, "Smith", hn)
 
     def test_constants_invalid_type_raises_typeerror(self) -> None:
-        with pytest.raises(TypeError):
+        with pytest.raises(TypeError, match="constants must be"):
             HumanName("John Doe", constants="not a Constants")  # type: ignore[arg-type]
 
+    def test_constants_class_instead_of_instance_raises_with_hint(self) -> None:
+        with pytest.raises(TypeError, match=r"did you mean Constants\(\)"):
+            HumanName("John Doe", constants=Constants)  # type: ignore[arg-type]
+
     def test_remove_title(self) -> None:
         hn = HumanName("Hon Solo", constants=None)
         start_len = len(hn.C.titles)