0
# Administration Interface
1

2
Django's admin interface provides automatic administrative interface generation for Django models, including customizable model admin classes, inline editing, actions, and permissions integration.
3

4
## Capabilities
5

6
### Admin Site
7

8
Core admin site classes for managing the administrative interface.
9

10
```python { .api }
11
class AdminSite:
12
    """
13
    Administrative interface site manager.
14
    
15
    Central registry for models and admin configuration with authentication.
16
    """
17
    name: str = 'admin'
18
    app_name: str = 'admin'
19
    
20
    def __init__(self, name: str = 'admin'): ...
21
    
22
    def register(self, model_or_iterable, admin_class=None, **options) -> None: ...
23
    def unregister(self, model_or_iterable) -> None: ...
24
    def is_registered(self, model) -> bool: ...
25
    def add_action(self, action, name: str = None) -> None: ...
26
    def disable_action(self, name: str) -> None: ...
27
    def get_action(self, name: str): ...
28
    def has_permission(self, request: HttpRequest) -> bool: ...
29
    def admin_view(self, view, cacheable: bool = False): ...
30
    def get_urls(self) -> list: ...
31
    def get_app_list(self, request: HttpRequest) -> list: ...
32
    def index(self, request: HttpRequest, extra_context: dict = None) -> HttpResponse: ...
33
    def app_index(self, request: HttpRequest, app_label: str, extra_context: dict = None) -> HttpResponse: ...
34
    def i18n_javascript(self, request: HttpRequest) -> HttpResponse: ...
35
    def logout(self, request: HttpRequest, extra_context: dict = None) -> HttpResponse: ...
36
    def login(self, request: HttpRequest, extra_context: dict = None) -> HttpResponse: ...
37
    def password_change(self, request: HttpRequest, extra_context: dict = None) -> HttpResponse: ...
38
    def password_change_done(self, request: HttpRequest, extra_context: dict = None) -> HttpResponse: ...
39
    def each_context(self, request: HttpRequest) -> dict: ...
40
    
41
    site_header: str
42
    site_title: str
43
    site_url: str
44
    index_title: str
45
    index_template: str
46
    app_index_template: str
47
    login_template: str
48
    login_form: str
49
    logout_template: str
50
    password_change_template: str
51
    password_change_done_template: str
52

53
site: AdminSite  # Default admin site instance
54

55
def autodiscover() -> None:
56
    """
57
    Automatically discover admin.py modules in installed apps.
58
    
59
    Imports admin modules to trigger model registration.
60
    """
61
```
62

63
### Model Admin
64

65
Base classes for customizing model administration interfaces.
66

