Django Documentation s.org

Django Documentation

Release 1.3.7 Django Software Foundation

January 07, 2015

Contents

1 Django documentation

1

1.1 Getting help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

1.2 First steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

1.3 The model layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

1.4 The template layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

1.5 The view layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

1.6 Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

1.7 The development process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

1.8 Other batteries included . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

1.9 The Django open-source project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

2 Getting started

5

2.1 Django at a glance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

2.2 Quick install guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

2.3 Writing your first Django app, part 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

2.4 Writing your first Django app, part 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

2.5 Writing your first Django app, part 3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

2.6 Writing your first Django app, part 4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

2.7 What to read next . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

3 Using Django

47

3.1 How to install Django . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

3.2 Models and databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

3.3 Handling HTTP requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

3.4 Working with forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151

3.5 The Django template language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180

3.6 Class-based generic views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190

3.7 Migrating function-based generic views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198

3.8 Managing files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201

3.9 Testing Django applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203

3.10 User authentication in Django . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226

3.11 Django's cache framework . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247

3.12 Conditional View Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263

3.13 Sending e-mail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266

3.14 Internationalization and localization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274

3.15 Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294

3.16 Pagination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301

3.17 Serializing Django objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305

i

3.18 Django settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310 3.19 Signals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314 3.20 Deprecated features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317

4 "How-to" guides

325

4.1 Authenticating against Django's user database from Apache . . . . . . . . . . . . . . . . . . . . . . 325

4.2 Authentication using REMOTE_USER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327

4.3 How to contribute to Django . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328

4.4 Writing custom django-admin commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332

4.5 Writing custom model fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336

4.6 Custom template tags and filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346

4.7 Writing a custom storage system . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359

4.8 Deploying Django . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361

4.9 Error reporting via e-mail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374

4.10 Providing initial data for models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375

4.11 Using internationalization in your own projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377

4.12 Running Django on Jython . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379

4.13 Integrating Django with a legacy database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380

4.14 Outputting CSV with Django . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381

4.15 Outputting PDFs with Django . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383

4.16 Managing static files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385

5 Django FAQ

393

5.1 FAQ: General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393

5.2 FAQ: Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396

5.3 FAQ: Using Django . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397

5.4 FAQ: Getting Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398

5.5 FAQ: Databases and models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399

5.6 FAQ: The admin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401

5.7 FAQ: Contributing code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402

6 API Reference

405

6.1 Authentication backends . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405

6.2 contrib packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405

6.3 Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 619

6.4 django-admin.py and manage.py . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 628

6.5 Running management commands from your code . . . . . . . . . . . . . . . . . . . . . . . . . . . . 646

6.6 Django Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 647

6.7 File handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 649

6.8 Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 652

6.9 Class-based generic views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 688

6.10 Middleware . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 705

6.11 Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 707

6.12 Request and response objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 760

6.13 TemplateResponse and SimpleTemplateResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . 769

6.14 Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 772

6.15 Signals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 798

6.16 Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 804

6.17 Unicode data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 847

6.18 Django Utils . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 852

6.19 Validators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 859

6.20 Deprecated features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 861

7 Meta-documentation and miscellany

877

7.1 API stability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 877

ii

7.2 Design philosophies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 880 7.3 Third-party distributions of Django . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 884

8 Glossary

885

9 Release notes

887

9.1 Final releases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 887

9.2 Development releases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 945

10 Django internals

979

10.1 Contributing to Django . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 979

10.2 How the Django documentation works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 997

10.3 Django committers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1000

10.4 Django's release process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1004

10.5 Django Deprecation Timeline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1007

10.6 The Django source code repository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1009

11 Indices, glossary and tables

1013

12 Deprecated/obsolete documentation

1015

12.1 Deprecated/obsolete documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1015

Python Module Index

1019

iii

 ................
................

In order to avoid copyright disputes, this page is only a partial summary.

Google Online Preview   Download