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

Names

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

Installation

To install, simply use pipenv (or pip):

>>> pipenv install django-names

Add names to your INSTALLED_APPS setting:

INSTALLED_APPS = [
    ...
    "names",
]

Run migrations:

>>> python manage.py 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
'Natalia'
>>> name.middle
'Alianovna'
>>> name.last
'Romanova'
>>> name.nickname
'Natasha'

Features

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
'Anthony'
>>> name.middle
'Edward'
>>> name.last
'Stark'
>>> name.suffix
''
>>> name.nickname
'Tony'

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

>>> name.nickname = "Iron Man"
>>> name.save()
>>> 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)
>>> user.name.full
'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):
    pass
>>> user = User.objects.create(full="General Nicholas Joseph 'Nick' Fury")
>>> user.full
'General Nicholas Joseph Fury (Nick)'
>>> user.title
'General'

Settings

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

MAX_LENGTH

type <int>

Max length of each CharField defined in the NameModelMixin mixin.

Default:

100

STRING_FORMAT

type <str>

Sets the output string for the full field.

Default

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

Learn more

Change the output string with string formatting

EMPTY_ATTRIBUTE_DEFAULT

type <str>

Value returned by empty name attributes.

Default

""  # empty string

OPTIONS

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.

Default

"OPTIONS": {
   "TITLES": TITLES,
   "SUFFIX_NOT_ACRONYMS": SUFFIX_NOT_ACRONYMS,
   "CONJUNCTIONS": CONJUNCTIONS,
   "PREFIXES": PREFIXES,
   "CAPITALIZATION_EXCEPTIONS": CAPITALIZATION_EXCEPTIONS,
   "REGEXES": REGEXES,
}

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.

Files for django-names, version 1.0.5
Filename, size File type Python version Upload date Hashes
Filename, size django_names-1.0.5-py2.py3-none-any.whl (9.3 kB) File type Wheel Python version py2.py3 Upload date Hashes View hashes
Filename, size django-names-1.0.5.tar.gz (15.8 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page