67
```python { .api }
68
class BaseModelAdmin:
69
    """
70
    Base functionality for model admin classes.
71
    
72
    Provides common admin features without ModelAdmin inheritance.
73
    """
74
    autocomplete_fields: tuple = ()
75
    raw_id_fields: tuple = ()
76
    fields = None
77
    exclude = None
78
    fieldsets = None
79
    filter_horizontal: tuple = ()
80
    filter_vertical: tuple = ()
81
    radio_fields: dict = {}
82
    prepopulated_fields: dict = {}
83
    formfield_overrides: dict = {}
84
    readonly_fields: tuple = ()
85
    ordering = None
86
    sortable_by = None
87
    view_on_site: bool = True
88
    show_full_result_count: bool = True
89
    
90
    def check(self, **kwargs) -> list: ...
91
    def formfield_for_dbfield(self, db_field, request: HttpRequest, **kwargs): ...
92
    def formfield_for_choice_field(self, db_field, request: HttpRequest, **kwargs): ...
93
    def formfield_for_foreignkey(self, db_field, request: HttpRequest, **kwargs): ...
94
    def formfield_for_manytomany(self, db_field, request: HttpRequest, **kwargs): ...
95
    def get_field_queryset(self, db, db_field, request: HttpRequest): ...
96
    def get_changelist(self, request: HttpRequest): ...
97
    def get_changelist_form(self, request: HttpRequest, **kwargs): ...
98
    def get_changelist_formset(self, request: HttpRequest, **kwargs): ...
99
    def lookup_allowed(self, lookup: str, value: str) -> bool: ...
100
    def to_field_allowed(self, request: HttpRequest, to_field: str) -> bool: ...
101
    def get_readonly_fields(self, request: HttpRequest, obj=None) -> tuple: ...
102
    def get_prepopulated_fields(self, request: HttpRequest, obj=None) -> dict: ...
103
    def get_queryset(self, request: HttpRequest): ...
104
    def message_user(self, request: HttpRequest, message: str, level: int = None, extra_tags: str = '', fail_silently: bool = False) -> None: ...
105
    def get_paginator(self, request: HttpRequest, queryset, per_page: int, orphans: int = 0, allow_empty_first_page: bool = True): ...
106
    def get_object(self, request: HttpRequest, object_id: str, from_field=None): ...
107
    def get_form(self, request: HttpRequest, obj=None, change: bool = False, **kwargs): ...
108
    def get_formsets_with_inlines(self, request: HttpRequest, obj=None): ...
109
    def get_formsets(self, request: HttpRequest, obj=None): ...
110
    def get_inline_instances(self, request: HttpRequest, obj=None) -> list: ...
111

112
class ModelAdmin(BaseModelAdmin):
113
    """
114
    Model administration interface configuration.
115
    
116
    Main class for customizing model admin behavior and display.
117
    """
118
    list_display: tuple = ('__str__',)
119
    list_display_links = None
120
    list_filter: tuple = ()
121
    list_select_related: bool = False
122
    list_per_page: int = 100
123
    list_max_show_all: int = 200
124
    list_editable: tuple = ()
125
    search_fields: tuple = ()
126
    search_help_text: str = None
127
    date_hierarchy: str = None
128
    save_as: bool = False
129
    save_as_continue: bool = True
130
    save_on_top: bool = False
131
    paginator = None
132
    preserve_filters: bool = True
133
    inlines: list = []
134
    add_form_template: str = None
135
    change_form_template: str = None
136
    change_list_template: str = None
137
    delete_confirmation_template: str = None
138
    delete_selected_confirmation_template: str = None
139
    object_history_template: str = None
140
    popup_response_template: str = None
141
    
142
    def get_urls(self) -> list: ...
143
    def get_model_perms(self, request: HttpRequest) -> dict: ...
144
    def has_view_permission(self, request: HttpRequest, obj=None) -> bool: ...
145
    def has_add_permission(self, request: HttpRequest) -> bool: ...
146
    def has_change_permission(self, request: HttpRequest, obj=None) -> bool: ...
147
    def has_delete_permission(self, request: HttpRequest, obj=None) -> bool: ...
148
    def has_module_permission(self, request: HttpRequest) -> bool: ...
149
    def get_queryset(self, request: HttpRequest): ...
150
    def get_search_results(self, request: HttpRequest, queryset, search_term: str) -> tuple: ...
151
    def get_preserved_filters(self, request: HttpRequest) -> str: ...
152
    def construct_change_message(self, request: HttpRequest, form, formsets: list, add: bool = False) -> list: ...
153
    def message_user(self, request: HttpRequest, message: str, level: int = None, extra_tags: str = '', fail_silently: bool = False) -> None: ...
154
    def save_model(self, request: HttpRequest, obj, form, change: bool) -> None: ...
155
    def delete_model(self, request: HttpRequest, obj) -> None: ...
156
    def save_related(self, request: HttpRequest, form, formsets: list, change: bool) -> None: ...
157
    def save_formset(self, request: HttpRequest, form, formset, change: bool) -> None: ...
158
    def get_ordering(self, request: HttpRequest) -> list: ...
159
    def get_search_fields(self, request: HttpRequest) -> tuple: ...
160
    def get_sortable_by(self, request: HttpRequest) -> tuple: ...
161
    def get_inline_instances(self, request: HttpRequest, obj=None) -> list: ...
162
    def get_inlines(self, request: HttpRequest, obj) -> list: ...
163
    def add_view(self, request: HttpRequest, form_url: str = '', extra_context: dict = None) -> HttpResponse: ...
164
    def change_view(self, request: HttpRequest, object_id: str, form_url: str = '', extra_context: dict = None) -> HttpResponse: ...
165
    def changelist_view(self, request: HttpRequest, extra_context: dict = None) -> HttpResponse: ...
166
    def delete_view(self, request: HttpRequest, object_id: str, extra_context: dict = None) -> HttpResponse: ...
167
    def history_view(self, request: HttpRequest, object_id: str, extra_context: dict = None) -> HttpResponse: ...
168
    def response_add(self, request: HttpRequest, obj, post_url_continue: str = None) -> HttpResponse: ...
169
    def response_change(self, request: HttpRequest, obj) -> HttpResponse: ...
170
    def response_delete(self, request: HttpRequest, obj_display: str, obj_id: str) -> HttpResponse: ...
171
    def get_changeform_initial_data(self, request: HttpRequest) -> dict: ...
172
    def get_deleted_objects(self, objs: list, request: HttpRequest) -> tuple: ...
173
```
174

