Two Scoops of Django 1.11: Best Practices for the Django Web Framework

553 Pages·2017·5.36 MB·English

Two Scoops of Django
1.11
Best Practices for Django
Daniel Roy Greenfeld
Audrey Roy Greenfeld
TwoScoopsofDjango1.11:BestPracticesforDjango
FourthEdition,2017-06-03
byDanielRoyGreenfeldandAudreyRoyGreenfeld
Copyright©2013-2017DanielRoyGreenfeld,AudreyRoyGreenfeld,andTwoScoopsPress.
Allrightsreserved.Thisbookmaynotbereproducedinanyform,inwholeorinpart,withoutwrittenpermissionfromthe
authors,exceptinthecaseofbriefquotationsembodiedinarticlesorreviews.
LimitofLiabilityandDisclaimerofWarranty:Theauthorshaveusedtheirbesteffortsinpreparingthisbook,andthe
informationprovidedherein“asis.”Theinformationprovidedissoldwithoutwarranty,eitherexpressorimplied.Neitherthe
authorsnorCartwheelWebwillbeheldliableforanydamagestobecausedeitherdirectlyorindirectlybythecontentsof
thisbook.
Trademarks:Ratherthanindicatingeveryoccurrenceofatrademarkednameassuch,thisbookusesthenamesonlyinan
editorialfashionandtothebenefitofthetrademarkownerwithnointentionofinfringementofthetrademark.
FirstPrinting,April2017,Version20170603
Formoreinformation,visithttps://twoscoopspress.com.
iii
iv
Dedication
For Malcolm Tredinnick
1971-2013
We miss you.
twoscoopspress.com/pages/malcolm-tredinnick-memorial
v
AbouttheDedication
Malcolm Tredinnick wasn’t just a Django core developer and reviewer of “Two Scoops of Django:
BestPracticesforDjango1.5.”Tous,hewasmuch,muchmore.
DanielhadworkedwithMalcolmTredinnickinthesummerof2010,butwefirstmethiminperson
atDjangoCon2010.Hewasfunnyandcharming,sharplyopinionatedbutalwaysagentleman;we
instantlybecameclosefriends.
In2012,whenweco-organizedthefirstPyConPhilippines,assoonaswetoldhimaboutit,Mal-
colminstantlydeclaredhewascoming.Hegavetwomemorabletalksandrananimpromptuall-day
Djangotutorial.HealsopushedandencouragedthelocalcommunitytoworkonFilipinolanguage
translationsforDjango,includingTagalog,Tausug,Cebuano,andmore.
Aftertheconference,westartedworkingonabookaboutDjangobestpractices.Wegatheredfriends
andcolleaguestohelpusastechnicalreviewers.MalcolmTredinnickbecamethemostactiveofthem.
Hewasourmentorandforcedustodigdeeperandworkharder.Hedidthiswhileworkingaday
jobastheleaderofacombinedRailsandHaskellteam;Malcolmwasatrueprogramminglanguage
polyglot.
Forourbook,heprovidedsomuchassistanceandguidancewetriedtofigureoutawaytoinclude
him in the author credits. When we told him about our dilemma, he laughed it off saying, “For a
book called ‘Two Scoops’, you can’t have three authors.” We suggested he share credit with us on
a second book, and he refused, saying he preferred to just comment on our work. He said that he
wantedpeopletohaveproperreferences,andforhim,simplyreviewingourworkwascontributing
tothegreatergood.Eventuallythetwoofusquietlyplannedtosomehowcoercehimintobeinga
co-authoronafuturework.
Aftermonthsofeffort,wereleasedthefirstiterationonJanuary17th,2013.Malcolmsteppedback
fromTwoScoopsofDjango,butwestayedintouch.SinceMalcolmwasunabletoattendPyCon
US2013weweren’tsurewhenwewouldmeethimagain.
Twomonthslater,onMarch17th,2013,Malcolmpassedaway.
We knew Malcolm for less than three years and yet he made an incredible difference in our lives.
We’veheardmanysimilarstoriesinthecommunityaboutMalcolm;Hewasafriendandmentorto
countlessothersaroundtheworld.Hislastlessontouswentbeyondcodeorwriting,hetaughtus
tonevertakeforgrantedfriends,family,mentors,andteachers.
Contents
Dedication v
AbouttheDedication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vi
Authors’Notes xxvii
AFewWordsFromDanielRoyGreenfeld . . . . . . . . . . . . . . . . . . . . . . . . . xxvii
AFewWordsFromAudreyRoyGreenfeld . . . . . . . . . . . . . . . . . . . . . . . .xxviii
Introduction xxix
AWordAboutOurRecommendations . . . . . . . . . . . . . . . . . . . . . . . . . . xxix
WhyTwoScoopsofDjango? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxx
BeforeYouBegin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxxi
ThisbookisintendedforDjango1.11andPython3.6.x/2.7.12 . . . . . . . . . . . xxxi
EachChapterStandsOnItsOwn . . . . . . . . . . . . . . . . . . . . . . . . . . xxxi
ConventionsUsedinThisBook. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxxii
CoreConcepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xxxiii
KeepItSimple,Stupid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xxxiii
FatModels,UtilityModules,ThinViews,StupidTemplates . . . . . . . . . . . .xxxiv
StartWithDjangoByDefault . . . . . . . . . . . . . . . . . . . . . . . . . . . .xxxiv
BeFamiliarwithDjango’sDesignPhilosophies . . . . . . . . . . . . . . . . . . .xxxiv
TheTwelve-FactorApp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxxv
OurWritingConcepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxxv
ProvidetheBestMaterial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxxv
StandontheShouldersofGiants . . . . . . . . . . . . . . . . . . . . . . . . . . .xxxvi
ListentoOurReadersandReviewers . . . . . . . . . . . . . . . . . . . . . . . .xxxvi
PublishErrata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xxxvi
1 CodingStyle 1
1.1 TheImportanceofMakingYourCodeReadable . . . . . . . . . . . . . . . . . . 1
vii
Contents
1.2 PEP8 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.2.1 The79-CharacterLimit . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.3 TheWordonImports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.4 UseExplicitRelativeImports . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.5 AvoidUsingImport* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
1.5.1 OtherPythonNamingCollisions. . . . . . . . . . . . . . . . . . . . . . 8
1.6 DjangoCodingStyle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
1.6.1 ConsidertheDjangoCodingStyleGuidelines . . . . . . . . . . . . . . . 9
1.6.2 UseUnderscoresinURLPatternNamesRatherThanDashes. . . . . . . 9
1.6.3 UseUnderscoresinTemplateBlockNamesRatherThanDashes . . . . . 10
1.7 ChooseJS,HTML,andCSSStyleGuides . . . . . . . . . . . . . . . . . . . . . 10
1.7.1 JavaScriptStyleGuides . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
1.7.2 HTMLandCSSStyleGuides . . . . . . . . . . . . . . . . . . . . . . . 11
1.8 NeverCodetotheIDE(OrTextEditor) . . . . . . . . . . . . . . . . . . . . . . 11
1.9 Summary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
2 TheOptimalDjangoEnvironmentSetup 13
2.1 UsetheSameDatabaseEngineEverywhere . . . . . . . . . . . . . . . . . . . . 13
2.1.1 YouCan’tExamineanExactCopyofProductionDataLocally . . . . . . 13
2.1.2 DifferentDatabasesHaveDifferentFieldTypes/Constraints . . . . . . . 14
2.1.3 FixturesAreNotaMagicSolution . . . . . . . . . . . . . . . . . . . . . 15
2.2 UsePipandVirtualenv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
2.2.1 virtualenvwrapper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
2.3 InstallDjangoandOtherDependenciesviaPip . . . . . . . . . . . . . . . . . . 18
2.4 UseaVersionControlSystem . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
2.5 Optional:IdenticalEnvironments . . . . . . . . . . . . . . . . . . . . . . . . . . 19
2.5.1 Docker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
2.6 Summary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
3 HowtoLayOutDjangoProjects 21
3.1 Django1.11’sDefaultProjectLayout . . . . . . . . . . . . . . . . . . . . . . . . 21
3.2 OurPreferredProjectLayout . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
3.2.1 TopLevel:RepositoryRoot. . . . . . . . . . . . . . . . . . . . . . . . . 23
3.2.2 SecondLevel:DjangoProjectRoot. . . . . . . . . . . . . . . . . . . . . 23
3.2.3 SecondLevel:ConfigurationRoot . . . . . . . . . . . . . . . . . . . . . 23
3.3 SampleProjectLayout. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
viii