namefully 1.2.0

Handle personal names in a particular order, way, or shape.

namefully

Name handling made easy.

Installation

pip install namefully

Note: Python 3.7+ is required.

Usage

>>> from namefully import Namefully
>>> name = Namefully('Thomas Alva Edison')
>>> name.short
'Thomas Edison'
>>> name.public
'Thomas E'
>>> name.initials()
['T', 'A', 'E']
>>> name.format('L, f m')
'EDISON, Thomas Alva'
>>> name.zip()
'Thomas A. E.'

NOTE: if you intend to use this utility for non-standard name cases such as many middle names or last names, use Namefully.parse() or NameBuilder instead.

See examples or test cases for more details.

Additional Settings

Below are enlisted additional settings supported by namefully. Use the following keyword arguments to customize the output of the name parts.

ordered_by

first_name | last_name - default: first_name

ordered_by specifies the order of name pieces when provided as raw string values or string array values.

>>> from namefully import Namefully
>>> name = Namefully('Smith John Joe', ordered_by='last_name')
>>> name.last
'Smith'
>>> name = Namefully(['De La Cruz', 'Antonio'], ordered_by='last_name')
>>> name.first
'Antonio'

Note: The order of appearance set initially will be prioritized in other operations. However, it can be adjusted dynamically as needed. See the example below.

>>> from namefully import Namefully
>>> name = Namefully('Smith John Joe', ordered_by='last_name')
>>> name.full
'Smith John Joe'
>>> name.full_name(ordered_by='first_name')
'John Joe Smith'

separator

'' | , | : | " | - | . | ; | ' | ' ' | _ - default: ' ' (whitespace)

Supported separators are: empty, comma, colon, double quotes, hyphen, period, semicolon, single quote, whitespace, and underscore. Though only valid for raw string values, separator indicates how to split the parts of a raw string name under the hood. If you want more control, use a custom Parser.

>>> from namefully import Namefully
>>> name = Namefully('John,Smith', separator=',')
>>> name.full
'John Smith'

title

uk | us - default: uk

title abides by the ways the international community defines an abbreviated title. American and Canadian English follow slightly different rules for abbreviated titles than British and Australian English. In North American English, titles before a name require a period: Mr., Mrs., Ms., Dr.. In British and Australian English, no periods are used in these abbreviations.

>>> from namefully import Namefully
>>> name = Namefully.only(prefix='Mr', first='John', last='Smith', title='us')
>>> name.full
'Mr. John Smith'
>>> name.prefix
'Mr.'

ending

bool - default: False

This sets an ending character after the full name (a comma before the suffix actually).

>>> from namefully import Namefully
>>> name = Namefully.only('John', 'Smith', suffix='PhD', ending=True)
>>> name.full
'John Smith, PhD'
>>> name.suffix
'PhD'

surname

father | mother | hyphenated | all - default: father

surname defines the distinct formats to output a compound surname (e.g., Hispanic surnames).

>>> from namefully import Namefully, FirstName, LastName
>>> name = Namefully([FirstName('John'), LastName('Doe', 'Smith')], surname='hyphenated')
>>> name.full
'John Doe-Smith'

bypass

bool - default: True

This will bypass all the built-in validators (i.e., validation rules, regular expressions).

>>> from namefully import Namefully
>>> name = Namefully.only('Jane', 'Smith', suffix='M.Sc', bypass=False)
Traceback (most recent call last):
  ...
ValidationError (suffix='M.Sc'): invalid content

To sum it all up, the default values are:

>>> from namefully import Config
>>> config = Config.create()
>>> print(config)
<Config: default>
>>> config.to_dict()
{'name': 'default', 'ordered_by': 'first_name', 'separator': ' ', 'title': 'uk', 'ending': False, 'bypass': True, 'surname': 'father'}

Do It Yourself

Customize your own parser to indicate the full name yourself.

>>> from namefully import Namefully, Parser, FullName
>>>
>>> class SimpleParser(Parser):
...     def parse(self, **options) -> FullName:
...         fn, ln = self.raw.split('#', 1)
...         return FullName.parse({'first_name': fn, 'last_name': ln}, **options)
>>>
>>> name = Namefully(SimpleParser('Juan#Garcia'))
>>> name.full
'Juan Garcia'

Or use NameIndex to specify where the name parts are located in a text.

>>> from namefully import Namefully, NameIndex
>>> name = Namefully.parse('Dwayne "The Rock" Johnson', index=NameIndex.only(first_name=0, last_name=3))
>>> name.full
'Dwayne Johnson'

Or simply use NameBuilder to build a name on the fly (with lifecycle hooks if needed).

>>> from namefully import Name
>>> from namefully.builder import NameBuilder
>>>
>>> builder = NameBuilder.of(Name.first('Nikola')) # can be more than one name
>>> builder.add(Name.last('Tesla'))
>>> builder.add(Name.prefix('Mr'))
>>> name = builder.build(title='us')
>>> name.full
'Mr. Nikola Tesla'

Concepts and examples

The name standards (inspired by this UK name guide) used for the current version of this library are as follows:

[prefix] first_name [middle_name] last_name [suffix]

The opening [ and closing ] brackets mean that these parts are optional. In other words, the most basic/typical case is a name that looks like this: John Smith, where John is the firstName and Smith, the lastName.

NOTE: Do note that the order of appearance matters and (as shown in ordered_by) can be altered through configured parameters. By default, the order of appearance is as shown above and will be used as a basis for future examples and use cases.

Basic cases

Let us take a common example with all the parts:

Mr John Joe Smith PhD

So, this utility understands the name parts as follows:

• prefix: Mr
• first name: John
• middle name: Joe
• last name: Smith
• suffix: PhD
• full name: Mr John Joe Smith PhD
• birth name: John Joe Smith
• short version: John Smith
• flattened: John J. S.
• initials: J J S
• public: John S
• salutation: Mr Smith

Limitations

namefully does not support certain use cases:

• mononame: Plato - a workaround is to set the mononame as both first and last name;
• nickname: Dwayne "The Rock" Johnson - use custom parser instead.
• multiple prefixes or suffixes: Prof. Dr. Einstein.

Contributing

Visit CONTRIBUTING.md for details on the contribution guidelines, the code of conduct, and the process for submitting pull requests.

License

The underlying content of this utility is licensed under MIT License.