Add CONSTANTS.empty_attribute_default, fix #44

Author: derek73

docs/customize.rst

@@ -6,21 +6,6 @@ matching the lower case characters of a name piece with pre-defined sets
 of strings located in :py:mod:`nameparser.config`. You can adjust
 these predefined sets to help fine tune the parser for your dataset.
 
-Editable CONSTANTS sets:
-
-* `titles` - Pieces that come before the name. Cannot include things that may be first names
-* `first_name_titles` - Titles that, when followed by a single name, that name is a first name, e.g. "King David"
-* `suffix_acronyms` - Pieces that come at the end of the name that may or may not have periods separating the letters, e.g. "m.d."
-* `suffix_not_acronyms` - Pieces that come at the end of the name that never have periods separating the letters, e.g. "Jr."
-* `conjunctions` - Connectors like "and" that join the preceeding piece to the following piece.
-* `prefixes` - Connectors like "del" and "bin" that join to the following piece but not the preceeding
-* `capitalization_exceptions` - Dictionary of pieces that do not capitalize the first letter, e.g. "Ph.D"
-* `regexes` - Regular expressions used to find words, initials, nicknames, etc.
-
-Each set of constants comes with `add()` and `remove()` methods for tuning
-the constants for your project. These methods automatically lower case and
-remove punctuation to normalize them for comparison.
-
 Changing the Parser Constants
 -----------------------------
 
@@ -49,14 +34,39 @@ Both places are usually a reference to the same shared module-level
 :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
-in the constants. Here's a quick walk through of some examples where you
-might want to adjust them.
+
+
+Editable attributes of nameparser.config.CONSTANTS
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* :py:attr:`~nameparser.config.Constants.titles` - Pieces that come before the name. Cannot include things that may be first names
+* :py:attr:`~nameparser.config.Constants.first_name_titles` - Titles that, when followed by a single name, that name is a first name, e.g. "King David"
+* :py:attr:`~nameparser.config.Constants.suffix_acronyms` - Pieces that come at the end of the name that may or may not have periods separating the letters, e.g. "m.d."
+* :py:attr:`~nameparser.config.Constants.suffix_not_acronyms` - Pieces that come at the end of the name that never have periods separating the letters, e.g. "Jr."
+* :py:attr:`~nameparser.config.Constants.conjunctions` - Connectors like "and" that join the preceeding piece to the following piece.
+* :py:attr:`~nameparser.config.Constants.prefixes` - Connectors like "del" and "bin" that join to the following piece but not the preceeding
+* :py:attr:`~nameparser.config.Constants.capitalization_exceptions` - Dictionary of pieces that do not capitalize the first letter, e.g. "Ph.D"
+* :py:attr:`~nameparser.config.Constants.regexes` - Regular expressions used to find words, initials, nicknames, etc.
+
+Each set of constants comes with `add()` and `remove()` methods for tuning
+the constants for your project. These methods automatically lower case and
+remove punctuation to normalize them for comparison.
+
+Other editable attributes
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* :py:attr:`~nameparser.config.Constants.string_format`
+* :py:attr:`~nameparser.config.Constants.empty_attribute_default`
+
 
 
 Parser Customization Examples
 -----------------------------
 
+Take a look at the :py:mod:`nameparser.config` documentation to see what's
+in the constants. Here's a quick walk through of some examples where you
+might want to adjust them.
+
 "Hon" is a common abbreviation for "Honorable", a title used when
 addressing judges, and is included in the default tiles constants. This
 means it will never be considered a first name, because titles are the
@@ -99,7 +109,7 @@ 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 :py:func:`~nameparser.config.SetManager.add` 
+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

docs/release_log.rst

@@ -1,5 +1,7 @@
 Release Log
 ===========
+* 0.3.14 - March 18, 2016
+    - Add `CONSTANTS.empty_attribute_default` to customize value returned for empty attributes (#44)
 * 0.3.13 - March 14, 2016
     - Improve string format handling (#41)
 * 0.3.12 - March 13, 2016

nameparser/__init__.py

@@ -1,4 +1,4 @@
-VERSION = (0, 3, 13)
+VERSION = (0, 3, 14)
 __version__ = '.'.join(map(str, VERSION))
 __author__ = "Derek Gulbranson"
 __author_email__ = '[email protected]'

nameparser/config/__init__.py

@@ -150,7 +150,23 @@ class Constants(object):
 
     string_format = "{title} {first} {middle} {last} {suffix} ({nickname})"
     """
-    The default string format use for all new HumanName instances.
+    The default string format use for all new `HumanName` instances.
+    """
+    empty_attribute_default = ''
+    """
+    Default return value for empty attributes. Setting this to something other than empty
+    string will causes :py:attr:`string_format` not to work.
+    
+    .. doctest::
+    
+        >>> from nameparser.config import CONSTANTS
+        >>> CONSTANTS.empty_attribute_default = None
+        >>> name = HumanName("John Doe")
+        >>> name.title
+        None
+        >>>name.first
+        'John'
+        
     """
 
 

nameparser/parser.py

@@ -180,31 +180,31 @@ def title(self):
         :py:mod:`~nameparser.config.titles` or :py:mod:`~nameparser.config.conjunctions`
         at the beginning of :py:attr:`full_name`.
         """
-        return " ".join(self.title_list)
+        return " ".join(self.title_list) or self.C.empty_attribute_default
 
     @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)
+        return " ".join(self.first_list) or self.C.empty_attribute_default
 
     @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)
+        return " ".join(self.middle_list) or self.C.empty_attribute_default
 
     @property
     def last(self):
         """
         The person's last name. The last name piece parsed from 
         :py:attr:`full_name`.
         """
-        return " ".join(self.last_list)
+        return " ".join(self.last_list) or self.C.empty_attribute_default
 
     @property
     def suffix(self):
@@ -214,15 +214,15 @@ def suffix(self):
         of comma separated formats, e.g. "Lastname, Title Firstname Middle[,] Suffix 
         [, Suffix]" parsed from :py:attr:`full_name`.
         """
-        return ", ".join(self.suffix_list)
+        return ", ".join(self.suffix_list) or self.C.empty_attribute_default
 
     @property
     def nickname(self):
         """
         The person's nicknames. Any text found inside of quotes (``""``) or 
         parenthesis (``()``)
         """
-        return " ".join(self.nickname_list)
+        return " ".join(self.nickname_list) or self.C.empty_attribute_default
 
     ### setter methods
 

tests.py

@@ -1261,6 +1261,17 @@ def test_chain_multiple_arguments(self):
         self.m(hn.middle,"Hon", hn)
         self.m(hn.last,"Solo", hn)
 
+    def test_empty_attribute_default(self):
+        from nameparser.config import CONSTANTS
+        _orig = CONSTANTS.empty_attribute_default
+        CONSTANTS.empty_attribute_default = None
+        hn = HumanName("Benjamin Franklin")
+        self.m(hn.first,"Benjamin", hn)
+        self.m(hn.middle,None, hn)
+        self.m(hn.last,"Franklin", hn)
+        CONSTANTS.empty_attribute_default = _orig
+
+
 class HumanNameNicknameTestCase(HumanNameTestBase):
     # https://code.google.com/p/python-nameparser/issues/detail?id=33
     def test_nickname_in_parenthesis(self):