Merge pull request #90 from jcp/capitalization

 Added capitalization rules to Constants class

Author: derek73

docs/customize.rst

@@ -57,6 +57,8 @@ Other editable attributes
 
 * :py:obj:`~nameparser.config.Constants.string_format` - controls output from `str()`
 * :py:obj:`~nameparser.config.Constants.empty_attribute_default` - value returned by empty attributes, defaults to empty string
+* :py:obj:`~nameparser.config.Constants.capitalize_name` - If set, applies :py:meth:`~nameparser.parser.HumanName.capitalize` to :py:class:`~nameparser.parser.HumanName` instance.
+* :py:obj:`~nameparser.config.Constants.force_mixed_case_capitalization` - If set, forces the capitalization of mixed case strings when :py:meth:`~nameparser.parser.HumanName.capitalize` is called.
 
 
 

docs/usage.rst

@@ -72,9 +72,8 @@ Capitalization Support
 
 The HumanName class can try to guess the correct capitalization of name
 entered in all upper or lower case. By default, it will not adjust 
-the case of names entered in mixed case. To run capitalization on all names
-pass the parameter `force=True`.
-
+the case of names entered in mixed case. To run capitalization on a
+`HumanName` instance, pass the parameter `force=True`.
 
     Capitalize the name.
 
@@ -94,6 +93,31 @@ pass the parameter `force=True`.
     >>> str(name) 
     'Shirley MacLaine'
 
+To apply capitalization to all `HumanName` instances, set
+:py:attr:`~nameparser.config.Constants.capitalize_name` to `True`.
+
+.. doctest:: capitalize_name
+    :options: +NORMALIZE_WHITESPACE
+
+    >>> from nameparser.config import CONSTANTS
+    >>> CONSTANTS.capitalize_name = True
+    >>> name = HumanName("bob v. de la macdole-eisenhower phd")
+    >>> str(name)
+    'Bob V. de la MacDole-Eisenhower Ph.D.'
+
+To force the capitalization of mixed case strings on all `HumanName` instances,
+set :py:attr:`~nameparser.config.Constants.force_mixed_case_capitalization` to `True`. 
+
+.. doctest:: force_mixed_case_capitalization
+    :options: +NORMALIZE_WHITESPACE
+
+    >>> from nameparser.config import CONSTANTS
+    >>> CONSTANTS.force_mixed_case_capitalization = True
+    >>> name = HumanName('Shirley Maclaine')
+    >>> name.capitalize()
+    >>> str(name)
+    'Shirley MacLaine'
+
 
 Nickname Handling
 ------------------

nameparser/config/__init__.py

@@ -179,8 +179,37 @@ class Constants(object):
         'John'
         
     """
-    
-    
+    capitalize_name = False
+    """
+    If set, applies :py:meth:`~nameparser.parser.HumanName.capitalize` to
+    :py:class:`~nameparser.parser.HumanName` instance.
+
+    .. doctest::
+
+        >>> from nameparser.config import CONSTANTS
+        >>> CONSTANTS.capitalize_name = True
+        >>> name = HumanName("bob v. de la macdole-eisenhower phd")
+        >>> str(name)
+        'Bob V. de la MacDole-Eisenhower Ph.D.'
+
+    """
+    force_mixed_case_capitalization = False
+    """
+    If set, forces the capitalization of mixed case strings when
+    :py:meth:`~nameparser.parser.HumanName.capitalize` is called.
+
+    .. doctest::
+
+        >>> from nameparser.config import CONSTANTS
+        >>> CONSTANTS.force_mixed_case_capitalization = True
+        >>> name = HumanName('Shirley Maclaine')
+        >>> name.capitalize()
+        >>> str(name)
+        'Shirley MacLaine'
+
+    """
+
+
     def __init__(self, 
                     prefixes=PREFIXES, 
                     suffix_acronyms=SUFFIX_ACRONYMS,

nameparser/parser.py

@@ -387,7 +387,7 @@ 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. Runs :py:func:`parse_nicknames` and py:func:`squash_emoji`.
+        subclass. Runs :py:func:`parse_nicknames` and :py:func:`squash_emoji`.
         
         """
         self.fix_phd()
