Add AGENTS.md, update docs and tooling for Python 3.10+ drop of legacy support

- Add AGENTS.md (AI assistant guidance with architecture overview)
- Update .gitignore with venv, AI tool dirs (.claude, .codex, .gemini), and editor files
- Update CONTRIBUTING.md: remove Travis CI / Python 2.6 references, reflect GitHub Actions and Python 3.10-3.13
- Update README.rst and docs/usage.rst: drop Python 2.6/3.2 version references

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: derek73

.gitignore

@@ -12,6 +12,19 @@ dist
 .idea
 Pipfile
 Pipfile.lock
+.tm_properties
+
+# virtual environments
+.env/
+.venv/
+venv/
+env/
+
+# tools
+.claude/
+.codex/
+.gemini/
+.pytest_cache/
 
 # docs
 docs/_*

AGENTS.md

@@ -0,0 +1,70 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+```bash
+# Install dev dependencies
+pip install -r dev-requirements.txt
+
+# Run all tests
+python tests.py
+
+# Run a single test by class/method
+python -m unittest tests.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"
+
+# Build docs
+sphinx-build -b html docs dist/docs
+
+# Build package for release
+python setup.py sdist bdist_wheel
+twine upload dist/*
+```
+
+Enable debug logging to see the parser's internal decisions:
+
+```python
+import logging
+logging.getLogger('HumanName').setLevel(logging.DEBUG)
+```
+
+## Architecture
+
+The library has two layers: `nameparser/config/` (data) and `nameparser/parser.py` (logic).
+
+### Configuration layer (`nameparser/config/`)
+
+Each module defines a plain Python set of known name pieces:
+
+- `titles.py` — `TITLES` (prenominals) and `FIRST_NAME_TITLES` (e.g. "Sir", which treat the following name as first, not last)
+- `suffixes.py` — `SUFFIX_ACRONYMS` (with periods, e.g. "M.D.") and `SUFFIX_NOT_ACRONYMS` (e.g. "Jr.")
+- `prefixes.py` — `PREFIXES` (lastname particles, e.g. "de", "van")
+- `conjunctions.py` — `CONJUNCTIONS` (e.g. "and", "of") used to chain multi-word titles
+- `capitalization.py` — `CAPITALIZATION_EXCEPTIONS` mapping (e.g. `{'phd': 'Ph.D.'}`)
+- `regexes.py` — compiled regular expressions wrapped in a `TupleManager`
+
+`config/__init__.py` wraps everything into `SetManager` and `TupleManager` instances inside a `Constants` class. A module-level singleton `CONSTANTS` is shared across all `HumanName` instances by default.
+
+**Two-tier config pattern**: `CONSTANTS` is global; passing `None` as the second arg to `HumanName` creates a fresh per-instance `Constants()`. After modifying per-instance config you must call `hn.parse_full_name()` again. `SetManager.add()`/`remove()` normalizes inputs to lowercase with no periods, so callers don't need to worry about case.
+
+### Parser (`nameparser/parser.py`)
+
+`HumanName` is the single public class. Assigning to `full_name` (or instantiating with a string) triggers `parse_full_name()`.
+
+Parse flow:
+1. `pre_process()` — strips nicknames (parenthesis/quotes) and emoji, fixes "Ph.D." variant spellings
+2. Split on commas → 1 part (no comma), 2 parts (suffix-comma or lastname-comma), 3+ parts
+3. `parse_pieces()` — splits on spaces, detects dotted abbreviations like "Lt.Gov." and adds them to constants dynamically
+4. `join_on_conjunctions()` — merges pieces adjacent to conjunctions into single tokens (e.g. `['Secretary', 'of', 'State']` → `['Secretary of State']`); also joins prefix particles to the following lastname token
+5. Iterates pieces, assigning to `title_list`, `first_list`, `middle_list`, `last_list`, `suffix_list`
+6. `post_process()` — `handle_firstnames()` swaps first/last when only a title + one name; `handle_capitalization()` applies optional auto-cap
+
+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`)
+
+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`.

CONTRIBUTING.md

@@ -4,35 +4,16 @@ Contributing
 Development Environment Setup
 --------------------------------
 
-There are some external dependencies required in order to run the
-tests, located in the dev-requirements.txt file.
+Install dev dependencies:
 
     pip install -r dev-requirements.txt
 
-If you are running Python 2.6 you will also need to `pip install unitest2`
-in order to run the tests.
-
-Travis CI
----------
-
-[![Build Status](https://travis-ci.org/derek73/python-nameparser.svg?branch=master)](https://travis-ci.org/derek73/python-nameparser)
-
-The GitHub project is set up with Travis CI. Tests are run
-automatically against new code pushes to any branch in the main
-repository. Test results may be viewed here:
-
-https://travis-ci.org/derek73/python-nameparser
-
 Running Tests
 ---------------
 
-To run the tests locally, run `python tests.py`.
-
-
     python tests.py
 
-
-You can also pass a name string to `tests.py` to see how it will be parsed.
+You can also pass a name string to `tests.py` to see how it will be parsed:
 
     $ python tests.py "Secretary of State Hillary Rodham-Clinton"
     <HumanName : [
@@ -43,32 +24,19 @@ You can also pass a name string to `tests.py` to see how it will be parsed.
     	Suffix: ''
     ]>
 
+CI runs tests against Python 3.10–3.13 via GitHub Actions on every push and pull request.
 
 Writing Tests
 ----------------
 
-If you make changes, please make sure you include tests with example
-names that you want to be parsed correctly.
-
-It's a good idea to include tests of alternate comma placement formats
-of the name to ensure that the 3 code paths for the 3 formats work in
-the same way.
+If you make changes, please include tests with example names that should parse correctly.
 
-The tests could be MUCH better. If the spirit moves you to design or
-implement a much more intelligent test strategy, please know that your
-efforts will be welcome and appreciated.
-
-Unless you add better coverage someplace else, add a few examples of
-your names to `TEST_NAMES`. A test attempts to try the 3 different
-comma variations of these names automatically and make sure things
-don't blow up, so it can be a helpful regression indicator.
+It's a good idea to include tests of alternate comma placement formats of the name to ensure that the 3 code paths for the 3 formats work in the same way.
 
+Unless you add better coverage someplace else, add a few examples of your names to `TEST_NAMES`. A test attempts to try the 3 different comma variations of these names automatically and make sure things don't blow up, so it can be a helpful regression indicator.
 
 New Releases
 ------------
 
-[Publishing to Pypi Guide](https://hynek.me/articles/sharing-your-labor-of-love-pypi-quick-and-dirty/)
-
     $ python setup.py sdist bdist_wheel
     $ twine upload dist/*
-

README.rst

@@ -3,7 +3,7 @@ Name Parser
 
 |Build Status| |PyPI| |PyPI version| |Documentation|
 
-A simple Python (3.2+ & 2.6+) module for parsing human names into their
+A simple Python (3.10+) module for parsing human names into their
 individual components. 
 
 * hn.title

docs/usage.rst

@@ -4,7 +4,7 @@ Using the HumanName Parser
 Example Usage
 -------------
 
-The examples use Python 3, but Python 2.6+ is supported.
+Requires Python 3.10+.
 
 .. doctest::
     :options: +NORMALIZE_WHITESPACE