summaryrefslogtreecommitdiff
path: root/docs/topics
AgeCommit message (Collapse)Author
10 daysFixed #36022 -- Renamed django-admin to django.Ryan Hiebert
This change implements DEP 16: to rename the django-admin command to django. django-admin is kept as an alias. Docs references to the "django-admin" command are updated to "django" or “The django command”. Renamed the `django-admin` Sphinx directive to `cmd`, and the `django-admin-option` directive to `cli-option`. Thanks Johannes Maron, Mike Edmunds, and Jacob Walls for reviews.
13 daysFixed #37468 -- Clarified the effects of changing primary keys to existing ↵Sarah Boyce
values.
2026-10-28Refs #35899 -- Added allow_multiline_tags transitional template option to ↵=?UTF-8?q?Anders=20Hovm=C3=B6ller?=
disable multiline template tags. Co-authored-by: Sarah Boyce <42296566+sarahboyce@users.noreply.github.com>
2026-10-26Fixed #37232 -- Added support for the HTTP QUERY method.Michiel W. Beijen
QUERY (RFC 10008) is a safe, idempotent method that carries the query in the request content rather than in the URI's query component. Treat it as safe throughout: exempt it from CSRF protection, evaluate request preconditions as for GET, accept it in require_safe(), and dispatch it from View. Query content is available as HttpRequest.body and is not parsed into HttpRequest.POST. Caching is left for a follow-up. Per RFC 10008 Section 2.7 the cache key for a QUERY request must incorporate the request content, which the cache middleware and cache_page() don't do, so they continue to ignore QUERY. Thanks Ben Atkinson, Jonathan Biemond, and Jacob Walls for reviews.
2026-10-23Refs #30949 -- Replaced django.utils.functional.cached_property with ↵Jacob Rief
functools.cached_property. Since Python 3.12, `functools.cached_property` no longer takes a lock (https://github.com/python/cpython/issues/87634), which was the main objection to using it instead of Django's own implementation. `Prefetch(to_attr=...)` and the admindocs model detail page now accept `functools.cached_property` as well as Django's own `cached_property`. Co-authored-by: Natalia <124304+nessita@users.noreply.github.com>
2026-10-20Fixed #37431 -- Added support for serializing frozendicts in migrations.Aman Kumar Jain
2026-10-14Fixed #37409 -- Removed ambiguous "Overview" link text from the docs home page.Natalia
The docs home page used "Overview" as the link text 15 times, the only duplicated link text on that page. A reader navigating by a list of links got identical entries with no indication of which section each belonged to. A sixteenth "Overview" comes from the main site's navbar and is outside this repository. Every one of those targets already has a distinct title of its own, which `docs/index.txt` was overriding with the generic word. Most of them now use it, via `:doc:` without an explicit title. Three would have repeated their group label, and are given a short unique title instead. Also retitled five of those documents so that the home page can use their own titles: two to sentence case, matching the rest, and three to drop a redundant "in Django" suffix.
2026-10-09Refs #29504 -- Used "object" when referring to JSON keys in query docs.Jacob Walls
2026-10-09Fixed #29504 -- Documented limitations of integer-like keys in JSONField.abheetsharma09
2026-10-07Refs #37065 -- Added missing await in method_decorator example.Jacob Walls
2026-10-02Fixed #37381 -- Corrected execute_wrapper() module reference in docs.David Smith
The currentmodule directive used django.db.backends.base.DatabaseWrapper, which is not a real module path. Documented the method on the public django.db.connection object instead, consistent with the cache docs. Also indented the method description so it renders as the method body. Thanks Tim Graham for the review and Tim Schilling for the ticket. Co-authored-by: Natalia <124304+nessita@users.noreply.github.com>
2026-10-01Fixed #37167 -- Allowed email.headerregistry.Address objects as email addresses.VIZZARD-X
Address is the safe way to build an email address with a display name from variable parts (see #34753), but `ADMINS` and `MANAGERS` rejected non-string values, so it could not be used there. This branch allows `Address` instances in those settings, documents, and tests the support already present in `DEFAULT_FROM_EMAIL`, `SERVER_EMAIL`, `send_mail()`, `send_mass_mail()`, and `EmailMessage`. Co-authored-by: Natalia <124304+nessita@users.noreply.github.com>
2026-09-28Fixed #37374 -- Removed unused hyperlink targets pointing to nonexistent ↵HardMax71
docs pages.
2026-09-24Fixed #37177 -- Reduced per-middleware context switching under ASGI.Jacob Walls
Relying on MiddlewareMixin.__acall__() to handle async requests imposed per-middleware context switching, defeating BaseHandler's intent to transition only once per middleware chain. To minimize breaking changes, MiddlewareMixin's default value did not change: only the values on Django's own subclasses. Use cases where the prior behavior is preferable (in order to avoid pinning a thread per request) are fleshed out in docs. Thanks Mykhailo Havelia for the report.
2026-09-07Moved the sqlmigrate walkthrough out of the tutorial.Andreu Vallbona
Tutorial 2 interrupted the makemigrations/migrate narrative with a long sqlmigrate digression and a list of schema conventions. The command, its example output, and those notes now live where readers look for them: * docs/topics/migrations.txt gained an "Executing sqlmigrate" section, with the books models the example SQL is generated from. * docs/topics/db/models.txt absorbed the notes on table naming and on Django tailoring SQL to the database backend. * Tutorial 2 now links to the migrations topic for the details. Co-authored-by: Natalia <124304+nessita@users.noreply.github.com>
2026-09-07Fixed #37127 -- Added source links for form templates.rshide
2026-09-03Refs #37293 -- Aliased RemovedInDjango70Warning to RemovedInDjango2028Warning.Carlton Gibson
Updated references to RemovedInDjango70Warning to use the new warning, and adjusted references to "Django 7.0" to "Django 2028". RemovedInDjango70Warning remains importable as an alias of the same class, so existing warning filters and except clauses in third-party code keep working across the rename.
2026-09-02Added remaining community package mentions to the documentation.Tim Schilling
2026-08-06Fixed #37196 -- Documented SimpleTestCase.async_client_class and ↵VIZZARD-X
async_client in testing tools.
2026-08-03Refs #28586 -- Renamed RAISE fetch mode to FETCH_RAISE.Jacob Walls
This aims for consistency in the django.db.models namespace. Thanks Natalia Bidart and Simon Charette for the idea.
2026-07-24Fixed typo and versionadded locations in email docs.Mike Edmunds
* Moved versionadded annotation to top of `mailers` section. * Added versionadded to `mailers.default` to help avoid confusion over deprecated annotation in same entry. * Added missing "a" in `get_connection()` deprecation note.
2026-07-24Fixed minor typos and grammatical errors in docs and docstrings.Jacob Walls
Thanks to these people for pointing these out: * Hojeong Park * Natalia Bidart * Sulav Raj Bista
2026-07-20Refs #15855 -- Documented that cache_page caches responses before response ↵Sarah Boyce
middleware runs.
2026-07-16Fixed #37218 -- Doc'd that on-demand fetching is sync only.Jacob Walls
2026-07-14Fixed #37210 -- Logged cached_db session cache delete failures.vismaytiwari
2026-07-14Fixed #37131 -- Improved XSS section in security documentation.VIZZARD-X
Co-authored-by: Daniele Procida <evildmp@users.noreply.github.com> Co-authored-by: James Bligh <blighj@users.noreply.github.com>
2026-07-13Fixed #37178 -- Moved MiddlewareMixin out of utils.deprecation.CharulL00
2026-07-06Fixed #37172 -- Linked to upload handlers section in FILE_UPLOAD_* settings ↵Lincoln Puzey
see for details.
2026-07-01Fixed #34753 -- Extended security and safety remarks in email topics docs.Mike Edmunds
Reworked the outdated "Preventing header injection" section: * Added a "Safely sending email" section noting that the topic is relevant but beyond the scope of Django's own docs. * Added a section on correctly formatting email addresses with a variable display name to avoid injection attacks. * Updated the existing "Preventing header injection" section to note that Django (via Python) already prevents CRLF injection, but that custom email backends that bypass Django's protections may need to handle it. Also added references to the new "Formatting email addresses" section from the `ADMINS`, `DEFAULT_FROM_EMAIL`, and `SERVER_EMAIL` settings.
2026-06-30Fixed #37162 -- Updated ContactForm docs example to use safe practices.Mike Edmunds
Updated the `ContactForm` examples in the "Forms" topic and reference docs to avoid broken and unsafe practices around sending email: * Stopped using user-provided `sender` address as `from_email`. Instead, renamed to `contact_email` and used it as the `reply_to` address. * Removed `cc_myself` option to prevent using the form to send spam. Substituted an `urgent` field to demonstrate `BooleanField` use. * Identified email as coming from the contact form and added other content to reduce impersonation/phishing risks. Also updated some example output in the forms reference docs where it had drifted from the example code over time: email fields default to `maxlength=320`; the `ContactForm` example has been using a `TextArea` widget for its message field.
2026-06-26Clarified "plaintext" vs. "plain-text" in password hashers docs.Mike Edmunds
Replaced "plain-text" with "plaintext" where it is used to describe the unencrypted input to a password hashing function. (In a cryptography context this is the preferred spelling, and it is already used that way in Django's release notes.) This reduces ambiguity about whether make_password() expects UTF-8 encoded Unicode text ("plain-text bytes") or the unencrypted material for the user's password ("plaintext bytes"). (See #37184.) All other current uses of "plain text" and "plain-text" in docs and docstrings (including the one elsewhere in passwords.txt) are describing text that is plain (unformatted; not rich text).
2026-06-24Refs #37174 -- Doc'd that args to the {% cache %} tag are stringified.Jacob Walls
2026-06-23Removed additional versionchanged notices for 6.0.Jacob Walls
2026-06-19Fixed #37165 -- Updated Async Support topics doc.Carlton Gibson
Removed outdated warnings, and updated performance considerations to reflect current realities. Thanks to Mykhailo Havelia for the detailed review.
2026-06-16Fixed #37152 -- Raised ValueError when Bcc is used in EmailMessage headers.diaxoaine
Bcc addresses are sent via the SMTP envelope and must never appear in the message itself. A "Bcc" key in `extra_headers` was not excluded like From/To/Cc/Reply-To, so it leaked into the generated message as a visible header. Thanks Mike Edmunds for reviews.
2026-06-16Fixed typo in section "Configuring email" in docs/topics/email.txt.Mike Edmunds
2026-06-15Fixed password hashing anchor link for references.Tim Schilling
2026-06-15Fixed #37128 -- Doc'd setUpTestData as test speed up.Tim Schilling
Revises the AnimalTestCase to better show test data isolation and avoid the opportunity to use setUpTestData.
2026-06-11Fixed #37129 -- Clarified database cache culling behavior in docs.VIZZARD-X
2026-06-11Fixed #36837 -- Skipped backends not implementing (a)get_user() in ↵Sezer BOZKIR
(a)force_login(). Co-authored-by: Mykhailo Havelia <Arfey17.mg@gmail.com>
2026-06-08Fixed #32785 -- Optimized cull frequency for DBCache.eevelweezel
2026-06-03Fixed CVE-2026-35193 -- Varied on Authorization when caching non-public ↵Jacob Walls
responses. Thanks Shai Berger for the report, and Natalia Bidart and Sarah Boyce for reviews.
2026-05-27Fixed #35596 -- Removed mention of unlimited results from QuerySet.get().CodeQuiver
Obsolete since 330638b89f14e1fb06e9d313ccc9768ae167c53f.
2026-05-27Fixed #37065 -- Doc'd method_decorator usage on dispatch for async views.Carlton Gibson
2026-05-25Corrected indentation in topics/http/shortcuts.txt.Mariusz Felisiak
2026-05-20Removed versionadded/changed annotations for 6.0.Sarah Boyce
2026-05-20Fixed #37045 -- Renamed savepoint() to savepoint_create().Samuel Searles-Bryant
This makes the name consistent with the `savepoint_commit` and `savepoint_rollback` functions. The previous name is maintained as a deprecated alias. This also frees up the `savepoint` name, which would allow the context manager from `django-subatomic` to be included in Django. Co-authored-by: Lily <code@lilyf.org>
2026-05-20Refs #35514 -- Cleaned up mailers docs.Mike Edmunds
* Fixed typos related to automated EMAIL_PROVIDERS -> MAILERS renaming. * Clarified wording in some recently added/updated sections. * Removed deprecated, extraneous `fail_silently=False` from examples. * Moved EmailBackend API documentation out of "Email backends" intro into a dedicated section in email.txt. * Sorted MAILERS alphabetically in settings.txt.
2026-05-13Fixed #35514 -- Implemented dictionary-based MAILERS.Mike Edmunds
See DEP 0018. Added: * MAILERS setting. * django.core.mail.mailers dict-like EmailBackend factory. * `using` argument to mail sending APIs. * `sent_using` attribute to mail.outbox messages in locmem backend. * MAILERS in startproject settings template, set to console backend. * AdminLogHandler.using argument. * BrokenLinkEmailsMiddleware.send_mail() method. Updated: * BaseEmailBackend to track the MAILERS alias used to construct it, and to report errors for unknown kwargs (OPTIONS). * EmailBackend implementations to initialize from kwargs (OPTIONS) only when MAILERS is being used. * smtp.EmailBackend to require `host` option and to default `port` option based on SSL/TLS options. * SimpleTestCase setup to substitute the locmem backend for all defined MAILERS configurations. * Django's tests that send mail to define MAILERS. Deprecated: * EMAIL_BACKEND and other backend-related EMAIL_* settings. * mail.get_connection(). * The `connection`, `fail_silently`, `auth_user`, and `auth_password` arguments to mail functions. * The EmailMessage.connection attribute. * BaseEmailBackend support for `fail_silently`. Backends that support fail_silently (SMTP, console, file) now implement it directly. * AdminEmailHandler.email_backend argument. Removed undocumented features without deprecation: * EmailMessage.get_connection() method. (send() now raises an error if a subclass has attempted to override it.) * EmailMessage.send() no longer sets self.connection to the connection used for sending. (It still _uses_ a pre-existing self.connection.) * AdminEmailHandler.connection() method. (Init now raises an error if a subclass has attempted to override it.) Thanks to Natalia Bidart for shepherding DEP 0018 and for extensive reviews and suggestions on the implementation. Thanks to Jacob Rief for the initial implementation and multiple iterations while refining the design. Co-authored-by: Jacob Rief <jacob.rief@gmail.com>
2026-05-11Fixed typo in docs/topics/db/search.txt.Stephanie