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.

Source Distribution

django-names-1.0.5.tar.gz (15.8 kB view details)

Uploaded Source

Built Distribution

django_names-1.0.5-py2.py3-none-any.whl (9.3 kB view details)

Uploaded Python 2Python 3

File details

Details for the file django-names-1.0.5.tar.gz.

File metadata

  • Download URL: django-names-1.0.5.tar.gz
  • Upload date:
  • Size: 15.8 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/1.13.0 pkginfo/1.5.0.1 requests/2.22.0 setuptools/41.0.1 requests-toolbelt/0.9.1 tqdm/4.32.2 CPython/3.7.3

File hashes

Hashes for django-names-1.0.5.tar.gz
Algorithm Hash digest
SHA256 60a0161d42c05559c8bcb0495288577d6a87b9aa1f51a0bfb8b2b24935e6d52b
MD5 0a7a8eb71d264436ce806125ddc0e057
BLAKE2b-256 03bfca5dd7e53a6385020c70fdad3895f6796d96261074e60b9ab4ac5a870ade

See more details on using hashes here.

File details

Details for the file django_names-1.0.5-py2.py3-none-any.whl.

File metadata

  • Download URL: django_names-1.0.5-py2.py3-none-any.whl
  • Upload date:
  • Size: 9.3 kB
  • Tags: Python 2, Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/1.13.0 pkginfo/1.5.0.1 requests/2.22.0 setuptools/41.0.1 requests-toolbelt/0.9.1 tqdm/4.32.2 CPython/3.7.3

File hashes

Hashes for django_names-1.0.5-py2.py3-none-any.whl
Algorithm Hash digest
SHA256 9c3f39a97115154b2474cf696c7d69d1361a93046cc0298d76c66178052ac504
MD5 93d5808395b35f7428a74365844c6792
BLAKE2b-256 65d6f51c8c91762b3159be62e15e9081e9fa5fd257135f7e73de609e7ff4c337

See more details on using hashes here.

Supported by

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