Code

Opened 5 months ago

Closed 5 months ago

Last modified 5 months ago

#21427 closed Cleanup/optimization (fixed)

Clearly state the value range of all integer type fields in the model field documentation

Reported by: giuliettamasina Owned by: nobody
Component: Documentation Version: master
Severity: Normal Keywords:
Cc: Triage Stage: Ready for checkin
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no

Description

The documentation for BigIntegerField, PositiveSmallIntegerField and SmallIntegerField clearly state what integer values fit into that field's size:

https://docs.djangoproject.com/en/dev/ref/models/fields/#bigintegerfield
https://docs.djangoproject.com/en/dev/ref/models/fields/#positivesmallintegerfield
https://docs.djangoproject.com/en/dev/ref/models/fields/#smallintegerfield

But these do not state the same info:

https://docs.djangoproject.com/en/dev/ref/models/fields/#integerfield
https://docs.djangoproject.com/en/dev/ref/models/fields/#positiveintegerfield

For clarity, I think all of the above fields should be documented with a standardized sentence like this:

"Values from X to Y are safe in all databases supported by Django."

Attachments (0)

Change History (8)

comment:1 Changed 5 months ago by timo

  • Needs documentation unset
  • Needs tests unset
  • Patch needs improvement unset
  • Triage Stage changed from Unreviewed to Accepted
  • Version set to master

comment:2 Changed 5 months ago by giuliettamasina

Opened a pull request here: https://github.com/django/django/pull/1949

comment:3 Changed 5 months ago by timo

  • Has patch set
  • Triage Stage changed from Accepted to Ready for checkin

Assuming the ranges are correct, this looks good. Could you amend your PR to follow the commit message guidelines? Also, don't forget to check "Has patch" so the ticket appears in the review queue. Thanks!

comment:4 Changed 5 months ago by claudep

  • Triage Stage changed from Ready for checkin to Accepted

Sorry, but I'd like to know where do the new figures come from. Could you please document here your findings (with appropriate links to backends documentation)?

comment:5 Changed 5 months ago by giuliettamasina

Sorry, I did not do my homework properly, and the values were not correct.

I've now corrected them and opened a new pull request (following commit message guidelines): https://github.com/django/django/pull/1955

The values and their sources are as follows:

MySQL
IntegerField (integer): -2147483648 to 2147483647
PositiveIntegerField (integer UNSIGNED): 0 to 2147483647
PositiveSmallIntegerField (smallint UNSIGNED): 0 to 32767
Source: http://dev.mysql.com/doc/refman/5.0/en/integer-types.html

Postgres
IntegerField (integer): -2147483648 to 2147483647
PositiveIntegerField (integer): 0 to 2147483647
PositiveSmallIntegerField (smallint): 0 to 32767
Source: http://www.postgresql.org/docs/devel/static/datatype-numeric.html

Oracle
IntegerField (NUMBER(11)): -99999999999 to 99999999999
PositiveIntegerField (NUMBER(11)): 0 to 99999999999
PositiveSmallIntegerField (NUMBER(11)): 0 to 99999999999
Source: http://docs.oracle.com/cd/E11882_01/server.112/e25513/limits001.htm

SQLite
("1, 2, 3, 4, 6, or 8 bytes depending on the magnitude of the value.")
IntegerField (integer): -9223372036854775808 to 9223372036854775807
PositiveIntegerField (integer unsigned): 0 to 9223372036854775807
PositiveSmallIntegerField (smallint unsigned): 0 to 9223372036854775807
Source: http://www.sqlite.org/datatype3.html

comment:6 Changed 5 months ago by bmispelon

  • Triage Stage changed from Accepted to Ready for checkin

Everything looks good.

Thanks for finding all the references too, this is very valuable.

I'll mark the ticket as ready for checkin and commit it later today if no one does it before.

comment:7 Changed 5 months ago by Baptiste Mispelon <bmispelon@…>

  • Resolution set to fixed
  • Status changed from new to closed

In b6a6cf4ab791b092e18ab16537aa88dd7ae9bc36:

Fixed #21427 -- Clearly state integer field value ranges in docs

Added an explicit mention of the exact value ranges for integer type
fields that are safe in all databases supported by Django. Also, put
all value numbers inside double ticks.

comment:8 Changed 5 months ago by Baptiste Mispelon <bmispelon@…>

In 47abfa237e21ca71d8ee901cf8ba1f1c89ae1f2e:

[1.6.x] Fixed #21427 -- Clearly state integer field value ranges in docs

Added an explicit mention of the exact value ranges for integer type
fields that are safe in all databases supported by Django. Also, put
all value numbers inside double ticks.

Backport of b6a6cf4ab791b092e18ab16537aa88dd7ae9bc36 from master.

Add Comment

Modify Ticket

Change Properties
<Author field>
Action
as closed
as The resolution will be set. Next status will be 'closed'
The resolution will be deleted. Next status will be 'new'
Author


E-mail address and user name can be saved in the Preferences.

 
Note: See TracTickets for help on using tickets.