django-nx

Lightweight Django field utilities and extensions that reduce boilerplate and enforce sensible defaults.

Installation

pip install django-nx

Requires Python >= 3.9, Django >= 3.2, and Django REST Framework >= 3.12.4.

Quick Start

from nx import nx

class Product(nx.Model):
    name = nx.CharField('Name') # Default max_length=128
    price = nx.MoneyField('Price')
    status = nx.IntChoiceField('Status', choices=ProductStatus)
    tags = nx.ArrayField('Tags')
    metadata = nx.ObjectField('Metadata')

Table of Contents

• Model Fields
• Choices
• Base Model
• QuerySet
• DRF Serializers
• DRF Views
• DRF Router
• Utilities

Model Fields

All fields automatically use verbose_name as help_text when help_text is not explicitly provided.

Character Fields

name = nx.CharField('Name', max_length=255)
description = nx.TextField('Description')
priority = nx.TextChoiceField('Priority', choices=PriorityLevel)

Numeric Fields

quantity = nx.IntegerField('Quantity')
price = nx.MoneyField('Price')           # DECIMAL(18,2)
discount = nx.MoneyField('Discount', max_digits=5, decimal_places=4)
status = nx.IntChoiceField('Status', choices=OrderStatus)

Boolean & Temporal Fields

is_active = nx.BooleanField('Is Active')
published_at = nx.DateTimeField('Published At')
birth_date = nx.DateField('Birth Date')

Relationship Fields

user = nx.ForeignKey('auth.User', 'User')
profile = nx.OneToOne('accounts.Profile', 'Profile')
tags = nx.ManyToMany('products.Tag', 'Tags')

# Soft / logical foreign key (no DB-level constraint)
legacy_id = nx.ShadowForeignKey('legacy.Model', 'Legacy Ref')

JSON & UUID Fields

config = nx.ObjectField('Config')
items = nx.ArrayField('Items')
code = nx.ShortUUIDField('Code')

Base Model

nx.Model is an abstract base model that provides:

• created_at – auto_now_add timestamp
• updated_at – auto_now timestamp
• is_deleted – soft-delete flag (default False)
• Auto-generated db_table – {app_label}_{snake_case_model_name} via humps.decamelize

import nx

class Product(nx.Model):
    name = nx.CharField('Name', max_length=255)

    class Meta:
        app_label = 'shop'
        # db_table = 'shop_product'  # auto-generated if omitted

Explicitly set Meta.db_table to skip auto-naming.

QuerySet

nx.QuerySet adds soft-delete aware query methods. It reads deleted_field from Model.Meta (defaults to is_deleted).

from nx.models.querysets import QuerySet

class ProductQuerySet(QuerySet):
    pass

class Product(nx.Model):
    ...
    class Meta:
        deleted_field = 'is_deleted'

Product.objects.valid()     # is_deleted=False / 0
Product.objects.invalid()   # is_deleted=True / 1

DRF Serializers

from rest_framework import serializers
import nx

class ProductSerializer(nx.drf.AutoInstanceLookupMixin, serializers.ModelSerializer):
    price = nx.drf.MoneyField()
    stock = nx.drf.QuantityField()
    category_name = nx.drf.MethodField()

    class Meta:
        model = Product
        fields = ['id', 'price', 'stock', 'category_name']

    def get_category_name(self, obj):
        return obj.category.name if obj.category else None

DRF Views

ListMetadataMixin

Inject a top-level meta object (or any custom root key) into list responses.

from rest_framework import viewsets
import nx

class ProductViewSet(nx.drf.ListMetadataMixin, viewsets.ModelViewSet):
    queryset = Product.objects.all()
    serializer_class = ProductSerializer
    list_metadata_root = "meta"  # optional; omit to merge at top-level

    def get_list_metadata(self, request, queryset, response):
        return {
            "total": queryset.count(),
            "timestamp": timezone.now().isoformat(),
        }

Response shape with list_metadata_root = "meta":

{
  "count": 100,
  "results": [...],
  "meta": {
    "total": 100,
    "timestamp": "2024-01-15T09:30:00Z"
  }
}

Response shape without list_metadata_root:

{
  "count": 100,
  "results": [...],
  "total": 100,
  "timestamp": "2024-01-15T09:30:00Z"
}

DRF Router

nx.Router wraps DRF's DefaultRouter. Routes have no trailing slash, and register() derives the default basename from the singular form of prefix. An explicitly supplied basename is left unchanged.

from nx import nx

router = nx.Router()
router.register("products", ProductViewSet)

# Route: /products (not /products/)
# Basename: product

Utilities

get_stat_datetime_range

Returns today, week, month, and year datetime ranges respecting USE_TZ.

from nx.utils import get_stat_datetime_range

ranges = get_stat_datetime_range()
# ranges.today  -> (2024-01-15 00:00:00, 2024-01-15 23:59:59.999999)
# ranges.week   -> (Mon 00:00:00, Sun 23:59:59.999999)
# ranges.month  -> (1st 00:00:00, last_day 23:59:59.999999)
# ranges.year   -> (Jan 1 00:00:00, Dec 31 23:59:59.999999)

Development

# Install dependencies
uv sync

# Run tests
pytest

# Lint
ruff check .

# Build
uv build

License

MIT License — see LICENSE for details.