fix errors in docs found with doctest, add nickname to _members

Author: derek73

docs/conf.py

@@ -261,3 +261,8 @@
 
 # If true, do not generate a @detailmenu in the "Top" node's menu.
 #texinfo_no_detailmenu = False
+
+doctest_global_setup = """from nameparser import HumanName
+from nameparser.config import CONSTANTS, Constants
+CONSTANTS = Constants()
+"""

docs/customize.rst

@@ -49,7 +49,8 @@ But "Hon" is also sometimes a first name. If your dataset contains more
 "Hon"s than "Honorable"s, you may wish to remove it from the titles
 constant so that "Hon" can be parsed as a first name.
 
-::
+.. doctest::
+    :options: +ELLIPSIS, +NORMALIZE_WHITESPACE
 
     >>> from nameparser import HumanName
     >>> hn = HumanName("Hon Solo")
@@ -63,7 +64,7 @@ constant so that "Hon" can be parsed as a first name.
     	nickname: ''
     ]>
     >>> from nameparser.config import CONSTANTS
-    >>> CONSTANTS.titles.remove('hon') # doctest: +ELLIPSIS
+    >>> CONSTANTS.titles.remove('hon')
     SetManager(set([u'msgt', ..., u'adjutant']))
     >>> hn = HumanName("Hon Solo")
     >>> hn
@@ -86,11 +87,12 @@ 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.
 
-::
+.. doctest::
+    :options: +ELLIPSIS, +NORMALIZE_WHITESPACE
 
     >>> from nameparser import HumanName
     >>> from nameparser.config import CONSTANTS
-    >>> CONSTANTS.titles.add('dean', 'Chemistry') # doctest: +ELLIPSIS
+    >>> CONSTANTS.titles.add('dean', 'Chemistry')
     SetManager(set([u'msgt', ..., u'adjutant']))
     >>> hn = HumanName("Assoc Dean of Chemistry Robert Johns")
     >>> hn
@@ -112,11 +114,12 @@ HumanName instances. This could be a handy way to set it up for your entire
 project, but it could also lead to some unexpected behavior because changing
 the config on one instance could modify the behavior of another instance.
 
-::
+.. doctest:: module config
+    :options: +ELLIPSIS, +NORMALIZE_WHITESPACE
 
     >>> from nameparser import HumanName
     >>> hn = HumanName("Dean Robert Johns")
