Skip to main content

Names is a reusable app for Django that provides mixins, models and form fields to store a full name and its individual components.

Project description


pypi pypi codecov Build Status

Names is a reusable app for Django that provides mixins, models and form fields to store a full name and its individual components. The following name components are supported:

  • Full name
  • Title
  • First name
  • Middle name
  • Last name
  • Suffix
  • Nickname

Names officially supports the following:

  • Python 3.6 - 3.7
  • Django 1.11, 2.0 - 2.2

Table of Contents


To install, simply use pipenv (or pip):

>>> pipenv install django-names

Add names to your INSTALLED_APPS setting:


Run migrations:

>>> python migrate names

Basic Usage

>>> from names.models import Name
>>> name = Name.objects.create(full="Natalia Alianovna 'Natasha' Romanova")
>>> name.full
'Natalia Alianovna Romanova (Natasha)'
>>> name.first
>>> name.middle
>>> name.last
>>> name.nickname


Names was designed to be flexible. It comes with three primary features:

  • Name: A model that parses and stores full names.
  • NameField: A model field that provides a one-to-one relationship to a Name instance.
  • NameModelMixin: A mixin that can be used to extend existing models.

Name model

The Name model contains fields and methods that store a full name and its individual components.

>>> from names.models import Name
>>> name = Name.objects.create(full="Anthony Edward Stark (Tony)")
>>> name
<Name: Anthony Edward Stark (Tony)>
>>> name.full
'Anthony Edward Stark (Tony)'
>>> name.title
>>> name.first
>>> name.middle
>>> name.last
>>> name.suffix
>>> name.nickname

When you update an individual name component, the full name updates automatically when the instance is saved.

>>> name.nickname = "Iron Man"
>>> name.full
'Anthony Edward Stark (Iron Man)'

NameField model field

NameField has a one-to-one relationship to a Name instance.

from names.fields import NameField

class User(models.Model):
    name = NameField(on_delete=models.CASCADE)
>>> from names.models import Name
>>> name = Name.objects.create(full="Carol Susan Jane Danvers")
>>> User = User.objects.create(name=name)
'Carol Susan Jane Danvers'

NameModelMixin mixin

Name inherits its functionality from the NameModelMixin mixin. You can use this mixin to extend existing models to avoid adding a field with a one-to-one relationship or additional database tables.

from names.mixins import NameModelMixin

class User(NameModelMixin):
>>> user = User.objects.create(full="General Nicholas Joseph 'Nick' Fury")
>>> user.full
'General Nicholas Joseph Fury (Nick)'
>>> user.title


Names uses the NAME_SETTINGS namespace for all settings. The following settings are supported:


type <int>

Max length of each CharField defined in the NameModelMixin mixin.




type <str>

Sets the output string for the full field.


"{title} {first} {middle} {last} {suffix} ({nickname})"

Learn more

Change the output string with string formatting


type <str>

Value returned by empty name attributes.


""  # empty string


type <dict>

Handles recognition of titles, prefixes, suffixes and conjunctions. The OPTIONS setting is very powerful and can be used to customize how you parse names.



Options are imported from python-nameparser, which is the library used to parse names.

Learn more

Editable attributes

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

django-names-1.0.3.tar.gz (16.7 kB view hashes)

Uploaded Source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page