1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
|
Metadata-Version: 2.1
Name: nameparser
Version: 1.1.3
Summary: A simple Python module for parsing human names into their individual components.
Home-page: https://github.com/derek73/python-nameparser
Author: Derek Gulbranson
Author-email: derek73@gmail.com
License: LGPL
Keywords: names,parser
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: License :: OSI Approved :: GNU Library or Lesser General Public License (LGPL)
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 3
Classifier: Development Status :: 5 - Production/Stable
Classifier: Natural Language :: English
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Text Processing :: Linguistic
Description-Content-Type: text/x-rst
License-File: LICENSE
License-File: AUTHORS
Name Parser
===========
|Build Status| |PyPI| |PyPI version| |Documentation|
A simple Python (3.2+ & 2.6+) module for parsing human names into their
individual components.
* hn.title
* hn.first
* hn.middle
* hn.last
* hn.suffix
* hn.nickname
* hn.surnames *(middle + last)*
* hn.initials *(first initial of each name part)*
Supported Name Structures
~~~~~~~~~~~~~~~~~~~~~~~~~
The supported name structure is generally "Title First Middle Last Suffix", where all pieces
are optional. Comma-separated format like "Last, First" is also supported.
1. Title Firstname "Nickname" Middle Middle Lastname Suffix
2. Lastname [Suffix], Title Firstname (Nickname) Middle Middle[,] Suffix [, Suffix]
3. Title Firstname M Lastname [Suffix], Suffix [Suffix] [, Suffix]
Instantiating the `HumanName` class with a string splits on commas and then spaces,
classifying name parts based on placement in the string and matches against known name
pieces like titles and suffixes.
It correctly handles some common conjunctions and special prefixes to last names
like "del". Titles and conjunctions can be chained together to handle complex
titles like "Asst Secretary of State". It can also try to correct capitalization
of names that are all upper- or lowercase names.
It attempts the best guess that can be made with a simple, rule-based approach.
Its main use case is English and it is not likely to be useful for languages
that do not conform to the supported name structure. It's not perfect, but it
gets you pretty far.
Installation
------------
::
pip install nameparser
If you want to try out the latest code from GitHub you can
install with pip using the command below.
``pip install -e git+git://github.com/derek73/python-nameparser.git#egg=nameparser``
If you need to handle lists of names, check out
`namesparser <https://github.com/gwu-libraries/namesparser>`_, a
compliment to this module that handles multiple names in a string.
Quick Start Example
-------------------
::
>>> from nameparser import HumanName
>>> name = HumanName("Dr. Juan Q. Xavier de la Vega III (Doc Vega)")
>>> name
<HumanName : [
title: 'Dr.'
first: 'Juan'
middle: 'Q. Xavier'
last: 'de la Vega'
suffix: 'III'
nickname: 'Doc Vega'
]>
>>> name.last
'de la Vega'
>>> name.as_dict()
{'last': 'de la Vega', 'suffix': 'III', 'title': 'Dr.', 'middle': 'Q. Xavier', 'nickname': 'Doc Vega', 'first': 'Juan'}
>>> str(name)
'Dr. Juan Q. Xavier de la Vega III (Doc Vega)'
>>> name.string_format = "{first} {last}"
>>> str(name)
'Juan de la Vega'
The parser does not attempt to correct mistakes in the input. It mostly just splits on white
space and puts things in buckets based on their position in the string. This also means
the difference between 'title' and 'suffix' is positional, not semantic. "Dr" is a title
when it comes before the name and a suffix when it comes after. ("Pre-nominal"
and "post-nominal" would probably be better names.)
::
>>> name = HumanName("1 & 2, 3 4 5, Mr.")
>>> name
<HumanName : [
title: ''
first: '3'
middle: '4 5'
last: '1 & 2'
suffix: 'Mr.'
nickname: ''
]>
Customization
-------------
Your project may need some adjustment for your dataset. You can
do this in your own pre- or post-processing, by `customizing the configured pre-defined
sets`_ of titles, prefixes, etc., or by subclassing the `HumanName` class. See the
`full documentation`_ for more information.
`Full documentation`_
~~~~~~~~~~~~~~~~~~~~~
.. _customizing the configured pre-defined sets: http://nameparser.readthedocs.org/en/latest/customize.html
.. _Full documentation: http://nameparser.readthedocs.org/en/latest/
Contributing
------------
If you come across name piece that you think should be in the default config, you're
probably right. `Start a New Issue`_ and we can get them added.
Please let me know if there are ways this library could be structured to make
it easier for you to use in your projects. Read CONTRIBUTING.md_ for more info
on running the tests and contributing to the project.
**GitHub Project**
https://github.com/derek73/python-nameparser
.. _CONTRIBUTING.md: https://github.com/derek73/python-nameparser/tree/master/CONTRIBUTING.md
.. _Start a New Issue: https://github.com/derek73/python-nameparser/issues
.. _click here to propose changes to the titles: https://github.com/derek73/python-nameparser/edit/master/nameparser/config/titles.py
.. |Build Status| image:: https://github.com/derek73/python-nameparser/actions/workflows/python-package.yml/badge.svg
:target: https://github.com/derek73/python-nameparser/actions/workflows/python-package.yml
.. |PyPI| image:: https://img.shields.io/pypi/v/nameparser.svg
:target: https://pypi.org/project/nameparser/
.. |Documentation| image:: https://readthedocs.org/projects/nameparser/badge/?version=latest
:target: http://nameparser.readthedocs.io/en/latest/?badge=latest
.. |PyPI version| image:: https://img.shields.io/pypi/pyversions/nameparser.svg
:target: https://pypi.org/project/nameparser/
|
