Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We鈥檒l occasionally send you account related emails.

Already on GitHub? Sign in to your account

minor documentation improvements and fixes #8903

Merged
merged 2 commits into from
Mar 14, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/api-guide/authentication.md
Original file line number Diff line number Diff line change
Expand Up @@ -414,7 +414,7 @@ The [HawkREST][hawkrest] library builds on the [Mohawk][mohawk] library to let y

## HTTP Signature Authentication

HTTP Signature (currently a [IETF draft][http-signature-ietf-draft]) provides a way to achieve origin authentication and message integrity for HTTP messages. Similar to [Amazon's HTTP Signature scheme][amazon-http-signature], used by many of its services, it permits stateless, per-request authentication. [Elvio Toccalino][etoccalino] maintains the [djangorestframework-httpsignature][djangorestframework-httpsignature] (outdated) package which provides an easy to use HTTP Signature Authentication mechanism. You can use the updated fork version of [djangorestframework-httpsignature][djangorestframework-httpsignature], which is [drf-httpsig][drf-httpsig].
HTTP Signature (currently a [IETF draft][http-signature-ietf-draft]) provides a way to achieve origin authentication and message integrity for HTTP messages. Similar to [Amazon's HTTP Signature scheme][amazon-http-signature], used by many of its services, it permits stateless, per-request authentication. [Elvio Toccalino][etoccalino] maintains the [djangorestframework-httpsignature][djangorestframework-httpsignature] (outdated) package which provides an easy-to-use HTTP Signature Authentication mechanism. You can use the updated fork version of [djangorestframework-httpsignature][djangorestframework-httpsignature], which is [drf-httpsig][drf-httpsig].

## Djoser

Expand Down
2 changes: 1 addition & 1 deletion docs/api-guide/exceptions.md
Original file line number Diff line number Diff line change
Expand Up @@ -179,7 +179,7 @@ By default this exception results in a response with the HTTP status code "403 F

**Signature:** `NotFound(detail=None, code=None)`

Raised when a resource does not exists at the given URL. This exception is equivalent to the standard `Http404` Django exception.
Raised when a resource does not exist at the given URL. This exception is equivalent to the standard `Http404` Django exception.

By default this exception results in a response with the HTTP status code "404 Not Found".

Expand Down
8 changes: 4 additions & 4 deletions docs/api-guide/fields.md
Original file line number Diff line number Diff line change
Expand Up @@ -251,7 +251,7 @@ Corresponds to `django.forms.fields.IPAddressField` and `django.forms.fields.Gen

**Signature**: `IPAddressField(protocol='both', unpack_ipv4=False, **options)`

* `protocol` Limits valid inputs to the specified protocol. Accepted values are 'both' (default), 'IPv4' or 'IPv6'. Matching is case insensitive.
* `protocol` Limits valid inputs to the specified protocol. Accepted values are 'both' (default), 'IPv4' or 'IPv6'. Matching is case-insensitive.
* `unpack_ipv4` Unpacks IPv4 mapped addresses like ::ffff:192.0.2.1. If this option is enabled that address would be unpacked to 192.0.2.1. Default is disabled. Can only be used when protocol is set to 'both'.

---
Expand Down Expand Up @@ -294,7 +294,7 @@ Corresponds to `django.db.models.fields.DecimalField`.
* `max_value` Validate that the number provided is no greater than this value.
* `min_value` Validate that the number provided is no less than this value.
* `localize` Set to `True` to enable localization of input and output based on the current locale. This will also force `coerce_to_string` to `True`. Defaults to `False`. Note that data formatting is enabled if you have set `USE_L10N=True` in your settings file.
* `rounding` Sets the rounding mode used when quantising to the configured precision. Valid values are [`decimal` module rounding modes][python-decimal-rounding-modes]. Defaults to `None`.
* `rounding` Sets the rounding mode used when quantizing to the configured precision. Valid values are [`decimal` module rounding modes][python-decimal-rounding-modes]. Defaults to `None`.
* `normalize_output` Will normalize the decimal value when serialized. This will strip all trailing zeroes and change the value's precision to the minimum required precision to be able to represent the value without loosing data. Defaults to `False`.

#### Example usage
Expand All @@ -321,13 +321,13 @@ Corresponds to `django.db.models.fields.DateTimeField`.

* `format` - A string representing the output format. If not specified, this defaults to the same value as the `DATETIME_FORMAT` settings key, which will be `'iso-8601'` unless set. Setting to a format string indicates that `to_representation` return values should be coerced to string output. Format strings are described below. Setting this value to `None` indicates that Python `datetime` objects should be returned by `to_representation`. In this case the datetime encoding will be determined by the renderer.
* `input_formats` - A list of strings representing the input formats which may be used to parse the date. If not specified, the `DATETIME_INPUT_FORMATS` setting will be used, which defaults to `['iso-8601']`.
* `default_timezone` - A `tzinfo` subclass (`zoneinfo` or `pytz`) prepresenting the timezone. If not specified and the `USE_TZ` setting is enabled, this defaults to the [current timezone][django-current-timezone]. If `USE_TZ` is disabled, then datetime objects will be naive.
* `default_timezone` - A `tzinfo` subclass (`zoneinfo` or `pytz`) representing the timezone. If not specified and the `USE_TZ` setting is enabled, this defaults to the [current timezone][django-current-timezone]. If `USE_TZ` is disabled, then datetime objects will be naive.

#### `DateTimeField` format strings.

Format strings may either be [Python strftime formats][strftime] which explicitly specify the format, or the special string `'iso-8601'`, which indicates that [ISO 8601][iso8601] style datetimes should be used. (eg `'2013-01-29T12:34:56.000000Z'`)

When a value of `None` is used for the format `datetime` objects will be returned by `to_representation` and the final output representation will determined by the renderer class.
When a value of `None` is used for the format `datetime` objects will be returned by `to_representation` and the final output representation will be determined by the renderer class.

#### `auto_now` and `auto_now_add` model fields.

Expand Down
4 changes: 2 additions & 2 deletions docs/api-guide/filtering.md
Original file line number Diff line number Diff line change
Expand Up @@ -253,7 +253,7 @@ The `OrderingFilter` class supports simple query parameter controlled ordering o

![Ordering Filter](../img/ordering-filter.png)

By default, the query parameter is named `'ordering'`, but this may by overridden with the `ORDERING_PARAM` setting.
By default, the query parameter is named `'ordering'`, but this may be overridden with the `ORDERING_PARAM` setting.

For example, to order users by username:

Expand All @@ -269,7 +269,7 @@ Multiple orderings may also be specified:

### Specifying which fields may be ordered against

It's recommended that you explicitly specify which fields the API should allowing in the ordering filter. You can do this by setting an `ordering_fields` attribute on the view, like so:
It's recommended that you explicitly specify which fields the API should allow in the ordering filter. You can do this by setting an `ordering_fields` attribute on the view, like so:

class UserListView(generics.ListAPIView):
queryset = User.objects.all()
Expand Down
4 changes: 2 additions & 2 deletions docs/api-guide/pagination.md
Original file line number Diff line number Diff line change
Expand Up @@ -240,7 +240,7 @@ Suppose we want to replace the default pagination output style with a modified f
'results': data
})

We'd then need to setup the custom class in our configuration:
We'd then need to set up the custom class in our configuration:

REST_FRAMEWORK = {
'DEFAULT_PAGINATION_CLASS': 'my_project.apps.core.pagination.CustomPagination',
Expand All @@ -262,7 +262,7 @@ API responses for list endpoints will now include a `Link` header, instead of in

![Link Header][link-header]

*A custom pagination style, using the 'Link' header'*
*A custom pagination style, using the 'Link' header*

---

Expand Down
2 changes: 1 addition & 1 deletion docs/api-guide/parsers.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ sending more complex data than simple forms
>
> — Malcom Tredinnick, [Django developers group][cite]

REST framework includes a number of built in Parser classes, that allow you to accept requests with various media types. There is also support for defining your own custom parsers, which gives you the flexibility to design the media types that your API accepts.
REST framework includes a number of built-in Parser classes, that allow you to accept requests with various media types. There is also support for defining your own custom parsers, which gives you the flexibility to design the media types that your API accepts.

## How the parser is determined

Expand Down
4 changes: 2 additions & 2 deletions docs/api-guide/serializers.md
Original file line number Diff line number Diff line change
Expand Up @@ -758,11 +758,11 @@ This is `True` by default, but can be set to `False` if you want to disallow emp

### `max_length`

This is `None` by default, but can be set to a positive integer if you want to validates that the list contains no more than this number of elements.
This is `None` by default, but can be set to a positive integer if you want to validate that the list contains no more than this number of elements.

### `min_length`

This is `None` by default, but can be set to a positive integer if you want to validates that the list contains no fewer than this number of elements.
This is `None` by default, but can be set to a positive integer if you want to validate that the list contains no fewer than this number of elements.

### Customizing `ListSerializer` behavior

Expand Down