add docstrings for name attributes

Author: derek73

docs/customize.rst

@@ -45,7 +45,7 @@ Parser Customization Examples
 addressing judges, and is included in the default tiles constants which
 means it will never be considered a first name. 
 
-But "Hon is also sometimes a first name. If your dataset contains more
+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.
 

nameparser/config/__init__.py

@@ -83,15 +83,15 @@ def __next__(self):
     def add(self, *strings):
         """
         Add the lower case and no-period version of the string arguments to the set.
-        Return's ``self`` for chaining.
+        Returns ``self`` for chaining.
         """
         [self.elements.add(lc(s)) for s in strings]
         return self
 
     def remove(self, *strings):
         """
         Remove the lower case and no-period version of the string arguments from the set.
-        Return's ``self`` for chaining.
+        Returns ``self`` for chaining.
         """
         [self.elements.remove(lc(s)) for s in strings if lc(s) in self.elements]
         return self
@@ -110,53 +110,24 @@ def __getattr__(self, attr):
 
 class Constants(object):
     """
-    This class is used to hold all of the configuration for the parser.
-    An instance of this class is available via 
-    ``from nameparser.config import CONSTANTS`` or on the
-    ``C`` attribute of a :py:class:`~nameparser.parser.HumanName` instance, e.g. ``hn.C``.
+    An instance of this class hold all of the configuration constants for the parser.
 
     :param set prefixes: 
         :py:attr:`prefixes` wrapped with :py:class:`SetManager`.
-        
-        Parts that come before last names, e.g. 'del' or 'van'. 
-      
     :param set titles: 
         :py:attr:`titles` wrapped with :py:class:`SetManager`.
-        
-        Parts that come before the first names. Any strings included in
-        here will never be considered a first name, so use with care.
-      
     :param set first_name_titles: 
         :py:attr:`first_name_titles` wrapped with :py:class:`SetManager`.
-        
-        When these titles appear with a single other name, that name is a first name, e.g.
-        "Sir John", "Sister Mary", "Queen Elizabeth".
-      
     :param set suffixes: 
         :py:attr:`suffixes`  wrapped with :py:class:`SetManager`.
-        
-        Parts that appear after the last name, e.g. "Jr." or "MD".
-      
     :param set conjunctions: 
         :py:attr:`conjunctions`  wrapped with :py:class:`SetManager`.
-        
-        Parts that are used to join names together, e.g. "and", "y" and "&".
-        "of" and "the" are also include to facilitate joining multiple titles,
-        e.g. "President of the United States".
-      
+    :type capitalization_exceptions: tuple or dict
     :param capitalization_exceptions: 
         :py:attr:`capitalization_exceptions` wrapped with :py:class:`TupleManager`.
-        
-        Most parts should be capitalized by capitalizing the first letter.
-        There are some exceptions, such as roman numbers used for suffixes.
-        You can update this with a dictionary or a tuple. 
-    :type capitalization_exceptions: tuple or dict
-        
+    :type regexes: tuple or dict
     :param regexes: 
         :py:attr:`regexes`  wrapped with :py:class:`TupleManager`.
-        
-        Contains all the various regular expressions used in the parser.
-    :type regexes: tuple or dict
     """
     def __init__(self, 
                     prefixes=PREFIXES, 

nameparser/config/capitalization.py

@@ -9,5 +9,5 @@
     ('phd','Ph.D.'),
 )
 """
-Pieces that are not capitalized by capitalizing the first letter.
+Any pieces that are not capitalized by capitalizing the first letter.
 """

nameparser/config/conjunctions.py

@@ -1,7 +1,6 @@
 # -*- coding: utf-8 -*-
 from __future__ import unicode_literals
 
-#: Pieces that should join to their neighboring pieces.
 CONJUNCTIONS = set([
     '&',
     'and',
@@ -12,3 +11,8 @@
     'und',
     'y',
 ])
+"""
+Pieces that should join to their neighboring pieces, e.g. "and", "y" and "&".
+"of" and "the" are also include to facilitate joining multiple titles,
+e.g. "President of the United States".
+"""

nameparser/config/titles.py

@@ -1,10 +1,6 @@
 # -*- coding: utf-8 -*-
 from __future__ import unicode_literals
 
-# ## Titles ##
-# 
-#: When these titles are used with a single name, 
-#: that name is a first name rather than a last name.
 FIRST_NAME_TITLES = set([
     'sir',
     'dame',
@@ -21,6 +17,10 @@
     'father',
     'pope',
 ])
+"""
+When these titles appear with a single other name, that name is a first name, e.g.
+"Sir John", "Sister Mary", "Queen Elizabeth".
+"""
 
 #: **Cannot include things that could also be first names**, e.g. "dean".
 #: Many of these from wikipedia: https://en.wikipedia.org/wiki/Title.

nameparser/parser.py

