django/docs/index.txt

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

347 lines
12 KiB
Plaintext
Raw Normal View History

====================
Django documentation
====================
.. rubric:: Everything you need to know about Django.
.. _index-first-steps:
First steps
===========
Are you new to Django or to programming? This is the place to start!
* **From scratch:**
:doc:`Overview <intro/overview>` |
:doc:`Installation <intro/install>`
* **Tutorial:**
:doc:`Part 1: Requests and responses <intro/tutorial01>` |
:doc:`Part 2: Models and the admin site <intro/tutorial02>` |
:doc:`Part 3: Views and templates <intro/tutorial03>` |
:doc:`Part 4: Forms and generic views <intro/tutorial04>` |
:doc:`Part 5: Testing <intro/tutorial05>` |
:doc:`Part 6: Static files <intro/tutorial06>` |
:doc:`Part 7: Customizing the admin site <intro/tutorial07>`
* **Advanced Tutorials:**
:doc:`How to write reusable apps <intro/reusable-apps>` |
:doc:`Writing your first patch for Django <intro/contributing>`
Getting help
============
Having trouble? We'd like to help!
* Try the :doc:`FAQ <faq/index>` -- it's got answers to many common questions.
* Looking for specific information? Try the :ref:`genindex`, :ref:`modindex` or
the :doc:`detailed table of contents <contents>`.
2020-03-22 02:25:17 +08:00
* Not found anything? See :doc:`faq/help` for information on getting support
and asking questions to the community.
* Report bugs with Django in our `ticket tracker`_.
.. _ticket tracker: https://code.djangoproject.com/
How the documentation is organized
==================================
Django has a lot of documentation. A high-level overview of how it's organized
will help you know where to look for certain things:
* :doc:`Tutorials </intro/index>` take you by the hand through a series of
steps to create a web application. Start here if you're new to Django or web
application development. Also look at the ":ref:`index-first-steps`".
* :doc:`Topic guides </topics/index>` discuss key topics and concepts at a
2016-01-18 14:42:54 +08:00
fairly high level and provide useful background information and explanation.
* :doc:`Reference guides </ref/index>` contain technical reference for APIs and
other aspects of Django's machinery. They describe how it works and how to
use it but assume that you have a basic understanding of key concepts.
* :doc:`How-to guides </howto/index>` are recipes. They guide you through the
steps involved in addressing key problems and use-cases. They are more
advanced than tutorials and assume some knowledge of how Django works.
The model layer
===============
Django provides an abstraction layer (the "models") for structuring and
manipulating the data of your web application. Learn more about it below:
* **Models:**
:doc:`Introduction to models <topics/db/models>` |
:doc:`Field types <ref/models/fields>` |
:doc:`Indexes <ref/models/indexes>` |
:doc:`Meta options <ref/models/options>` |
:doc:`Model class <ref/models/class>`
* **QuerySets:**
:doc:`Making queries <topics/db/queries>` |
:doc:`QuerySet method reference <ref/models/querysets>` |
:doc:`Lookup expressions <ref/models/lookups>`
* **Model instances:**
:doc:`Instance methods <ref/models/instances>` |
:doc:`Accessing related objects <ref/models/relations>`
* **Migrations:**
:doc:`Introduction to Migrations<topics/migrations>` |
:doc:`Operations reference <ref/migration-operations>` |
2015-02-04 02:09:54 +08:00
:doc:`SchemaEditor <ref/schema-editor>` |
:doc:`Writing migrations <howto/writing-migrations>`
* **Advanced:**
:doc:`Managers <topics/db/managers>` |
:doc:`Raw SQL <topics/db/sql>` |
:doc:`Transactions <topics/db/transactions>` |
:doc:`Aggregation <topics/db/aggregation>` |
:doc:`Search <topics/db/search>` |
:doc:`Custom fields <howto/custom-model-fields>` |
Fixed #16187 -- refactored ORM lookup system Allowed users to specify which lookups or transforms ("nested lookus") are available for fields. The implementation is now class based. Squashed commit of the following: commit fa7a7195f1952a9c8dea7f6e89ee13f81757eda7 Author: Anssi Kääriäinen <akaariai@gmail.com> Date: Sat Jan 18 10:53:24 2014 +0200 Added lookup registration API docs commit eb1c8ce164325e0d8641f14202e12486c70efdb6 Author: Anssi Kääriäinen <akaariai@gmail.com> Date: Tue Jan 14 18:59:36 2014 +0200 Release notes and other minor docs changes commit 11501c29c9352d17f22f3a0f59d3b805913dedcc Author: Anssi Kääriäinen <akaariai@gmail.com> Date: Sun Jan 12 20:53:03 2014 +0200 Forgot to add custom_lookups tests in prev commit commit 83173b960ea7eb2b24d573f326be59948df33536 Author: Anssi Kääriäinen <akaariai@gmail.com> Date: Sun Jan 12 19:59:12 2014 +0200 Renamed Extract -> Transform commit 3b18d9f3a1bcdd93280f79654eba0efa209377bd Author: Anssi Kääriäinen <akaariai@gmail.com> Date: Sun Jan 12 19:51:53 2014 +0200 Removed suggestion of temporary lookup registration from docs commit 21d0c7631c161fc0c67911480be5d3f13f1afa68 Merge: 2509006 f2dc442 Author: Anssi Kääriäinen <akaariai@gmail.com> Date: Sun Jan 12 09:38:23 2014 -0800 Merge pull request #2 from mjtamlyn/lookups_3 Reworked custom lookups docs. commit f2dc4429a1da04c858364972eea57a35a868dab4 Author: Marc Tamlyn <marc.tamlyn@gmail.com> Date: Sun Jan 12 13:15:05 2014 +0000 Reworked custom lookups docs. Mostly just formatting and rewording, but also replaced the example using ``YearExtract`` to use an example which is unlikely to ever be possible directly in the ORM. commit 250900650628d1f11beadb22814abd666029fb81 Author: Anssi Kääriäinen <akaariai@gmail.com> Date: Sun Jan 12 13:19:13 2014 +0200 Removed unused import commit 4fba5dfaa022653ffa72497258ffd8f8b7476f92 Author: Anssi Kääriäinen <akaariai@gmail.com> Date: Sat Jan 11 22:34:41 2014 +0200 Added docs to index commit 6d53963f375c77a1f287833b19b976d23f36c30b Author: Anssi Kääriäinen <akaariai@gmail.com> Date: Sat Jan 11 22:10:24 2014 +0200 Dead code removal commit f9cc0390078e21f1ea5a7bc1f15b09f8f6b0904d Author: Anssi Kääriäinen <akaariai@gmail.com> Date: Sat Jan 11 19:00:43 2014 +0200 A new try for docs commit 33aa18a6e3c831930bda0028222a26f9c1d96e66 Author: Anssi Kääriäinen <akaariai@gmail.com> Date: Sat Jan 11 14:57:12 2014 +0200 Renamed get_cols to get_group_by_cols commit c7d5f8661b7d364962bed2e6f81161c1b4f1bcc3 Author: Anssi Kääriäinen <akaariai@gmail.com> Date: Sat Jan 11 14:45:53 2014 +0200 Altered query string customization for backends vendors The new way is trying to call first method 'as_' + connection.vendor. If that doesn't exist, then call as_sql(). Also altered how lookup registration is done. There is now RegisterLookupMixin class that is used by Field, Extract and sql.Aggregate. This allows one to register lookups for extracts and aggregates in the same way lookup registration is done for fields. commit 90e7004ec14e15503f828cc9bde2a7dab593814d Merge: 66649ff f7c2c0a Author: Anssi Kääriäinen <akaariai@gmail.com> Date: Sat Jan 11 13:21:01 2014 +0200 Merge branch 'master' into lookups_3 commit 66649ff891c7c73c7eecf6038c9a6802611b5d8a Author: Anssi Kääriäinen <akaariai@gmail.com> Date: Sat Jan 11 13:16:01 2014 +0200 Some rewording in docs commit 31b8faa62714b4b6b6057a9f5cc106c4dd73caab Author: Anssi Kääriäinen <akaariai@gmail.com> Date: Sun Dec 29 15:52:29 2013 +0200 Cleanup based on review comments commit 1016159f34674c0df871ed891cde72be8340bb5d Author: Anssi Kääriäinen <akaariai@gmail.com> Date: Sat Dec 28 18:37:04 2013 +0200 Proof-of-concept fix for #16731 Implemented only for SQLite and PostgreSQL, and only for startswith and istartswith lookups. commit 193cd097ca8f2cc6a911e57b8e3fb726f96ee6a6 Author: Anssi Kääriäinen <akaariai@gmail.com> Date: Sat Dec 28 17:57:58 2013 +0200 Fixed #11722 -- iexact=F() produced invalid SQL commit 08ed3c3b49e100ed9019831e770c25c8f61b70f9 Author: Anssi Kääriäinen <akaariai@gmail.com> Date: Sat Dec 21 23:59:52 2013 +0200 Made Lookup and Extract available from django.db.models commit b99c8d83c972786c6fcd0e84c9e5cb08c1368300 Author: Anssi Kääriäinen <akaariai@gmail.com> Date: Sat Dec 21 23:06:29 2013 +0200 Fixed review notes by Loic commit 049eebc0703c151127f4f0265beceea7b8b39e72 Merge: ed8fab7 b80a835 Author: Anssi Kääriäinen <akaariai@gmail.com> Date: Sat Dec 21 22:53:10 2013 +0200 Merge branch 'master' into lookups_3 Conflicts: django/db/models/fields/__init__.py django/db/models/sql/compiler.py django/db/models/sql/query.py tests/null_queries/tests.py commit ed8fab7fe8867ff3eb801c3697a426478387bb2f Author: Anssi Kääriäinen <akaariai@gmail.com> Date: Sat Dec 21 22:47:23 2013 +0200 Made Extracts aware of full lookup path commit 27a57b7aed91b2f346abc4a77da838bffa17c727 Author: Anssi Kääriäinen <akaariai@gmail.com> Date: Sun Dec 1 21:10:11 2013 +0200 Removed debugger import commit 074e0f5aca0572e368c11e6d2c73c9026e7d63d7 Author: Anssi Kääriäinen <akaariai@gmail.com> Date: Sun Dec 1 21:02:16 2013 +0200 GIS lookup support added commit 760e28e72bae475b442b026650969b0d182dbe53 Author: Anssi Kääriäinen <akaariai@gmail.com> Date: Sun Dec 1 20:04:31 2013 +0200 Removed usage of Constraint, used Lookup instead commit eac47766844b90e7d3269e7a8c012eee34ec0093 Author: Anssi Kääriäinen <akaariai@gmail.com> Date: Sun Dec 1 02:22:30 2013 +0200 Minor cleanup of Lookup API commit 2adf50428d59a783078b0da3d5d035106640c899 Author: Anssi Kääriäinen <akaariai@gmail.com> Date: Sun Dec 1 02:14:19 2013 +0200 Added documentation, polished implementation commit 32c04357a87e3727a34f8c5e6ec0114d1fbbb303 Author: Anssi Kääriäinen <akaariai@gmail.com> Date: Sat Nov 30 23:10:15 2013 +0200 Avoid OrderedDict creation on lookup aggregate check commit 7c8b3a32cc17b4dbca160921d48125f1631e0df4 Author: Anssi Kääriäinen <akaariai@gmail.com> Date: Sat Nov 30 23:04:34 2013 +0200 Implemented nested lookups But there is no support of using lookups outside filtering yet. commit 4d219d4cdef21d9c14e5d6b9299d583d1975fcba Author: Anssi Kääriäinen <akaariai@gmail.com> Date: Wed Nov 27 22:07:30 2013 +0200 Initial implementation of custom lookups
2014-01-18 17:09:43 +08:00
:doc:`Multiple databases <topics/db/multi-db>` |
:doc:`Custom lookups <howto/custom-lookups>` |
:doc:`Query Expressions <ref/models/expressions>` |
:doc:`Conditional Expressions <ref/models/conditional-expressions>` |
:doc:`Database Functions <ref/models/database-functions>`
* **Other:**
:doc:`Supported databases <ref/databases>` |
:doc:`Legacy databases <howto/legacy-databases>` |
:doc:`Providing initial data <howto/initial-data>` |
Added array field support for PostgreSQL. The first part of django.contrib.postgres, including model and two form fields for arrays of other data types. This commit is formed of the following work: Add shell of postgres app and test handling. First draft of array fields. Use recursive deconstruction. Stop creating classes at lookup time. Add validation and size parameter. Add contained_by lookup. Add SimpleArrayField for forms. Add SplitArrayField (mainly for admin). Fix prepare_value for SimpleArrayField. Stop using MultiValueField and MultiWidget. They don't play nice with flexible sizes. Add basics of admin integration. Missing: - Tests - Fully working js Add reference document for django.contrib.postgres.fields.ArrayField. Various performance and style tweaks. Fix internal docs link, formalise code snippets. Remove the admin code for now. It needs a better way of handing JS widgets in the admin as a whole before it is easy to write. In particular there are serious issues involving DateTimePicker when used in an array. Add a test for nested array fields with different delimiters. This will be a documented pattern so having a test for it is useful. Add docs for SimpleArrayField. Add docs for SplitArrayField. Remove admin related code for now. definition -> description Fix typo. Py3 errors. Avoid using regexes where they're not needed. Allow passing tuples by the programmer. Add some more tests for multidimensional arrays. Also fix slicing as much as it can be fixed. Simplify SplitArrayWidget's data loading. If we aren't including the variable size one, we don't need to search like this.
2014-03-27 00:44:21 +08:00
:doc:`Optimize database access <topics/db/optimization>` |
:doc:`PostgreSQL specific features <ref/contrib/postgres/index>`
The view layer
==============
Django has the concept of "views" to encapsulate the logic responsible for
processing a user's request and for returning the response. Find all you need
to know about views via the links below:
* **The basics:**
:doc:`URLconfs <topics/http/urls>` |
:doc:`View functions <topics/http/views>` |
:doc:`Shortcuts <topics/http/shortcuts>` |
:doc:`Decorators <topics/http/decorators>` |
:doc:`Asynchronous Support <topics/async>`
* **Reference:**
:doc:`Built-in Views <ref/views>` |
:doc:`Request/response objects <ref/request-response>` |
:doc:`TemplateResponse objects <ref/template-response>`
* **File uploads:**
:doc:`Overview <topics/http/file-uploads>` |
:doc:`File objects <ref/files/file>` |
:doc:`Storage API <ref/files/storage>` |
:doc:`Managing files <topics/files>` |
:doc:`Custom storage <howto/custom-file-storage>`
* **Class-based views:**
:doc:`Overview <topics/class-based-views/index>` |
:doc:`Built-in display views <topics/class-based-views/generic-display>` |
:doc:`Built-in editing views <topics/class-based-views/generic-editing>` |
:doc:`Using mixins <topics/class-based-views/mixins>` |
:doc:`API reference <ref/class-based-views/index>` |
:doc:`Flattened index<ref/class-based-views/flattened-index>`
* **Advanced:**
:doc:`Generating CSV <howto/outputting-csv>` |
:doc:`Generating PDF <howto/outputting-pdf>`
* **Middleware:**
:doc:`Overview <topics/http/middleware>` |
:doc:`Built-in middleware classes <ref/middleware>`
The template layer
==================
The template layer provides a designer-friendly syntax for rendering the
information to be presented to the user. Learn how this syntax can be used by
designers and how it can be extended by programmers:
* **The basics:**
:doc:`Overview <topics/templates>`
* **For designers:**
:doc:`Language overview <ref/templates/language>` |
:doc:`Built-in tags and filters <ref/templates/builtins>` |
:doc:`Humanization <ref/contrib/humanize>`
* **For programmers:**
:doc:`Template API <ref/templates/api>` |
:doc:`Custom tags and filters <howto/custom-template-tags>` |
:doc:`Custom template backend <howto/custom-template-backend>`
Forms
=====
Django provides a rich framework to facilitate the creation of forms and the
manipulation of form data.
* **The basics:**
:doc:`Overview <topics/forms/index>` |
:doc:`Form API <ref/forms/api>` |
:doc:`Built-in fields <ref/forms/fields>` |
:doc:`Built-in widgets <ref/forms/widgets>`
* **Advanced:**
:doc:`Forms for models <topics/forms/modelforms>` |
:doc:`Integrating media <topics/forms/media>` |
:doc:`Formsets <topics/forms/formsets>` |
:doc:`Customizing validation <ref/forms/validation>`
The development process
=======================
Learn about the various components and tools to help you in the development and
testing of Django applications:
* **Settings:**
:doc:`Overview <topics/settings>` |
:doc:`Full list of settings <ref/settings>`
* **Applications:**
:doc:`Overview <ref/applications>`
* **Exceptions:**
:doc:`Overview <ref/exceptions>`
* **django-admin and manage.py:**
:doc:`Overview <ref/django-admin>` |
:doc:`Adding custom commands <howto/custom-management-commands>`
* **Testing:**
:doc:`Introduction <topics/testing/index>` |
:doc:`Writing and running tests <topics/testing/overview>` |
:doc:`Included testing tools <topics/testing/tools>` |
2013-05-13 04:29:34 +08:00
:doc:`Advanced topics <topics/testing/advanced>`
* **Deployment:**
:doc:`Overview <howto/deployment/index>` |
:doc:`WSGI servers <howto/deployment/wsgi/index>` |
:doc:`ASGI servers <howto/deployment/asgi/index>` |
:doc:`Deploying static files <howto/static-files/deployment>` |
:doc:`Tracking code errors by email <howto/error-reporting>` |
:doc:`Deployment checklist <howto/deployment/checklist>`
The admin
=========
Find all you need to know about the automated admin interface, one of Django's
most popular features:
* :doc:`Admin site <ref/contrib/admin/index>`
* :doc:`Admin actions <ref/contrib/admin/actions>`
* :doc:`Admin documentation generator<ref/contrib/admin/admindocs>`
Security
========
Security is a topic of paramount importance in the development of web
applications and Django provides multiple protection tools and mechanisms:
* :doc:`Security overview <topics/security>`
* :doc:`Disclosed security issues in Django <releases/security>`
* :doc:`Clickjacking protection <ref/clickjacking>`
2014-11-01 06:39:46 +08:00
* :doc:`Cross Site Request Forgery protection <ref/csrf>`
* :doc:`Cryptographic signing <topics/signing>`
* :ref:`Security Middleware <security-middleware>`
Internationalization and localization
=====================================
Django offers a robust internationalization and localization framework to
assist you in the development of applications for multiple languages and world
regions:
* :doc:`Overview <topics/i18n/index>` |
:doc:`Internationalization <topics/i18n/translation>` |
:ref:`Localization <how-to-create-language-files>` |
:doc:`Localized web UI formatting and form input <topics/i18n/formatting>`
* :doc:`Time zones </topics/i18n/timezones>`
Performance and optimization
============================
There are a variety of techniques and tools that can help get your code running
more efficiently - faster, and using fewer system resources.
* :doc:`Performance and optimization overview <topics/performance>`
Geographic framework
====================
:doc:`GeoDjango <ref/contrib/gis/index>` intends to be a world-class geographic
web framework. Its goal is to make it as easy as possible to build GIS web
applications and harness the power of spatially enabled data.
Common web application tools
============================
Django offers multiple tools commonly needed in the development of web
applications:
* **Authentication:**
:doc:`Overview <topics/auth/index>` |
:doc:`Using the authentication system <topics/auth/default>` |
:doc:`Password management <topics/auth/passwords>` |
:doc:`Customizing authentication <topics/auth/customizing>` |
:doc:`API Reference <ref/contrib/auth>`
* :doc:`Caching <topics/cache>`
* :doc:`Logging <topics/logging>`
* :doc:`Sending emails <topics/email>`
* :doc:`Syndication feeds (RSS/Atom) <ref/contrib/syndication>`
* :doc:`Pagination <topics/pagination>`
* :doc:`Messages framework <ref/contrib/messages>`
* :doc:`Serialization <topics/serialization>`
* :doc:`Sessions <topics/http/sessions>`
* :doc:`Sitemaps <ref/contrib/sitemaps>`
* :doc:`Static files management <ref/contrib/staticfiles>`
* :doc:`Data validation <ref/validators>`
Other core functionalities
==========================
Learn about some other core functionalities of the Django framework:
* :doc:`Conditional content processing <topics/conditional-view-processing>`
* :doc:`Content types and generic relations <ref/contrib/contenttypes>`
* :doc:`Flatpages <ref/contrib/flatpages>`
* :doc:`Redirects <ref/contrib/redirects>`
* :doc:`Signals <topics/signals>`
* :doc:`System check framework <topics/checks>`
* :doc:`The sites framework <ref/contrib/sites>`
* :doc:`Unicode in Django <ref/unicode>`
The Django open-source project
==============================
Learn about the development process for the Django project itself and about how
you can contribute:
* **Community:**
:doc:`How to get involved <internals/contributing/index>` |
:doc:`The release process <internals/release-process>` |
:doc:`Team organization <internals/organization>` |
:doc:`The Django source code repository <internals/git>` |
:doc:`Security policies <internals/security>` |
:doc:`Mailing lists <internals/mailing-lists>`
* **Design philosophies:**
:doc:`Overview <misc/design-philosophies>`
* **Documentation:**
:doc:`About this documentation <internals/contributing/writing-documentation>`
* **Third-party distributions:**
:doc:`Overview <misc/distributions>`
* **Django over time:**
:doc:`API stability <misc/api-stability>` |
:doc:`Release notes and upgrading instructions <releases/index>` |
:doc:`Deprecation Timeline <internals/deprecation>`