175
### Inline Admin
176

177
Classes for editing related objects inline within parent object forms.
178

179
```python { .api }
180
class InlineModelAdmin(BaseModelAdmin):
181
    """
182
    Base class for inline model administration.
183
    
184
    Provides functionality for editing related objects within parent forms.
185
    """
186
    model = None
187
    fk_name: str = None
188
    formset = None
189
    form = None
190
    extra: int = 3
191
    min_num: int = None
192
    max_num: int = None
193
    template: str = None
194
    verbose_name: str = None
195
    verbose_name_plural: str = None
196
    can_delete: bool = True
197
    show_change_link: bool = False
198
    classes: list = None
199
    
200
    def get_formset(self, request: HttpRequest, obj=None, **kwargs): ...
201
    def get_queryset(self, request: HttpRequest): ...
202
    def get_extra(self, request: HttpRequest, obj=None, **kwargs) -> int: ...
203
    def get_min_num(self, request: HttpRequest, obj=None, **kwargs) -> int: ...
204
    def get_max_num(self, request: HttpRequest, obj=None, **kwargs) -> int: ...
205
    def has_add_permission(self, request: HttpRequest, obj=None) -> bool: ...
206
    def has_change_permission(self, request: HttpRequest, obj=None) -> bool: ...
207
    def has_delete_permission(self, request: HttpRequest, obj=None) -> bool: ...
208
    def has_view_permission(self, request: HttpRequest, obj=None) -> bool: ...
209

210
class StackedInline(InlineModelAdmin):
211
    """
212
    Inline admin with stacked layout.
213
    
214
    Displays each related object in a separate fieldset block.
215
    """
216
    template: str = 'admin/edit_inline/stacked.html'
217

218
class TabularInline(InlineModelAdmin):
219
    """
220
    Inline admin with tabular layout.
221
    
222
    Displays related objects in a compact table format.
223
    """
224
    template: str = 'admin/edit_inline/tabular.html'
225

226
class GenericInlineModelAdmin(InlineModelAdmin):
227
    """
228
    Inline admin for generic foreign key relationships.
229
    """
230
    ct_field: str = 'content_type'
231
    ct_fk_field: str = 'object_id'
232
    formset = None
233
    
234
    def get_formset(self, request: HttpRequest, obj=None, **kwargs): ...
235

236
class GenericStackedInline(GenericInlineModelAdmin):
237
    """
238
    Generic inline with stacked layout.
239
    """
240
    template: str = 'admin/edit_inline/stacked.html'
241

242
class GenericTabularInline(GenericInlineModelAdmin):
243
    """
244
    Generic inline with tabular layout.
245
    """
246
    template: str = 'admin/edit_inline/tabular.html'
247
```
248