@@ -26,18 +26,19 @@ class HumanName(object):
     """
     Parse a person's name into individual components.
     
+    Instantiation assigns to ``full_name``, and assignment to :py:attr:`full_name`
+    triggers :py:func:`parse_full_name`. After parsing the name, these instance 
+    attributes are available.
+    
     **HumanName Instance Attributes**
     
-    * o.title
-    * o.first
-    * o.middle
-    * o.last
-    * o.suffix
-    * o.nickname
+    * :py:attr:`title`
+    * :py:attr:`first`
+    * :py:attr:`middle`
+    * :py:attr:`last`
+    * :py:attr:`suffix`
+    * :py:attr:`nickname`
     
-    Instantiation assigns to ``full_name``, and assignment to :py:attr:`full_name`
-    triggers :py:func:`parse_full_name`, where most of the action happens.
-     
     :param str full_name: The name string to be parsed.
     :param constants constants: 
         a :py:class:`~nameparser.config.Constants` instance. Pass ``None`` for 
@@ -144,26 +145,53 @@ def _dict(self):
 
     @property
     def title(self):
+        """
+        The person's titles. Any string of consecutive pieces in 
+        :py:mod:`~nameparser.config.titles` or :py:mod:`~nameparser.config.conjunctions`
+        at the beginning of :py:attr:`full_name`.
+        """
         return " ".join(self.title_list)
 
     @property
     def first(self):
+        """
+        The person's first name. The first name piece after any known 
+        :py:attr:`title` pieces parsed from :py:attr:`full_name`.
+        """
         return " ".join(self.first_list)
 
     @property
     def middle(self):
+        """
+        The person's middle names. All name pieces after the first name and before 
+        the last name parsed from :py:attr:`full_name`.
+        """
         return " ".join(self.middle_list)
 
     @property
     def last(self):
+        """
+        The person's last name. The last name piece parsed from 
+        :py:attr:`full_name`.
+        """
         return " ".join(self.last_list)
 
     @property
     def suffix(self):
+        """
+        The persons's suffixes. Pieces at the end of the name that are found in
+        :py:mod:`~nameparser.config.suffixes`, or pieces that are at the end
+        of comma separated formats, e.g. "Lastname, Title Firstname Middle[,] Suffix 
+        [, Suffix]" parsed from :py:attr:`full_name`.
+        """
         return ", ".join(self.suffix_list)
 
     @property
     def nickname(self):
+        """
+        The person's nicknames. Any text found inside of quotes (``""``) or 
+        parenthesis (``()``)
+        """
         return " ".join(self.nickname_list)
 
     ### setter methods
@@ -198,19 +226,19 @@ def nickname(self, value):
     ### Parse helpers
 
     def is_title(self, value):
-        """Is in the titles set"""
+        """Is in the :py:data:`~nameparser.config.titles.TITLES` set."""
         return lc(value) in self.C.titles
 
     def is_conjunction(self, piece):
-        """Is in the conjuctions set or :py:func:`is_an_initial()`"""
+        """Is in the conjuctions set or :py:func:`is_an_initial()`."""
         return lc(piece) in self.C.conjunctions and not self.is_an_initial(piece)
 
     def is_prefix(self, piece):
-        """Is in the prefixes set or :py:func:`is_an_initial()`"""
+        """Is in the prefixes set or :py:func:`is_an_initial()`."""
         return lc(piece) in self.C.prefixes and not self.is_an_initial(piece)
 
     def is_suffix(self, piece):
-        """Is in the suffixes set or :py:func:`is_an_initial()`"""
+        """Is in the suffixes set or :py:func:`is_an_initial()`."""
         return lc(piece) in self.C.suffixes and not self.is_an_initial(piece)
 
     def is_rootname(self, piece):
@@ -219,7 +247,10 @@ def is_rootname(self, piece):
             and not self.is_an_initial(piece) 
 
     def is_an_initial(self, value):
-        """Matches the regular expression for initials."""
+        """
+        Matches the ``initial`` regular expression in 
+        :py:data:`~nameparser.config.regexes.REGEXES`.
+        """
         return self.C.regexes.initial.match(value) or False
 
     # def is_a_roman_numeral(value):
@@ -230,6 +261,7 @@ def is_an_initial(self, value):
 
     @property
     def full_name(self):
+        """The name string to be parsed."""
         return self._full_name
 
     @full_name.setter
@@ -242,15 +274,16 @@ def pre_process(self):
         """
         This method happens at the beginning of the :py:func:`parse_full_name` before
         any other processing of the string aside from unicode normalization, so
-        it's a good place to do any custom handling in a subclass.
+        it's a good place to do any custom handling in a subclass. 
+        Runs :py:func:`parse_nicknames`.
         """
         self.parse_nicknames()
 
 
     def post_process(self):
         """
         This happens at the end of the :py:func:`parse_full_name` after
-        all other processing has taken place.
+        all other processing has taken place. Runs :py:func:`handle_firstnames`.
         """
         self.handle_firstnames()
 
@@ -274,20 +307,19 @@ def handle_firstnames(self):
         a first name. 
         """
         if self.title \
-            and len(self) == 2 \
-            and not lc(self.title) in self.C.first_name_titles:
+                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
         :py:attr:`full_name` attribute or instantiation.
 
-        Basic flow is the hand off to :py:func:`pre_process` to handle nicknames, split
-        on commas to figure out which comma format to work with. :py:func:`parse_pieces`
-        splits on spaces and :py:func:`join_on_conjunctions` joins any pieces next to
-        conjunctions.
-        """
+        Basic flow is the hand off to :py:func:`pre_process` to handle nicknames. It
+        then splits on commas and chooses a code path depending on the number of commas.
+        :py:func:`parse_pieces` then splits those parts on spaces and
+        :py:func:`join_on_conjunctions` joins any pieces next to conjunctions. """
 
         self.title_list = []
         self.first_list = []
@@ -406,6 +438,7 @@ def parse_pieces(self, parts, additional_parts_count=0):
         Split parts on spaces and remove commas, join on conjunctions and
         lastname prefixes.
         
+        :param list parts: name part strings from the comma split
         :param int additional_parts_count: 
         
             if the comma format contains other parts, we need to know 
@@ -435,6 +468,8 @@ def join_on_conjunctions(self, pieces, additional_parts_count=0):
         Join conjunctions to surrounding pieces, e.g.:
         ['Mr. and Mrs.'], ['King of the Hill'], ['Jack and Jill'], ['Velasquez y Garcia']
         
+        :param list pieces: name pieces strings after split on spaces
+        :param int additional_parts_count: 
         :return: new list with piece next to conjunctions merged into one piece with spaces in it.
         :rtype: list