update docs to python 3, fix links, clarify suffix handling

Author: derek73

docs/customize.rst

@@ -46,7 +46,7 @@ The other is the ``C`` attribute of a ``HumanName`` instance, e.g.
     <Constants() instance>
 
 Both places are usually a reference to the same shared module-level
-:py:class:`~nameparser.config.Constants` instance, depending on how you
+:py:class:`~nameparser.config.CONSTANTS` instance, depending on how you
 instantiate the :py:class:`~nameparser.parser.HumanName` class (see below).
 
 Take a look at the :py:mod:`nameparser.config` documentation to see what's
@@ -82,7 +82,7 @@ constant so that "Hon" can be parsed as a first name.
     ]>
     >>> from nameparser.config import CONSTANTS
     >>> CONSTANTS.titles.remove('hon')
-    SetManager(set([u'msgt', ..., u'adjutant']))
+    SetManager({'right', ..., 'tax'})
     >>> hn = HumanName("Hon Solo")
     >>> hn
     <HumanName : [
@@ -99,7 +99,8 @@ constant so that "Hon" can be parsed as a first name.
 constant. But in some contexts it is more common as a title. If you would
 like "Dean" to be parsed as a title, simply add it to the titles constant.
 
-You can pass multiple strings to both the ``add()`` and ``remove()``
+You can pass multiple strings to both the :py:func:`~nameparser.config.SetManager.add` 
+and :py:func:`~nameparser.config.SetManager.remove`
 methods and each string will be added or removed. Both functions
 automatically normalize the strings for the parser's comparison method by
 making them lower case and removing periods.
@@ -110,7 +111,7 @@ making them lower case and removing periods.
     >>> from nameparser import HumanName
     >>> from nameparser.config import CONSTANTS
     >>> CONSTANTS.titles.add('dean', 'Chemistry')
-    SetManager(set([u'msgt', ..., u'adjutant']))
+    SetManager({'right', ..., 'tax'})
     >>> hn = HumanName("Assoc Dean of Chemistry Robert Johns")
     >>> hn
     <HumanName : [
@@ -137,7 +138,7 @@ the config on one instance could modify the behavior of another instance.
     >>> from nameparser import HumanName
     >>> instance = HumanName("")
     >>> instance.C.titles.add('dean')
-    SetManager(set([u'msgt', ..., u'adjutant']))
+    SetManager({'right', ..., 'tax'})
     >>> other_instance = HumanName("Dean Robert Johns")
     >>> other_instance # Dean parses as title
     <HumanName : [
@@ -164,7 +165,7 @@ reference to the module-level config values with the behavior described above.
     >>> instance.has_own_config
     False
     >>> instance.C.titles.add('dean')
-    SetManager(set([u'msgt', ..., u'adjutant']))
+    SetManager({'right', ..., 'tax'})
     >>> other_instance = HumanName("Dean Robert Johns", None) # <-- pass None for per-instance config
     >>> other_instance
     <HumanName : [
@@ -203,7 +204,7 @@ those changes with ``repr()``.
       nickname: ''
     ]>
     >>> CONSTANTS.titles.add('dean')
-    SetManager(set([u'msgt', ..., u'adjutant']))
+    SetManager({'right', ..., 'tax'})
     >>> hn
     <HumanName : [
       title: ''

docs/usage.rst

@@ -4,6 +4,8 @@ Using the HumanName Parser
 Example Usage
 -------------
 
+The examples use Python 3, but Python 2.6+ is supported.
+
 .. doctest::
     :options: +NORMALIZE_WHITESPACE
 
@@ -43,8 +45,8 @@ Example Usage
         suffix: 'Jr.'
         nickname: ''
     ]>
-    >>> name.suffix = ["custom","values"]
-    >>> name.suffix
+    >>> name.middle = ["custom","values"]
+    >>> name.middle
     'custom values'
     >>> name.full_name = 'Doe-Ray, Jonathan "John" A. Harris'
     >>> name.as_dict()
@@ -63,12 +65,12 @@ Example Usage
     ['Juan', 'Q. Xavier', 'de la Vega']
     >>> name = HumanName('bob v. de la macdole-eisenhower phd')
     >>> name.capitalize()
-    >>> unicode(name)
+    >>> str(name)
     'Bob V. de la MacDole-Eisenhower Ph.D.'
     >>> # Don't touch mixed case names
     >>> name = HumanName('Shirley Maclaine')
     >>> name.capitalize()
-    >>> unicode(name) 
+    >>> str(name) 
     'Shirley Maclaine'
 
 Capitalization Support
@@ -86,7 +88,7 @@ entered in all upper or lower case.
 
     >>> name = HumanName("bob v. de la macdole-eisenhower phd")
     >>> name.capitalize()
-    >>> unicode(name)
+    >>> str(name)
     'Bob V. de la MacDole-Eisenhower Ph.D.'
 
 It will not adjust the case of mixed case names.
@@ -96,7 +98,7 @@ Nickname Handling
 ------------------
 
 The content of parenthesis or double quotes in the name will be
-available from the nickname attribute. (Added in v0.2.9)
+available from the nickname attribute.
 
 .. doctest:: nicknames
     :options: +NORMALIZE_WHITESPACE
@@ -118,7 +120,8 @@ Change the output string with string formatting
 The string representation of a `HumanName` instance is controlled by its `string_format` attribute. The default value, "{title} {first} {middle} {last} {suffix} ({nickname})", includes parenthesis around nicknames. Trailing commas and empty quotes and parenthesis are automatically removed if the name has no nickname pieces.
 
 You can change the default formatting for all `HumanName` instances by setting a new
-`CONSTANTS.string_format` value.
+:py:attr:`~nameparser.config.Constants.string_format` value on the shared
+:py:class:`~nameparser.config.CONSTANTS` configuration instance.
 
 .. doctest:: string format
 

nameparser/config/__init__.py

@@ -133,14 +133,16 @@ class Constants(object):
     :param set titles: 
         :py:attr:`titles` wrapped with :py:class:`SetManager`.
     :param set first_name_titles: 
-        :py:attr:`first_name_titles` wrapped with :py:class:`SetManager`.
-    :param set suffixes: 
-        :py:attr:`suffixes`  wrapped with :py:class:`SetManager`.
+        :py:attr:`~titles.FIRST_NAME_TITLES` wrapped with :py:class:`SetManager`.
+    :param set suffix_acronyms: 
+        :py:attr:`~suffixes.SUFFIX_ACRONYMS`  wrapped with :py:class:`SetManager`.
+    :param set suffix_not_acronyms: 
+        :py:attr:`~suffixes.SUFFIX_NOT_ACRONYMS`  wrapped with :py:class:`SetManager`.
     :param set conjunctions: 
         :py:attr:`conjunctions`  wrapped with :py:class:`SetManager`.
     :type capitalization_exceptions: tuple or dict
     :param capitalization_exceptions: 
-        :py:attr:`capitalization_exceptions` wrapped with :py:class:`TupleManager`.
+        :py:attr:`~capitalization.CAPITALIZATION_EXCEPTIONS` wrapped with :py:class:`TupleManager`.
     :type regexes: tuple or dict
     :param regexes: 
         :py:attr:`regexes`  wrapped with :py:class:`TupleManager`.

nameparser/config/suffixes.py

@@ -15,6 +15,12 @@
     'iv',
     'v',
 ])
+"""
+
+Post-nominal pieces that are not acronyms. The parser does not remove periods
+when matching against these pieces.
+
+"""
 SUFFIX_ACRONYMS = set([
     'ae',
     'afc',
@@ -109,13 +115,14 @@
     'vd',
     'vrd',
 ])
-SUFFIXES = SUFFIX_ACRONYMS | SUFFIX_NOT_ACRONYMS
 """
 
-Pieces that come at the end of the name but are not last names. These potentially
-conflict with initials that might be at the end of the name.
+Post-nominal acronyms. Titles, degrees and other things people stick after their name
+that may or may not have periods between the letters. The parser removes periods 
+when matching against these pieces.
 
-These may be updated in the future because some of them are actually titles that just
-come at the end of the name, so semantically this is wrong. Positionally, it's correct.
-
-"""
+"""
+SUFFIXES = SUFFIX_ACRONYMS | SUFFIX_NOT_ACRONYMS
+"""
+A union of the sets :py:attr:`SUFFIX_ACRONYMS` and :py:attr:`SUFFIX_NOT_ACRONYMS`
+"""

nameparser/parser.py

@@ -156,9 +156,9 @@ def as_dict(self, include_empty=True):
         
             >>> name = HumanName("Bob Dole")
             >>> name.as_dict()
-            {u'last': u'Dole', u'suffix': u'', u'title': u'', u'middle': u'', u'nickname': u'', u'first': u'Bob'}
+            {'last': 'Dole', 'suffix': '', 'title': '', 'middle': '', 'nickname': '', 'first': 'Bob'}
             >>> name.as_dict(False)
-            {u'last': u'Dole', u'first': u'Bob'}
+            {'last': 'Dole', 'first': 'Bob'}
             
         """
         d = {}
@@ -694,13 +694,13 @@ def capitalize(self):
         
             >>> name = HumanName('bob v. de la macdole-eisenhower phd')
             >>> name.capitalize()
-            >>> unicode(name)
-            u'Bob V. de la MacDole-Eisenhower Ph.D.'
+            >>> str(name)
+            'Bob V. de la MacDole-Eisenhower Ph.D.'
             >>> # Don't touch good names
             >>> name = HumanName('Shirley Maclaine')
             >>> name.capitalize()
-            >>> unicode(name) 
-            u'Shirley Maclaine'
+            >>> str(name) 
+            'Shirley Maclaine'
         
         """
         name = u(self)