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
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 aName
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
- STRING_FORMAT
- EMPTY_ATTRIBUTE_DEFAULT
- OPTIONS
- TITLES
- FIRST_NAME_TITLES
- SUFFIX_ACRONYMS
- SUFFIX_NOT_ACRONYMS
- CONJUNCTIONS
- PREFIXES
- CAPITALIZATION_EXCEPTIONS
- REGEXES
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
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
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for django_names-1.0.5-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 9c3f39a97115154b2474cf696c7d69d1361a93046cc0298d76c66178052ac504 |
|
MD5 | 93d5808395b35f7428a74365844c6792 |
|
BLAKE2-256 | 65d6f51c8c91762b3159be62e15e9081e9fa5fd257135f7e73de609e7ff4c337 |