@@ -397,9 +397,11 @@ def pre_process(self):
     def post_process(self):
         """
         This happens at the end of the :py:func:`parse_full_name` after
-        all other processing has taken place. Runs :py:func:`handle_firstnames`.
+        all other processing has taken place. Runs :py:func:`handle_firstnames`
+        and :py:func:`handle_capitalization`.
         """
         self.handle_firstnames()
+        self.handle_capitalization()
 
     def fix_phd(self):
         _re =  self.C.regexes.phd
@@ -675,9 +677,9 @@ def join_on_conjunctions(self, pieces, additional_parts_count=0):
         :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.
+            with spaces in it.
         :rtype: list
-        
+
         """
         length = len(pieces) + additional_parts_count
         # don't join on conjunctions if there's only 2 parts
@@ -833,14 +835,16 @@ def cap_piece(self, piece, attribute):
         replacement = lambda m: self.cap_word(m.group(0), attribute)
         return self.C.regexes.word.sub(replacement, piece)
 
-    def capitalize(self, force=False):
+    def capitalize(self, force=None):
         """
         The HumanName class can try to guess the correct capitalization of name
         entered in all upper or lower case. By default, it will not adjust the
         case of names entered in mixed case. To run capitalization on all names
         pass the parameter `force=True`.
         
-        :param bool force: force capitalization of strings that include mixed case
+        :param bool force: Forces capitalization of mixed case strings. This
+            parameter overrides rules set within
+            :py:class:`~nameparser.config.CONSTANTS`.
 
         **Usage**
         
@@ -861,10 +865,21 @@ def capitalize(self, force=False):
         
         """
         name = u(self)
+        force = self.C.force_mixed_case_capitalization \
+            if force is None else force
+
         if not force and not (name == name.upper() or name == name.lower()):
             return
         self.title_list  = self.cap_piece(self.title , 'title').split(' ')
         self.first_list  = self.cap_piece(self.first , 'first').split(' ')
         self.middle_list = self.cap_piece(self.middle, 'middle').split(' ')
         self.last_list   = self.cap_piece(self.last  , 'last').split(' ')
         self.suffix_list = self.cap_piece(self.suffix, 'suffix').split(', ')
+
+    def handle_capitalization(self):
+        """
+        Handles capitalization configurations set within
+        :py:class:`~nameparser.config.CONSTANTS`.
+        """
+        if self.C.capitalize_name:
+            self.capitalize()

tests.py

@@ -2088,6 +2088,28 @@ def test_formatting_constants_attribute(self):
         self.assertEqual(u(hn), "TEST2")
         CONSTANTS.string_format = _orig
 
+    def test_capitalize_name_constants_attribute(self):
+        from nameparser.config import CONSTANTS
+        CONSTANTS.capitalize_name = True
+        hn = HumanName("bob v. de la macdole-eisenhower phd")
+        self.assertEqual(str(hn), "Bob V. de la MacDole-Eisenhower Ph.D.")
+        CONSTANTS.capitalize_name = False
+
+    def test_force_mixed_case_capitalization_constants_attribute(self):
+        from nameparser.config import CONSTANTS
+        CONSTANTS.force_mixed_case_capitalization = True
+        hn = HumanName('Shirley Maclaine')
+        hn.capitalize()
+        self.assertEqual(str(hn), "Shirley MacLaine")
+        CONSTANTS.force_mixed_case_capitalization = False
+
+    def test_capitalize_name_and_force_mixed_case_capitalization_constants_attributes(self):
+        from nameparser.config import CONSTANTS
+        CONSTANTS.capitalize_name = True
+        CONSTANTS.force_mixed_case_capitalization = True
+        hn = HumanName('Shirley Maclaine')
+        self.assertEqual(str(hn), "Shirley MacLaine")
+
     def test_quote_nickname_formating(self):
         hn = HumanName("Rev John A. Kenneth Doe III (Kenny)")
         hn.string_format = "{title} {first} {middle} {last} {suffix} '{nickname}'"