Merge pull request #165 from derek73/test-reorg-pytest

Reorganize tests into a pytest package (and fix bugs it exposed)

Author: derek73

.github/workflows/python-package.yml

@@ -40,7 +40,7 @@ jobs:
       run: mypy
     - name: Run Tests
       run: |
-        python tests.py
+        pytest
         python -m build --sdist
         twine check dist/*
         sphinx-build -b html docs dist/docs

AGENTS.md

@@ -9,13 +9,14 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 pip install --group dev
 
 # Run all tests
-python tests.py
+pytest
 
-# Run a single test by class/method
-python -m unittest tests.HumanNamePythonTests.test_utf8
+# Run a single test file / class / method
+pytest tests/test_python_api.py
+pytest tests/test_python_api.py::HumanNamePythonTests::test_utf8
 
 # Debug how a specific name string is parsed (prints HumanName repr)
-python tests.py "Dr. Juan Q. Xavier de la Vega III"
+python -m nameparser "Dr. Juan Q. Xavier de la Vega III"
 
 # Build docs
 sphinx-build -b html docs dist/docs
@@ -65,6 +66,6 @@ Parse flow:
 
 Each named attribute (`title`, `first`, etc.) is a `@property` that joins its corresponding `_list`. Setters call `_set_list()` which runs the value through `parse_pieces()`, so assigning `hn.last = "de la Vega"` correctly re-parses prefix tokens.
 
-### Tests (`tests.py`)
+### Tests (`tests/`)
 
-All tests live in a single file. `HumanNameTestBase.m()` is a custom assert helper that prints the original name string on failure. Many test classes group cases by name format type. `TEST_NAMES` is a list of name strings that gets automatically permuted into comma-separated variants as a regression check. When adding a new parsing case, add it to the relevant test class and consider adding the base form to `TEST_NAMES`.
+Tests run under **pytest** and are split one file per concern (`tests/test_titles.py`, `tests/test_suffixes.py`, etc.). `tests/base.py` holds `HumanNameTestBase` — a plain (non-`unittest`) base whose `m()` helper is a custom assert that prints the original name string on failure (plus thin `assert*` shims so the moved test bodies are unchanged). `tests/conftest.py` defines an autouse fixture that runs **every test twice** — once with `empty_attribute_default = ''` and once with `None` — so reported counts are doubled (e.g. 11 methods → 22 results); it also snapshots/restores the scalar `CONSTANTS` config around each test to keep tests order-independent. `TEST_NAMES` (in `tests/test_variations.py`) is a list of name strings permuted into comma-separated variants as a regression check. Tests that should fail use `@pytest.mark.xfail`. When adding a parsing case, add it to the relevant `tests/test_*.py` file and consider adding the base form to `TEST_NAMES`.

CONTRIBUTING.md

@@ -11,17 +11,23 @@ Install dev dependencies:
 Running Tests
 ---------------
 
-    python tests.py
+    pytest
 
-You can also pass a name string to `tests.py` to see how it will be parsed:
+Run a single test file or test:
 
-    $ python tests.py "Secretary of State Hillary Rodham-Clinton"
+    pytest tests/test_titles.py
+    pytest tests/test_titles.py::TitleTestCase
+
+You can also pass a name string to see how it will be parsed:
+
+    $ python -m nameparser "Secretary of State Hillary Rodham-Clinton"
     <HumanName : [
-    	Title: 'Secretary of State' 
-    	First: 'Hillary' 
-    	Middle: '' 
-    	Last: 'Rodham-Clinton' 
-    	Suffix: ''
+    	title: 'Secretary of State'
+    	first: 'Hillary'
+    	middle: ''
+    	last: 'Rodham-Clinton'
+    	suffix: ''
+    	nickname: ''
     ]>
 
 CI runs tests against Python 3.10–3.14 via GitHub Actions on every push and pull request.

MANIFEST.in

@@ -1,4 +1,4 @@
 include AUTHORS
 include LICENSE
 include README.rst
-include tests.py
+recursive-include tests *.py

docs/release_log.rst

@@ -1,5 +1,9 @@
 Release Log
 ===========
+* Unreleased
+    - Fix ``initials()`` interpolating the literal ``None`` for empty name parts when ``empty_attribute_default = None`` (e.g. ``"J. None D."``); empty parts now render as an empty string and a fully-empty result returns ``empty_attribute_default``
+    - Add ``python -m nameparser "Name String"`` command-line helper that prints a parsed name
+    - Reorganize the test suite from a single ``tests.py`` into a ``tests/`` pytest package
 * 1.2.0 - June 11, 2026
     - Drop Python 2 and Python < 3.10 support; Python 3.10–3.14 now required
     - Add type hints and type declarations (PEP 561 ``py.typed`` marker)

docs/usage.rst

@@ -191,8 +191,9 @@ Three attributes exist for the format, `first`, `middle` and `last`.
   >>> CONSTANTS.initials_format = "{first} {middle}"
   >>> HumanName("Doe, John A. Kenneth, Jr.").initials()
   'J. A. K.'
-  >>> HumanName("Doe, John A. Kenneth, Jr.", initials_format="{last}, {first}).initials()
+  >>> HumanName("Doe, John A. Kenneth, Jr.", initials_format="{last}, {first}").initials()
   'D., J.'
+  >>> CONSTANTS.initials_format = "{first} {middle} {last}"
 
 
 Furthermore, the delimiter for the string output can be set through:
@@ -201,16 +202,15 @@ Furthermore, the delimiter for the string output can be set through:
 .. doctest:: initials delimiter
 
   >>> HumanName("Doe, John A. Kenneth, Jr.", initials_delimiter=";").initials()
-  "J; A; K;"
-  >>> from nameparser.config import CONSTANTS
-  >>> CONSTANTS.initials_delimiter = "."
-  >>> HumanName("Doe, John A. Kenneth, Jr.", initials_format="{first}{middle}{last}).initials()
-  "J.A.K.D."
+  'J; A; K; D;'
+  >>> HumanName("Doe, John A. Kenneth, Jr.", initials_format="{first}{middle}{last}", initials_delimiter=".").initials()
+  'J.A. K.D.'
 
 To get a list representation of the initials, use :py:meth:`~nameparser.HumanName.initials_list`.
 This function is unaffected by :py:attr:`~nameparser.config.Constants.initials_format`
 
 .. doctest:: list format
+
   >>> HumanName("Doe, John A. Kenneth, Jr.", initials_delimiter=";").initials_list()
-  ["J", "A", "K", "D"]
+  ['J', 'A', 'K', 'D']
 

nameparser/__main__.py

@@ -0,0 +1,31 @@
+"""Command-line debug helper: parse a name and print the result.
+
+Usage:
+
+    python -m nameparser "Dr. Juan Q. Xavier de la Vega III"
+"""
+import logging
+import sys
+
+from nameparser import HumanName
+
+
+def main() -> None:
+    if len(sys.argv) <= 1:
+        print('Usage: python -m nameparser "Name String"')
+        raise SystemExit(1)
+    log = logging.getLogger('HumanName')
+    log.setLevel(logging.ERROR)
+    log.addHandler(logging.StreamHandler())
+    name_string = sys.argv[1]
+    hn = HumanName(name_string)
+    print(repr(hn))
+    hn.capitalize()
+    print(repr(hn))
+    # Use comma rather than concatenation: initials() returns
+    # empty_attribute_default (possibly None) when there are no initials.
+    print("Initials:", hn.initials())
+
+
+if __name__ == '__main__':
+    main()

nameparser/parser.py

@@ -273,17 +273,21 @@ def initials(self) -> str:
         middle_initials_list = [self.__process_initial__(name) for name in self.middle_list if name]
         last_initials_list = [self.__process_initial__(name) for name in self.last_list if name]
 
+        # Empty parts must render as '' (not empty_attribute_default, which may be
+        # None) so str.format does not interpolate the literal "None" into the
+        # output. A fully-empty result falls back to empty_attribute_default,
+        # matching the other attribute accessors (e.g. ``first``).
         initials_dict = {
             "first":  (self.initials_delimiter + " ").join(first_initials_list) + self.initials_delimiter
-            if len(first_initials_list) else self.C.empty_attribute_default,
+            if len(first_initials_list) else "",
             "middle": (self.initials_delimiter + " ").join(middle_initials_list) + self.initials_delimiter
-            if len(middle_initials_list) else self.C.empty_attribute_default,
+            if len(middle_initials_list) else "",
             "last": (self.initials_delimiter + " ").join(last_initials_list) + self.initials_delimiter
-            if len(last_initials_list) else self.C.empty_attribute_default
+            if len(last_initials_list) else ""
         }
 
         _s = self.initials_format.format(**initials_dict)
-        return self.collapse_whitespace(_s)
+        return self.collapse_whitespace(_s) or self.C.empty_attribute_default
 
     @property
     def has_own_config(self) -> bool:

pyproject.toml

@@ -39,6 +39,7 @@ nameparser = ["py.typed"]
 
 [dependency-groups]
 dev = [
+  "pytest (>=8)",
   "dill (>=0.2.5)",
   "sphinx (>=8)",
   "mypy (>=2.1)",
@@ -54,6 +55,13 @@ module = [
 ]
 ignore_missing_imports = true
 
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_classes = ["*Tests", "*TestCase"]
+# Fail if an xfail-marked test unexpectedly passes, so a fixed/regressed
+# expectation surfaces instead of silently turning into an xpass.
+xfail_strict = true
+
 [tool.ruff.lint]
 extend-select = [
   "ANN",   # flake8-annotations