249
### Admin Actions
250

251
System for defining bulk actions on admin change lists.
252

253
```python { .api }
254
def action(function=None, *, permissions: list = None, description: str = None):
255
    """
256
    Decorator for creating admin actions.
257
    
258
    Args:
259
        function: Action function to decorate
260
        permissions: Required permissions for action
261
        description: Human-readable action description
262
        
263
    Returns:
264
        Decorated action function
265
    """
266

267
def delete_selected(modeladmin, request: HttpRequest, queryset) -> HttpResponse:
268
    """
269
    Built-in action for deleting selected objects.
270
    
271
    Args:
272
        modeladmin: ModelAdmin instance
273
        request: HTTP request object
274
        queryset: Selected objects queryset
275
        
276
    Returns:
277
        Confirmation page or redirect after deletion
278
    """
279
delete_selected.short_description = "Delete selected %(verbose_name_plural)s"
280
```
281

282
### Admin Display Decorators
283

284
Decorators for customizing field display in admin interface.
285

286
```python { .api }
287
def display(function=None, *, boolean: bool = None, ordering: str = None, description: str = None, empty_value: str = None):
288
    """
289
    Decorator for configuring admin field display.
290
    
291
    Args:
292
        function: Method to decorate
293
        boolean: Whether field represents boolean value
294
        ordering: Database field for sorting
295
        description: Column header text
296
        empty_value: Display value for empty fields
297
        
298
    Returns:
299
        Decorated display method
300
    """
301
```
302

303
### Registration Functions
304

305
Functions for registering models with admin site.
306

307
```python { .api }
308
def register(*models, site: AdminSite = None):
309
    """
310
    Decorator for registering models with admin site.
311
    
312
    Args:
313
        *models: Model classes to register
314
        site: Admin site instance (defaults to default site)
315
        
316
    Returns:
317
        Decorator function or admin class
318
    """
319
```
320

321
### Admin Forms
322

323
Specialized forms for admin interface with enhanced widgets.
324

325
```python { .api }
326
class AdminForm:
327
    """
328
    Wrapper for forms used in admin interface.
329
    
330
    Provides fieldset organization and admin-specific rendering.
331
    """
332
    def __init__(self, form, fieldsets: list, prepopulated_fields: dict, readonly_fields: list = None, model_admin=None): ...
333
    
334
    def __iter__(self): ...
335
    def __getitem__(self, name: str): ...
336
    def errors(self): ...
337
    def non_field_errors(self): ...
338
    def media(self): ...
339
    
340
    form: Form
341
    fieldsets: list
342
    prepopulated_fields: dict
343
    model_admin: ModelAdmin
344

345
class AdminErrorList(list):
346
    """
347
    Error list with admin-specific formatting.
348
    """
349
    def __init__(self, form, errors: list): ...
350
    def as_ul(self) -> str: ...
351
    def as_text(self) -> str: ...
352

353
class AdminReadonlyField:
354
    """
355
    Display-only field for admin forms.
356
    """
357
    def __init__(self, form, field: str, is_first: bool, model_admin=None): ...
358
    def label_tag(self) -> str: ...
359
    def contents(self) -> str: ...
360

361
class Fieldset:
362
    """
363
    Fieldset grouping for admin forms.
364
    """
365
    def __init__(self, form, name: str = None, readonly_fields: tuple = (), fields: tuple = (), classes: tuple = (), description: str = None, model_admin=None): ...
366
    
367
    def __iter__(self): ...
368
    def media(self): ...
369
    
370
    name: str
371
    fields: tuple
372
    classes: str
373
    description: str
374
```
375

376
### Admin Widgets
377

378
Enhanced widgets for admin interface forms.
379