-    >>> hn.C.titles.add('dean') # doctest: +ELLIPSIS
+    >>> hn.C.titles.add('dean')
     SetManager(set([u'msgt', ..., u'adjutant']))
     >>> hn
     <HumanName : [
@@ -149,8 +152,9 @@ reference to the module-level config values with the behavior described above.
 
     >>> from nameparser import HumanName
     >>> hn = HumanName("Dean Robert Johns", None)
-    >>> hn.C.titles.add('dean') # doctest: +ELLIPSIS
+    >>> hn.C.titles.add('dean')
     SetManager(set([u'msgt', ..., u'adjutant']))
+    >>> hn.parse_full_name() # need to refresh parse after changing config
     >>> hn
     <HumanName : [
     	title: 'Dean' 
@@ -185,35 +189,36 @@ data after assigning the full name, the name will need to be re-parsed with the
 :py:func:`~nameparser.parser.HumanName.parse_full_name()` method before you see 
 those changes with ``repr()``.
 
+::
 
     >>> from nameparser import HumanName
     >>> hn = HumanName("Dean Robert Johns")
     >>> hn
     <HumanName : [
-    	title: 'Dean' 
-    	first: 'Robert' 
-    	middle: '' 
+    	title: '' 
+    	first: 'Dean' 
+    	middle: 'Robert' 
     	last: 'Johns' 
     	suffix: ''
     	nickname: ''
     ]>
-    >>> hn.C.titles.add('dean') # doctest: +ELLIPSIS
+    >>> hn.C.titles.add('dean')
     SetManager(set([u'msgt', ..., u'adjutant']))
     >>> hn
     <HumanName : [
-    	title: 'Dean' 
-    	first: 'Robert' 
-    	middle: '' 
+    	title: '' 
+    	first: 'Dean' 
+    	middle: 'Robert' 
     	last: 'Johns' 
     	suffix: ''
     	nickname: ''
     ]>
     >>> hn.parse_full_name()
     >>> hn
     <HumanName : [
-    	title: '' 
-    	first: 'Dean' 
-    	middle: 'Robert' 
+    	title: 'Dean' 
+    	first: 'Robert' 
+    	middle: '' 
     	last: 'Johns' 
     	suffix: ''
     	nickname: ''

docs/usage.rst

@@ -4,7 +4,8 @@ Using the HumanName Parser
 Example
 -------
 
-::
+.. doctest::
+    :options: -ELLIPSIS, +NORMALIZE_WHITESPACE
 
     >>> from nameparser import HumanName
     >>> name = HumanName("Dr. Juan Q. Xavier de la Vega III")
@@ -18,13 +19,13 @@ Example
     u'de la Vega'
     >>> name.suffix
     u'III'
-    >>> name.full_name = 'Doe-Ray, Col. Jonathan "John" A. Jérôme III'
+    >>> name.full_name = 'Doe-Ray, Col. Jonathan "John" A. Harris III'
     >>> name.title
     u'Col.'
     >>> name.first
-    u'John'
+    u'Jonathan'
     >>> name.middle
-    u'A. Jérôme'
+    u'A. Harris'
     >>> name.last
     u'Doe-Ray'
     >>> name.suffix
@@ -61,8 +62,8 @@ Example
     >>> len(name)
     5
     >>> list(name)
-    ['Dr.', 'Juan', 'Q. Xavier', 'de la Vega', 'III']
-    >>> name[1:-1]
+    [u'Dr.', u'Juan', u'Q. Xavier', u'de la Vega', u'III']
+    >>> name[1:-2]
     [u'Juan', u'Q. Xavier', u'de la Vega']
     >>> name = HumanName('bob v. de la macdole-eisenhower phd')
     >>> name.capitalize()
@@ -86,12 +87,12 @@ entered in all upper or lower case.
 
     * bob v. de la macdole-eisenhower phd -> Bob V. de la MacDole-Eisenhower Ph.D.
 
-::
+.. doctest:: capitalize
 
     >>> name = HumanName("bob v. de la macdole-eisenhower phd")
     >>> name.capitalize()
     >>> unicode(name)
-    "Bob V. de la MacDole-Eisenhower Ph.D."
+    u'Bob V. de la MacDole-Eisenhower Ph.D.'
 
 It will not adjust the case of mixed case names.
 
@@ -102,7 +103,8 @@ Handling Nicknames
 The content of parenthesis or double quotes in the name will be
 available from the nickname attribute. (Added in v0.2.9)
 
-::
+.. doctest:: nicknames
+    :options: +NORMALIZE_WHITESPACE
 
     >>> name = HumanName('Jonathan "John" A. Smith')
     >>> name
@@ -123,12 +125,12 @@ The format of the strings returned with ``unicode()`` can be adjusted
 using standard python string formatting. The string's ``format()``
 method will be passed a dictionary of names.
 
-::
+.. doctest:: string format
 
     >>> name = HumanName("Rev John A. Kenneth Doe III")
     >>> unicode(name)
-    "Rev John A. Kenneth Doe III"
+    u'Rev John A. Kenneth Doe III'
     >>> name.string_format = "{last}, {title} {first} {middle}, {suffix}"
     >>> unicode(name)
-    "Doe, Rev John A. Kenneth, III"
+    u'Doe, Rev John A. Kenneth, III'
 

nameparser/config/__init__.py

@@ -42,7 +42,8 @@
 
 class SetManager(collections.Set):
     '''
-    Easily add and remove config variables per module or instance.
+    Easily add and remove config variables per module or instance. Subclass of
+    ``collections.Set``.
     
     Only special functionality beyond that provided by set() is
     to normalize constants for comparison (lower case, no periods)

nameparser/parser.py

@@ -47,32 +47,32 @@ class HumanName(object):
     :param str string_format: python string formatting 
     """
 
-    CONSTANTS = CONSTANTS
+    has_own_config = False
+    """True if this instance is not using the shared module-level configuration."""
+    
+    C = CONSTANTS
+    """
+    A reference to the configuration for this instance, which may or may not be a
+    reference to the module-wide instance at :py:mod:`~nameparser.config.CONSTANTS`.
+    See `Customizing the Parser <customize.html>`_.
+    """
+    
+    count = 0
+    _members = ['title','first','middle','last','suffix','nickname']
+    unparsable = True
+    _full_name = ''
 
     def __init__(self, full_name="", constants=CONSTANTS, encoding=ENCODING, 
                 string_format=None):
-        
+        global CONSTANTS
         self.C = constants
-        """
-        A reference to the configuration for this instance, which may be a
-        reference to the module-wide instance at :py:mod:`~nameparser.config.CONSTANTS`.
-        See `Customizing the Parser <customize.html>`_.
-        """
-        
-        self.has_own_config = False
-        
         if not self.C:
             self.C = Constants()
-        if self.C is not self.CONSTANTS:
-            #: True if this instance is not using the module-level configuration.
+        if self.C is not CONSTANTS:
             self.has_own_config = True
 
         self.ENCODING = encoding
         self.string_format = string_format
-        self.count = 0
-        self._members = ['title','first','middle','last','suffix']
-        self.unparsable = True
-        self._full_name = ''
         self.full_name = full_name
 
     def __iter__(self):
@@ -114,7 +114,7 @@ def __next__(self):
 
     def __unicode__(self):
         if self.string_format:
-            # string_format = "{title} {first} {middle} {last} {suffix}"
+            # string_format = "{title} {first} {middle} {last} {suffix} ({nickname})"
             return self.string_format.format(**self._dict)
         return " ".join(self)
 
@@ -580,7 +580,7 @@ def capitalize(self):
         
         **Usage**
         
-        ::
+        .. doctest:: capitalize
         
             >>> name = HumanName('bob v. de la macdole-eisenhower phd')
             >>> name.capitalize()
@@ -596,8 +596,8 @@ def capitalize(self):
         name = u(self)
         if not (name == name.upper() or name == name.lower()):
             return
-        self.title_list = self.cap_piece(self.title).split(' ')
-        self.first_list = self.cap_piece(self.first).split(' ')
+        self.title_list  = self.cap_piece(self.title ).split(' ')
+        self.first_list  = self.cap_piece(self.first ).split(' ')
         self.middle_list = self.cap_piece(self.middle).split(' ')
-        self.last_list = self.cap_piece(self.last).split(' ')
+        self.last_list   = self.cap_piece(self.last  ).split(' ')
         self.suffix_list = self.cap_piece(self.suffix).split(' ')

tests.py

@@ -120,8 +120,8 @@ def test_comparison_case_insensitive(self):
     def test_slice(self):
         hn = HumanName("Doe-Ray, Dr. John P., CLU, CFP, LUTC")
         self.m(list(hn), ['Dr.', 'John', 'P.', 'Doe-Ray', 'CLU, CFP, LUTC'], hn)
-        self.m(hn[1:], ['John', 'P.', 'Doe-Ray', 'CLU, CFP, LUTC'], hn)
-        self.m(hn[1:-1], ['John', 'P.', 'Doe-Ray'], hn)
+        self.m(hn[1:], ['John', 'P.', 'Doe-Ray', 'CLU, CFP, LUTC',''], hn)
+        self.m(hn[1:-2], ['John', 'P.', 'Doe-Ray'], hn)
 
     def test_conjunction_names(self):
         hn = HumanName("johnny y")
@@ -1511,11 +1511,11 @@ def test_downcasing_mc(self):
 
 class HumanNameOutputFormatTests(HumanNameTestBase):
     def test_formating(self):
-        hn = HumanName("Rev John A. Kenneth Doe III")
-        hn.string_format = "{title} {first} {middle} {last} {suffix}"
-        self.assertEqual(u(hn), "Rev John A. Kenneth Doe III")
-        hn.string_format = "{last}, {title} {first} {middle}, {suffix}"
-        self.assertEqual(u(hn), "Doe, Rev John A. Kenneth, III")
+        hn = HumanName("Rev John A. Kenneth Doe III (Kenny)")
+        hn.string_format = "{title} {first} {middle} {last} {suffix} ({nickname})"
+        self.assertEqual(u(hn), "Rev John A. Kenneth Doe III (Kenny)")
+        hn.string_format = "{last}, {title} {first} {middle}, {suffix} ({nickname})"
+        self.assertEqual(u(hn), "Doe, Rev John A. Kenneth, III (Kenny)")
 
 
 TEST_NAMES = (
@@ -1706,9 +1706,27 @@ def test_variations_of_TEST_NAMES(self):
             hn = HumanName(name)
             if len(hn.suffix_list) > 1:
                 hn = HumanName("{title} {first} {middle} {last} {suffix}".format(**hn._dict).split(',')[0])
-            nocomma = HumanName("{title} {first} {middle} {last} {suffix}".format(**hn._dict))
-            lastnamecomma = HumanName("{last}, {title} {first} {middle} {suffix}".format(**hn._dict))
-            suffixcomma = HumanName("{title} {first} {middle} {last}, {suffix}".format(**hn._dict))
+            hn_dict = hn._dict.copy()
+            attrs = [
+                'title',
+                'first',
+                'middle',
+                'last',
+                'suffix',
+                'nickname',
+            ]
+            for attr in attrs:
+                if not getattr(hn, attr):
+                    setattr(hn,attr,'')
+            nocomma = HumanName("{title} {first} {middle} {last} {suffix}".format(**hn_dict))
+            lastnamecomma = HumanName("{last}, {title} {first} {middle} {suffix}".format(**hn_dict))
+            if hn.suffix:
+                suffixcomma = HumanName("{title} {first} {middle} {last}, {suffix}".format(**hn_dict))
+            if hn.nickname:
+                nocomma = HumanName("{title} {first} {middle} {last} {suffix} ({nickname})".format(**hn_dict))
+                lastnamecomma = HumanName("{last}, {title} {first} {middle} {suffix} ({nickname})".format(**hn_dict))
+                if hn.suffix:
+                    suffixcomma = HumanName("{title} {first} {middle} {last}, {suffix} ({nickname})".format(**hn_dict))
             for attr in hn._members:
                 self.m(getattr(hn, attr), getattr(nocomma, attr), hn)
                 self.m(getattr(hn, attr), getattr(lastnamecomma, attr), hn)