Skip to content

Model Fields

fields

USAddressField(*args, **kwargs)

Bases: TextField

Model field that stores a US address as a JSON object.

Stored format:

{"street_address": "123 Main St", "street_address_2": "Apt 4B",
 "city": "New York", "state": "NY", "zip_code": "10001"}

Renders in forms as five separate inputs (street, street 2, city, state dropdown, ZIP) via USAddressWidget. Automatically adds a get_<field>_display() method that returns a formatted address string.

Supports querying individual components via custom lookups:

  • address__city='New York'
  • address__state='NY'
  • address__zip_code='10001'
  • address__city__icontains='new'
Example 
class Person(TimeStampedModel):
    home_address = USAddressField(blank=True, null=True)

person = Person.objects.first()
person.home_address              # {'street_address': '...', ...}
person.get_home_address_display() # '123 Main St, New York, NY 10001'

# Query by component
Person.objects.filter(home_address__state='NY')
Person.objects.filter(home_address__city__icontains='york')

from_db_value(value, expression, connection)

Convert database value to Python object

to_python(value)

Convert value to Python object

get_prep_value(value)

Convert Python object to database value

validate(value, model_instance)

Validate the address data

contribute_to_class(cls, name, **kwargs)

Called when the field is added to a model class

MultipleChoiceField(choices=None, *args, **kwargs)

Bases: TextField

Model field that stores multiple choice selections as a JSON array.

Stores values as a JSON array in a TextField (e.g. ["Admin", "User"]). Renders as checkboxes in forms via CheckboxMultipleChoiceField. Automatically adds a get_<field>_display() method to the model that returns a comma-separated string of selected values.

Example 
class Person(TimeStampedModel):
    roles = MultipleChoiceField(
        choices=[('Admin', 'Admin'), ('User', 'User'), ('Guest', 'Guest')],
        null=True, blank=True, default=['Guest'],
    )

person = Person.objects.first()
person.roles                  # ['Admin', 'User']
person.get_roles_display()    # 'Admin, User'

from_db_value(value, expression, connection)

Convert database value to Python object

to_python(value)

Convert value to Python object

get_prep_value(value)

Convert Python object to database value

validate(value, model_instance)

Validate the choice selections

contribute_to_class(cls, name, **kwargs)

Called when the field is added to a model class

CurrencyField(*args, **kwargs)

Bases: DecimalField

DecimalField pre-configured for currency values.

Defaults to decimal_places=2. Renders in forms with CurrencyInput, which adds client-side $ formatting and comma separators.

Example 
class Musician(models.Model):
    net_worth = CurrencyField(max_digits=20, decimal_places=2,
                              null=True, blank=True)