From f4daa98f48f9a25079531058fba4387949a4b54f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20Bl=C3=A4ul?= <6819464+gogowitsch@users.noreply.github.com> Date: Fri, 26 Apr 2024 14:18:16 +0200 Subject: [PATCH 01/25] Remove an unnecessary step from quickstart.md (#9387) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Since django is a dependency of djangorestframework, we don’t need to install it manually. --- docs/tutorial/quickstart.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/tutorial/quickstart.md b/docs/tutorial/quickstart.md index 7b46a44e62..a140dbce0a 100644 --- a/docs/tutorial/quickstart.md +++ b/docs/tutorial/quickstart.md @@ -15,7 +15,6 @@ Create a new Django project named `tutorial`, then start a new app called `quick source env/bin/activate # On Windows use `env\Scripts\activate` # Install Django and Django REST framework into the virtual environment - pip install django pip install djangorestframework # Set up a new project with a single application From 97c5617edcf4189e8f9dca688ce8364992567b72 Mon Sep 17 00:00:00 2001 From: Jakub Szaredko <54867641+Szaroslav@users.noreply.github.com> Date: Sat, 27 Apr 2024 12:57:48 +0200 Subject: [PATCH 02/25] Docs: Add Python 3.12 to the requirements (#9382) --- docs/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/index.md b/docs/index.md index 222b28de58..4c5f20c48f 100644 --- a/docs/index.md +++ b/docs/index.md @@ -86,7 +86,7 @@ continued development by **[signing up for a paid plan][funding]**. REST framework requires the following: -* Python (3.6, 3.7, 3.8, 3.9, 3.10, 3.11) +* Python (3.6, 3.7, 3.8, 3.9, 3.10, 3.11, 3.12) * Django (3.0, 3.1, 3.2, 4.0, 4.1, 4.2, 5.0) We **highly recommend** and only officially support the latest patch release of From f96c065607e6f4651edaeef5cb75e0b44b324c56 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Sat, 27 Apr 2024 11:58:44 +0100 Subject: [PATCH 03/25] Update README.md (#9375) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Drop unnecessary self-serving promo text. (blergh) 😅 --- README.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/README.md b/README.md index 75d177001a..cadfd73a53 100644 --- a/README.md +++ b/README.md @@ -172,8 +172,6 @@ Full documentation for the project is available at [https://www.django-rest-fram For questions and support, use the [REST framework discussion group][group], or `#restframework` on libera.chat IRC. -You may also want to [follow the author on Twitter][twitter]. - # Security Please see the [security policy][security-policy]. @@ -184,7 +182,6 @@ Please see the [security policy][security-policy]. [codecov]: https://codecov.io/github/encode/django-rest-framework?branch=master [pypi-version]: https://img.shields.io/pypi/v/djangorestframework.svg [pypi]: https://pypi.org/project/djangorestframework/ -[twitter]: https://twitter.com/starletdreaming [group]: https://groups.google.com/forum/?fromgroups#!forum/django-rest-framework [funding]: https://fund.django-rest-framework.org/topics/funding/ From 7f18ec1b536a90b1fc194ef6140a6dcd8b605051 Mon Sep 17 00:00:00 2001 From: Max Muoto Date: Sat, 27 Apr 2024 06:07:05 -0500 Subject: [PATCH 04/25] Revert "Ensure CursorPagination respects nulls in the ordering field (#8912)" (#9381) This reverts commit b1cec517ff33d633d3ebcf5794a5f0f0583fabe6. --- rest_framework/pagination.py | 16 ++--- tests/test_pagination.py | 134 +---------------------------------- 2 files changed, 8 insertions(+), 142 deletions(-) diff --git a/rest_framework/pagination.py b/rest_framework/pagination.py index 2b20e76af5..a543ceeb50 100644 --- a/rest_framework/pagination.py +++ b/rest_framework/pagination.py @@ -11,7 +11,6 @@ from django.core.paginator import InvalidPage from django.core.paginator import Paginator as DjangoPaginator -from django.db.models import Q from django.template import loader from django.utils.encoding import force_str from django.utils.translation import gettext_lazy as _ @@ -631,7 +630,7 @@ def paginate_queryset(self, queryset, request, view=None): queryset = queryset.order_by(*self.ordering) # If we have a cursor with a fixed position then filter by that. - if str(current_position) != 'None': + if current_position is not None: order = self.ordering[0] is_reversed = order.startswith('-') order_attr = order.lstrip('-') @@ -642,12 +641,7 @@ def paginate_queryset(self, queryset, request, view=None): else: kwargs = {order_attr + '__gt': current_position} - filter_query = Q(**kwargs) - # If some records contain a null for the ordering field, don't lose them. - # When reverse ordering, nulls will come last and need to be included. - if (reverse and not is_reversed) or is_reversed: - filter_query |= Q(**{order_attr + '__isnull': True}) - queryset = queryset.filter(filter_query) + queryset = queryset.filter(**kwargs) # If we have an offset cursor then offset the entire page by that amount. # We also always fetch an extra item in order to determine if there is a @@ -720,7 +714,7 @@ def get_next_link(self): # The item in this position and the item following it # have different positions. We can use this position as # our marker. - has_item_with_unique_position = position is not None + has_item_with_unique_position = True break # The item in this position has the same position as the item @@ -773,7 +767,7 @@ def get_previous_link(self): # The item in this position and the item following it # have different positions. We can use this position as # our marker. - has_item_with_unique_position = position is not None + has_item_with_unique_position = True break # The item in this position has the same position as the item @@ -896,7 +890,7 @@ def _get_position_from_instance(self, instance, ordering): attr = instance[field_name] else: attr = getattr(instance, field_name) - return None if attr is None else str(attr) + return str(attr) def get_paginated_response(self, data): return Response({ diff --git a/tests/test_pagination.py b/tests/test_pagination.py index 090eb0d813..02d443ade0 100644 --- a/tests/test_pagination.py +++ b/tests/test_pagination.py @@ -972,24 +972,17 @@ class MockQuerySet: def __init__(self, items): self.items = items - def filter(self, q): - q_args = dict(q.deconstruct()[1]) - if not q_args: - # django 3.0.x artifact - q_args = dict(q.deconstruct()[2]) - created__gt = q_args.get('created__gt') - created__lt = q_args.get('created__lt') - + def filter(self, created__gt=None, created__lt=None): if created__gt is not None: return MockQuerySet([ item for item in self.items - if item.created is None or item.created > int(created__gt) + if item.created > int(created__gt) ]) assert created__lt is not None return MockQuerySet([ item for item in self.items - if item.created is None or item.created < int(created__lt) + if item.created < int(created__lt) ]) def order_by(self, *ordering): @@ -1108,127 +1101,6 @@ def get_pages(self, url): return (previous, current, next, previous_url, next_url) -class NullableCursorPaginationModel(models.Model): - created = models.IntegerField(null=True) - - -class TestCursorPaginationWithNulls(TestCase): - """ - Unit tests for `pagination.CursorPagination` with ordering on a nullable field. - """ - - def setUp(self): - class ExamplePagination(pagination.CursorPagination): - page_size = 1 - ordering = 'created' - - self.pagination = ExamplePagination() - data = [ - None, None, 3, 4 - ] - for idx in data: - NullableCursorPaginationModel.objects.create(created=idx) - - self.queryset = NullableCursorPaginationModel.objects.all() - - get_pages = TestCursorPagination.get_pages - - def test_ascending(self): - """Test paginating one row at a time, current should go 1, 2, 3, 4, 3, 2, 1.""" - (previous, current, next, previous_url, next_url) = self.get_pages('/') - - assert previous is None - assert current == [None] - assert next == [None] - - (previous, current, next, previous_url, next_url) = self.get_pages(next_url) - - assert previous == [None] - assert current == [None] - assert next == [3] - - (previous, current, next, previous_url, next_url) = self.get_pages(next_url) - - assert previous == [3] # [None] paging artifact documented at https://github.com/ddelange/django-rest-framework/blob/3.14.0/rest_framework/pagination.py#L789 - assert current == [3] - assert next == [4] - - (previous, current, next, previous_url, next_url) = self.get_pages(next_url) - - assert previous == [3] - assert current == [4] - assert next is None - assert next_url is None - - (previous, current, next, previous_url, next_url) = self.get_pages(previous_url) - - assert previous == [None] - assert current == [3] - assert next == [4] - - (previous, current, next, previous_url, next_url) = self.get_pages(previous_url) - - assert previous == [None] - assert current == [None] - assert next == [None] # [3] paging artifact documented at https://github.com/ddelange/django-rest-framework/blob/3.14.0/rest_framework/pagination.py#L731 - - (previous, current, next, previous_url, next_url) = self.get_pages(previous_url) - - assert previous is None - assert current == [None] - assert next == [None] - - def test_descending(self): - """Test paginating one row at a time, current should go 4, 3, 2, 1, 2, 3, 4.""" - self.pagination.ordering = ('-created',) - (previous, current, next, previous_url, next_url) = self.get_pages('/') - - assert previous is None - assert current == [4] - assert next == [3] - - (previous, current, next, previous_url, next_url) = self.get_pages(next_url) - - assert previous == [None] # [4] paging artifact - assert current == [3] - assert next == [None] - - (previous, current, next, previous_url, next_url) = self.get_pages(next_url) - - assert previous == [None] # [3] paging artifact - assert current == [None] - assert next == [None] - - (previous, current, next, previous_url, next_url) = self.get_pages(next_url) - - assert previous == [None] - assert current == [None] - assert next is None - assert next_url is None - - (previous, current, next, previous_url, next_url) = self.get_pages(previous_url) - - assert previous == [3] - assert current == [None] - assert next == [None] - - (previous, current, next, previous_url, next_url) = self.get_pages(previous_url) - - assert previous == [None] - assert current == [3] - assert next == [3] # [4] paging artifact documented at https://github.com/ddelange/django-rest-framework/blob/3.14.0/rest_framework/pagination.py#L731 - - # skip back artifact - (previous, current, next, previous_url, next_url) = self.get_pages(previous_url) - (previous, current, next, previous_url, next_url) = self.get_pages(previous_url) - - (previous, current, next, previous_url, next_url) = self.get_pages(previous_url) - - assert previous is None - assert current == [4] - assert next == [3] - - def test_get_displayed_page_numbers(): """ Test our contextual page display function. From e596f43c4e8183e4639996f95477b71eba3c8d80 Mon Sep 17 00:00:00 2001 From: Terence Honles Date: Sat, 27 Apr 2024 13:15:06 +0200 Subject: [PATCH 05/25] use warnings rather than logging a warning for DecimalField warnings (#9367) --- rest_framework/fields.py | 8 +++----- tests/test_fields.py | 23 ++++++++++++++--------- 2 files changed, 17 insertions(+), 14 deletions(-) diff --git a/rest_framework/fields.py b/rest_framework/fields.py index fda656507b..cbc02e2c2b 100644 --- a/rest_framework/fields.py +++ b/rest_framework/fields.py @@ -4,9 +4,9 @@ import decimal import functools import inspect -import logging import re import uuid +import warnings from collections.abc import Mapping from enum import Enum @@ -44,8 +44,6 @@ from rest_framework.utils.timezone import valid_datetime from rest_framework.validators import ProhibitSurrogateCharactersValidator -logger = logging.getLogger("rest_framework.fields") - class empty: """ @@ -989,9 +987,9 @@ def __init__(self, max_digits, decimal_places, coerce_to_string=None, max_value= self.min_value = min_value if self.max_value is not None and not isinstance(self.max_value, decimal.Decimal): - logger.warning("max_value in DecimalField should be Decimal type.") + warnings.warn("max_value should be a Decimal instance.") if self.min_value is not None and not isinstance(self.min_value, decimal.Decimal): - logger.warning("min_value in DecimalField should be Decimal type.") + warnings.warn("min_value should be a Decimal instance.") if self.max_digits is not None and self.decimal_places is not None: self.max_whole_digits = self.max_digits - self.decimal_places diff --git a/tests/test_fields.py b/tests/test_fields.py index 2b6fc56ac0..9ac84dd210 100644 --- a/tests/test_fields.py +++ b/tests/test_fields.py @@ -4,6 +4,7 @@ import re import sys import uuid +import warnings from decimal import ROUND_DOWN, ROUND_UP, Decimal from enum import auto from unittest.mock import patch @@ -1254,15 +1255,19 @@ class TestMinMaxDecimalField(FieldValues): ) def test_warning_when_not_decimal_types(self, caplog): - import logging - serializers.DecimalField( - max_digits=3, decimal_places=1, - min_value=10, max_value=20 - ) - assert caplog.record_tuples == [ - ("rest_framework.fields", logging.WARNING, "max_value in DecimalField should be Decimal type."), - ("rest_framework.fields", logging.WARNING, "min_value in DecimalField should be Decimal type.") - ] + with warnings.catch_warnings(record=True) as w: + warnings.simplefilter('always') + + serializers.DecimalField( + max_digits=3, decimal_places=1, + min_value=10, max_value=20 + ) + + assert len(w) == 2 + assert all(issubclass(i.category, UserWarning) for i in w) + + assert 'max_value should be a Decimal instance' in str(w[0].message) + assert 'min_value should be a Decimal instance' in str(w[1].message) class TestAllowEmptyStrDecimalFieldWithValidators(FieldValues): From 430de731e7b521e95ca7d5b77a561ffc94d970c5 Mon Sep 17 00:00:00 2001 From: Peter Thomassen Date: Fri, 26 Apr 2024 12:13:17 +0200 Subject: [PATCH 06/25] Clean up project management docs --- docs/community/project-management.md | 58 +++------------------------- 1 file changed, 6 insertions(+), 52 deletions(-) diff --git a/docs/community/project-management.md b/docs/community/project-management.md index 8545fe2b72..5fadca7b67 100644 --- a/docs/community/project-management.md +++ b/docs/community/project-management.md @@ -13,55 +13,13 @@ The aim is to ensure that the project has a high ## Maintenance team -We have a quarterly maintenance cycle where new members may join the maintenance team. We currently cap the size of the team at 5 members, and may encourage folks to step out of the team for a cycle to allow new members to participate. +[Participating actively in the REST framework project](contributing.md) **does not require being part of the maintenance team**. Almost every important part of issue triage and project improvement can be actively worked on regardless of your collaborator status on the repository. -#### Current team +#### Composition -The [maintenance team for Q4 2015](https://github.com/encode/django-rest-framework/issues/2190): +The composition of the maintenance team is handled by [@tomchristie](https://github.com/encode/). Team members will be added as collaborators to the repository. -* [@tomchristie](https://github.com/encode/) -* [@xordoquy](https://github.com/xordoquy/) (Release manager.) -* [@carltongibson](https://github.com/carltongibson/) -* [@kevin-brown](https://github.com/kevin-brown/) -* [@jpadilla](https://github.com/jpadilla/) - -#### Maintenance cycles - -Each maintenance cycle is initiated by an issue being opened with the `Process` label. - -* To be considered for a maintainer role simply comment against the issue. -* Existing members must explicitly opt-in to the next cycle by check-marking their name. -* The final decision on the incoming team will be made by `@tomchristie`. - -Members of the maintenance team will be added as collaborators to the repository. - -The following template should be used for the description of the issue, and serves as the formal process for selecting the team. - - This issue is for determining the maintenance team for the *** period. - - Please see the [Project management](https://www.django-rest-framework.org/topics/project-management/) section of our documentation for more details. - - --- - - #### Renewing existing members. - - The following people are the current maintenance team. Please checkmark your name if you wish to continue to have write permission on the repository for the *** period. - - - [ ] @*** - - [ ] @*** - - [ ] @*** - - [ ] @*** - - [ ] @*** - - --- - - #### New members. - - If you wish to be considered for this or a future date, please comment against this or subsequent issues. - - To modify this process for future maintenance cycles make a pull request to the [project management](https://www.django-rest-framework.org/topics/project-management/) documentation. - -#### Responsibilities of team members +#### Responsibilities Team members have the following responsibilities. @@ -78,16 +36,12 @@ Further notes for maintainers: * Each issue/pull request should have exactly one label once triaged. * Search for un-triaged issues with [is:open no:label][un-triaged]. -It should be noted that participating actively in the REST framework project clearly **does not require being part of the maintenance team**. Almost every import part of issue triage and project improvement can be actively worked on regardless of your collaborator status on the repository. - --- ## Release process -The release manager is selected on every quarterly maintenance cycle. - -* The manager should be selected by `@tomchristie`. -* The manager will then have the maintainer role added to PyPI package. +* The release manager is selected by `@tomchristie`. +* The release manager will then have the maintainer role added to PyPI package. * The previous manager will then have the maintainer role removed from the PyPI package. Our PyPI releases will be handled by either the current release manager, or by `@tomchristie`. Every release should have an open issue tagged with the `Release` label and marked against the appropriate milestone. From f642d85be26e0c7b7733a774363528022e769f7f Mon Sep 17 00:00:00 2001 From: Peter Thomassen Date: Fri, 26 Apr 2024 12:13:39 +0200 Subject: [PATCH 07/25] Fix docs typo --- docs/community/project-management.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/community/project-management.md b/docs/community/project-management.md index 5fadca7b67..4f203e13bb 100644 --- a/docs/community/project-management.md +++ b/docs/community/project-management.md @@ -152,7 +152,7 @@ If `@tomchristie` ceases to participate in the project then `@j4mie` has respons The following issues still need to be addressed: -* Ensure `@jamie` has back-up access to the `django-rest-framework.org` domain setup and admin. +* Ensure `@j4mie` has back-up access to the `django-rest-framework.org` domain setup and admin. * Document ownership of the [mailing list][mailing-list] and IRC channel. * Document ownership and management of the security mailing list. From 52bfe20decf2e637cbb4ce848601556999c72bdb Mon Sep 17 00:00:00 2001 From: Peter Thomassen Date: Fri, 26 Apr 2024 15:13:37 +0200 Subject: [PATCH 08/25] Adapt docs to reflect stability-focused contribution policy --- docs/community/contributing.md | 15 ++++++--------- docs/community/release-notes.md | 8 +++++--- docs/index.md | 2 +- docs_theme/css/default.css | 14 ++++++++++++++ mkdocs.yml | 1 + 5 files changed, 27 insertions(+), 13 deletions(-) diff --git a/docs/community/contributing.md b/docs/community/contributing.md index 994226b97a..5dea6426db 100644 --- a/docs/community/contributing.md +++ b/docs/community/contributing.md @@ -6,11 +6,9 @@ There are many ways you can contribute to Django REST framework. We'd like it to be a community-led project, so please get involved and help shape the future of the project. ---- +!!! note -**Note**: At this point in it's lifespan we consider Django REST framework to be essentially feature-complete. We may accept pull requests that track the continued development of Django versions, but would prefer not to accept new features or code formatting changes. - ---- + At this point in its lifespan we consider Django REST framework to be feature-complete. We focus on pull requests that track the continued development of Django versions, and generally do not accept new features or code formatting changes. ## Community @@ -36,10 +34,9 @@ Our contribution process is that the [GitHub discussions page](https://github.co Some tips on good potential issue reporting: -* When describing issues try to phrase your ticket in terms of the *behavior* you think needs changing rather than the *code* you think need changing. +* Django REST framework is considered feature-complete. Please do not file requests to change behavior, unless it is required for security reasons or to maintain compatibility with upcoming Django or Python versions. * Search the GitHub project page for related items, and make sure you're running the latest version of REST framework before reporting an issue. -* Feature requests will often be closed with a recommendation that they be implemented outside of the core REST framework library. Keeping new feature requests implemented as third party libraries allows us to keep down the maintenance overhead of REST framework, so that the focus can be on continued stability, bugfixes, and great documentation. At this point in it's lifespan we consider Django REST framework to be essentially feature-complete. -* Closing an issue doesn't necessarily mean the end of a discussion. If you believe your issue has been closed incorrectly, explain why and we'll consider if it needs to be reopened. +* Feature requests will typically be closed with a recommendation that they be implemented outside the core REST framework library (e.g. as third-party libraries). This approach allows us to keep down the maintenance overhead of REST framework, so that the focus can be on continued stability and great documentation. ## Triaging issues @@ -48,8 +45,8 @@ Getting involved in triaging incoming issues is a good way to start contributing * Read through the ticket - does it make sense, is it missing any context that would help explain it better? * Is the ticket reported in the correct place, would it be better suited as a discussion on the discussion group? * If the ticket is a bug report, can you reproduce it? Are you able to write a failing test case that demonstrates the issue and that can be submitted as a pull request? -* If the ticket is a feature request, do you agree with it, and could the feature request instead be implemented as a third party package? -* If a ticket hasn't had much activity and it addresses something you need, then comment on the ticket and try to find out what's needed to get it moving again. +* If the ticket is a feature request, could the feature request instead be implemented as a third party package? +* If a ticket hasn't had much activity and addresses something you need, then comment on the ticket and try to find out what's needed to get it moving again. # Development diff --git a/docs/community/release-notes.md b/docs/community/release-notes.md index 6da3efb9f5..f983424da4 100644 --- a/docs/community/release-notes.md +++ b/docs/community/release-notes.md @@ -2,11 +2,13 @@ ## Versioning -Minor version numbers (0.0.x) are used for changes that are API compatible. You should be able to upgrade between minor point releases without any other code changes. +- **Minor** version numbers (0.0.x) are used for changes that are API compatible. You should be able to upgrade between minor point releases without any other code changes. -Medium version numbers (0.x.0) may include API changes, in line with the [deprecation policy][deprecation-policy]. You should read the release notes carefully before upgrading between medium point releases. +- **Medium** version numbers (0.x.0) may include API changes, in line with the [deprecation policy][deprecation-policy]. You should read the release notes carefully before upgrading between medium point releases. -Major version numbers (x.0.0) are reserved for substantial project milestones. +- **Major** version numbers (x.0.0) are reserved for substantial project milestones. + +As REST Framework is considered feature-complete, most releases are expected to be minor releases. ## Deprecation policy diff --git a/docs/index.md b/docs/index.md index 4c5f20c48f..adc66226ee 100644 --- a/docs/index.md +++ b/docs/index.md @@ -184,7 +184,7 @@ Can't wait to get started? The [quickstart guide][quickstart] is the fastest way ## Development See the [Contribution guidelines][contributing] for information on how to clone -the repository, run the test suite and contribute changes back to REST +the repository, run the test suite and help maintain the code base of REST Framework. ## Support diff --git a/docs_theme/css/default.css b/docs_theme/css/default.css index 7006f2a668..dfde262933 100644 --- a/docs_theme/css/default.css +++ b/docs_theme/css/default.css @@ -439,3 +439,17 @@ ul.sponsor { display: inline-block !important; } +/* admonition */ +.admonition { + border: .075rem solid #448aff; + border-radius: .2rem; + margin: 1.5625em 0; + padding: 0 .6rem; +} +.admonition-title { + background: #448aff1a; + font-weight: 700; + margin: 0 -.6rem 1em; + padding: 0.4rem 0.6rem; +} + diff --git a/mkdocs.yml b/mkdocs.yml index 79831fe95a..a031dd69b3 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -9,6 +9,7 @@ theme: custom_dir: docs_theme markdown_extensions: + - admonition - toc: anchorlink: True From 861b7ac42b2c0f3a82f9c3fc0fd49e2393e52ca3 Mon Sep 17 00:00:00 2001 From: Peter Thomassen Date: Fri, 26 Apr 2024 15:27:55 +0200 Subject: [PATCH 09/25] Adapt issue/PR template to better reflect contribution policy --- .github/ISSUE_TEMPLATE/1-issue.md | 9 ++++++++- PULL_REQUEST_TEMPLATE.md | 2 +- 2 files changed, 9 insertions(+), 2 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/1-issue.md b/.github/ISSUE_TEMPLATE/1-issue.md index 0da1549534..87fa57a893 100644 --- a/.github/ISSUE_TEMPLATE/1-issue.md +++ b/.github/ISSUE_TEMPLATE/1-issue.md @@ -5,6 +5,13 @@ about: Please only raise an issue if you've been advised to do so after discussi ## Checklist + + - [ ] Raised initially as discussion #... -- [ ] This cannot be dealt with as a third party library. (We prefer new functionality to be [in the form of third party libraries](https://www.django-rest-framework.org/community/third-party-packages/#about-third-party-packages) where possible.) +- [ ] This is not a feature request suitable for implementation outside this project. Please elaborate what it is: + - [ ] compatibility fix for new Django/Python version ... + - [ ] other type of bug fix + - [ ] other type of improvement that does not touch existing code or change existing behavior (e.g. wrapper for new Django field) - [ ] I have reduced the issue to the simplest possible case. diff --git a/PULL_REQUEST_TEMPLATE.md b/PULL_REQUEST_TEMPLATE.md index e9230d5c99..1c6881858f 100644 --- a/PULL_REQUEST_TEMPLATE.md +++ b/PULL_REQUEST_TEMPLATE.md @@ -1,4 +1,4 @@ -*Note*: Before submitting this pull request, please review our [contributing guidelines](https://www.django-rest-framework.org/community/contributing/#pull-requests). +*Note*: Before submitting a code change, please review our [contributing guidelines](https://www.django-rest-framework.org/community/contributing/#pull-requests). ## Description From 7900778fbeec79a1994d577ed33e13b0ef2e51f3 Mon Sep 17 00:00:00 2001 From: Peter Thomassen Date: Fri, 26 Apr 2024 20:04:12 +0200 Subject: [PATCH 10/25] Remove obsolete sentence from docs --- docs/api-guide/serializers.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/api-guide/serializers.md b/docs/api-guide/serializers.md index 0f355c76d2..eae79b62f6 100644 --- a/docs/api-guide/serializers.md +++ b/docs/api-guide/serializers.md @@ -845,8 +845,6 @@ Here's an example of how you might choose to implement multiple updates: class Meta: list_serializer_class = BookListSerializer -It is possible that a third party package may be included alongside the 3.1 release that provides some automatic support for multiple update operations, similar to the `allow_add_remove` behavior that was present in REST framework 2. - #### Customizing ListSerializer initialization When a serializer with `many=True` is instantiated, we need to determine which arguments and keyword arguments should be passed to the `.__init__()` method for both the child `Serializer` class, and for the parent `ListSerializer` class. From 91bbac1f673390df32a39f59cede25d7a4577ff0 Mon Sep 17 00:00:00 2001 From: Peter Thomassen Date: Fri, 26 Apr 2024 15:48:51 +0200 Subject: [PATCH 11/25] bump mkdocs, no longer need to pin jinja2 Addresses https://github.com/encode/django-rest-framework/security/dependabot/11 --- requirements/requirements-documentation.txt | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/requirements/requirements-documentation.txt b/requirements/requirements-documentation.txt index 25f5121f2e..2cf936ef38 100644 --- a/requirements/requirements-documentation.txt +++ b/requirements/requirements-documentation.txt @@ -1,6 +1,5 @@ # MkDocs to build our documentation. -mkdocs==1.2.4 -jinja2>=2.10,<3.1.0 # contextfilter has been renamed +mkdocs==1.6.0 # pylinkvalidator to check for broken links in documentation. pylinkvalidator==0.3 From 1f2daaf53cb1e62080be99ea15986f607a193817 Mon Sep 17 00:00:00 2001 From: Peter Thomassen Date: Fri, 26 Apr 2024 16:49:58 +0200 Subject: [PATCH 12/25] Drop support for Django < 4.2 and Python < 3.8 Discussion: https://github.com/encode/django-rest-framework/discussions/8814#discussioncomment-9237791 --- .github/workflows/main.yml | 11 ----------- README.md | 4 ++-- docs/index.md | 4 ++-- setup.py | 13 +++---------- tox.ini | 12 ++---------- 5 files changed, 9 insertions(+), 35 deletions(-) diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index c3c587cbf1..6276dddcde 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -14,8 +14,6 @@ jobs: strategy: matrix: python-version: - - '3.6' - - '3.7' - '3.8' - '3.9' - '3.10' @@ -37,18 +35,9 @@ jobs: - name: Install dependencies run: python -m pip install --upgrade codecov tox - - name: Install tox-py - if: ${{ matrix.python-version == '3.6' }} - run: python -m pip install --upgrade tox-py - - name: Run tox targets for ${{ matrix.python-version }} - if: ${{ matrix.python-version != '3.6' }} run: tox run -f py$(echo ${{ matrix.python-version }} | tr -d .) - - name: Run tox targets for ${{ matrix.python-version }} - if: ${{ matrix.python-version == '3.6' }} - run: tox --py current - - name: Run extra tox targets if: ${{ matrix.python-version == '3.9' }} run: | diff --git a/README.md b/README.md index cadfd73a53..d32fbc331c 100644 --- a/README.md +++ b/README.md @@ -53,8 +53,8 @@ Some reasons you might want to use REST framework: # Requirements -* Python 3.6+ -* Django 5.0, 4.2, 4.1, 4.0, 3.2, 3.1, 3.0 +* Python 3.8+ +* Django 5.0, 4.2 We **highly recommend** and only officially support the latest patch release of each Python and Django series. diff --git a/docs/index.md b/docs/index.md index adc66226ee..98cbf6a401 100644 --- a/docs/index.md +++ b/docs/index.md @@ -86,8 +86,8 @@ continued development by **[signing up for a paid plan][funding]**. REST framework requires the following: -* Python (3.6, 3.7, 3.8, 3.9, 3.10, 3.11, 3.12) -* Django (3.0, 3.1, 3.2, 4.0, 4.1, 4.2, 5.0) +* Django (4.2, 5.0) +* Python (3.8, 3.9, 3.10, 3.11, 3.12) We **highly recommend** and only officially support the latest patch release of each Python and Django series. diff --git a/setup.py b/setup.py index 40898b6c15..d2cfe877e2 100755 --- a/setup.py +++ b/setup.py @@ -8,7 +8,7 @@ from setuptools import find_packages, setup CURRENT_PYTHON = sys.version_info[:2] -REQUIRED_PYTHON = (3, 6) +REQUIRED_PYTHON = (3, 8) # This check and everything above must remain compatible with Python 2.7. if CURRENT_PYTHON < REQUIRED_PYTHON: @@ -83,18 +83,13 @@ def get_version(package): author_email='tom@tomchristie.com', # SEE NOTE BELOW (*) packages=find_packages(exclude=['tests*']), include_package_data=True, - install_requires=["django>=3.0", 'backports.zoneinfo;python_version<"3.9"'], - python_requires=">=3.6", + install_requires=["django>=4.2", 'backports.zoneinfo;python_version<"3.9"'], + python_requires=">=3.8", zip_safe=False, classifiers=[ 'Development Status :: 5 - Production/Stable', 'Environment :: Web Environment', 'Framework :: Django', - 'Framework :: Django :: 3.0', - 'Framework :: Django :: 3.1', - 'Framework :: Django :: 3.2', - 'Framework :: Django :: 4.0', - 'Framework :: Django :: 4.1', 'Framework :: Django :: 4.2', 'Framework :: Django :: 5.0', 'Intended Audience :: Developers', @@ -102,8 +97,6 @@ def get_version(package): 'Operating System :: OS Independent', 'Programming Language :: Python', 'Programming Language :: Python :: 3', - 'Programming Language :: Python :: 3.6', - 'Programming Language :: Python :: 3.7', 'Programming Language :: Python :: 3.8', 'Programming Language :: Python :: 3.9', 'Programming Language :: Python :: 3.10', diff --git a/tox.ini b/tox.ini index ffcbd6729d..45429371d6 100644 --- a/tox.ini +++ b/tox.ini @@ -1,10 +1,7 @@ [tox] envlist = - {py36,py37,py38,py39}-django30 - {py36,py37,py38,py39}-django31 - {py36,py37,py38,py39,py310}-django32 - {py38,py39,py310}-{django40,django41,django42,djangomain} - {py311}-{django41,django42,django50,djangomain} + {py38,py39,py310}-{django42,djangomain} + {py311}-{django42,django50,djangomain} {py312}-{django42,djanggo50,djangomain} base dist @@ -17,11 +14,6 @@ setenv = PYTHONDONTWRITEBYTECODE=1 PYTHONWARNINGS=once deps = - django30: Django>=3.0,<3.1 - django31: Django>=3.1,<3.2 - django32: Django>=3.2,<4.0 - django40: Django>=4.0,<4.1 - django41: Django>=4.1,<4.2 django42: Django>=4.2,<5.0 django50: Django>=5.0,<5.1 djangomain: https://github.com/django/django/archive/main.tar.gz From 82d91a85fffea6a3cab2aa2c8bdd86e5581ccd7a Mon Sep 17 00:00:00 2001 From: Peter Thomassen Date: Fri, 26 Apr 2024 17:16:28 +0200 Subject: [PATCH 13/25] Fix tox config --- tox.ini | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/tox.ini b/tox.ini index 45429371d6..16cc3f8f44 100644 --- a/tox.ini +++ b/tox.ini @@ -1,8 +1,9 @@ [tox] envlist = - {py38,py39,py310}-{django42,djangomain} + {py38,py39}-{django42} + {py310}-{django42,django50,djangomain} {py311}-{django42,django50,djangomain} - {py312}-{django42,djanggo50,djangomain} + {py312}-{django42,django50,djangomain} base dist docs From d38aab39e49e2c9ba8f06b89b3de1e0ff29c207f Mon Sep 17 00:00:00 2001 From: Peter Thomassen Date: Fri, 26 Apr 2024 16:50:27 +0200 Subject: [PATCH 14/25] Remove unused code --- rest_framework/__init__.py | 6 ------ rest_framework/authtoken/__init__.py | 4 ---- rest_framework/compat.py | 24 --------------------- rest_framework/filters.py | 4 ---- rest_framework/parsers.py | 2 +- rest_framework/renderers.py | 3 ++- rest_framework/request.py | 2 +- rest_framework/test.py | 17 ++------------- rest_framework/utils/mediatypes.py | 2 +- tests/authentication/test_authentication.py | 17 ++++----------- tests/conftest.py | 8 +------ tests/test_model_serializer.py | 10 +++------ tests/test_testing.py | 17 ++++----------- 13 files changed, 19 insertions(+), 97 deletions(-) diff --git a/rest_framework/__init__.py b/rest_framework/__init__.py index fe2eab04ba..4bd5bdbdab 100644 --- a/rest_framework/__init__.py +++ b/rest_framework/__init__.py @@ -7,8 +7,6 @@ \_| \_\____/\____/ \_/ |_| |_| \__,_|_| |_| |_|\___| \_/\_/ \___/|_| |_|\_| """ -import django - __title__ = 'Django REST framework' __version__ = '3.15.1' __author__ = 'Tom Christie' @@ -25,10 +23,6 @@ ISO_8601 = 'iso-8601' -if django.VERSION < (3, 2): - default_app_config = 'rest_framework.apps.RestFrameworkConfig' - - class RemovedInDRF315Warning(DeprecationWarning): pass diff --git a/rest_framework/authtoken/__init__.py b/rest_framework/authtoken/__init__.py index 285fe15c6b..e69de29bb2 100644 --- a/rest_framework/authtoken/__init__.py +++ b/rest_framework/authtoken/__init__.py @@ -1,4 +0,0 @@ -import django - -if django.VERSION < (3, 2): - default_app_config = 'rest_framework.authtoken.apps.AuthTokenConfig' diff --git a/rest_framework/compat.py b/rest_framework/compat.py index afc06b6cb7..27c5632be5 100644 --- a/rest_framework/compat.py +++ b/rest_framework/compat.py @@ -151,30 +151,6 @@ def md_filter_add_syntax_highlight(md): return False -if django.VERSION >= (4, 2): - # Django 4.2+: use the stock parse_header_parameters function - # Note: Django 4.1 also has an implementation of parse_header_parameters - # which is slightly different from the one in 4.2, it needs - # the compatibility shim as well. - from django.utils.http import parse_header_parameters -else: - # Django <= 4.1: create a compatibility shim for parse_header_parameters - from django.http.multipartparser import parse_header - - def parse_header_parameters(line): - # parse_header works with bytes, but parse_header_parameters - # works with strings. Call encode to convert the line to bytes. - main_value_pair, params = parse_header(line.encode()) - return main_value_pair, { - # parse_header will convert *some* values to string. - # parse_header_parameters converts *all* values to string. - # Make sure all values are converted by calling decode on - # any remaining non-string values. - k: v if isinstance(v, str) else v.decode() - for k, v in params.items() - } - - if django.VERSION >= (5, 1): # Django 5.1+: use the stock ip_address_validators function # Note: Before Django 5.1, ip_address_validators returns a tuple containing diff --git a/rest_framework/filters.py b/rest_framework/filters.py index 435c30c88d..3f4730da84 100644 --- a/rest_framework/filters.py +++ b/rest_framework/filters.py @@ -114,10 +114,6 @@ def construct_search(self, field_name, queryset): if hasattr(field, "path_infos"): # Update opts to follow the relation. opts = field.path_infos[-1].to_opts - # django < 4.1 - elif hasattr(field, 'get_path_info'): - # Update opts to follow the relation. - opts = field.get_path_info()[-1].to_opts # Otherwise, use the field with icontains. lookup = 'icontains' return LOOKUP_SEP.join([field_name, lookup]) diff --git a/rest_framework/parsers.py b/rest_framework/parsers.py index f0fd2b8844..0e8e4bcb8d 100644 --- a/rest_framework/parsers.py +++ b/rest_framework/parsers.py @@ -15,9 +15,9 @@ from django.http.multipartparser import \ MultiPartParser as DjangoMultiPartParser from django.http.multipartparser import MultiPartParserError +from django.utils.http import parse_header_parameters from rest_framework import renderers -from rest_framework.compat import parse_header_parameters from rest_framework.exceptions import ParseError from rest_framework.settings import api_settings from rest_framework.utils import json diff --git a/rest_framework/renderers.py b/rest_framework/renderers.py index db1fdd128b..ea73c6657e 100644 --- a/rest_framework/renderers.py +++ b/rest_framework/renderers.py @@ -19,12 +19,13 @@ from django.template import engines, loader from django.urls import NoReverseMatch from django.utils.html import mark_safe +from django.utils.http import parse_header_parameters from django.utils.safestring import SafeString from rest_framework import VERSION, exceptions, serializers, status from rest_framework.compat import ( INDENT_SEPARATORS, LONG_SEPARATORS, SHORT_SEPARATORS, coreapi, coreschema, - parse_header_parameters, pygments_css, yaml + pygments_css, yaml ) from rest_framework.exceptions import ParseError from rest_framework.request import is_form_media_type, override_method diff --git a/rest_framework/request.py b/rest_framework/request.py index 93109226d9..f30578fa24 100644 --- a/rest_framework/request.py +++ b/rest_framework/request.py @@ -16,9 +16,9 @@ from django.http import HttpRequest, QueryDict from django.http.request import RawPostDataException from django.utils.datastructures import MultiValueDict +from django.utils.http import parse_header_parameters from rest_framework import exceptions -from rest_framework.compat import parse_header_parameters from rest_framework.settings import api_settings diff --git a/rest_framework/test.py b/rest_framework/test.py index 04409f9621..e939adcd7e 100644 --- a/rest_framework/test.py +++ b/rest_framework/test.py @@ -3,7 +3,6 @@ import io from importlib import import_module -import django from django.conf import settings from django.core.exceptions import ImproperlyConfigured from django.core.handlers.wsgi import WSGIHandler @@ -394,19 +393,7 @@ def setUpClass(cls): cls._override.enable() - if django.VERSION > (4, 0): - cls.addClassCleanup(cls._override.disable) - cls.addClassCleanup(cleanup_url_patterns, cls) + cls.addClassCleanup(cls._override.disable) + cls.addClassCleanup(cleanup_url_patterns, cls) super().setUpClass() - - if django.VERSION < (4, 0): - @classmethod - def tearDownClass(cls): - super().tearDownClass() - cls._override.disable() - - if hasattr(cls, '_module_urlpatterns'): - cls._module.urlpatterns = cls._module_urlpatterns - else: - del cls._module.urlpatterns diff --git a/rest_framework/utils/mediatypes.py b/rest_framework/utils/mediatypes.py index b9004d4963..8641732f00 100644 --- a/rest_framework/utils/mediatypes.py +++ b/rest_framework/utils/mediatypes.py @@ -3,7 +3,7 @@ See https://www.w3.org/Protocols/rfc2616/rfc2616-sec3.html#sec3.7 """ -from rest_framework.compat import parse_header_parameters +from django.utils.http import parse_header_parameters def media_type_matches(lhs, rhs): diff --git a/tests/authentication/test_authentication.py b/tests/authentication/test_authentication.py index 22e837ef40..2f05ce7d19 100644 --- a/tests/authentication/test_authentication.py +++ b/tests/authentication/test_authentication.py @@ -1,6 +1,5 @@ import base64 -import django import pytest from django.conf import settings from django.contrib.auth.models import User @@ -235,21 +234,13 @@ def test_post_form_session_auth_passing_csrf(self): Ensure POSTing form over session authentication with CSRF token succeeds. Regression test for #6088 """ - # Remove this shim when dropping support for Django 3.0. - if django.VERSION < (3, 1): - from django.middleware.csrf import _get_new_csrf_token - else: - from django.middleware.csrf import ( - _get_new_csrf_string, _mask_cipher_secret - ) - - def _get_new_csrf_token(): - return _mask_cipher_secret(_get_new_csrf_string()) - self.csrf_client.login(username=self.username, password=self.password) # Set the csrf_token cookie so that CsrfViewMiddleware._get_token() works - token = _get_new_csrf_token() + from django.middleware.csrf import ( + _get_new_csrf_string, _mask_cipher_secret + ) + token = _mask_cipher_secret(_get_new_csrf_string()) self.csrf_client.cookies[settings.CSRF_COOKIE_NAME] = token # Post the token matching the cookie value diff --git a/tests/conftest.py b/tests/conftest.py index b67475d8a7..01914ae778 100644 --- a/tests/conftest.py +++ b/tests/conftest.py @@ -13,8 +13,6 @@ def pytest_addoption(parser): def pytest_configure(config): from django.conf import settings - # USE_L10N is deprecated, and will be removed in Django 5.0. - use_l10n = {"USE_L10N": True} if django.VERSION < (4, 0) else {} settings.configure( DEBUG_PROPAGATE_EXCEPTIONS=True, DATABASES={ @@ -64,7 +62,6 @@ def pytest_configure(config): PASSWORD_HASHERS=( 'django.contrib.auth.hashers.MD5PasswordHasher', ), - **use_l10n, ) # guardian is optional @@ -87,10 +84,7 @@ def pytest_configure(config): import rest_framework settings.STATIC_ROOT = os.path.join(os.path.dirname(rest_framework.__file__), 'static-root') backend = 'django.contrib.staticfiles.storage.ManifestStaticFilesStorage' - if django.VERSION < (4, 2): - settings.STATICFILES_STORAGE = backend - else: - settings.STORAGES['staticfiles']['BACKEND'] = backend + settings.STORAGES['staticfiles']['BACKEND'] = backend django.setup() diff --git a/tests/test_model_serializer.py b/tests/test_model_serializer.py index d69f1652d4..ae1a2b0fa1 100644 --- a/tests/test_model_serializer.py +++ b/tests/test_model_serializer.py @@ -12,7 +12,6 @@ import sys import tempfile -import django import pytest from django.core.exceptions import ImproperlyConfigured from django.core.serializers.json import DjangoJSONEncoder @@ -453,14 +452,11 @@ class Meta: model = ArrayFieldModel fields = ['array_field', 'array_field_with_blank'] - validators = "" - if django.VERSION < (4, 1): - validators = ", validators=[]" expected = dedent(""" TestSerializer(): - array_field = ListField(allow_empty=False, child=CharField(label='Array field'%s)) - array_field_with_blank = ListField(child=CharField(label='Array field with blank'%s), required=False) - """ % (validators, validators)) + array_field = ListField(allow_empty=False, child=CharField(label='Array field')) + array_field_with_blank = ListField(child=CharField(label='Array field with blank'), required=False) + """) self.assertEqual(repr(TestSerializer()), expected) @pytest.mark.skipif(hasattr(models, 'JSONField'), reason='has models.JSONField') diff --git a/tests/test_testing.py b/tests/test_testing.py index 196319a29e..7c2a09fae4 100644 --- a/tests/test_testing.py +++ b/tests/test_testing.py @@ -2,7 +2,6 @@ from io import BytesIO from unittest.mock import patch -import django from django.contrib.auth.models import User from django.http import HttpResponseRedirect from django.shortcuts import redirect @@ -334,18 +333,10 @@ def setUpClass(cls): super().setUpClass() assert urlpatterns is cls.urlpatterns - if django.VERSION > (4, 0): - cls.addClassCleanup( - check_urlpatterns, - cls - ) - - if django.VERSION < (4, 0): - @classmethod - def tearDownClass(cls): - assert urlpatterns is cls.urlpatterns - super().tearDownClass() - assert urlpatterns is not cls.urlpatterns + cls.addClassCleanup( + check_urlpatterns, + cls + ) def test_urlpatterns(self): assert self.client.get('/').status_code == 200 From d58b8da591120abedc94c1b71576cb9afb2d7868 Mon Sep 17 00:00:00 2001 From: Peter Thomassen Date: Fri, 26 Apr 2024 16:50:40 +0200 Subject: [PATCH 15/25] Update deprecation hints --- rest_framework/__init__.py | 2 +- rest_framework/schemas/openapi.py | 6 +++--- tests/test_fields.py | 2 +- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/rest_framework/__init__.py b/rest_framework/__init__.py index 4bd5bdbdab..bc16b221b2 100644 --- a/rest_framework/__init__.py +++ b/rest_framework/__init__.py @@ -23,7 +23,7 @@ ISO_8601 = 'iso-8601' -class RemovedInDRF315Warning(DeprecationWarning): +class RemovedInDRF316Warning(DeprecationWarning): pass diff --git a/rest_framework/schemas/openapi.py b/rest_framework/schemas/openapi.py index 38031e646d..f35106fe5a 100644 --- a/rest_framework/schemas/openapi.py +++ b/rest_framework/schemas/openapi.py @@ -12,7 +12,7 @@ from django.utils.encoding import force_str from rest_framework import ( - RemovedInDRF315Warning, exceptions, renderers, serializers + RemovedInDRF316Warning, exceptions, renderers, serializers ) from rest_framework.compat import inflection, uritemplate from rest_framework.fields import _UnvalidatedField, empty @@ -725,7 +725,7 @@ def get_tags(self, path, method): def _get_reference(self, serializer): warnings.warn( "Method `_get_reference()` has been renamed to `get_reference()`. " - "The old name will be removed in DRF v3.15.", - RemovedInDRF315Warning, stacklevel=2 + "The old name will be removed in DRF v3.16.", + RemovedInDRF316Warning, stacklevel=2 ) return self.get_reference(serializer) diff --git a/tests/test_fields.py b/tests/test_fields.py index 9ac84dd210..4306817634 100644 --- a/tests/test_fields.py +++ b/tests/test_fields.py @@ -1633,7 +1633,7 @@ def test_should_render_date_time_in_default_timezone(self): assert rendered_date == rendered_date_in_timezone -@pytest.mark.skipif(pytz is None, reason="As Django 4.0 has deprecated pytz, this test should eventually be able to get removed.") +@pytest.mark.skipif(pytz is None, reason="Django 5.0 has removed pytz; this test should eventually be able to get removed.") class TestPytzNaiveDayLightSavingTimeTimeZoneDateTimeField(FieldValues): """ Invalid values for `DateTimeField` with datetime in DST shift (non-existing or ambiguous) and timezone with DST. From 22377241a89c8233b45441b5adde5b858edef371 Mon Sep 17 00:00:00 2001 From: Peter Thomassen Date: Fri, 26 Apr 2024 16:01:11 +0200 Subject: [PATCH 16/25] bump pygments (security hygiene) Addresses https://github.com/encode/django-rest-framework/security/dependabot/9 --- requirements/requirements-optionals.txt | 2 +- tests/test_description.py | 2 +- tests/test_renderers.py | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/requirements/requirements-optionals.txt b/requirements/requirements-optionals.txt index e54100f522..bac597c953 100644 --- a/requirements/requirements-optionals.txt +++ b/requirements/requirements-optionals.txt @@ -6,5 +6,5 @@ django-guardian>=2.4.0,<2.5 inflection==0.5.1 markdown>=3.3.7 psycopg2-binary>=2.9.5,<2.10 -pygments>=2.12.0,<2.14.0 +pygments~=2.17.0 pyyaml>=5.3.1,<5.4 diff --git a/tests/test_description.py b/tests/test_description.py index ecc6b9776d..93539a8386 100644 --- a/tests/test_description.py +++ b/tests/test_description.py @@ -41,7 +41,7 @@

indented

hash style header

-
[{
    "alpha": 1,
    "beta": "this is a string"
}]
+
[{
    "alpha": 1,
    "beta": "this is a string"
}]


""" diff --git a/tests/test_renderers.py b/tests/test_renderers.py index 247737576f..d04ff300ff 100644 --- a/tests/test_renderers.py +++ b/tests/test_renderers.py @@ -910,7 +910,7 @@ def test_shell_code_example_rendering(self): 'link': coreapi.Link(url='/data/', action='get', fields=[]), } html = template.render(context) - assert 'testcases list' in html + assert 'testcases list' in html @pytest.mark.skipif(not coreapi, reason='coreapi is not installed') From ab681f2d5e4a9645aa68eabf1ff18e41d0d5f642 Mon Sep 17 00:00:00 2001 From: Peter Thomassen Date: Fri, 26 Apr 2024 17:09:08 +0200 Subject: [PATCH 17/25] Update requirements in docs --- docs/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/index.md b/docs/index.md index 98cbf6a401..864c1d0723 100644 --- a/docs/index.md +++ b/docs/index.md @@ -95,8 +95,8 @@ each Python and Django series. The following packages are optional: * [PyYAML][pyyaml], [uritemplate][uriteemplate] (5.1+, 3.0.0+) - Schema generation support. -* [Markdown][markdown] (3.0.0+) - Markdown support for the browsable API. -* [Pygments][pygments] (2.4.0+) - Add syntax highlighting to Markdown processing. +* [Markdown][markdown] (3.3.0+) - Markdown support for the browsable API. +* [Pygments][pygments] (2.7.0+) - Add syntax highlighting to Markdown processing. * [django-filter][django-filter] (1.0.1+) - Filtering support. * [django-guardian][django-guardian] (1.1.1+) - Object level permissions support. From b34bde47d7fff403df4143a35c71975d7c2e7763 Mon Sep 17 00:00:00 2001 From: Peter Thomassen Date: Fri, 26 Apr 2024 18:02:19 +0200 Subject: [PATCH 18/25] Fix typo in setup.cfg setting --- setup.cfg | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/setup.cfg b/setup.cfg index e7e288816f..4592388360 100644 --- a/setup.cfg +++ b/setup.cfg @@ -3,7 +3,7 @@ license_files = LICENSE.md [tool:pytest] addopts=--tb=short --strict-markers -ra -testspath = tests +testpaths = tests filterwarnings = ignore:CoreAPI compatibility is deprecated*:rest_framework.RemovedInDRF317Warning [flake8] From 9d4ed054bf8acfac6209b7e7f837fc97517affcc Mon Sep 17 00:00:00 2001 From: Peter Thomassen Date: Fri, 26 Apr 2024 18:05:13 +0200 Subject: [PATCH 19/25] Don't use Windows line endings --- docs/community/funding.md | 796 +++++++++++++++++----------------- docs/topics/html-and-forms.md | 440 +++++++++---------- tests/test_description.py | 310 ++++++------- 3 files changed, 773 insertions(+), 773 deletions(-) diff --git a/docs/community/funding.md b/docs/community/funding.md index 951833682e..10e09bf713 100644 --- a/docs/community/funding.md +++ b/docs/community/funding.md @@ -1,398 +1,398 @@ - - - - -# Funding - -If you use REST framework commercially we strongly encourage you to invest in its continued development by signing up for a paid plan. - -**We believe that collaboratively funded software can offer outstanding returns on investment, by encouraging our users to collectively share the cost of development.** - -Signing up for a paid plan will: - -* Directly contribute to faster releases, more features, and higher quality software. -* Allow more time to be invested in documentation, issue triage, and community support. -* Safeguard the future development of REST framework. - -REST framework continues to be open-source and permissively licensed, but we firmly believe it is in the commercial best-interest for users of the project to invest in its ongoing development. - ---- - -## What funding has enabled so far - -* The [3.4](https://www.django-rest-framework.org/community/3.4-announcement/) and [3.5](https://www.django-rest-framework.org/community/3.5-announcement/) releases, including schema generation for both Swagger and RAML, a Python client library, a Command Line client, and addressing of a large number of outstanding issues. -* The [3.6](https://www.django-rest-framework.org/community/3.6-announcement/) release, including JavaScript client library, and API documentation, complete with auto-generated code samples. -* The [3.7 release](https://www.django-rest-framework.org/community/3.7-announcement/), made possible due to our collaborative funding model, focuses on improvements to schema generation and the interactive API documentation. -* The recent [3.8 release](https://www.django-rest-framework.org/community/3.8-announcement/). -* Tom Christie, the creator of Django REST framework, working on the project full-time. -* Around 80-90 issues and pull requests closed per month since Tom Christie started working on the project full-time. -* A community & operations manager position part-time for 4 months, helping mature the business and grow sponsorship. -* Contracting development time for the work on the JavaScript client library and API documentation tooling. - ---- - -## What future funding will enable - -* Realtime API support, using WebSockets. This will consist of documentation and support for using REST framework together with Django Channels, plus integrating WebSocket support into the client libraries. -* Better authentication defaults, possibly bringing JWT & CORS support into the core package. -* Securing the community & operations manager position long-term. -* Opening up and securing a part-time position to focus on ticket triage and resolution. -* Paying for development time on building API client libraries in a range of programming languages. These would be integrated directly into the upcoming API documentation. - -Sign up for a paid plan today, and help ensure that REST framework becomes a sustainable, full-time funded project. - ---- - -## What our sponsors and users say - -> As a developer, Django REST framework feels like an obvious and natural extension to all the great things that make up Django and it's community. Getting started is easy while providing simple abstractions which makes it flexible and customizable. Contributing and supporting Django REST framework helps ensure its future and one way or another it also helps Django, and the Python ecosystem. -> -> — José Padilla, Django REST framework contributor - -  - -> The number one feature of the Python programming language is its community. Such a community is only possible because of the Open Source nature of the language and all the culture that comes from it. Building great Open Source projects require great minds. Given that, we at Vinta are not only proud to sponsor the team behind DRF but we also recognize the ROI that comes from it. -> -> — Filipe Ximenes, Vinta Software - -  - -> It's really awesome that this project continues to endure. The code base is top notch and the maintainers are committed to the highest level of quality. -DRF is one of the core reasons why Django is top choice among web frameworks today. In my opinion, it sets the standard for rest frameworks for the development community at large. -> -> — Andrew Conti, Django REST framework user - ---- - -## Individual plan - -This subscription is recommended for individuals with an interest in seeing REST framework continue to improve. - -If you are using REST framework as a full-time employee, consider recommending that your company takes out a [corporate plan](#corporate-plans). - -
-
-
-
- {{ symbol }} - {{ rates.personal1 }} - /month{% if vat %} +VAT{% endif %} -
-
Individual
-
-
- Support ongoing development -
-
- Credited on the site -
-
- -
-
-
-
- -*Billing is monthly and you can cancel at any time.* - ---- - -## Corporate plans - -These subscriptions are recommended for companies and organizations using REST framework either publicly or privately. - -In exchange for funding you'll also receive advertising space on our site, allowing you to **promote your company or product to many tens of thousands of developers worldwide**. - -Our professional and premium plans also include **priority support**. At any time your engineers can escalate an issue or discussion group thread, and we'll ensure it gets a guaranteed response within the next working day. - -
-
-
-
- {{ symbol }} - {{ rates.corporate1 }} - /month{% if vat %} +VAT{% endif %} -
-
Basic
-
-
- Support ongoing development -
-
- Funding page ad placement -
-
- -
-
-
-
-
- {{ symbol }} - {{ rates.corporate2 }} - /month{% if vat %} +VAT{% endif %} -
-
Professional
-
-
- Support ongoing development -
-
- Sidebar ad placement -
-
- Priority support for your engineers -
-
- -
-
-
-
-
- {{ symbol }} - {{ rates.corporate3 }} - /month{% if vat %} +VAT{% endif %} -
-
Premium
-
-
- Support ongoing development -
-
- Homepage ad placement -
-
- Sidebar ad placement -
-
- Priority support for your engineers -
-
- -
-
-
- -
- -*Billing is monthly and you can cancel at any time.* - -Once you've signed up, we will contact you via email and arrange your ad placements on the site. - -For further enquires please contact funding@django-rest-framework.org. - ---- - -## Accountability - -In an effort to keep the project as transparent as possible, we are releasing [monthly progress reports](https://www.encode.io/reports/march-2018/) and regularly include financial reports and cost breakdowns. - - - - -
-
-
-

Stay up to date, with our monthly progress reports...

-
- - -
-
- - -
- -
-
-
-
- - - ---- - -## Frequently asked questions - -**Q: Can you issue monthly invoices?** -A: Yes, we are happy to issue monthly invoices. Please just email us and let us know who to issue the invoice to (name and address) and which email address to send it to each month. - -**Q: Does sponsorship include VAT?** -A: Sponsorship is VAT exempt. - -**Q: Do I have to sign up for a certain time period?** -A: No, we appreciate your support for any time period that is convenient for you. Also, you can cancel your sponsorship anytime. - -**Q: Can I pay yearly? Can I pay upfront fox X amount of months at a time?** -A: We are currently only set up to accept monthly payments. However, if you'd like to support Django REST framework and you can only do yearly/upfront payments, we are happy to work with you and figure out a convenient solution. - -**Q: Are you only looking for corporate sponsors?** -A: No, we value individual sponsors just as much as corporate sponsors and appreciate any kind of support. - ---- - -## Our sponsors - -
- - + + + + +# Funding + +If you use REST framework commercially we strongly encourage you to invest in its continued development by signing up for a paid plan. + +**We believe that collaboratively funded software can offer outstanding returns on investment, by encouraging our users to collectively share the cost of development.** + +Signing up for a paid plan will: + +* Directly contribute to faster releases, more features, and higher quality software. +* Allow more time to be invested in documentation, issue triage, and community support. +* Safeguard the future development of REST framework. + +REST framework continues to be open-source and permissively licensed, but we firmly believe it is in the commercial best-interest for users of the project to invest in its ongoing development. + +--- + +## What funding has enabled so far + +* The [3.4](https://www.django-rest-framework.org/community/3.4-announcement/) and [3.5](https://www.django-rest-framework.org/community/3.5-announcement/) releases, including schema generation for both Swagger and RAML, a Python client library, a Command Line client, and addressing of a large number of outstanding issues. +* The [3.6](https://www.django-rest-framework.org/community/3.6-announcement/) release, including JavaScript client library, and API documentation, complete with auto-generated code samples. +* The [3.7 release](https://www.django-rest-framework.org/community/3.7-announcement/), made possible due to our collaborative funding model, focuses on improvements to schema generation and the interactive API documentation. +* The recent [3.8 release](https://www.django-rest-framework.org/community/3.8-announcement/). +* Tom Christie, the creator of Django REST framework, working on the project full-time. +* Around 80-90 issues and pull requests closed per month since Tom Christie started working on the project full-time. +* A community & operations manager position part-time for 4 months, helping mature the business and grow sponsorship. +* Contracting development time for the work on the JavaScript client library and API documentation tooling. + +--- + +## What future funding will enable + +* Realtime API support, using WebSockets. This will consist of documentation and support for using REST framework together with Django Channels, plus integrating WebSocket support into the client libraries. +* Better authentication defaults, possibly bringing JWT & CORS support into the core package. +* Securing the community & operations manager position long-term. +* Opening up and securing a part-time position to focus on ticket triage and resolution. +* Paying for development time on building API client libraries in a range of programming languages. These would be integrated directly into the upcoming API documentation. + +Sign up for a paid plan today, and help ensure that REST framework becomes a sustainable, full-time funded project. + +--- + +## What our sponsors and users say + +> As a developer, Django REST framework feels like an obvious and natural extension to all the great things that make up Django and it's community. Getting started is easy while providing simple abstractions which makes it flexible and customizable. Contributing and supporting Django REST framework helps ensure its future and one way or another it also helps Django, and the Python ecosystem. +> +> — José Padilla, Django REST framework contributor + +  + +> The number one feature of the Python programming language is its community. Such a community is only possible because of the Open Source nature of the language and all the culture that comes from it. Building great Open Source projects require great minds. Given that, we at Vinta are not only proud to sponsor the team behind DRF but we also recognize the ROI that comes from it. +> +> — Filipe Ximenes, Vinta Software + +  + +> It's really awesome that this project continues to endure. The code base is top notch and the maintainers are committed to the highest level of quality. +DRF is one of the core reasons why Django is top choice among web frameworks today. In my opinion, it sets the standard for rest frameworks for the development community at large. +> +> — Andrew Conti, Django REST framework user + +--- + +## Individual plan + +This subscription is recommended for individuals with an interest in seeing REST framework continue to improve. + +If you are using REST framework as a full-time employee, consider recommending that your company takes out a [corporate plan](#corporate-plans). + +
+
+
+
+ {{ symbol }} + {{ rates.personal1 }} + /month{% if vat %} +VAT{% endif %} +
+
Individual
+
+
+ Support ongoing development +
+
+ Credited on the site +
+
+ +
+
+
+
+ +*Billing is monthly and you can cancel at any time.* + +--- + +## Corporate plans + +These subscriptions are recommended for companies and organizations using REST framework either publicly or privately. + +In exchange for funding you'll also receive advertising space on our site, allowing you to **promote your company or product to many tens of thousands of developers worldwide**. + +Our professional and premium plans also include **priority support**. At any time your engineers can escalate an issue or discussion group thread, and we'll ensure it gets a guaranteed response within the next working day. + +
+
+
+
+ {{ symbol }} + {{ rates.corporate1 }} + /month{% if vat %} +VAT{% endif %} +
+
Basic
+
+
+ Support ongoing development +
+
+ Funding page ad placement +
+
+ +
+
+
+
+
+ {{ symbol }} + {{ rates.corporate2 }} + /month{% if vat %} +VAT{% endif %} +
+
Professional
+
+
+ Support ongoing development +
+
+ Sidebar ad placement +
+
+ Priority support for your engineers +
+
+ +
+
+
+
+
+ {{ symbol }} + {{ rates.corporate3 }} + /month{% if vat %} +VAT{% endif %} +
+
Premium
+
+
+ Support ongoing development +
+
+ Homepage ad placement +
+
+ Sidebar ad placement +
+
+ Priority support for your engineers +
+
+ +
+
+
+ +
+ +*Billing is monthly and you can cancel at any time.* + +Once you've signed up, we will contact you via email and arrange your ad placements on the site. + +For further enquires please contact funding@django-rest-framework.org. + +--- + +## Accountability + +In an effort to keep the project as transparent as possible, we are releasing [monthly progress reports](https://www.encode.io/reports/march-2018/) and regularly include financial reports and cost breakdowns. + + + + +
+
+
+

Stay up to date, with our monthly progress reports...

+
+ + +
+
+ + +
+ +
+
+
+
+ + + +--- + +## Frequently asked questions + +**Q: Can you issue monthly invoices?** +A: Yes, we are happy to issue monthly invoices. Please just email us and let us know who to issue the invoice to (name and address) and which email address to send it to each month. + +**Q: Does sponsorship include VAT?** +A: Sponsorship is VAT exempt. + +**Q: Do I have to sign up for a certain time period?** +A: No, we appreciate your support for any time period that is convenient for you. Also, you can cancel your sponsorship anytime. + +**Q: Can I pay yearly? Can I pay upfront fox X amount of months at a time?** +A: We are currently only set up to accept monthly payments. However, if you'd like to support Django REST framework and you can only do yearly/upfront payments, we are happy to work with you and figure out a convenient solution. + +**Q: Are you only looking for corporate sponsors?** +A: No, we value individual sponsors just as much as corporate sponsors and appreciate any kind of support. + +--- + +## Our sponsors + +
+ + diff --git a/docs/topics/html-and-forms.md b/docs/topics/html-and-forms.md index 17c9e3314c..c7e51c1526 100644 --- a/docs/topics/html-and-forms.md +++ b/docs/topics/html-and-forms.md @@ -1,220 +1,220 @@ -# HTML & Forms - -REST framework is suitable for returning both API style responses, and regular HTML pages. Additionally, serializers can be used as HTML forms and rendered in templates. - -## Rendering HTML - -In order to return HTML responses you'll need to use either `TemplateHTMLRenderer`, or `StaticHTMLRenderer`. - -The `TemplateHTMLRenderer` class expects the response to contain a dictionary of context data, and renders an HTML page based on a template that must be specified either in the view or on the response. - -The `StaticHTMLRender` class expects the response to contain a string of the pre-rendered HTML content. - -Because static HTML pages typically have different behavior from API responses you'll probably need to write any HTML views explicitly, rather than relying on the built-in generic views. - -Here's an example of a view that returns a list of "Profile" instances, rendered in an HTML template: - -**views.py**: - - from my_project.example.models import Profile - from rest_framework.renderers import TemplateHTMLRenderer - from rest_framework.response import Response - from rest_framework.views import APIView - - - class ProfileList(APIView): - renderer_classes = [TemplateHTMLRenderer] - template_name = 'profile_list.html' - - def get(self, request): - queryset = Profile.objects.all() - return Response({'profiles': queryset}) - -**profile_list.html**: - - -

Profiles

-
    - {% for profile in profiles %} -
  • {{ profile.name }}
    • - {% endfor %} -
- - -## Rendering Forms - -Serializers may be rendered as forms by using the `render_form` template tag, and including the serializer instance as context to the template. - -The following view demonstrates an example of using a serializer in a template for viewing and updating a model instance: - -**views.py**: - - from django.shortcuts import get_object_or_404 - from my_project.example.models import Profile - from rest_framework.renderers import TemplateHTMLRenderer - from rest_framework.views import APIView - - - class ProfileDetail(APIView): - renderer_classes = [TemplateHTMLRenderer] - template_name = 'profile_detail.html' - - def get(self, request, pk): - profile = get_object_or_404(Profile, pk=pk) - serializer = ProfileSerializer(profile) - return Response({'serializer': serializer, 'profile': profile}) - - def post(self, request, pk): - profile = get_object_or_404(Profile, pk=pk) - serializer = ProfileSerializer(profile, data=request.data) - if not serializer.is_valid(): - return Response({'serializer': serializer, 'profile': profile}) - serializer.save() - return redirect('profile-list') - -**profile_detail.html**: - - {% load rest_framework %} - - - -

Profile - {{ profile.name }}

- -
- {% csrf_token %} - {% render_form serializer %} - -
- - - -### Using template packs - -The `render_form` tag takes an optional `template_pack` argument, that specifies which template directory should be used for rendering the form and form fields. - -REST framework includes three built-in template packs, all based on Bootstrap 3. The built-in styles are `horizontal`, `vertical`, and `inline`. The default style is `horizontal`. To use any of these template packs you'll want to also include the Bootstrap 3 CSS. - -The following HTML will link to a CDN hosted version of the Bootstrap 3 CSS: - - - … - - - -Third party packages may include alternate template packs, by bundling a template directory containing the necessary form and field templates. - -Let's take a look at how to render each of the three available template packs. For these examples we'll use a single serializer class to present a "Login" form. - - class LoginSerializer(serializers.Serializer): - email = serializers.EmailField( - max_length=100, - style={'placeholder': 'Email', 'autofocus': True} - ) - password = serializers.CharField( - max_length=100, - style={'input_type': 'password', 'placeholder': 'Password'} - ) - remember_me = serializers.BooleanField() - ---- - -#### `rest_framework/vertical` - -Presents form labels above their corresponding control inputs, using the standard Bootstrap layout. - -*This is the default template pack.* - - {% load rest_framework %} - - ... - -
- {% csrf_token %} - {% render_form serializer template_pack='rest_framework/vertical' %} - -
- -![Vertical form example](../img/vertical.png) - ---- - -#### `rest_framework/horizontal` - -Presents labels and controls alongside each other, using a 2/10 column split. - -*This is the form style used in the browsable API and admin renderers.* - - {% load rest_framework %} - - ... - -
- {% csrf_token %} - {% render_form serializer %} -
-
- -
-
-
- -![Horizontal form example](../img/horizontal.png) - ---- - -#### `rest_framework/inline` - -A compact form style that presents all the controls inline. - - {% load rest_framework %} - - ... - -
- {% csrf_token %} - {% render_form serializer template_pack='rest_framework/inline' %} - -
- -![Inline form example](../img/inline.png) - -## Field styles - -Serializer fields can have their rendering style customized by using the `style` keyword argument. This argument is a dictionary of options that control the template and layout used. - -The most common way to customize the field style is to use the `base_template` style keyword argument to select which template in the template pack should be use. - -For example, to render a `CharField` as an HTML textarea rather than the default HTML input, you would use something like this: - - details = serializers.CharField( - max_length=1000, - style={'base_template': 'textarea.html'} - ) - -If you instead want a field to be rendered using a custom template that is *not part of an included template pack*, you can instead use the `template` style option, to fully specify a template name: - - details = serializers.CharField( - max_length=1000, - style={'template': 'my-field-templates/custom-input.html'} - ) - -Field templates can also use additional style properties, depending on their type. For example, the `textarea.html` template also accepts a `rows` property that can be used to affect the sizing of the control. - - details = serializers.CharField( - max_length=1000, - style={'base_template': 'textarea.html', 'rows': 10} - ) - -The complete list of `base_template` options and their associated style options is listed below. - -base_template | Valid field types | Additional style options ------------------------|-------------------------------------------------------------|----------------------------------------------- -input.html | Any string, numeric or date/time field | input_type, placeholder, hide_label, autofocus -textarea.html | `CharField` | rows, placeholder, hide_label -select.html | `ChoiceField` or relational field types | hide_label -radio.html | `ChoiceField` or relational field types | inline, hide_label -select_multiple.html | `MultipleChoiceField` or relational fields with `many=True` | hide_label -checkbox_multiple.html | `MultipleChoiceField` or relational fields with `many=True` | inline, hide_label -checkbox.html | `BooleanField` | hide_label -fieldset.html | Nested serializer | hide_label -list_fieldset.html | `ListField` or nested serializer with `many=True` | hide_label +# HTML & Forms + +REST framework is suitable for returning both API style responses, and regular HTML pages. Additionally, serializers can be used as HTML forms and rendered in templates. + +## Rendering HTML + +In order to return HTML responses you'll need to use either `TemplateHTMLRenderer`, or `StaticHTMLRenderer`. + +The `TemplateHTMLRenderer` class expects the response to contain a dictionary of context data, and renders an HTML page based on a template that must be specified either in the view or on the response. + +The `StaticHTMLRender` class expects the response to contain a string of the pre-rendered HTML content. + +Because static HTML pages typically have different behavior from API responses you'll probably need to write any HTML views explicitly, rather than relying on the built-in generic views. + +Here's an example of a view that returns a list of "Profile" instances, rendered in an HTML template: + +**views.py**: + + from my_project.example.models import Profile + from rest_framework.renderers import TemplateHTMLRenderer + from rest_framework.response import Response + from rest_framework.views import APIView + + + class ProfileList(APIView): + renderer_classes = [TemplateHTMLRenderer] + template_name = 'profile_list.html' + + def get(self, request): + queryset = Profile.objects.all() + return Response({'profiles': queryset}) + +**profile_list.html**: + + +

Profiles

+
    + {% for profile in profiles %} +
  • {{ profile.name }}
    • + {% endfor %} +
+ + +## Rendering Forms + +Serializers may be rendered as forms by using the `render_form` template tag, and including the serializer instance as context to the template. + +The following view demonstrates an example of using a serializer in a template for viewing and updating a model instance: + +**views.py**: + + from django.shortcuts import get_object_or_404 + from my_project.example.models import Profile + from rest_framework.renderers import TemplateHTMLRenderer + from rest_framework.views import APIView + + + class ProfileDetail(APIView): + renderer_classes = [TemplateHTMLRenderer] + template_name = 'profile_detail.html' + + def get(self, request, pk): + profile = get_object_or_404(Profile, pk=pk) + serializer = ProfileSerializer(profile) + return Response({'serializer': serializer, 'profile': profile}) + + def post(self, request, pk): + profile = get_object_or_404(Profile, pk=pk) + serializer = ProfileSerializer(profile, data=request.data) + if not serializer.is_valid(): + return Response({'serializer': serializer, 'profile': profile}) + serializer.save() + return redirect('profile-list') + +**profile_detail.html**: + + {% load rest_framework %} + + + +

Profile - {{ profile.name }}

+ +
+ {% csrf_token %} + {% render_form serializer %} + +
+ + + +### Using template packs + +The `render_form` tag takes an optional `template_pack` argument, that specifies which template directory should be used for rendering the form and form fields. + +REST framework includes three built-in template packs, all based on Bootstrap 3. The built-in styles are `horizontal`, `vertical`, and `inline`. The default style is `horizontal`. To use any of these template packs you'll want to also include the Bootstrap 3 CSS. + +The following HTML will link to a CDN hosted version of the Bootstrap 3 CSS: + + + … + + + +Third party packages may include alternate template packs, by bundling a template directory containing the necessary form and field templates. + +Let's take a look at how to render each of the three available template packs. For these examples we'll use a single serializer class to present a "Login" form. + + class LoginSerializer(serializers.Serializer): + email = serializers.EmailField( + max_length=100, + style={'placeholder': 'Email', 'autofocus': True} + ) + password = serializers.CharField( + max_length=100, + style={'input_type': 'password', 'placeholder': 'Password'} + ) + remember_me = serializers.BooleanField() + +--- + +#### `rest_framework/vertical` + +Presents form labels above their corresponding control inputs, using the standard Bootstrap layout. + +*This is the default template pack.* + + {% load rest_framework %} + + ... + +
+ {% csrf_token %} + {% render_form serializer template_pack='rest_framework/vertical' %} + +
+ +![Vertical form example](../img/vertical.png) + +--- + +#### `rest_framework/horizontal` + +Presents labels and controls alongside each other, using a 2/10 column split. + +*This is the form style used in the browsable API and admin renderers.* + + {% load rest_framework %} + + ... + +
+ {% csrf_token %} + {% render_form serializer %} +
+
+ +
+
+
+ +![Horizontal form example](../img/horizontal.png) + +--- + +#### `rest_framework/inline` + +A compact form style that presents all the controls inline. + + {% load rest_framework %} + + ... + +
+ {% csrf_token %} + {% render_form serializer template_pack='rest_framework/inline' %} + +
+ +![Inline form example](../img/inline.png) + +## Field styles + +Serializer fields can have their rendering style customized by using the `style` keyword argument. This argument is a dictionary of options that control the template and layout used. + +The most common way to customize the field style is to use the `base_template` style keyword argument to select which template in the template pack should be use. + +For example, to render a `CharField` as an HTML textarea rather than the default HTML input, you would use something like this: + + details = serializers.CharField( + max_length=1000, + style={'base_template': 'textarea.html'} + ) + +If you instead want a field to be rendered using a custom template that is *not part of an included template pack*, you can instead use the `template` style option, to fully specify a template name: + + details = serializers.CharField( + max_length=1000, + style={'template': 'my-field-templates/custom-input.html'} + ) + +Field templates can also use additional style properties, depending on their type. For example, the `textarea.html` template also accepts a `rows` property that can be used to affect the sizing of the control. + + details = serializers.CharField( + max_length=1000, + style={'base_template': 'textarea.html', 'rows': 10} + ) + +The complete list of `base_template` options and their associated style options is listed below. + +base_template | Valid field types | Additional style options +-----------------------|-------------------------------------------------------------|----------------------------------------------- +input.html | Any string, numeric or date/time field | input_type, placeholder, hide_label, autofocus +textarea.html | `CharField` | rows, placeholder, hide_label +select.html | `ChoiceField` or relational field types | hide_label +radio.html | `ChoiceField` or relational field types | inline, hide_label +select_multiple.html | `MultipleChoiceField` or relational fields with `many=True` | hide_label +checkbox_multiple.html | `MultipleChoiceField` or relational fields with `many=True` | inline, hide_label +checkbox.html | `BooleanField` | hide_label +fieldset.html | Nested serializer | hide_label +list_fieldset.html | `ListField` or nested serializer with `many=True` | hide_label diff --git a/tests/test_description.py b/tests/test_description.py index 93539a8386..7fb93ed4e5 100644 --- a/tests/test_description.py +++ b/tests/test_description.py @@ -1,155 +1,155 @@ -import pytest -from django.test import TestCase - -from rest_framework.compat import apply_markdown -from rest_framework.utils.formatting import dedent -from rest_framework.views import APIView - -# We check that docstrings get nicely un-indented. -DESCRIPTION = """an example docstring -==================== - -* list -* list - -another header --------------- - - code block - -indented - -# hash style header # - -```json -[{ - "alpha": 1, - "beta": "this is a string" -}] -```""" - - -# If markdown is installed we also test it's working -# (and that our wrapped forces '=' to h2 and '-' to h3) -MARKDOWN_DOCSTRING = """

an example docstring

-
    -
  • list
    • -
  • list
    • -
-

another header

-
code block
-
-

indented

-

hash style header

-
[{
    "alpha": 1,
    "beta": "this is a string"
}]
-


""" - - -class TestViewNamesAndDescriptions(TestCase): - def test_view_name_uses_class_name(self): - """ - Ensure view names are based on the class name. - """ - class MockView(APIView): - pass - assert MockView().get_view_name() == 'Mock' - - def test_view_name_uses_name_attribute(self): - class MockView(APIView): - name = 'Foo' - assert MockView().get_view_name() == 'Foo' - - def test_view_name_uses_suffix_attribute(self): - class MockView(APIView): - suffix = 'List' - assert MockView().get_view_name() == 'Mock List' - - def test_view_name_preferences_name_over_suffix(self): - class MockView(APIView): - name = 'Foo' - suffix = 'List' - assert MockView().get_view_name() == 'Foo' - - def test_view_description_uses_docstring(self): - """Ensure view descriptions are based on the docstring.""" - class MockView(APIView): - """an example docstring - ==================== - - * list - * list - - another header - -------------- - - code block - - indented - - # hash style header # - - ```json - [{ - "alpha": 1, - "beta": "this is a string" - }] - ```""" - - assert MockView().get_view_description() == DESCRIPTION - - def test_view_description_uses_description_attribute(self): - class MockView(APIView): - description = 'Foo' - assert MockView().get_view_description() == 'Foo' - - def test_view_description_allows_empty_description(self): - class MockView(APIView): - """Description.""" - description = '' - assert MockView().get_view_description() == '' - - def test_view_description_can_be_empty(self): - """ - Ensure that if a view has no docstring, - then it's description is the empty string. - """ - class MockView(APIView): - pass - assert MockView().get_view_description() == '' - - def test_view_description_can_be_promise(self): - """ - Ensure a view may have a docstring that is actually a lazily evaluated - class that can be converted to a string. - - See: https://github.com/encode/django-rest-framework/issues/1708 - """ - # use a mock object instead of gettext_lazy to ensure that we can't end - # up with a test case string in our l10n catalog - - class MockLazyStr: - def __init__(self, string): - self.s = string - - def __str__(self): - return self.s - - class MockView(APIView): - __doc__ = MockLazyStr("a gettext string") - - assert MockView().get_view_description() == 'a gettext string' - - @pytest.mark.skipif(not apply_markdown, reason="Markdown is not installed") - def test_markdown(self): - """ - Ensure markdown to HTML works as expected. - """ - assert apply_markdown(DESCRIPTION) == MARKDOWN_DOCSTRING - - -def test_dedent_tabs(): - result = 'first string\n\nsecond string' - assert dedent(" first string\n\n second string") == result - assert dedent("first string\n\n second string") == result - assert dedent("\tfirst string\n\n\tsecond string") == result - assert dedent("first string\n\n\tsecond string") == result +import pytest +from django.test import TestCase + +from rest_framework.compat import apply_markdown +from rest_framework.utils.formatting import dedent +from rest_framework.views import APIView + +# We check that docstrings get nicely un-indented. +DESCRIPTION = """an example docstring +==================== + +* list +* list + +another header +-------------- + + code block + +indented + +# hash style header # + +```json +[{ + "alpha": 1, + "beta": "this is a string" +}] +```""" + + +# If markdown is installed we also test it's working +# (and that our wrapped forces '=' to h2 and '-' to h3) +MARKDOWN_DOCSTRING = """

an example docstring

+
    +
  • list
    • +
  • list
    • +
+

another header

+
code block
+
+

indented

+

hash style header

+
[{
    "alpha": 1,
    "beta": "this is a string"
}]
+


""" + + +class TestViewNamesAndDescriptions(TestCase): + def test_view_name_uses_class_name(self): + """ + Ensure view names are based on the class name. + """ + class MockView(APIView): + pass + assert MockView().get_view_name() == 'Mock' + + def test_view_name_uses_name_attribute(self): + class MockView(APIView): + name = 'Foo' + assert MockView().get_view_name() == 'Foo' + + def test_view_name_uses_suffix_attribute(self): + class MockView(APIView): + suffix = 'List' + assert MockView().get_view_name() == 'Mock List' + + def test_view_name_preferences_name_over_suffix(self): + class MockView(APIView): + name = 'Foo' + suffix = 'List' + assert MockView().get_view_name() == 'Foo' + + def test_view_description_uses_docstring(self): + """Ensure view descriptions are based on the docstring.""" + class MockView(APIView): + """an example docstring + ==================== + + * list + * list + + another header + -------------- + + code block + + indented + + # hash style header # + + ```json + [{ + "alpha": 1, + "beta": "this is a string" + }] + ```""" + + assert MockView().get_view_description() == DESCRIPTION + + def test_view_description_uses_description_attribute(self): + class MockView(APIView): + description = 'Foo' + assert MockView().get_view_description() == 'Foo' + + def test_view_description_allows_empty_description(self): + class MockView(APIView): + """Description.""" + description = '' + assert MockView().get_view_description() == '' + + def test_view_description_can_be_empty(self): + """ + Ensure that if a view has no docstring, + then it's description is the empty string. + """ + class MockView(APIView): + pass + assert MockView().get_view_description() == '' + + def test_view_description_can_be_promise(self): + """ + Ensure a view may have a docstring that is actually a lazily evaluated + class that can be converted to a string. + + See: https://github.com/encode/django-rest-framework/issues/1708 + """ + # use a mock object instead of gettext_lazy to ensure that we can't end + # up with a test case string in our l10n catalog + + class MockLazyStr: + def __init__(self, string): + self.s = string + + def __str__(self): + return self.s + + class MockView(APIView): + __doc__ = MockLazyStr("a gettext string") + + assert MockView().get_view_description() == 'a gettext string' + + @pytest.mark.skipif(not apply_markdown, reason="Markdown is not installed") + def test_markdown(self): + """ + Ensure markdown to HTML works as expected. + """ + assert apply_markdown(DESCRIPTION) == MARKDOWN_DOCSTRING + + +def test_dedent_tabs(): + result = 'first string\n\nsecond string' + assert dedent(" first string\n\n second string") == result + assert dedent("first string\n\n second string") == result + assert dedent("\tfirst string\n\n\tsecond string") == result + assert dedent("first string\n\n\tsecond string") == result From 36d5c0e74f562cbe3055f0d20818bd48d3c32359 Mon Sep 17 00:00:00 2001 From: Stanislav Levin Date: Tue, 7 May 2024 10:05:03 +0300 Subject: [PATCH 20/25] tests: Check urlpatterns after cleanups (#9400) According to docs: https://docs.python.org/3/library/unittest.html#unittest.TestCase.addClassCleanup > Add a function to be called after tearDownClass() to cleanup resources used during the test class. Functions will be called in reverse order to the order they are added (LIFO). This was revealed with recent change in pytest (`8.2.0`): > pytest-dev/pytest#11728: For unittest-based tests, exceptions during class cleanup (as raised by functions registered with TestCase.addClassCleanup) are now reported instead of silently failing. `check_urlpatterns` is called before `cleanup_url_patterns` and fails (problem was hidden by `pytest < 8.2.0`). `doClassCleanups` can be used instead to check after-cleanup state: https://docs.python.org/3/library/unittest.html#unittest.TestCase.doClassCleanups > This method is called unconditionally after tearDownClass(), or after setUpClass() if setUpClass() raises an exception. It is responsible for calling all the cleanup functions added by addClassCleanup(). If you need cleanup functions to be called prior to tearDownClass() then you can call doClassCleanups() yourself. Fixes: https://github.com/encode/django-rest-framework/issues/9399 Signed-off-by: Stanislav Levin --- tests/test_testing.py | 13 +++++-------- 1 file changed, 5 insertions(+), 8 deletions(-) diff --git a/tests/test_testing.py b/tests/test_testing.py index 7c2a09fae4..a7e00ab63e 100644 --- a/tests/test_testing.py +++ b/tests/test_testing.py @@ -318,10 +318,6 @@ def test_empty_request_content_type(self): assert request.META['CONTENT_TYPE'] == 'application/json' -def check_urlpatterns(cls): - assert urlpatterns is not cls.urlpatterns - - class TestUrlPatternTestCase(URLPatternsTestCase): urlpatterns = [ path('', view), @@ -333,10 +329,11 @@ def setUpClass(cls): super().setUpClass() assert urlpatterns is cls.urlpatterns - cls.addClassCleanup( - check_urlpatterns, - cls - ) + @classmethod + def doClassCleanups(cls): + assert urlpatterns is cls.urlpatterns + super().doClassCleanups() + assert urlpatterns is not cls.urlpatterns def test_urlpatterns(self): assert self.client.get('/').status_code == 200 From fbdab09c776d5ceef041793a7acd1c9e91695e5d Mon Sep 17 00:00:00 2001 From: wkwkhautbois Date: Sun, 2 Jun 2024 13:14:37 +0900 Subject: [PATCH 21/25] docs: Correct some evaluation results and a httpie option in Tutorial1 (#9421) * Tutorial 1: Added --unsorted option to httpie calls to prevent automatic json key sorting * Tutorial 1: Changed evaluation results accurate --- docs/tutorial/1-serialization.md | 62 ++++++++++++++++++-------------- 1 file changed, 35 insertions(+), 27 deletions(-) diff --git a/docs/tutorial/1-serialization.md b/docs/tutorial/1-serialization.md index c860081046..1dac5e0d84 100644 --- a/docs/tutorial/1-serialization.md +++ b/docs/tutorial/1-serialization.md @@ -150,7 +150,7 @@ At this point we've translated the model instance into Python native datatypes. content = JSONRenderer().render(serializer.data) content - # b'{"id": 2, "title": "", "code": "print(\\"hello, world\\")\\n", "linenos": false, "language": "python", "style": "friendly"}' + # b'{"id":2,"title":"","code":"print(\\"hello, world\\")\\n","linenos":false,"language":"python","style":"friendly"}' Deserialization is similar. First we parse a stream into Python native datatypes... @@ -165,7 +165,7 @@ Deserialization is similar. First we parse a stream into Python native datatype serializer.is_valid() # True serializer.validated_data - # OrderedDict([('title', ''), ('code', 'print("hello, world")\n'), ('linenos', False), ('language', 'python'), ('style', 'friendly')]) + # {'title': '', 'code': 'print("hello, world")', 'linenos': False, 'language': 'python', 'style': 'friendly'} serializer.save() # @@ -175,7 +175,7 @@ We can also serialize querysets instead of model instances. To do so we simply serializer = SnippetSerializer(Snippet.objects.all(), many=True) serializer.data - # [OrderedDict([('id', 1), ('title', ''), ('code', 'foo = "bar"\n'), ('linenos', False), ('language', 'python'), ('style', 'friendly')]), OrderedDict([('id', 2), ('title', ''), ('code', 'print("hello, world")\n'), ('linenos', False), ('language', 'python'), ('style', 'friendly')]), OrderedDict([('id', 3), ('title', ''), ('code', 'print("hello, world")'), ('linenos', False), ('language', 'python'), ('style', 'friendly')])] + # [{'id': 1, 'title': '', 'code': 'foo = "bar"\n', 'linenos': False, 'language': 'python', 'style': 'friendly'}, {'id': 2, 'title': '', 'code': 'print("hello, world")\n', 'linenos': False, 'language': 'python', 'style': 'friendly'}, {'id': 3, 'title': '', 'code': 'print("hello, world")', 'linenos': False, 'language': 'python', 'style': 'friendly'}] ## Using ModelSerializers @@ -321,42 +321,50 @@ You can install httpie using pip: Finally, we can get a list of all of the snippets: - http http://127.0.0.1:8000/snippets/ + http http://127.0.0.1:8000/snippets/ --unsorted HTTP/1.1 200 OK ... [ - { - "id": 1, - "title": "", - "code": "foo = \"bar\"\n", - "linenos": false, - "language": "python", - "style": "friendly" - }, - { - "id": 2, - "title": "", - "code": "print(\"hello, world\")\n", - "linenos": false, - "language": "python", - "style": "friendly" - } + { + "id": 1, + "title": "", + "code": "foo = \"bar\"\n", + "linenos": false, + "language": "python", + "style": "friendly" + }, + { + "id": 2, + "title": "", + "code": "print(\"hello, world\")\n", + "linenos": false, + "language": "python", + "style": "friendly" + }, + { + "id": 3, + "title": "", + "code": "print(\"hello, world\")", + "linenos": false, + "language": "python", + "style": "friendly" + } ] Or we can get a particular snippet by referencing its id: - http http://127.0.0.1:8000/snippets/2/ + http http://127.0.0.1:8000/snippets/2/ --unsorted HTTP/1.1 200 OK ... { - "id": 2, - "title": "", - "code": "print(\"hello, world\")\n", - "linenos": false, - "language": "python", - "style": "friendly" + "id": 2, + "title": "", + "code": "print(\"hello, world\")\n", + "linenos": false, + "language": "python", + "style": "friendly" } Similarly, you can have the same json displayed by visiting these URLs in a web browser. From fe92f0dd0d4c587eed000c7de611ddbff241bd6a Mon Sep 17 00:00:00 2001 From: Ivan Studinsky Date: Mon, 10 Jun 2024 13:19:06 +0700 Subject: [PATCH 22/25] Add `__hash__` method for `permissions.OperandHolder` class (#9417) `OperandHolder` is not hashable, so need to add `__hash__` method --- rest_framework/permissions.py | 3 +++ 1 file changed, 3 insertions(+) diff --git a/rest_framework/permissions.py b/rest_framework/permissions.py index 71de226f98..7c15eca589 100644 --- a/rest_framework/permissions.py +++ b/rest_framework/permissions.py @@ -54,6 +54,9 @@ def __eq__(self, other): self.op2_class == other.op2_class ) + def __hash__(self): + return hash((self.operator_class, self.op1_class, self.op2_class)) + class AND: def __init__(self, op1, op2): From 3b41f0124194430da957b119712978fa2266b642 Mon Sep 17 00:00:00 2001 From: Seokchan Yoon Date: Fri, 14 Jun 2024 18:52:02 +0900 Subject: [PATCH 23/25] Fix potential XSS vulnerability in break_long_headers template filter (#9435) The header input is now properly escaped before splitting and joining with
tags. This prevents potential XSS attacks if the header contains unsanitized user input. --- rest_framework/templatetags/rest_framework.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rest_framework/templatetags/rest_framework.py b/rest_framework/templatetags/rest_framework.py index e01568cf2c..dba8153b13 100644 --- a/rest_framework/templatetags/rest_framework.py +++ b/rest_framework/templatetags/rest_framework.py @@ -322,5 +322,5 @@ def break_long_headers(header): when possible (are comma separated) """ if len(header) > 160 and ',' in header: - header = mark_safe('
' + ',
'.join(header.split(','))) + header = mark_safe('
' + ',
'.join(escape(header).split(','))) return header From c7a7eae551528b6887614df816c8a26df70272d6 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Fri, 14 Jun 2024 16:34:21 +0100 Subject: [PATCH 24/25] Version 3.15.2 (#9439) --- docs/community/release-notes.md | 9 +++++++++ rest_framework/__init__.py | 2 +- 2 files changed, 10 insertions(+), 1 deletion(-) diff --git a/docs/community/release-notes.md b/docs/community/release-notes.md index f983424da4..5ec415a799 100644 --- a/docs/community/release-notes.md +++ b/docs/community/release-notes.md @@ -38,6 +38,15 @@ You can determine your currently installed version using `pip show`: ## 3.15.x series +### 3.15.2 + +**Date**: 14th June 2024 + +* Fix potential XSS vulnerability in browsable API. [#9435](https://github.com/encode/django-rest-framework/pull/9157) +* Revert "Ensure CursorPagination respects nulls in the ordering field". [#9381](https://github.com/encode/django-rest-framework/pull/9381) +* Use warnings rather than logging a warning for DecimalField. [#9367](https://github.com/encode/django-rest-framework/pull/9367) +* Remove unused code. [#9393](https://github.com/encode/django-rest-framework/pull/9393) + ### 3.15.1 Date: 22nd March 2024 diff --git a/rest_framework/__init__.py b/rest_framework/__init__.py index bc16b221b2..636f0c8ade 100644 --- a/rest_framework/__init__.py +++ b/rest_framework/__init__.py @@ -8,7 +8,7 @@ """ __title__ = 'Django REST framework' -__version__ = '3.15.1' +__version__ = '3.15.2' __author__ = 'Tom Christie' __license__ = 'BSD 3-Clause' __copyright__ = 'Copyright 2011-2023 Encode OSS Ltd' From 1e9b5c15ecc165e6d7658a6db13de98560f2b8df Mon Sep 17 00:00:00 2001 From: Ivan Studinsky Date: Sat, 15 Jun 2024 15:00:28 +0700 Subject: [PATCH 25/25] Provide tests for hashing of `OperandHolder` (#9437) --- tests/test_permissions.py | 56 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 56 insertions(+) diff --git a/tests/test_permissions.py b/tests/test_permissions.py index aefff981ee..39b7ed6622 100644 --- a/tests/test_permissions.py +++ b/tests/test_permissions.py @@ -716,3 +716,59 @@ def has_object_permission(self, request, view, obj): composed_perm = (IsAuthenticatedUserOwner | permissions.IsAdminUser) hasperm = composed_perm().has_object_permission(request, None, None) assert hasperm is False + + def test_operand_holder_is_hashable(self): + assert hash((permissions.IsAuthenticated & permissions.IsAdminUser)) + + def test_operand_holder_hash_same_for_same_operands_and_operator(self): + first_operand_holder = ( + permissions.IsAuthenticated & permissions.IsAdminUser + ) + second_operand_holder = ( + permissions.IsAuthenticated & permissions.IsAdminUser + ) + + assert hash(first_operand_holder) == hash(second_operand_holder) + + def test_operand_holder_hash_differs_for_different_operands(self): + first_operand_holder = ( + permissions.IsAuthenticated & permissions.IsAdminUser + ) + second_operand_holder = ( + permissions.AllowAny & permissions.IsAdminUser + ) + third_operand_holder = ( + permissions.IsAuthenticated & permissions.AllowAny + ) + + assert hash(first_operand_holder) != hash(second_operand_holder) + assert hash(first_operand_holder) != hash(third_operand_holder) + assert hash(second_operand_holder) != hash(third_operand_holder) + + def test_operand_holder_hash_differs_for_different_operators(self): + first_operand_holder = ( + permissions.IsAuthenticated & permissions.IsAdminUser + ) + second_operand_holder = ( + permissions.IsAuthenticated | permissions.IsAdminUser + ) + + assert hash(first_operand_holder) != hash(second_operand_holder) + + def test_filtering_permissions(self): + unfiltered_permissions = [ + permissions.IsAuthenticated & permissions.IsAdminUser, + permissions.IsAuthenticated & permissions.IsAdminUser, + permissions.AllowAny, + ] + expected_permissions = [ + permissions.IsAuthenticated & permissions.IsAdminUser, + permissions.AllowAny, + ] + + filtered_permissions = [ + perm for perm + in dict.fromkeys(unfiltered_permissions) + ] + + assert filtered_permissions == expected_permissions