Clarify that RangeFields always return canonical form of ranges

[David Binetti]

Asked on #django to no response, so filing here.

When saving a postgres DateRange object to a DateRangeField, the bounds are always changed to the default, even if a different bounds is requested. The date payload (upper or lower), is also changed according to the new bounds. This may be as designed, but it unexpected from my perspective.

For instance, my users may enter data in a form to express a two day event as Jan 1 2016 - Jan 2 2106, '[]' (inclusive lower and inclusive upper.) However, this is translated in the database as Jan 1 2016 - Jan 3 2016 '[)' (inclusive lower *exclusive* upper with changed date) so if I then try to render the upper date directly, it will do so as Jan 3, confusing the user (and the developer :-) !)

Yes, I could accommodate this with some display logic, but that strikes me as the wrong approach. I've included a repo with a test demonstrating what I was expecting to see.

​https://github.com/dbinetti/djangodaterange

[Tim Graham]

From ​the PostgreSQL documentation:

The built-in range types int4range, int8range, and daterange all use a canonical form that includes the lower bound and excludes the upper bound; that is, [). User-defined range types can use other conventions, however.

Do we need to duplicate this information in Django's docs? Actually ​they do say, "The default is lower bound included, upper bound excluded." Maybe the implications of that statement are unclear?

[David Binetti]

Certainly was unclear from my perspective. The word "default" suggests an initial position that is subject to further modification/override. Upon reading the Postgres docs, I now see that it is a canonicalization that is always returned, but even though I read that before I didn't fully understand what was happening on the back-end. It was unclear to me that the bounds is used to produce the canonicalization, but that the bounds themselves were not persisted.

Make of that what you will.

[Tim Graham]

Feel free to propose some clarifications.

[Tim Graham]

Thanks for the draft, but this applies to IntegerRangeField and BigIntegerRangeField as well. Here's an ​alternate proposal.

[Tim Graham <timograham@…>]

In b3610f38:

Fixed #26345 -- Clarified which RangesFields always return a canonical form.

[Tim Graham <timograham@…>]

In d3c2d82d:

[1.9.x] Fixed #26345 -- Clarified which RangesFields always return a canonical form.

Backport of b3610f38facb33704c1fd77590c6a2fa07c40fa7 from master