380
```python { .api }
381
class AdminDateWidget(DateInput):
382
    """
383
    Date input widget with admin calendar popup.
384
    """
385
    template_name: str = 'admin/widgets/date.html'
386

387
class AdminTimeWidget(TimeInput):
388
    """
389
    Time input widget with admin time picker.
390
    """
391
    template_name: str = 'admin/widgets/time.html'
392

393
class AdminSplitDateTime(SplitDateTimeWidget):
394
    """
395
    Split date/time widget for admin interface.
396
    """
397
    template_name: str = 'admin/widgets/split_datetime.html'
398

399
class AdminRadioSelect(RadioSelect):
400
    """
401
    Radio button widget for admin forms.
402
    """
403
    template_name: str = 'admin/widgets/radio.html'
404

405
class AdminFileWidget(ClearableFileInput):
406
    """
407
    File upload widget with admin styling.
408
    """
409
    template_name: str = 'admin/widgets/clearable_file_input.html'
410

411
class ForeignKeyRawIdWidget(TextInput):
412
    """
413
    Raw ID widget for foreign key fields.
414
    
415
    Displays foreign key as text input with lookup popup.
416
    """
417
    template_name: str = 'admin/widgets/foreign_key_raw_id.html'
418
    
419
    def __init__(self, rel, admin_site: AdminSite, attrs: dict = None, using: str = None): ...
420
    
421
    def url_parameters(self) -> dict: ...
422
    def label_and_url_for_value(self, value) -> tuple: ...
423

424
class ManyToManyRawIdWidget(ForeignKeyRawIdWidget):
425
    """
426
    Raw ID widget for many-to-many fields.
427
    
428
    Displays many-to-many as text input with lookup popup.
429
    """
430
    template_name: str = 'admin/widgets/many_to_many_raw_id.html'
431

432
class RelatedFieldWidgetWrapper(Widget):
433
    """
434
    Wrapper widget that adds related field links.
435
    
436
    Adds change/add/delete links for foreign key widgets.
437
    """
438
    template_name: str = 'admin/widgets/related_widget_wrapper.html'
439
    
440
    def __init__(self, widget: Widget, rel, admin_site: AdminSite, can_add_related: bool = None, 
441
                 can_change_related: bool = None, can_delete_related: bool = None, can_view_related: bool = None): ...
442

443
class AutocompleteSelect(Select):
444
    """
445
    Select widget with autocomplete functionality.
446
    """
447
    template_name: str = 'admin/widgets/autocomplete_select.html'
448
    
449
    def __init__(self, rel, admin_site: AdminSite, attrs: dict = None, choices: tuple = (), using: str = None): ...
450

451
class AutocompleteSelectMultiple(SelectMultiple):
452
    """
453
    Multiple select widget with autocomplete functionality.
454
    """
455
    template_name: str = 'admin/widgets/autocomplete_select.html'
456
    
457
    def __init__(self, rel, admin_site: AdminSite, attrs: dict = None, choices: tuple = (), using: str = None): ...
458
```
459

460
### Admin Filters
461

462
Filter classes for admin change list sidebar filtering.
463

464
```python { .api }
465
class SimpleListFilter:
466
    """
467
    Base class for simple list filters.
468
    
469
    Provides dropdown filtering in admin change list sidebar.
470
    """
471
    title: str = None
472
    parameter_name: str = None
473
    template: str = 'admin/filter.html'
474
    
475
    def __init__(self, request: HttpRequest, params: dict, model, model_admin): ...
476
    def has_output(self) -> bool: ...
477
    def choices(self, changelist): ...
478
    def queryset(self, request: HttpRequest, queryset): ...
479
    def expected_parameters(self) -> list: ...
480
    def used_parameters(self) -> dict: ...
481
    def lookups(self, request: HttpRequest, model_admin): ...
482

483
class BooleanFieldListFilter(SimpleListFilter):
484
    """
485
    Filter for boolean fields with Yes/No/All options.
486
    """
487

488
class ChoicesFieldListFilter(SimpleListFilter):
489
    """
490
    Filter for fields with choices using choice values.
491
    """
492

493
class DateFieldListFilter(SimpleListFilter):
494
    """
495
    Filter for date fields with preset time ranges.
496
    """
497

498
class AllValuesFieldListFilter(SimpleListFilter):
499
    """
500
    Filter showing all distinct values for a field.
501
    """
502

503
class RelatedFieldListFilter(SimpleListFilter):
504
    """
505
    Filter for foreign key relationships.
506
    """
507

508
class RelatedOnlyFieldListFilter(RelatedFieldListFilter):
509
    """
510
    Filter for foreign keys showing only related objects.
511
    """
512

513
class EmptyFieldListFilter(SimpleListFilter):
514
    """
515
    Filter for empty/non-empty field values.
516
    """
517
```
518

