Store, validate, and convert physical quantities in Django using Pint.
Django Pint Field enables you to:
- Store quantities (like 1 gram, 3 miles, 8.120391 angstroms) in your Django models
- Edit quantities in forms with automatic unit conversion
- Compare quantities in different units (e.g., compare weights in pounds vs. kilograms)
- Display quantities in user-preferred units while maintaining accurate comparisons
- Perform aggregations and lookups across different units of measurement
The package uses a Postgres composite field to store both the magnitude and units, along with a base unit value for accurate comparisons. This approach ensures that users can work with their preferred units while maintaining data integrity and comparability. For this reason, the project only works with Postgresql databases.
- Python 3.10+
- Django 4.2+
- PostgreSQL database
- Pint 0.23+
pip install django-pint-fieldAdd to your INSTALLED_APPS:
INSTALLED_APPS = [
# ...
"django_pint_field",
# ...
]Run migrations:
python manage.py migrate django_pint_fieldFailure to run django-pint-field migrations before running migrations for models using PintFields will result in errors. The migration creates a required composite type in your PostgreSQL database.
Previous versions of the package added three composite types to the database. The newest migration modifies the columns with these types to use a single composite type.
If using [django-pgtrigger](https://django-pgtrigger.readthedocs.io/en/latest/commands/) or other packages that depend on it (e.g.: django-pghistory), we highly recommend that you temporarily uninstall all triggers before running the django-pint-field migrations. It is also a good practice to make a backup of your database before running the migration. Users freshly installing `django-pint-field` do not need to worry about this warning.
python manage.py pgtrigger uninstallThen run the migrations:
python manage.py migrate django_pint_fieldReinstall the triggers after the migrations are complete:
python manage.py pgtrigger install- Define your model:
from decimal import Decimal
from django.db import models
from django_pint_field.models import DecimalPintField
class Product(models.Model):
name = models.CharField(max_length=Decimal("100"))
weight = DecimalPintField(
default_unit="gram",
unit_choices=["gram", "kilogram", "pound", "ounce"],
)- Use it in your code:
from django_pint_field.units import ureg
# Create objects
product = Product.objects.create(
name="Coffee Bag",
weight=ureg.Quantity(Decimal("340"), "gram"),
)
# Query using different units
products = Product.objects.filter(
weight__gte=ureg.Quantity(Decimal("0.5"), "kilogram"),
)
# Access values
print(product.weight) # 3460 gram
print(product.weight.quantity) # 3460 gram (accessing the Pint Quantity object)
# Convert to different units
print(product.weight.quantity.to("kilogram")) # 0.346 kilogram
print(product.weight.kilogram) # 0.346 kilogram
print(product.weight.kilogram__2) # 0.35 kilogram (rounded to 2 decimal places)- IntegerPintField: For whole number quantities
- DecimalPintField: For precise decimal quantities
- BigIntegerPintField: For large whole number quantities (deprecated, use IntegerPintField instead)
- Built-in form fields with unit conversion
- TabledPintFieldWidget for displaying unit conversion tables
- Customizable validation and unit choices
- IntegerPintFormField: Used in forms with IntegerPintField and BigIntegerPintField.
- DecimalPintFormField: Used in forms with DecimalPintField.
- PintFieldWidget: Default widget for all django pint field types.
- TabledPintFieldWidget: Provides a table showing conversion to each of the
unit_choices.
from django_pint_field.rest import DecimalPintRestField
class ProductSerializer(serializers.ModelSerializer):
weight = DecimalPintRestField()
class Meta:
model = Product
fields = ["name", "weight"]The package is tested to work with both Django REST Framework and Django Ninja.
exactgt,gtelt,lterangeisnull
from django_pint_field.aggregates import PintAvg, PintSum
Product.objects.aggregate(
avg_weight=PintAvg("weight"),
total_weight=PintSum("weight"),
)PintAvgPintCountPintMaxPintMinPintSumPintStdDevPintVariance
Create your own unit registry:
from pint import UnitRegistry
custom_ureg = UnitRegistry(non_int_type=Decimal)
custom_ureg.define("custom_unit = [custom]")
# In settings.py
DJANGO_PINT_FIELD_UNIT_REGISTER = custom_uregDjango Pint Field supports creating indexes on the comparator components of Pint fields. Indexes can improve query performance when filtering, ordering, or joining on Pint field values.
from django_pint_field.indexes import PintFieldComparatorIndex
class Package(models.Model):
weight = DecimalPintField("gram")
class Meta:
indexes = [PintFieldComparatorIndex(fields=["weight"])]from django_pint_field.indexes import PintFieldComparatorIndex
class Package(models.Model):
weight = DecimalPintField("gram")
volume = DecimalPintField("liter")
class Meta:
indexes = [PintFieldComparatorIndex(fields=["weight", "volume"])]You can also use additional index options, as usual. e.g.:
name: Custom index namecondition: Partial index conditioninclude: Additional columns to include in the indexdb_tablespace: Custom tablespace for the index
# settings.py
# Set decimal precision for the entire project
DJANGO_PINT_FIELD_DECIMAL_PRECISION = 40
# Configure custom unit registry
DJANGO_PINT_FIELD_UNIT_REGISTER = custom_ureg
# Set default format for quantity display
DJANGO_PINT_FIELD_DEFAULT_FORMAT = "D" # Options: D, P, ~P, etc.Modified from django-pint with a focus on composite field storage and enhanced comparison capabilities.