Code

Opened 6 years ago

Closed 6 years ago

Last modified 6 years ago

#8846 closed (fixed)

Remove comment recommending tuples in settings docs

Reported by: Daniel Pope <dan@…> Owned by: nobody
Component: Documentation Version: master
Severity: Keywords:
Cc: Triage Stage: Unreviewed
Has patch: no Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: UI/UX:

Description

In the documentation for Creating your own settings there's a recommendation which reads "For settings that are sequences, use tuples instead of lists. This is purely for performance."

This is bunk. Profiling shows that tuples run no faster than lists for most operations (certainly looping, which we are likely to do most often). On the other hand, list-literal syntax has the advantage that it doesn't collapse to a single value when you have a single item and omit the trailing comma, like tuple syntax. Using list syntax is no slower, more legible and less error prone. An often-expressed view in the wider Python community seems that tuples should not be considered as immutable lists. They are intended as fixed-length records - indeed the mathematical concept of a tuple is quite distinct from that of a sequence.

I suggest this (factually inaccurate) comment be removed, and in fact we should look at migrating all of the settings documentation to lists for legibility.

Attachments (0)

Change History (5)

comment:1 Changed 6 years ago by dc

  • Needs documentation unset
  • Needs tests unset
  • Patch needs improvement unset

It looks like a duck, it quacks like a duck... For all practical uses tuples behave like immutable lists.

And django settings are immutable too (sort of). And tuples are faster than lists.

So i don't think that this change will improve documentation.

comment:2 Changed 6 years ago by Daniel Pope <dan@…>

tuples behave like immutable lists, but tuple-literal syntax is worse for describing lists (understandable if the intention was not for them to be used as lists).

tuples are negligibly faster than lists:

mauve-desktop:~/dev/Django-1.0$ python -m timeit -s "a = range(1000)" "for i in a: pass"
10000 loops, best of 3: 50.4 usec per loop
mauve-desktop:~/dev/Django-1.0$ python -m timeit -s "a = tuple(range(1000))" "for i in a: pass"
10000 loops, best of 3: 49.3 usec per loop

comment:3 Changed 6 years ago by mtredinnick

We're certainly not about to move from tuples to lists there because it would break existing code that already expects things to be tuples. I'll remove the performance note, however, since it's not worth scaring people.

comment:4 Changed 6 years ago by mtredinnick

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

(In [9146]) Changed the "write your own settings" recommendation to mention that Django
uses tuples, but not making it a recommendation. That might head off the endless
tuples vs. lists debates.

Fixed #8846.

comment:5 Changed 6 years ago by mtredinnick

(In [9147]) [1.0.X] Changed the "write your own settings" recommendation to mention that Django
uses tuples, but not making it a recommendation. That might head off the endless
tuples vs. lists debates.

Fixed #8846.

Backport of r9146 from trunk.

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.