519
### Admin Utilities
520

521
Utility functions and helpers for admin functionality.
522

523
```python { .api }
524
def display_for_field(value, field, empty_value_display: str) -> str:
525
    """
526
    Format field value for admin display.
527
    
528
    Args:
529
        value: Field value to format
530
        field: Model field instance
531
        empty_value_display: Text for empty values
532
        
533
    Returns:
534
        Formatted display string
535
    """
536

537
def display_for_value(value, empty_value_display: str, boolean: bool = False) -> str:
538
    """
539
    Format raw value for admin display.
540
    
541
    Args:
542
        value: Value to format
543
        empty_value_display: Text for empty values
544
        boolean: Whether to format as boolean
545
        
546
    Returns:
547
        Formatted display string
548
    """
549

550
def label_for_field(name: str, model, model_admin=None, return_attr: bool = False) -> str:
551
    """
552
    Get display label for model field or attribute.
553
    
554
    Args:
555
        name: Field or attribute name
556
        model: Model class
557
        model_admin: ModelAdmin instance
558
        return_attr: Whether to return attribute info
559
        
560
    Returns:
561
        Field label string
562
    """
563

564
def help_text_for_field(name: str, model) -> str:
565
    """
566
    Get help text for model field.
567
    
568
    Args:
569
        name: Field name
570
        model: Model class
571
        
572
    Returns:
573
        Field help text
574
    """
575

576
def flatten_fieldsets(fieldsets: list) -> list:
577
    """
578
    Extract field names from nested fieldset structure.
579
    
580
    Args:
581
        fieldsets: Nested fieldset configuration
582
        
583
    Returns:
584
        Flat list of field names
585
    """
586

587
def normalize_fieldsets(fieldsets: list) -> list:
588
    """
589
    Normalize fieldset configuration format.
590
    
591
    Args:
592
        fieldsets: Raw fieldset configuration
593
        
594
    Returns:
595
        Normalized fieldset structure
596
    """
597

598
def construct_change_message(form, formsets: list, add: bool) -> list:
599
    """
600
    Build change message for admin log entries.
601
    
602
    Args:
603
        form: Main model form
604
        formsets: List of related formsets
605
        add: Whether this is object creation
606
        
607
    Returns:
608
        List of change descriptions
609
    """
610
```
611

612
### Admin Options
613

614
Configuration constants for admin interface customization.
615

616
```python { .api }
617
HORIZONTAL: int = 1  # Horizontal filter widget layout
618
VERTICAL: int = 2    # Vertical filter widget layout
619

620
# Field display options
621
class FieldListFilter:
622
    """Base class for admin list filters."""
623

624
class ListFilter:
625
    """Base interface for admin list filtering."""
626

627
class AdminCaption:
628
    """Caption display configuration for admin."""
629

630
# Admin template contexts
631
ADMIN_TEMPLATES: dict = {
632
    'admin/base.html': 'Base admin template',
633
    'admin/change_form.html': 'Object change form template',
634
    'admin/change_list.html': 'Object list template',
635
    'admin/delete_confirmation.html': 'Delete confirmation template',
636
    'admin/object_history.html': 'Object history template',
637
    'admin/popup_response.html': 'Popup response template',
638
}
639
```