document as_dict() method

Author: derek73

docs/customize.rst

@@ -42,8 +42,9 @@ Parser Customization Examples
 +++++++++++++++++++++++++++++
 
 "Hon" is a common abbreviation for "Honorable", a title used when
-addressing judges, and is included in the default tiles constants which
-means it will never be considered a first name. 
+addressing judges, and is included in the default tiles constants. This
+means it will never be considered a first name, because titles are the
+pieces before first names. 
 
 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

docs/usage.rst

@@ -5,7 +5,7 @@ Example
 -------
 
 .. doctest::
-    :options: -ELLIPSIS, +NORMALIZE_WHITESPACE
+    :options: +NORMALIZE_WHITESPACE
 
     >>> from nameparser import HumanName
     >>> name = HumanName("Dr. Juan Q. Xavier de la Vega III")
@@ -19,30 +19,16 @@ Example
     u'de la Vega'
     >>> name.suffix
     u'III'
-    >>> name.full_name = 'Doe-Ray, Col. Jonathan "John" A. Harris III'
-    >>> name.title
-    u'Col.'
-    >>> name.first
-    u'Jonathan'
-    >>> name.middle
-    u'A. Harris'
-    >>> name.last
-    u'Doe-Ray'
-    >>> name.suffix
-    u'III'
-    >>> name.nickname
-    u'John'
     >>> name.full_name = "Juan Q. Xavier Velasquez y Garcia, Jr."
-    >>> name.title
-    u''
-    >>> name.first
-    u'Juan'
-    >>> name.middle
-    u'Q. Xavier'
-    >>> name.last
-    u'Velasquez y Garcia'
-    >>> name.suffix
-    u'Jr.'
+    >>> name
+    <HumanName : [
+    	title: '' 
+    	first: 'Juan' 
+    	middle: 'Q. Xavier' 
+    	last: 'Velasquez y Garcia' 
+    	suffix: 'Jr.'
+    	nickname: ''
+    ]>
     >>> name.middle = "Jason Alexander"
     >>> name.middle
     u'Jason Alexander'
@@ -55,6 +41,9 @@ Example
         suffix: 'Jr.'
         nickname: ''
     ]>
+    >>> name.full_name = 'Doe-Ray, Col. Jonathan "John" A. Harris III'
+    >>> name.as_dict()
+    {u'last': u'Doe-Ray', u'suffix': u'III', u'title': u'Col.', u'middle': u'A. Harris', u'nickname': u'John', u'first': u'Jonathan'}
     >>> name = HumanName("Dr. Juan Q. Xavier de la Vega III")
     >>> name2 = HumanName("de la vega, dr. juan Q. xavier III")
     >>> name == name2

nameparser/parser.py

@@ -115,7 +115,7 @@ def __next__(self):
     def __unicode__(self):
         if self.string_format:
             # string_format = "{title} {first} {middle} {last} {suffix} ({nickname})"
-            return self.string_format.format(**self._dict)
+            return self.string_format.format(**self.as_dict())
         return " ".join(self)
 
     def __str__(self):
@@ -134,13 +134,13 @@ def __repr__(self):
             'nickname': self.nickname,
         }
 
-    @property
-    def _dict(self):
+    def as_dict(self):
+        """Return the parsed name as a dictionary of its attributes."""
         d = {}
         for m in self._members:
             d[m] = getattr(self, m)
         return d
-    
+        
     ### attributes
 
     @property
@@ -310,7 +310,7 @@ def handle_firstnames(self):
                 and len(self) == 2 \
                 and not lc(self.title) in self.C.first_name_titles:
             self.last, self.first = self.first, self.last
-
+    
     def parse_full_name(self):
         """
         The main parse method for the parser. This method is run upon assignment to the

tests.py

@@ -1705,8 +1705,8 @@ def test_variations_of_TEST_NAMES(self):
         for name in self.TEST_NAMES:
             hn = HumanName(name)
             if len(hn.suffix_list) > 1:
-                hn = HumanName("{title} {first} {middle} {last} {suffix}".format(**hn._dict).split(',')[0])
-            hn_dict = hn._dict.copy()
+                hn = HumanName("{title} {first} {middle} {last} {suffix}".format(**hn.as_dict()).split(',')[0])
+            hn_dict = hn.as_dict()
             attrs = [
                 'title',
                 'first',