0
# Django Extensions
1

2
A comprehensive collection of custom extensions that enhance the Django web framework with additional management commands, utilities, and developer tools. Django Extensions provides powerful debugging and development commands, custom model fields, validators, template tags, and administrative utilities that streamline the Django development workflow.
3

4
## Package Information
5

6
- **Package Name**: django-extensions
7
- **Language**: Python  
8
- **Installation**: `pip install django-extensions`
9
- **Django Version**: Django 3.2+
10
- **Python Version**: Python 3.6+
11

12
## Core Imports
13

14
```python
15
# Add to INSTALLED_APPS in settings.py
16
INSTALLED_APPS = [
17
    'django_extensions',
18
    # ... your other apps
19
]
20
```
21

22
Common imports for models and fields:
23

24
```python
25
from django_extensions.db.models import TimeStampedModel, TitleSlugDescriptionModel
26
from django_extensions.db.fields import AutoSlugField, CreationDateTimeField
27
```
28

29
For validators:
30

31
```python
32
from django_extensions.validators import NoControlCharactersValidator, NoWhitespaceValidator, HexValidator
33
```
34

35
For admin extensions:
36

37
```python
38
from django_extensions.admin import ForeignKeyAutocompleteAdmin, NullFieldListFilter, ForeignKeySearchInput
39
```
40

41
## Basic Usage
42

43
```python
44
# Using TimeStampedModel base class
45
from django.db import models
46
from django_extensions.db.models import TimeStampedModel
47

48
class Article(TimeStampedModel):
49
    title = models.CharField(max_length=200)
50
    content = models.TextField()
51
    # created and modified fields are automatically added
52

53
# Using AutoSlugField
54
from django_extensions.db.fields import AutoSlugField
55

56
class Post(models.Model):
57
    title = models.CharField(max_length=200)
58
    slug = AutoSlugField(populate_from='title')
59

60
# Using management commands
61
# python manage.py shell_plus  # Enhanced shell with models loaded
62
# python manage.py show_urls   # Display all URL patterns
63
# python manage.py graph_models # Generate model diagrams
64
```
65

66
## Architecture
67

68
Django Extensions extends Django through several key mechanisms:
69

70
- **Django App Integration**: Registered as a Django app providing management commands, model mixins, and template tags
71
- **Management Commands**: 44+ commands extending Django's built-in management system
72
- **Model Extensions**: Abstract base classes and custom fields that enhance Django's ORM
73
- **Template System Integration**: Custom template tags and filters for enhanced template functionality
74
- **Validation Framework**: Custom validators that integrate with Django's form and model validation
75

76
## Capabilities
77

78
### Management Commands
79

80
Django Extensions provides 44+ management commands for development, debugging, database operations, and administrative tasks. These commands enhance Django's built-in management system with powerful utilities for developers.
81

82
```python { .api }
83
# Key management commands (accessed via python manage.py <command>):
84
# shell_plus - Enhanced shell with auto-imported models
85
# show_urls - Display all URL patterns  
86
# graph_models - Generate model relationship diagrams
87
# runserver_plus - Enhanced development server
88
# reset_db - Reset database
89
# dumpscript - Export data as Python script
90
```
91

92
[Management Commands](./management-commands.md)
93

94
### Model Fields
95

96
Custom model fields that extend Django's field types with specialized functionality including auto-generated slugs, timestamps, UUIDs, and JSON data handling.
97

98
```python { .api }
99
class AutoSlugField(SlugField):
100
    def __init__(self, populate_from=None, separator='-', overwrite=False, **kwargs): ...
101

102
class CreationDateTimeField(DateTimeField): ...
103
class ModificationDateTimeField(DateTimeField): ...
104
class RandomCharField(CharField): ...
105
class JSONField(TextField): ...
106
```
107

108
[Model Fields](./model-fields.md)
109

110
### Model Base Classes
111

112
Abstract model classes providing common functionality patterns including timestamps, activation status, and title/description/slug combinations.
113

114
```python { .api }
115
class TimeStampedModel(models.Model):
116
    created: CreationDateTimeField
117
    modified: ModificationDateTimeField
118
    class Meta:
119
        abstract = True
120

121
class ActivatorModel(models.Model):
122
    status: int
123
    activate_date: DateTimeField  
124
    deactivate_date: DateTimeField
125
    objects: ActivatorModelManager
126
    class Meta:
127
        abstract = True
128
```
129

130
[Model Base Classes](./model-base-classes.md)
131

132
### Validators
133

134
Custom validation classes for field-level validation including control character prevention, whitespace validation, and hexadecimal string validation.
135

136
```python { .api }
137
class NoControlCharactersValidator:
138
    def __init__(self, message=None, code=None, whitelist=None): ...
139
    def __call__(self, value): ...
140

141
class HexValidator:
142
    def __init__(self, length=None, min_length=None, max_length=None, **kwargs): ...
143
    def __call__(self, value): ...
144
```
145

146
[Validators](./validators.md)
147

148
### Template Tags
149

150
Template tag libraries providing debugging capabilities, syntax highlighting, text formatting, and typography enhancements for Django templates.
151

152
```python { .api }
153
# Template tags available after {% load <library> %}
154
# debugger_tags: {% ipdb %}, {% pdb %}, {% wdb %}
155
# highlighting: {% highlight "python" %}code{% endhighlight %}
156
# syntax_color: {{ code|colorize:"python" }}
157
# widont: {{ text|widont }}
158
```
159

160
[Template Tags](./template-tags.md)
161

162
### Admin Extensions
163

164
Enhanced Django admin functionality including custom filters and widgets for improved administrative interfaces.
165

166
```python { .api }
167
class ForeignKeySearchInput(widgets.Input):
168
    def __init__(self, rel, admin_site, attrs=None, using=None): ...
169

170
class NullFieldListFilter(admin.SimpleListFilter): ...
171
```
172

173
[Admin Extensions](./admin-extensions.md)
174

175
## Types
176

177
```python { .api }
178
# Field Options Types
179
FieldOptions = dict[str, Any]  # Django field kwargs
180

181
# Validator Types  
182
ValidationError = django.core.exceptions.ValidationError
183

184
# Model Manager Types
185
QuerySet = django.db.models.QuerySet
186
Manager = django.db.models.Manager
187

188
# Status Constants (ActivatorModel)
189
INACTIVE_STATUS: int = 0
190
ACTIVE_STATUS: int = 1
191
STATUS_CHOICES: tuple[tuple[int, str], ...] = (
192
    (INACTIVE_STATUS, 'Inactive'),
193
    (ACTIVE_STATUS, 'Active')
194
)
195
```