diff --git a/Readme.rst b/Readme.rst index d7d26dfb1..f35c71225 100644 --- a/Readme.rst +++ b/Readme.rst @@ -3,6 +3,8 @@ Hitchhiker's Guide to Python **Python Best Practices Guidebook** +→ Read the free guide at: `docs.python-guide.org `_ + .. image:: https://farm1.staticflickr.com/628/33173824932_58add34581_k_d.jpg ----------- diff --git a/docs/Makefile b/docs/Makefile index 13201e251..963704aff 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -19,7 +19,7 @@ ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . # the i18n builder cannot share the environment and doctrees with the others I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . -.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext +.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf latexpdfja text man changes linkcheck doctest gettext help: @echo "Please use \`make ' where is one of" diff --git a/docs/_extra/ads.txt b/docs/_extra/ads.txt index fca0f39b3..52291a930 100644 --- a/docs/_extra/ads.txt +++ b/docs/_extra/ads.txt @@ -1,105 +1,340 @@ -google.com, pub-2802445174821308, RESELLER, f08c47fec0942fa0 - - -appnexus.com, 8692, DIRECT, f5ab79cb980f11d1 - - -districtm.io, 100835, DIRECT -appnexus.com, 1908, RESELLER, f5ab79cb980f11d1 -google.com, pub-9685734445476814, RESELLER, f08c47fec0942fa0 - - -appnexus.com, 1613, reseller -appnexus.com, 3326, reseller -google.com, pub-1409765517756851, reseller -google.com, pub-4075894099602271, reseller -freewheel.tv, 146081, reseller -rubiconproject.com, 8861, reseller, 0bfd66d529a55807 - - -aol.com, 11119, DIRECT -adtech.com, 11341, DIRECT -coxmt.com, 2000067907202, RESELLER -Openx.com, 537143344, RESELLER -indexexchange.com, 175407, RESELLER - - -sonobi.com, 337f0e70cc, DIRECT -rhythmone.com, 1059622079, RESELLER -contextweb.com, 560606, RESELLER - - -sovrn.com, 217352, DIRECT, fafdf38b16bf6b2b -lijit.com, 217352, DIRECT, fafdf38b16bf6b2b -openx.com, 537120960, RESELLER -openx.com, 83499, RESELLER -openx.com, 538959099, RESELLER -pubmatic.com, 137711, RESELLER -pubmatic.com, 156212, RESELLER -pubmatic.com, 62483, RESELLER -contextweb.com, 558511, RESELLER -gumgum.com, 11645, RESELLER, ffdef49475d318a9 - - -openx.com, 539824308, RESELLER, 6a698e2ec38604c6 - - -rubiconproject.com, 17822, DIRECT, 0bfd66d529a55807 - - -gumgum.com, 13174, DIRECT, ffdef49475d318a9 +33across.com, 0010b00002Mpn7AAAR, DIRECT, bbea06d9c4d2853c +33across.com, 0013300001kQj2HAAS, RESELLER, bbea06d9c4d2853c +33across.com, 0013300001qkdlwAAA, RESELLER 33across.com, 0013300001r0t9mAAA, RESELLER +33across.com, 0014000001aXjnGAAS, RESELLER, bbea06d9c4d2853c # 33 Across +33across.com,0013300001r0t9mAAA,reseller,bbea06d9c4d2853c +ad-generation.jp,12474,RESELLER,7f4ea9029ac04e53 +adform.com, 183, RESELLER +adform.com, 2708, DIRECT, 9f5210a2f0999e32 +adtech.com, 10947, DIRECT, e1a5b5b6e3255540 +adtech.com, 11095, RESELLER +adtech.com, 11119, RESELLER +adtech.com, 11208, RESELLER +adtech.com, 11341, DIRECT +adtech.com, 12094, RESELLER +adtech.com, 12094, RESELLER # 33 Across adtech.com, 9904, RESELLER +adtech.com,12068,RESELLER,e1a5b5b6e3255540 +advangelists.com, 8d3bba7425e7c98c50f52ca1b52d3735, RESELLER, 60d26397ec060f98 +advangelists.com, 8d3bba7425e7c98c50f52ca1b52d3735, RESELLER, 60d26397ec060f98 # 33 Across +advertising.com, 11602, RESELLER Advertising.com, 16736, RESELLER +advertising.com, 19623, RESELLER # AOL - One +advertising.com, 24410, RESELLER +advertising.com, 28409, DIRECT, e1a5b5b6e3255540 +advertising.com, 28509, DIRECT, e1a5b5b6e3255540 +advertising.com, 28605, RESELLER # RhythmOne +advertising.com, 7372, RESELLER +advertising.com, 8603, RESELLER # Taboola +amxrtb.com, 105199384, DIRECT +aol.com, 11119, DIRECT +aol.com, 53392, RESELLER # Taboola aolcloud.net, 9904, RESELLER appnexus.com, 1001, RESELLER, f5ab79cb980f11d1 +appnexus.com, 10239, RESELLER, f5ab79cb980f11d1 +appnexus.com, 10239, RESELLER, f5ab79cb980f11d1 # 33 Across +appnexus.com, 11786, RESELLER, f5ab79cb980f11d1 +appnexus.com, 11801, RESELLER +appnexus.com, 11924, RESELLER, f5ab79cb980f11d1 +appnexus.com, 12061, RESELLER +appnexus.com, 12263, RESELLER +appnexus.com, 12290, RESELLER, f5ab79cb980f11d1 +appnexus.com, 12366, RESELLER, f5ab79cb980f11d1 +appnexus.com, 1314, RESELLER +Appnexus.com, 1356, RESELLER, f5ab79cb980f11d1 +appnexus.com, 1360, RESELLER, f5ab79cb980f11d1 +appnexus.com, 1613, reseller +appnexus.com, 1908, RESELLER +appnexus.com, 1908, RESELLER, f5ab79cb980f11d1 +appnexus.com, 1908, RESELLER, f5ab79cb980f11d1 # DistrictM appnexus.com, 1942, RESELLER, f5ab79cb980f11d1 +appnexus.com, 2530, RESELLER appnexus.com, 2758, RESELLER, f5ab79cb980f11d1 appnexus.com, 3135, RESELLER, f5ab79cb980f11d1 +appnexus.com, 3153, DIRECT +appnexus.com, 3153, RESELLER +appnexus.com, 3153, RESELLER, f5ab79cb980f11d1 +appnexus.com, 3326, reseller +appnexus.com, 4052, RESELLER +appnexus.com, 4052, RESELLER, f5ab79cb980f11d1 # Conversant +appnexus.com, 6849, RESELLER, f5ab79cb980f11d1 # RhythmOne +appnexus.com, 7118, RESELLER +appnexus.com, 7556, DIRECT, f5ab79cb980f11d1 appnexus.com, 7597, RESELLER, f5ab79cb980f11d1 +appnexus.com, 7911, RESELLER #yieldmo +appnexus.com, 7944, RESELLER +appnexus.com, 8692, DIRECT, f5ab79cb980f11d1 +appnexus.com, 9316, RESELLER, f5ab79cb980f11d1 # AppNexus +appnexus.com, 9393, DIRECT +appnexus.com, 9393, RESELLER #Video #Display, f5ab79cb980f11d1 +appnexus.com,1001,reseller,f5ab79cb980f11d1 +appnexus.com,10239,reseller,f5ab79cb980f11d1 +appnexus.com,1356,reseller,f5ab79cb980f11d1 +appnexus.com,1908,RESELLER,f5ab79cb980f11d1 +appnexus.com,2758,reseller,f5ab79cb980f11d1 +appnexus.com,3663,RESELLER,f5ab79cb980f11d1 +appnexus.com,7597,reseller,f5ab79cb980f11d1 +appnexus.com,9316,reseller,f5ab79cb980f11d1 +aps.amazon.com,094e2c86-72d9-47d6-a647-d95ce39ad4c7,DIRECT +aps.amazon.com,2840f06c-5d89-4853-a03e-3bfa567dd33c,reseller +aps.amazon.com,48266a61-b3d9-4cb7-b172-553abc6a42a4,DIRECT +aralego.com, par-488A3E6BD8D997D0ED8B3BD34D8BA4B, RESELLER # ucFunnel +audienciad.com, 202922, DIRECT bidtellect.com, 1407, RESELLER, 1c34aa2d85d45e93 +bidtellect.com,1407,reseller,1c34aa2d85d45e93 +brightcom.com, 20292, DIRECT +ccoxmt.com, 2000067997702, RESELLER +consumable.com, 2000908, DIRECT, aefcd3d2f45b5070 contextweb.com, 558355, RESELLER +contextweb.com, 558511, RESELLER +contextweb.com, 560606, RESELLER +contextweb.com, 560606, RESELLER, 89ff185a4c4e857 +contextweb.com, 560606, RESELLER, 89ff185a4c4e857c +contextweb.com, 561118, RESELLER, 89ff185a4c4e857c #yieldmo +contextweb.com, 561998, RESELLER, 89ff185a4c4e857c +contextweb.com, 562350, RESELLER, 89ff185a4c4e857c +contextweb.com,558355,reseller +conversantmedia.com, 20923, RESELLER # Conversant +conversantmedia.com, 39882, DIRECT, 03113cd04947736d +conversantmedia.com, 40790, RESELLER, 03113cd04947736d +conversantmedia.com, 41812, DIRECT +coxmt.com, 2000067907202, RESELLER criteo.com, 109412, DIRECT, 9fac4a4a87c2a44f +districtm.io, 100808, DIRECT +districtm.io, 100835, DIRECT +districtm.io, 100835, DIRECT, 3fd707be9c4527c3 +districtm.io, 101080, RESELLER +districtm.io, 101769, RESELLER, 3fd707be9c4527c3 # DistrictM +districtm.io,100962,RESELLER,3fd707be9c4527c3 +EMXDGT.com, 1133, DIRECT, 1e1d41537f7cad7f +emxdgt.com, 20, DIRECT, 1e1d41537f7cad7f +emxdgt.com, 326, RESELLER, 1e1d41537f7cad7f +emxdgt.com, 326, RESELLER, 1e1d41537f7cad7f # 33 Across +EMXDGT.com,1284,reseller,1e1d41537f7cad7f +engagebdr.com, 10417, RESELLER # EngageDBR +freewheel.tv, 146081, reseller +freewheel.tv, 19129, RESELLER +freewheel.tv, 19133, RESELLER +freewheel.tv, 33081, RESELLER +freewheel.tv, 33601, RESELLER +freewheel.tv, 799841, RESELLER # Taboola +freewheel.tv, 799921, RESELLER # Taboola +google.com, pub-1320774679920841, RESELLER, f08c47fec0942fa0 +google.com, pub-1409765517756851, reseller +google.com, pub-2290755540215120, RESELLER, f08c47fec0942fa0 +google.com, pub-2802445174821308, RESELLER, f08c47fec0942fa0 google.com, pub-3848273848634341, RESELLER, f08c47fec0942fa0 +google.com, pub-4075894099602271, reseller +google.com, pub-4207323757133151, RESELLER, f08c47fec0942fa0 +google.com, pub-4641608711979091, DIRECT, f08c47fec0942fa0 +google.com, pub-5231479214411897, RESELLER, f08c47fec0942fa0 +Google.com, pub-5995202563537249, RESELLER, f08c47fec0942fa0 +google.com, pub-6314168058065736, RESELLER, f08c47fec0942fa0 +google.com, pub-8172268348509349, RESELLER, f08c47fec0942fa0 google.com, pub-9557089510405422, RESELLER, f08c47fec0942fa0 +google.com, pub-9557089510405422, RESELLER, f08c47fec0942fa0 # 33 Across +google.com, pub-9685734445476814, RESELLER, f08c47fec0942fa0 +google.com, pub-9685734445476814, RESELLER, f08c47fec0942fa0 # DistrictM +google.com,pub-3848273848634341,reseller,f08c47fec0942fa0 +google.com,pub-9557089510405422,reseller,f08c47fec0942fa0 +gumgum.com, 11645, RESELLER, ffdef49475d318a9 +gumgum.com, 13174, DIRECT, ffdef49475d318a9 +gumgum.com, 13318, RESELLER, ffdef49475d318a9 +gumgum.com, 13318, RESELLER, ffdef49475d318a9 # 33 Across +gumgum.com, 13504, RESELLER, ffdef49475d318a9 +gumgum.com,13174,DIRECT,ffdef49475d318a9 +gumgum.com,14141,RESELLER,ffdef49475d318a9 +improvedigital.com, 1362, RESELLER +improvedigital.com, 1669, RESELLER # ImproveDigital +improvedigital.com, 185, RESELLER +indexexchange.com, 175407, RESELLER indexexchange.com, 177754, RESELLER, 50b1c356f2c5c8fc +indexexchange.com, 182257, RESELLER, 50b1c356f2c5c8fc # RhythmOne +indexexchange.com, 183965, RESELLER, 50b1c356f2c5c8fc # AOL - One +indexexchange.com, 184914, DIRECT, 50b1c356f2c5c8fc +indexexchange.com, 186046, RESELLER +indexexchange.com, 186248, DIRECT, 50b1c356f2c5c8fc +indexexchange.com, 187196, DIRECT +indexexchange.com, 187454, DIRECT, 50b1c356f2c5c8fc +indexexchange.com, 189744, RESELLER +indexexchange.com, 189872, RESELLER +indexexchange.com, 191503, RESELLER, 50b1c356f2c5c8fc +indexexchange.com, 191740, RESELLER, 50b1c356f2c5c8fc # Index +indexexchange.com, 191923, RESELLER +indexexchange.com, 191973, RESELLER, 50b1c356f2c5c8fc +indexexchange.com, 193351, DIRECT +lijit.com, 217352, DIRECT, fafdf38b16bf6b2b +lijit.com, 217352-eb, DIRECT, fafdf38b16bf6b2b +lijit.com, 248396, DIRECT, fafdf38b16bf6b2b +lijit.com, 248396-eb, DIRECT, fafdf38b16bf6b2b +lijit.com, 260380, RESELLER, fafdf38b16bf6b2b +lijit.com, 270524, RESELLER, fafdf38b16bf6b2b +lijit.com,217352,DIRECT,fafdf38b16bf6b2b lkqd.com, 470, RESELLER, 59c49fa9598a0117 lkqd.net, 470, RESELLER, 59c49fa9598a0117 +Newormedia.com, 2169, DIRECT +newormedia.com, 4908, DIRECT +onetag.com, 572a470226457b8, RESELLER # OneTag +onetag.com, 664e107d9f2b748, RESELLER #yieldmo +onomagic.com, 202921, DIRECT +openx.com, 539824308, RESELLER, 6a698e2ec38604c6 openx.com, 537120563, RESELLER, 6a698e2ec38604c6 +openx.com, 537120563, RESELLER, 6a698e2ec38604c6 # 33 Across +openx.com, 537120960, RESELLER +openx.com, 537127577, RESELLER, 6a698e2ec38604c6 +Openx.com, 537143344, RESELLER openx.com, 537149485, RESELLER, 6a698e2ec38604c6 +openx.com, 537150004, DIRECT, 6a698e2ec38604c6 +openx.com, 537153209, RESELLER, 6a698e2ec38604c6 +openx.com, 538959099, RESELLER +openx.com, 538959099, RESELLER, 6a698e2ec38604c6 +openx.com, 539699341, DIRECT, 6a698e2ec38604c6 +openx.com, 539824308, RESELLER, 6a698e2ec38604c6 openx.com, 540003333, RESELLER, 6a698e2ec38604c6 -outbrain.com, 01a755b08c8c22b15d46a8b753ab6955d4, RESELLER +openx.com, 540031703, RESELLER, 6a698e2ec38604c6 +openx.com, 540031703, RESELLER, 6a698e2ec38604c6 # Conversant +openx.com, 540258065, RESELLER, 6a698e2ec38604c6 +openx.com, 540274407, RESELLER, 6a698e2ec38604c6 +openx.com, 540337213, RESELLER, 6a698e2ec38604c6 +openx.com, 540401713, RESELLER, 6a698e2ec38604c6 # OpenX +openx.com, 541159484, RESELLER, 6a698e2ec38604c6 +openx.com, 542511596, RESELLER, 6a698e2ec38604c6 +openx.com, 83499, RESELLER +openx.com,537149485,reseller,6a698e2ec38604c6 +openx.com,540191398,RESELLER,6a698e2ec38604c6 +openx.com,540833447, RESELLER, 6a698e2ec38604c6 outbrain.com, 01a755b08c8c22b15d46a8b753ab6955d4, DIRECT +outbrain.com, 01a755b08c8c22b15d46a8b753ab6955d4, RESELLER +outbrain.com,00254374f0c468f3b2732db17fd42cb6e5,reseller +pubmatic.com, 137711, RESELLER +pubmatic.com, 137711, RESELLER, 5d62403b186f2ace +pubmatic.com, 156084, RESELLER, 5d62403b186f2ace # AOL - One +pubmatic.com, 156212, RESELLER +pubmatic.com, 156212, RESELLER, 5d62403b186f2ace +pubmatic.com, 156307, RESELLER, 5d62403b186f2ace # Taboola +pubmatic.com, 156319, DIRECT, 5d62403b186f2ace +pubmatic.com, 156325, RESELLER, 5d62403b186f2ace # AOL - One +pubmatic.com, 156344, RESELLER, 5d62403b186f2ace # Pubmatic +pubmatic.com, 156423, RESELLER, 5d62403b186f2ace +pubmatic.com, 156423, RESELLER, 5d62403b186f2ace # 33 Across +pubmatic.com, 156458, RESELLER, 5d62403b186f2ace # AOL - One +pubmatic.com, 156557, RESELLER +pubmatic.com, 156595, RESELLER, 5d62403b186f2ace +pubmatic.com, 157367, DIRECT, 5d62403b186f2ace +pubmatic.com, 158100, RESELLER, 5d62403b186f2ace +pubmatic.com, 158355 , RESELLER, 5d62403b186f2ace +pubmatic.com, 158723, RESELLER, 5d62403b186f2ace +pubmatic.com, 159117, DIRECT, 5d62403b186f2ace +pubmatic.com, 159277, RESELLER, 5d62403b186f2ace # RhythmOne +pubmatic.com, 159330, RESELLER, 5d62403b186f2ace +pubmatic.com, 159477,RESELLER,5d62403b186f2ace +pubmatic.com, 160082 , RESELLER, 5d62403b186f2ace +pubmatic.com, 160131, RESELLER, 5d62403b186f2ace +pubmatic.com, 32987, RESELLER, 5d62403b186f2ace pubmatic.com, 50758, RESELLER, 5d62403b186f2ace +pubmatic.com, 62483, RESELLER +pubmatic.com, 79136 , RESELLER, 5d62403b186f2ace +pubmatic.com,157150,RESELLER,5d62403b186f2ace +pubmatic.com,157897,reseller,5d62403b186f2ace +pubmatic.com,160006,RESELLER,5d62403b186f2ace +pubmatic.com,160096,RESELLER,5d62403b186f2ace +pubnative.net, 1007284, RESELLER, d641df8625486a7b #yieldmodisplay +pubnative.net, 1007285, RESELLER, d641df8625486a7b #yieldmonative +pubnative.net, 1007286, RESELLER, d641df8625486a7b #yieldmovideo +pubnx.com, 337-1, RESELLER, 8728b7e97e589da4 # Vertoz revcontent.com, 76611, RESELLER -rhythmone.com, 78519861, RESELLER -smaato.com, 1100033117, RESELLER -spotx.tv, 147949, RESELLER, 7842df1d2fe2db34 -spotxchange.com, 147949, RESELLER, 7842df1d2fe2db34 -springserve.com, 686, DIRECT, a24eb641fc82e93d - - -indexexchange.com, 187196, DIRECT - +rhythmone.com, 1059622079, RESELLER rhythmone.com, 1059622079, RESELLER, a670c89d4a324e47 -contextweb.com, 560606, RESELLER, 89ff185a4c4e857 -ccoxmt.com, 2000067997702, RESELLER -adtech.com, 11119, RESELLER -33across.com, 0013300001r0t9mAAA, RESELLER -adtech.com, 9904, RESELLER -Advertising.com, 16736, RESELLER -aolcloud.net, 9904, RESELLER -appnexus.com, 7597, RESELLER, f5ab79cb980f11d1 -bidtellect.com, 1407, RESELLER, 1c34aa2d85d45e93 -contextweb.com, 558355, RESELLER -criteo.com, 109412, DIRECT, 9fac4a4a87c2a44f -indexexchange.com, 177754, RESELLER, 50b1c356f2c5c8fc -lkqd.com, 470, RESELLER, 59c49fa9598a0117 -lkqd.net, 470, RESELLER, 59c49fa9598a0117 -outbrain.com, 01a755b08c8c22b15d46a8b753ab6955d4, RESELLER -outbrain.com, 01a755b08c8c22b15d46a8b753ab6955d4, DIRECT -revcontent.com, 76611, RESELLER +rhythmone.com, 1114124056, RESELLER, a670c89d4a324e47 +rhythmone.com, 1166984029, RESELLER, a670c89d4a324e47 # Taboola +rhythmone.com, 2241341073, RESELLER, a670c89d4a324e47 +rhythmone.com, 2310154583, DIRECT, a670c89d4a324e47 +rhythmone.com, 2439829435, RESELLER, a670c89d4a324e47 +rhythmone.com, 2439829435, RESELLER, a670c89d4a324e47 # 33 Across +rhythmone.com, 78519861, RESELLER +rhythmone.com, 905992537, RESELLER, a670c89d4a324e47 # RhythmOne +rhythmone.com,1654642120,RESELLER,a670c89d4a324e47 +rhythmone.com,2310154583,DIRECT,a670c89d4a324e47 +rhythmone.com,78519861,reseller,a670c89d4a324e47 +rtk.io, 819, DIRECT +rubiconproject.com, 13344, RESELLER, 0bfd66d529a55807 # Rubicon +rubiconproject.com, 15268, RESELLER, 0bfd66d529a55807 # RhythmOne +rubiconproject.com, 16414, RESELLER, 0bfd66d529a55807 +rubiconproject.com, 16414, RESELLER, 0bfd66d529a55807 # 33 Across +rubiconproject.com, 17070, RESELLER, 0bfd66d529a55807 #yieldmo +rubiconproject.com, 17632, DIRECT, 0bfd66d529a55807 +rubiconproject.com, 17790, RESELLER, 0bfd66d529a55807 +rubiconproject.com, 17792, RESELLER, 0bfd66d529a55807 +rubiconproject.com, 17822, DIRECT, 0bfd66d529a55807 +rubiconproject.com, 17822, RESELLER, 0bfd66d529a55807 +rubiconproject.com, 17960, RESELLER, 0bfd66d529a55807 +rubiconproject.com, 18222, RESELLER, 0bfd66d529a55807 # AOL - One +rubiconproject.com, 18694, RESELLER, 0bfd66d529a55807 +rubiconproject.com, 18890, DIRECT, 0bfd66d529a55807 +rubiconproject.com, 20130, RESELLER, 0bfd66d529a55807 +rubiconproject.com, 20416, RESELLER, 0bfd66d529a55807 +rubiconproject.com, 21310, RESELLER , 0bfd66d529a55807 +rubiconproject.com, 21642, RESELLER, 0bfd66d529a55807 +rubiconproject.com, 8861, reseller, 0bfd66d529a55807 +rubiconproject.com,18020,RESELLER,0bfd66d529a55807 +Sekindo.com, 20749, DIRECT, b6b21d256ef43532 +sharethrough.com, 3a0f657b, DIRECT, d53b998a7bd4ecd2 +sharethrough.com, d09156e5, RESELLER, d53b998a7bd4ecd2 smaato.com, 1100033117, RESELLER +smaato.com, 1100047713, RESELLER, 07bcf65f187117b4 +smaato.com,1100044650,RESELLER,07bcf65f187117b4 +smartadserver.com, 3436, RESELLER +sonobi.com, 337f0e70cc, DIRECT +sonobi.com, 37dd19ad4a, RESELLER, d1a215d9eb5aee9e +sonobi.com, 6e5cfb5420, DIRECT, d1a215d9eb5aee9e +sonobi.com, e55fb5d7c2, DIRECT, d1a215d9eb5aee9e +sovrn.com, 217352, DIRECT, fafdf38b16bf6b2b +sovrn.com, 248396, DIRECT, fafdf38b16bf6b2b +sovrn.com, 260380, RESELLER, fafdf38b16bf6b2b +sovrn.com, 270524, RESELLER, fafdf38b16bf6b2b +sovrn.com,217352,DIRECT,fafdf38b16bf6b2b +sparcmedia.com, 310627, Direct +spotx.tv, 108933, RESELLER, 7842df1d2fe2db34 spotx.tv, 147949, RESELLER, 7842df1d2fe2db34 +spotx.tv, 212457, RESELLER +spotx.tv, 228454, RESELLER, 7842df1d2fe2db34 +spotx.tv, 270977, DIRECT, 7842df1d2fe2db34 +spotx.tv, 285547, RESELLER, 7842df1d2fe2db34 # RhythmOne +spotx.tv, 71451, RESELLER, 7842df1d2fe2db34 # Taboola +spotx.tv, 84294, RESELLER, 7842df1d2fe2db34 +spotx.tv, 94794, RESELLER, 7842df1d2fe2db34 # SpotX +spotxchange.com, 108933, RESELLER, 7842df1d2fe2db34 spotxchange.com, 147949, RESELLER, 7842df1d2fe2db34 +spotxchange.com, 212457, RESELLER +spotxchange.com, 228454, RESELLER, 7842df1d2fe2db34 +spotxchange.com, 270977, DIRECT, 7842df1d2fe2db34 +spotxchange.com, 285547, RESELLER, 7842df1d2fe2db34 # RhythmOne +spotxchange.com, 71451, RESELLER, 7842df1d2fe2db34 # Taboola +spotxchange.com, 84294, RESELLER, 7842df1d2fe2db34 +spotxchange.com, 94794, RESELLER, 7842df1d2fe2db34 # SpotX springserve.com, 686, DIRECT, a24eb641fc82e93d +synacor.com, 82350, RESELLER, e108f11b2cdf7d5b +synacor.com,82151,reseller,e108f11b2cdf7d5b +teads.tv, 19014, DIRECT, 15a9c44f6d26cbe1 +telaria.com, mb9eo-oqsbf, RESELLER, 1a4e959a1b50034a +telaria.com, vtrdn-wjdav, DIRECT, 1a4e959a1b50034a +telaria.com, vtrdn-ysjam, DIRECT, 1a4e959a1b50034a +themediagrid.com, P5JONV, RESELLER, 35d5010d7789b49d # Media Grid (IPONWEB) +tremorhub.com, mb9eo-oqsbf, RESELLER, 1a4e959a1b50034a +tremorhub.com, vtrdn-wjdav, DIRECT, 1a4e959a1b50034a +tremorhub.com, vtrdn-ysjam, DIRECT, 1a4e959a1b50034a +tremorhub.com, z87wm, RESELLER, 1a4e959a1b50034a # Taboola +triplelift.com, 7205, DIRECT, 6c33edb13117fd86 +ucfunnel.com, par-488A3E6BD8D997D0ED8B3BD34D8BA4B, RESELLER # ucFunnel +vertamedia.com, 287605, DIRECT, 7de89dc7742b5b11 +vertamedia.com, 287605, RESELLER, 7de89dc7742b5b11 +video.unrulymedia.com, 2310154583, DIRECT +video.unrulymedia.com, 905992537, RESELLER, a670c89d4a324e47 # RhythmOne +yahoo.com, 55771, RESELLER, e1a5b5b6e3255540 +yahoo.com, 55104, DIRECT, e1a5b5b6e3255540 +yahoo.com, 55317, RESELLER # Verizon +yahoo.com, 57289, RESELLER, e1a5b5b6e3255540 +yahoo.com, 57695, DIRECT, e1a5b5b6e3255540 +yahoo.com,55029,RESELLER,e1a5b5b6e3255540 +yieldmo.com, 2417496099628458357, DIRECT diff --git a/docs/_templates/sidebarintro.html b/docs/_templates/sidebarintro.html index 17527253f..9e2d92c2a 100644 --- a/docs/_templates/sidebarintro.html +++ b/docs/_templates/sidebarintro.html @@ -20,16 +20,13 @@ height: 100%; } - - - - + +

This opinionated guide exists to provide both novice and expert Python developers a best practice handbook to the installation, configuration, and usage of Python on a daily basis. @@ -59,8 +56,8 @@

Contributors

Useful Links

@@ -69,8 +66,8 @@

Translations

  • English
  • French
  • Chinese
    • -
  • Japanese
    • +
  • Japanese
  • Korean
    • -
  • Filipino
    • -
  • Brazilian Portuguese
    • +
  • Filipino
    • +
  • Brazilian Portuguese
    • diff --git a/docs/_templates/sidebarlogo.html b/docs/_templates/sidebarlogo.html index 363663f1b..540b92a48 100644 --- a/docs/_templates/sidebarlogo.html +++ b/docs/_templates/sidebarlogo.html @@ -6,6 +6,28 @@

    + + + + +

    This opinionated guide exists to provide both novice and expert Python developers a best practice handbook to the installation, configuration, and usage of Python on a daily basis.

    diff --git a/docs/conf.py b/docs/conf.py index 974736fd6..d732ac29f 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -11,7 +11,9 @@ # All configuration values have a default; values that are commented out # serve to show the default. -import sys, os +import datetime +import os +import sys # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the @@ -45,8 +47,11 @@ master_doc = 'index' # General information about the project. +current_year = datetime.datetime.now().year project = u'pythonguide' -copyright = u'2011–2018 Kenneth Reitz & Real Python. CC BY-NC-SA 3.0' +copyright = (u'2011-{} Kenneth Reitz' + ' & Real Python.' + ' CC BY-NC-SA 3.0').format(current_year) # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the @@ -241,7 +246,7 @@ epub_title = u'pythonguide' epub_author = u'Kenneth Reitz' epub_publisher = u'Kenneth Reitz' -epub_copyright = u'2011–2018, Kenneth Reitz & Real Python' +epub_copyright = u'2011–{}, Kenneth Reitz & Real Python'.format(current_year) # The language of the text. It defaults to the language option # or en if the language is not set. diff --git a/docs/contents.rst.inc b/docs/contents.rst.inc index 2e1e40496..29b076197 100644 --- a/docs/contents.rst.inc +++ b/docs/contents.rst.inc @@ -97,11 +97,12 @@ different scenarios. Shipping Great Python Code -------------------------- -This part of the guide focuses on deploying your Python code. +This part of the guide focuses on sharing and deploying your Python code. .. toctree:: :maxdepth: 2 + shipping/publishing shipping/packaging shipping/freezing diff --git a/docs/dev/env.rst b/docs/dev/env.rst index 042d42dce..7da63c0e6 100644 --- a/docs/dev/env.rst +++ b/docs/dev/env.rst @@ -87,10 +87,10 @@ using ```` key or any other customized keys. .. _indent: http://www.vim.org/scripts/script.php?script_id=974 .. _syntax: http://www.vim.org/scripts/script.php?script_id=790 -.. _Pyflakes: http://pypi.python.org/pypi/pyflakes/ -.. _pycodestyle: https://pypi.python.org/pypi/pycodestyle/ -.. _syntastic: https://github.com/scrooloose/syntastic -.. _Python-mode: https://github.com/klen/python-mode +.. _Pyflakes: http://pypi.org/project/pyflakes/ +.. _pycodestyle: https://pypi.org/project/pycodestyle/ +.. _syntastic: https://github.com/vim-syntastic/syntastic +.. _Python-mode: https://github.com/python-mode/python-mode .. _SuperTab: http://www.vim.org/scripts/script.php?script_id=1643 .. _vim-flake8: https://github.com/nvie/vim-flake8 @@ -103,7 +103,7 @@ Emacs user is `Python Programming in Emacs`_ at EmacsWiki. 1. Emacs itself comes with a Python mode. -.. _Python Programming in Emacs: http://emacswiki.org/emacs/PythonProgrammingInEmacs +.. _Python Programming in Emacs: https://www.emacswiki.org/emacs/PythonProgrammingInEmacs TextMate -------- @@ -135,9 +135,17 @@ Atom Atom is web native (HTML, CSS, JS), focusing on modular design and easy plugin development. It comes with native package control and a plethora of packages. Recommended for Python development is -`Linter `_ combined with +`Linter `_ combined with `linter-flake8 `_. +Python (on Visual Studio Code) +------------------------------ + +`Python for Visual Studio `_ is an extension for the `Visual Studio Code `_. +This is a free, lightweight, open source code editor, with support for Mac, Windows, and Linux. +Built using open source technologies such as Node.js and Python, with compelling features such as Intellisense (autocompletion), local and remote debugging, linting, and the like. + +MIT licensed. IDEs :::: @@ -152,18 +160,10 @@ features can be brought to IntelliJ with the free versions of PyCharm: Professional Edition (Free 30-day trial) and Community Edition (Apache 2.0 License) with fewer features. -Python (on Visual Studio Code) ------------------------------- - -`Python for Visual Studio `_ is an extension for the `Visual Studio Code IDE `_. -This is a free, lightweight, open source IDE, with support for Mac, Windows, and Linux. -Built using open source technologies such as Node.js and Python, with compelling features such as Intellisense (autocompletion), local and remote debugging, linting, and the like. - -MIT licensed. Enthought Canopy ---------------- -`Enthought Canopy `_ is a Python +`Enthought Canopy `_ is a Python IDE which is focused towards Scientists and Engineers as it provides pre installed libraries for data analysis. @@ -171,13 +171,13 @@ Eclipse ------- The most popular Eclipse plugin for Python development is Aptana's -`PyDev `_. +`PyDev `_. Komodo IDE ---------- -`Komodo IDE `_ is developed by +`Komodo IDE `_ is developed by ActiveState and is a commercial IDE for Windows, Mac, and Linux. `KomodoEdit `_ is the open source alternative. @@ -188,8 +188,8 @@ Spyder `Spyder `_ is an IDE specifically geared toward working with scientific Python libraries (namely -`SciPy `_). It includes integration with pyflakes_, -`pylint `_ and +`SciPy `_). It includes integration with pyflakes_, +`pylint `_ and `rope `_. Spyder is open source (free), offers code completion, syntax highlighting, @@ -231,6 +231,18 @@ based on the Qt GUI toolkit, integrating the Scintilla editor control. Eric is an open source software project (GPLv3 licence) with more than ten years of active development. +Mu +-- + +`Mu `_ is a minimalist Python IDE which can run Python 3 code +locally and can also deploy code to the BBC micro:bit and to Adafruit boards running +CircuitPython. + +Intended for beginners, mu includes a Python 3 interpreter, and is easy to install +on Windows, OS/X and Linux. It runs well on the Raspberry Pi. + +There's an active support community on gitter. + Interpreter Tools ::::::::::::::::: @@ -242,13 +254,13 @@ Virtual Environments Virtual Environments provide a powerful way to isolate project package dependencies. This means that you can use packages particular to a Python project without installing them system wide and thus avoiding potential version conflicts. To start using and see more information: -`Virtual Environments `_ docs. +`Virtual Environments `_ docs. pyenv ----- -`pyenv `_ is a tool to allow multiple versions +`pyenv `_ is a tool to allow multiple versions of the Python interpreter to be installed at the same time. This solves the problem of having different projects requiring different versions of Python. For example, it becomes very easy to install Python 2.7 for compatibility in @@ -264,7 +276,7 @@ pyenv. pyenv then works out which version of Python should be run based on environment variables, ``.python-version`` files, and the global default. pyenv isn't a tool for managing virtual environments, but there is the plugin -`pyenv-virtualenv `_ which automates +`pyenv-virtualenv `_ which automates the creation of different environments, and also makes it possible to use the existing pyenv tools to switch to different environments based on environment variables or ``.python-version`` files. @@ -314,7 +326,7 @@ To download and install IPython with all its optional dependencies for the noteb BPython ------- -`bpython `_ is an alternative interface to the +`bpython `_ is an alternative interface to the Python interpreter for Unix-like operating systems. It has the following features: @@ -334,8 +346,8 @@ features: ptpython -------- -`ptpython `_ is a REPL build -on top of the `prompt_toolkit `_ +`ptpython `_ is a REPL build +on top of the `prompt_toolkit `_ library. It is considered to be an alternative to BPython_. Features include: * Syntax highlighting diff --git a/docs/dev/pip-virtualenv.rst b/docs/dev/pip-virtualenv.rst index 61a777aff..667f30c7a 100644 --- a/docs/dev/pip-virtualenv.rst +++ b/docs/dev/pip-virtualenv.rst @@ -51,7 +51,7 @@ can be found at: .. code-block:: console - %HOME%\pip\pip.ini + %USERPROFILE%\pip\pip.ini If you don't have a :file:`pip.conf` or :file:`pip.ini` file at these locations, you can create a new file with the correct name for your operating system. @@ -79,7 +79,7 @@ adding the following to your :file:`~/.bashrc` file: .. code-block:: console gpip() { - PIP_REQUIRE_VIRTUALENV="" pip "$@" + PIP_REQUIRE_VIRTUALENV=false pip "$@" } After saving the changes and sourcing your :file:`~/.bashrc` file you can now @@ -122,7 +122,7 @@ add the following line to your :file:`pip.ini` file under ``[global]`` settings: .. code-block:: console - download-cache = %HOME%\pip\cache + download-cache = %USERPROFILE%\pip\cache Similarly, on Unix systems you should simply add the following line to your :file:`pip.conf` file under ``[global]`` settings: diff --git a/docs/dev/virtualenvs.rst b/docs/dev/virtualenvs.rst index 538bfdf11..fe6bd3f9e 100644 --- a/docs/dev/virtualenvs.rst +++ b/docs/dev/virtualenvs.rst @@ -101,7 +101,7 @@ Use ``pip`` to install Pipenv: user ``PATH`` permanently in the `Control Panel`_. You may need to log out for the ``PATH`` changes to take effect. -.. _Pipenv: https://docs.pipenv.org/ +.. _Pipenv: https://pipenv.kennethreitz.org/ .. _npm: https://www.npmjs.com/ .. _bundler: http://bundler.io/ .. _user base: https://docs.python.org/3/library/site.html#site.USER_BASE @@ -118,7 +118,7 @@ tutorial) and run: .. code-block:: console - $ cd myproject + $ cd project_folder $ pipenv install requests Pipenv will install the excellent `Requests`_ library and create a ``Pipfile`` @@ -156,7 +156,7 @@ when you share your project with others. You should get output similar to this Adding requests to Pipfile's [packages]... P.S. You have excellent taste! ✨ 🍰 ✨ -.. _Requests: http://python-requests.org +.. _Requests: https://requests.readthedocs.io/en/latest/ Using installed packages @@ -200,7 +200,7 @@ Congratulations, you now know how to install and use Python packages! ✨ 🍰 Lower level: virtualenv ======================= -`virtualenv `_ is a tool to create +`virtualenv `_ is a tool to create isolated Python environments. virtualenv creates a folder which contains all the necessary executables to use the packages that a Python project would need. @@ -225,7 +225,7 @@ Basic Usage .. code-block:: console - $ cd my_project_folder + $ cd project_folder $ virtualenv venv ``virtualenv venv`` will create a folder in the current directory which will @@ -260,19 +260,19 @@ or change the interpreter globally with an env variable in ``~/.bashrc``: $ source venv/bin/activate The name of the current virtual environment will now appear on the left of -the prompt (e.g. ``(venv)Your-Computer:your_project UserName$)`` to let you know +the prompt (e.g. ``(venv)Your-Computer:project_folder UserName$``) to let you know that it's active. From now on, any package that you install using pip will be placed in the ``venv`` folder, isolated from the global Python installation. -For Windows, same command which is mentioned in step 1 can be used for creation of virtual environment. But, to activate, we use the following command. +For Windows, the same command mentioned in step 1 can be used to create a virtual environment. However, activating the environment requires a slightly different command. -Assuming that you are in project directory: +Assuming that you are in your project directory: -.. code-block:: powershell +.. code-block:: console - PS C:\Users\suryav> \venv\Scripts\activate + C:\Users\SomeUser\project_folder> venv\Scripts\activate -Install packages as usual, for example: +Install packages using the ``pip`` command: .. code-block:: console @@ -283,13 +283,13 @@ Install packages as usual, for example: .. code-block:: console - $ deactivate + $ deactivate This puts you back to the system's default Python interpreter with all its installed libraries. To delete a virtual environment, just delete its folder. (In this case, -it would be ``rm -rf my_project``.) +it would be ``rm -rf venv``.) After a while, though, you might end up with a lot of virtual environments littered across your system, and it's possible you'll forget their names or @@ -366,23 +366,23 @@ Basic Usage .. code-block:: console - $ mkvirtualenv my_project + $ mkvirtualenv project_folder -This creates the :file:`my_project` folder inside :file:`~/Envs`. +This creates the :file:`project_folder` folder inside :file:`~/Envs`. 2. Work on a virtual environment: .. code-block:: console - $ workon my_project + $ workon project_folder Alternatively, you can make a project, which creates the virtual environment, and also a project directory inside ``$WORKON_HOME``, which is ``cd``-ed into -when you ``workon myproject``. +when you ``workon project_folder``. .. code-block:: console - $ mkproject myproject + $ mkproject project_folder **virtualenvwrapper** provides tab-completion on environment names. It really helps when you have a lot of environments and have trouble remembering their @@ -427,20 +427,15 @@ virtualenv-burrito With `virtualenv-burrito `_, you can have a working virtualenv + virtualenvwrapper environment in a single command. -autoenv +direnv ------- -When you ``cd`` into a directory containing a :file:`.env`, `autoenv `_ +When you ``cd`` into a directory containing a :file:`.env`, `direnv `_ automagically activates the environment. Install it on Mac OS X using ``brew``: .. code-block:: console - $ brew install autoenv - -And on Linux: - -.. code-block:: console + $ brew install direnv - $ git clone git://github.com/kennethreitz/autoenv.git ~/.autoenv - $ echo 'source ~/.autoenv/activate.sh' >> ~/.bashrc +On Linux follow the instructions at `direnv.net `_ diff --git a/docs/index.rst b/docs/index.rst index dcd56579f..df7fcb8ed 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -4,7 +4,7 @@ contain the root `toctree` directive. .. meta:: - :description: An opinionated guide to the Python programming language and a best practice handbook to the installation, configuration, and usage of Python on a daily basis. + :description: An opinionated guide to the Python programming language and a best practice handbook for the installation, configuration, and usage of Python on a daily basis. ################################# @@ -17,7 +17,7 @@ Greetings, Earthling! Welcome to The Hitchhiker's Guide to Python. `fork us on GitHub `_! This handcrafted guide exists to provide both novice and expert Python -developers a best practice handbook to the installation, configuration, and +developers a best practice handbook for the installation, configuration, and usage of Python on a daily basis. This guide is **opinionated** in a way that is almost, but not quite, entirely @@ -25,7 +25,7 @@ This guide is **opinionated** in a way that is almost, but not quite, entirely available here. Rather, you'll find a nice concise list of highly recommended options. -.. note:: The use of **Python 3** is *highly* preferred over Python 2. Consider upgrading your applications and infrastructure if you find yourself *still* using Python 2 in production today. If you are using Python 3, congratulations — you are indeed a person of excellent taste. +.. note:: The use of **Python 3** is *highly* recommended over Python 2. Consider upgrading your applications and infrastructures if you find yourself *still* using Python 2 in production today. If you are using Python 3, congratulations — you are indeed a person of excellent taste. —*Kenneth Reitz* Let's get started! But first, let's make sure you know where your towel is. diff --git a/docs/intro/duction.rst b/docs/intro/duction.rst index 7619002d6..16baebc0d 100644 --- a/docs/intro/duction.rst +++ b/docs/intro/duction.rst @@ -28,11 +28,11 @@ include: object serialization, and much more. Additionally, the - `Python Package Index `_ is available + `Python Package Index `_ is available for users to submit their packages for widespread use, similar to - Perl's `CPAN `_. There is a thriving community + Perl's `CPAN `_. There is a thriving community of very powerful Python frameworks and tools like - the `Django `_ web framework and the + the `Django `_ web framework and the `NumPy `_ set of math routines. * **integration with other systems** diff --git a/docs/intro/learning.rst b/docs/intro/learning.rst index 6e2d0ea41..b0c957398 100644 --- a/docs/intro/learning.rst +++ b/docs/intro/learning.rst @@ -30,7 +30,7 @@ Real Python is a repository of free and in-depth Python tutorials created by a d Python Basics ~~~~~~~~~~~~~ -pythonbasics.org is an introductiory tutorial for beginners. The tutorial includes exercises. It covers the basics and there are also in-depth lessons like object oriented programming and regular expressions. +pythonbasics.org is an introductory tutorial for beginners. The tutorial includes exercises. It covers the basics and there are also in-depth lessons like object oriented programming and regular expressions. `Python basics `_ @@ -41,14 +41,14 @@ thepythonguru.com is a tutorial focused on beginner programmers. It covers many in depth. It also teaches you some advanced constructs of Python like lambda expressions and regular expressions. And last it finishes off with the tutorial "How to access MySQL db using Python" - `Python for Beginners `_ + `Python for Beginners `_ Learn Python Interactive Tutorial ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Learnpython.org is an easy non-intimidating way to get introduced to Python. The website takes the same approach used on the popular -`Try Ruby `_ website. It has an interactive Python +`Try Ruby `_ website. It has an interactive Python interpreter built into the site that allows you to go through the lessons without having to install Python locally. @@ -65,9 +65,9 @@ resource for learning all aspects of the language. Learn Python Step by Step ~~~~~~~~~~~~~~~~~~~~~~~~~ -Techbeamers.com provides step-by-step tutorials to teach Python. Each tutorial is supplemented with logically added coding snippets and equips with a follow-up quiz on the subject learned. There is a section for `Python interview questions `_ to help job seekers. You can also read essential `Python tips `_ and learn `best coding practices `_ for writing quality code. Here, you'll get the right platform to learn Python quickly. +Techbeamers.com provides step-by-step tutorials to teach Python. Each tutorial is supplemented with logically added coding snippets and equips with a follow-up quiz on the subject learned. There is a section for `Python interview questions `_ to help job seekers. You can also read essential `Python tips `_ and learn `best coding practices `_ for writing quality code. Here, you'll get the right platform to learn Python quickly. -`Learn Python Basic to Advanced `_ +`Learn Python Basic to Advanced `_ Online Python Tutor @@ -108,7 +108,7 @@ Learn Python the Hard Way This is an excellent beginner programmer's guide to Python. It covers "hello world" from the console to the web. - `Learn Python the Hard Way `_ + `Learn Python the Hard Way `_ Crash into Python @@ -117,7 +117,7 @@ Crash into Python Also known as *Python for Programmers with 3 Hours*, this guide gives experienced developers from other languages a crash course on Python. - `Crash into Python `_ + `Crash into Python `_ Dive Into Python 3 @@ -161,11 +161,11 @@ For those used to languages and figuring out puzzles on their own, this can be a fun, attractive option. For those new to Python and programming, having an additional resource or reference will be helpful. - `Python Koans `_ + `Python Koans `_ More information about test driven development can be found at these resources: - `Test Driven Development `_ + `Test Driven Development `_ A Byte of Python @@ -178,13 +178,15 @@ no previous programming experience. `A Byte of Python for Python 3.x `_ -Learn to Program in Python with Codeacademy +Computer Science Path on Codecademy ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -A Codeacademy course for the absolute Python beginner. This free and interactive course provides and teaches the basics (and beyond) of Python programming while testing the user's knowledge in between progress. +A Codecademy course for the absolute Python beginner. This free and interactive +course provides and teaches the basics (and beyond) of Python programming while +testing the user's knowledge in between progress. This course also features a built-in interpreter for receiving instant feedback on your learning. - `Learn to Program in Python with Codeacademy `_ + `Computer Science Path on Codecademy `_ Code the blocks @@ -216,11 +218,11 @@ Effective Python ~~~~~~~~~~~~~~~~ This book contains 59 specific ways to improve writing Pythonic code. At 227 -pages, it is a very brief overview of some of the most common adapations +pages, it is a very brief overview of some of the most common adaptations programmers need to make to become efficient intermediate level Python programmers. - `Effective Python `_ + `Effective Python `_ ******** @@ -234,7 +236,7 @@ This book is for intermediate to advanced Python programmers who are looking to understand how and why Python works the way it does and how they can take their code to the next level. - `Pro Python `_ + `Pro Python `_ Expert Python Programming @@ -251,7 +253,7 @@ and eventually an application, including a chapter on using zc.buildout. Later chapters detail best practices such as writing documentation, test-driven development, version control, optimization, and profiling. - `Expert Python Programming `_ + `Expert Python Programming `_ A Guide to Python's Magic Methods @@ -278,7 +280,7 @@ A Primer on Scientific Programming with Python, written by Hans Petter Langtangen, mainly covers Python's usage in the scientific field. In the book, examples are chosen from mathematics and the natural sciences. - `A Primer on Scientific Programming with Python `_ + `A Primer on Scientific Programming with Python `_ Numerical Methods in Engineering with Python ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -286,7 +288,7 @@ Numerical Methods in Engineering with Python Numerical Methods in Engineering with Python, written by Jaan Kiusalaas, puts the emphasis on numerical methods and how to implement them in Python. - `Numerical Methods in Engineering with Python `_ + `Numerical Methods in Engineering with Python `_ ******************** @@ -405,6 +407,6 @@ some commonly used piece of code, followed by an explanation of why the idiom is important. It also contains two code samples for each idiom: the "Harmful" way to write it and the "Idiomatic" way. - `For Python 2.7.3+ `_ + `For Python 2.7.3+ `_ - `For Python 3.3+ `_ + `For Python 3.3+ `_ diff --git a/docs/intro/news.rst b/docs/intro/news.rst index 9f8e9232b..d1cda93be 100644 --- a/docs/intro/news.rst +++ b/docs/intro/news.rst @@ -32,7 +32,7 @@ Planet Python This is an aggregate of Python news from a growing number of developers. - `Planet Python `_ + `Planet Python `_ ********* @@ -42,7 +42,7 @@ This is an aggregate of Python news from a growing number of developers. /r/python is the Reddit Python community where users contribute and vote on Python-related news. - `/r/python `_ + `/r/python `_ ******************* @@ -70,7 +70,7 @@ Python Weekly Python Weekly is a free weekly newsletter featuring curated news, articles, new releases, jobs, etc. related to Python. - `Python Weekly `_ + `Python Weekly `_ *********** @@ -80,7 +80,7 @@ Python News Python News is the news section in the official Python web site (www.python.org). It briefly highlights the news from the Python community. - `Python News `_ + `Python News `_ ******************** diff --git a/docs/notes/contribute.rst b/docs/notes/contribute.rst index d82fb76da..b6c72bb4f 100644 --- a/docs/notes/contribute.rst +++ b/docs/notes/contribute.rst @@ -30,5 +30,5 @@ If you'd like to contribute, there's plenty to do. Here's a short todo_ list. .. include:: ../../TODO.rst -.. _GitHub: http://github.com/kennethreitz/python-guide/ +.. _GitHub: https://github.com/kennethreitz/python-guide/ .. _todo: https://github.com/kennethreitz/python-guide/blob/master/TODO.rst diff --git a/docs/notes/styleguide.rst b/docs/notes/styleguide.rst index d38fc22ef..5a715332e 100644 --- a/docs/notes/styleguide.rst +++ b/docs/notes/styleguide.rst @@ -31,7 +31,7 @@ Strive to keep any contributions relevant to the :ref:`purpose of The Guide relate to Python development. * Prefer to link to other sources if the information is already out there. Be sure to describe what and why you are linking. -* `Cite `_ +* `Cite `_ references where needed. * If a subject isn't directly relevant to Python, but useful in conjunction with Python (e.g., Git, GitHub, Databases), reference by linking to useful @@ -109,7 +109,10 @@ Command line examples: $ run command --help $ ls .. -Be sure to include the ``$`` prefix before each line. +Be sure to include the ``$`` prefix before each line for Unix console examples. + +For Windows console examples, use ``doscon`` or ``powershell`` instead of +``console``, and omit the ``$`` prefix. Python interpreter examples: @@ -143,14 +146,14 @@ Externally Linking Sphinx_ is used to document Python. - .. _Sphinx: http://sphinx.pocoo.org + .. _Sphinx: https://www.sphinx-doc.org * Prefer to use descriptive labels with inline links instead of leaving bare links: .. code-block:: rest - Read the `Sphinx Tutorial `_ + Read the `Sphinx Tutorial `_ * Avoid using labels such as "click here", "this", etc., preferring descriptive labels (SEO worthy) instead. @@ -161,7 +164,7 @@ Linking to Sections in The Guide ******************************** To cross-reference other parts of this documentation, use the `:ref: -`_ +`_ keyword and labels. To make reference labels more clear and unique, always add a ``-ref`` suffix: @@ -179,7 +182,7 @@ Notes and Warnings ****************** Make use of the appropriate `admonitions directives -`_ when making notes. +`_ when making notes. Notes: @@ -202,7 +205,7 @@ TODOs ***** Please mark any incomplete areas of The Guide with a `todo directive -`_. To +`_. To avoid cluttering the :ref:`todo-list-ref`, use a single ``todo`` for stub documents or large incomplete sections. diff --git a/docs/scenarios/admin.rst b/docs/scenarios/admin.rst index e275018ae..f6433c213 100644 --- a/docs/scenarios/admin.rst +++ b/docs/scenarios/admin.rst @@ -155,51 +155,49 @@ tests (net, CPU) fail, it will send an email. # Package for email services: import smtplib import string - MAX_NET_USAGE = 400000 + MAX_NET_USAGE = 400000 # bytes per seconds MAX_ATTACKS = 4 attack = 0 - counter = 0 while attack <= MAX_ATTACKS: sleep(4) - counter = counter + 1 - # Check the cpu usage - if cpu_percent(interval = 1) > 70: - attack = attack + 1 - # Check the net usage - neti1 = net_io_counters()[1] - neto1 = net_io_counters()[0] + + # Check the net usage wit named tuples + neti1 = net_io_counters().bytes_recv + neto1 = net_io_counters().bytes_sent sleep(1) - neti2 = net_io_counters()[1] - neto2 = net_io_counters()[0] + neti2 = net_io_counters().bytes_recv + neto2 = net_io_counters().bytes_sent + # Calculate the bytes per second net = ((neti2+neto2) - (neti1+neto1))/2 - if net > MAX_NET_USAGE: - attack = attack + 1 - if counter > 25: - attack = 0 - counter = 0 + + # Check the net and cpu usage + if (net > MAX_NET_USAGE) or (cpu_percent(interval = 1) > 70): + attack+=1 + elif attack > 1: + attack-=1 + # Write a very important email if attack is higher than 4 TO = "you@your_email.com" FROM = "webmaster@your_domain.com" SUBJECT = "Your domain is out of system resources!" text = "Go and fix your server!" - BODY = string.join(("From: %s" %FROM,"To: %s" %TO,"Subject: %s" %SUBJECT, "",text), "\r\n") + string="\r\n" + BODY = string.join(("From: %s" %FROM,"To: %s" %TO, + "Subject: %s" %SUBJECT, "",text)) server = smtplib.SMTP('127.0.0.1') server.sendmail(FROM, [TO], BODY) server.quit() -A full terminal application like a widely extended top which is based on -psutil and with the ability of a client-server monitoring is -`glance `_. - +A full terminal application like a widely extended top is `Glance `_, which is based on psutil and has the ability for client-server monitoring. ******* Ansible ******* `Ansible `_ is an open source system automation tool. -The biggest advantage over Puppet or Chef is it does not require an agent on +Its biggest advantage over Puppet or Chef is that it does not require an agent on the client machine. Playbooks are Ansible’s configuration, deployment, and orchestration language and are written in YAML with Jinja2 for templating. @@ -392,21 +390,8 @@ Buildout `Buildout `_ is an open source software build tool. Buildout is created using the Python programming language. It implements a -principle of separation of configuration from the scripts that do the setting up. -Buildout is primarily used to download and set up dependencies in Python eggs -format of the software being developed or deployed. Recipes for build tasks in any -environment can be created, and many are already available. - - -******* -Shinken -******* - -`Shinken `_ is a modern, Nagios compatible -monitoring framework written in Python. Its main goal is to give users a flexible -architecture for their monitoring system that is designed to scale to large -environments. - -Shinken is backwards-compatible with the Nagios configuration standard and -plugins. It works on any operating system and architecture that supports Python, -which includes Windows, Linux, and FreeBSD. +principle of separation of configuration from the scripts that do the setting +up. Buildout is primarily used to download and set up dependencies in `Python +eggs `_ +format of the software being developed or deployed. Recipes for build tasks in +any environment can be created, and many are already available. diff --git a/docs/scenarios/ci.rst b/docs/scenarios/ci.rst index ade9148c4..4296679c7 100644 --- a/docs/scenarios/ci.rst +++ b/docs/scenarios/ci.rst @@ -65,7 +65,7 @@ Travis-CI tests for open source projects for free. It provides multiple workers to run Python tests on and seamlessly integrates with GitHub. You can even have it comment on your Pull Requests whether this particular changeset breaks the -build or not. So if you are hosting your code on GitHub, Travis-CI is a great +build or not. So, if you are hosting your code on GitHub, Travis-CI is a great and easy way to get started with Continuous Integration. In order to get started, add a :file:`.travis.yml` file to your repository with diff --git a/docs/scenarios/cli.rst b/docs/scenarios/cli.rst index 44feade42..59f311e83 100644 --- a/docs/scenarios/cli.rst +++ b/docs/scenarios/cli.rst @@ -5,13 +5,12 @@ Command-line Applications .. image:: /_static/photos/34435690330_11930b5987_k_d.jpg -Command-line applications, also referred to as -`Console Applications `_, -are computer programs designed to be used from a text interface, such as a -`shell `_. Command-line -applications usually accept various inputs as arguments, often referred to as -parameters or sub-commands, as well as options, often referred to as flags or -switches. +Command-line applications, also referred to as `Console Applications +`_, are computer programs +designed to be used from a text interface, such as a `shell +`_. Command-line applications +usually accept various inputs as arguments, often referred to as parameters or +sub-commands, as well as options, often referred to as flags or switches. Some popular command-line applications include: @@ -28,10 +27,10 @@ Some popular command-line applications include: Click ***** -`click `_ is a Python package for creating -command-line interfaces in a composable way with as little code as -possible. This “Command-Line Interface Creation Kit” is highly -configurable but comes with good defaults out of the box. +`click `_ is a Python package for creating +command-line interfaces in a composable way with as little code as possible. +This “Command-Line Interface Creation Kit” is highly configurable but comes +with good defaults out of the box. ****** @@ -47,11 +46,11 @@ POSIX-style usage instructions. Plac **** -`Plac `_ is a simple wrapper +`Plac `_ is a simple wrapper over the Python standard library `argparse `_, which hides most of its complexity by using a declarative interface: the -argument parser is inferred rather than written down by imperatively. This -module targets especially unsophisticated users, programmers, sysadmins, +argument parser is inferred rather than written down imperatively. This +module targets unsophisticated users, programmers, sysadmins, scientists, and in general people writing throw-away scripts for themselves, who choose to create a command-line interface because it is quick and simple. @@ -72,12 +71,12 @@ sub-command to do the work. Cement ****** -`Cement `_ is an advanced CLI Application Framework. -Its goal is to introduce a standard and feature-full platform -for both simple and complex command line applications as well -as support rapid development needs without sacrificing quality. -Cement is flexible, and its use cases span from the simplicity of a micro-framework -to the complexity of a mega-framework. +`Cement `_ is an advanced CLI Application +Framework. Its goal is to introduce a standard and feature-full platform for +both simple and complex command line applications as well as support rapid +development needs without sacrificing quality. Cement is flexible, and its use +cases span from the simplicity of a micro-framework to the complexity of a +mega-framework. *********** diff --git a/docs/scenarios/clibs.rst b/docs/scenarios/clibs.rst index 5470576b0..13c9e4802 100644 --- a/docs/scenarios/clibs.rst +++ b/docs/scenarios/clibs.rst @@ -12,9 +12,9 @@ C Foreign Function Interface `CFFI `_ provides a simple to use mechanism for interfacing with C from both CPython and PyPy. It supports two -modes: an inline ABI compatibility mode (example provided below), which allows +modes: an inline `ABI `_ compatibility mode (example provided below), which allows you to dynamically load and run functions from executable modules (essentially -exposing the same functionality as LoadLibrary or dlopen), and an API mode, +exposing the same functionality as `LoadLibrary `_ or `dlopen `_), and an API mode, which allows you to build C extension modules. ABI Interaction @@ -41,13 +41,13 @@ library for interfacing with C/C++ from CPython, and it provides not only full access to the native C interface of most major operating systems (e.g., kernel32 on Windows, or libc on \*nix), but also provides support for loading and interfacing with dynamic libraries, such as DLLs or shared objects, at -runtime. It does bring along with it a whole host of types for interacting +runtime. It brings along with it a whole host of types for interacting with system APIs, and allows you to rather easily define your own complex types, such as structs and unions, and allows you to modify things such as padding and alignment, if needed. It can be a bit crufty to use, but in -conjunction with the `struct `_ +conjunction with the `struct `_ module, you are essentially provided full control over how your data types get -translated into something usable by a pure C(++) method. +translated into something usable by a pure C/C++ method. Struct Equivalents ~~~~~~~~~~~~~~~~~~ diff --git a/docs/scenarios/client.rst b/docs/scenarios/client.rst index a10f1db38..c2d5c289b 100644 --- a/docs/scenarios/client.rst +++ b/docs/scenarios/client.rst @@ -28,8 +28,8 @@ your URLs, or to form-encode your POST data. Keep-alive and HTTP connection pooling are 100% automatic, powered by urllib3, which is embedded within Requests. -- `Documentation `_ -- `PyPi `_ +- `Documentation `_ +- `PyPi `_ - `GitHub `_ diff --git a/docs/scenarios/crypto.rst b/docs/scenarios/crypto.rst index a5c3d7737..262337204 100644 --- a/docs/scenarios/crypto.rst +++ b/docs/scenarios/crypto.rst @@ -89,34 +89,3 @@ Example print("Hang on ... did you say *all* of GnuPG? Yep.") else: pass - - - -******** -PyCrypto -******** - -`PyCrypto `_ is another library, -which provides secure hash functions and various encryption algorithms. It -supports Python version 2.1 through 3.3. - -Installation -~~~~~~~~~~~~ - -.. code-block:: console - - $ pip install pycrypto - -Example -~~~~~~~ - -.. code-block:: python - - from Crypto.Cipher import AES - # Encryption - encryption_suite = AES.new('This is a key123', AES.MODE_CBC, 'This is an IV456') - cipher_text = encryption_suite.encrypt("A really secret message. Not for prying eyes.") - - # Decryption - decryption_suite = AES.new('This is a key123', AES.MODE_CBC, 'This is an IV456') - plain_text = decryption_suite.decrypt(cipher_text) diff --git a/docs/scenarios/db.rst b/docs/scenarios/db.rst index 58211e26b..21217477a 100644 --- a/docs/scenarios/db.rst +++ b/docs/scenarios/db.rst @@ -48,11 +48,24 @@ programmatically or exported to a number of useful data formats. Also included is a command-line tool for exporting SQL data. +****** +PugSQL +****** + +`PugSQL `_ is a simple Python interface for organizing +and using parameterized, handwritten SQL. It is an anti-ORM that is +philosophically lo-fi, but it still presents a clean interface in Python. + +.. code-block:: console + + $ pip install pugsql + + ********** Django ORM ********** -The Django ORM is the interface used by `Django `_ +The Django ORM is the interface used by `Django `_ to provide database access. It's based on the idea of diff --git a/docs/scenarios/gui.rst b/docs/scenarios/gui.rst index e012048bc..3ad0af364 100644 --- a/docs/scenarios/gui.rst +++ b/docs/scenarios/gui.rst @@ -14,8 +14,8 @@ Camelot ******* `Camelot `_ provides components for building -applications on top of Python, SQLAlchemy, and Qt. It is inspired by -the Django admin interface. +applications on top of Python, SQLAlchemy, and Qt. It is inspired by the Django +admin interface. The main resource for information is the website: http://www.python-camelot.com @@ -33,19 +33,17 @@ Cocoa GTk *** -PyGTK provides Python bindings for the GTK+ toolkit. Like the GTK+ library -itself, it is currently licensed under the GNU LGPL. It is worth noting that -PyGTK only currently supports the Gtk-2.X API (NOT Gtk-3.0). It is currently -recommended that PyGTK not be used for new projects and that existing -applications be ported from PyGTK to PyGObject. +.. note:: PyGTK provides Python bindings for the GTK+ toolkit. However, it has been superseded by PyGObject. PyGTK should not be used for new projects and existing projects should be ported to PyGObject. ******************** PyGObject aka (PyGi) ******************** -`PyGObject `_ provides Python bindings which gives access to the entire GNOME software platform. -It is fully compatible with GTK+ 3. Here is a tutorial to get started with `Python GTK+ 3 Tutorial `_. +`PyGObject `_ provides Python +bindings which gives access to the entire GNOME software platform. It is fully +compatible with GTK+ 3. Here is a tutorial to get started with `Python GTK+ 3 +Tutorial `_. `API Reference `_ @@ -56,8 +54,8 @@ Kivy `Kivy `_ is a Python library for development of multi-touch enabled media rich applications. The aim is to allow for quick and easy -interaction design and rapid prototyping, while making your code reusable -and deployable. +interaction design and rapid prototyping, while making your code reusable and +deployable. Kivy is written in Python, based on OpenGL, and supports different input devices such as: Mouse, Dual Mouse, TUIO, WiiMote, WM_TOUCH, HIDtouch, Apple's products, @@ -81,12 +79,15 @@ PySide ****** PySide is a Python binding of the cross-platform GUI toolkit Qt. +The package name depends on the major Qt version (`PySide` for Qt4, +`PySide2` for Qt5, and `PySide6` for Qt6). +This set of bindings is developed by `The Qt Company `_. .. code-block:: console - $ pip install pyside + $ pip install pyside6 -https://wiki.qt.io/Category:LanguageBindings::PySide::Downloads +https://pyside.org **** @@ -100,53 +101,56 @@ PyQt provides Python bindings for the Qt Framework (see below). http://www.riverbankcomputing.co.uk/software/pyqt/download -***************************** -PyjamasDesktop (pyjs Desktop) -***************************** +*************************************** +Pyjs Desktop (formerly Pyjamas Desktop) +*************************************** -PyjamasDesktop is a port of Pyjamas. PyjamasDesktop is application widget set -for desktop and a cross-platform framework. (After release v0.6 PyjamasDesktop -is a part of Pyjamas (Pyjs)). Briefly, it allows the exact same Python web -application source code to be executed as a standalone desktop application. +Pyjs Desktop is a application widget set for desktop and a cross-platform +framework. It allows the exact same Python web application source code to be +executed as a standalone desktop application. -`Python Wiki for PyjamasDesktop `_. -The main website: `pyjs Desktop `_. +The main website: `pyjs `_. ** Qt ** -`Qt `_ is a cross-platform application framework that -is widely used for developing software with a GUI but can also be used for -non-GUI applications. +`Qt `_ is a cross-platform application framework that is +widely used for developing software with a GUI but can also be used for non-GUI +applications. *********** PySimpleGUI *********** -`PySimpleGUI `_ is a wrapper for Tkinter and Qt (others on the way). The amount of code required to implement custom GUIs is much shorter using PySimpleGUI than if the same GUI were written directly using Tkinter or Qt. PySimpleGUI code can be "ported" between GUI frameworks by changing import statements. +`PySimpleGUI `_ is a wrapper for Tkinter +and Qt (others on the way). The amount of code required to implement custom +GUIs is much shorter using PySimpleGUI than if the same GUI were written +directly using Tkinter or Qt. PySimpleGUI code can be "ported" between GUI +frameworks by changing import statements. .. code-block:: console $ pip install pysimplegui -PySimpleGUI is contained in a single PySimpleGUI.py file. Should pip installation be impossible, copying the PySimpleGUI.py file into a project's folder is all that's required to import and begin using. +PySimpleGUI is contained in a single PySimpleGUI.py file. Should pip +installation be impossible, copying the PySimpleGUI.py file into a project's +folder is all that's required to import and begin using. **** Toga **** -`Toga `_ is a Python native, OS -native, cross platform GUI toolkit. Toga consists of a library of base -components with a shared interface to simplify platform-agnostic GUI -development. +`Toga `_ is a Python native, OS native, +cross platform GUI toolkit. Toga consists of a library of base components with a +shared interface to simplify platform-agnostic GUI development. -Toga is available on mOS, Windows, Linux (GTK), and mobile platforms such -as Android and iOS. +Toga is available on macOS, Windows, Linux (GTK), and mobile platforms such as +Android and iOS. ** @@ -161,8 +165,8 @@ Both Tk and Tkinter are available on most Unix platforms, as well as on Windows and Macintosh systems. Starting with the 8.0 release, Tk offers native look and feel on all platforms. -There's a good multi-language Tk tutorial with Python examples at -`TkDocs `_. There's more information +There's a good multi-language Tk tutorial with Python examples at `TkDocs +`_. There's more information available on the `Python Wiki `_. @@ -170,12 +174,12 @@ available on the `Python Wiki `_. wxPython ******** -wxPython is a GUI toolkit for the Python programming language. It allows -Python programmers to create programs with a robust, highly functional -graphical user interface, simply and easily. It is implemented as a Python -extension module (native code) that wraps the popular wxWidgets cross platform -GUI library, which is written in C++. +wxPython is a GUI toolkit for the Python programming language. It allows Python +programmers to create programs with a robust, highly functional graphical user +interface, simply and easily. It is implemented as a Python extension module +(native code) that wraps the popular wxWidgets cross platform GUI library, which +is written in C++. **Install (Stable) wxPython** -*go to http://www.wxpython.org/download.php#stable and download the appropriate +*go to https://www.wxpython.org/pages/downloads/ and download the appropriate package for your OS.* diff --git a/docs/scenarios/imaging.rst b/docs/scenarios/imaging.rst index 7b0e71935..8fe7e08fe 100644 --- a/docs/scenarios/imaging.rst +++ b/docs/scenarios/imaging.rst @@ -62,7 +62,7 @@ Example exif_data There are more examples of the Pillow library in the -`Pillow tutorial `_. +`Pillow tutorial `_. *************************** @@ -109,4 +109,4 @@ Example There are more Python-implemented examples of OpenCV in this `collection of tutorials -`_. +`_. diff --git a/docs/scenarios/json.rst b/docs/scenarios/json.rst index 130ad3031..1c3663777 100644 --- a/docs/scenarios/json.rst +++ b/docs/scenarios/json.rst @@ -5,7 +5,7 @@ JSON .. image:: /_static/photos/33928819683_97b5c6a184_k_d.jpg -The `json `_ library can parse +The `json `_ library can parse JSON from strings or files. The library parses JSON into a Python dictionary or list. It can also convert Python dictionaries or lists into JSON strings. @@ -46,27 +46,3 @@ You can also convert the following to JSON: print(json.dumps(d)) '{"first_name": "Guido", "last_name": "Rossum", "titles": ["BDFL", "Developer"]}' - - -********** -simplejson -********** - -The json library was added to Python in version 2.6. -If you're using an earlier version of Python, the -`simplejson `_ library is -available via PyPI. - -simplejson mimics the json standard library. It is available so that developers -that use older versions of Python can use the latest features available in the -json lib. - -You can start using simplejson when the json library is not available by -importing simplejson under a different name: - -.. code-block:: python - - import simplejson as json - -After importing simplejson as `json`, the above examples will all work as if you -were using the standard json library. diff --git a/docs/scenarios/network.rst b/docs/scenarios/network.rst index f8306c70a..bb751b78e 100644 --- a/docs/scenarios/network.rst +++ b/docs/scenarios/network.rst @@ -10,19 +10,19 @@ Networking Twisted ******* -`Twisted `_ is an event-driven networking +`Twisted `_ is an event-driven networking engine. It can be used to build applications around many different networking protocols, including HTTP servers and clients, applications using SMTP, POP3, IMAP, or SSH protocols, instant messaging, -and `much more `_. +and `much more `_. ***** PyZMQ ***** -`PyZMQ `_ is the Python binding for -`ZeroMQ `_, which is a high-performance asynchronous +`PyZMQ `_ is the Python binding for +`ZeroMQ `_, which is a high-performance asynchronous messaging library. One great advantage of ZeroMQ is that it can be used for message queuing without a message broker. The basic patterns for this are: diff --git a/docs/scenarios/scientific.rst b/docs/scenarios/scientific.rst index 3461bb353..bb0547323 100644 --- a/docs/scenarios/scientific.rst +++ b/docs/scenarios/scientific.rst @@ -91,13 +91,24 @@ are available in the `matplotlib gallery Pandas ------ -`Pandas `_ is data manipulation library +`Pandas `_ is a data manipulation library based on NumPy which provides many useful functions for accessing, indexing, merging, and grouping data easily. The main data structure (DataFrame) is close to what could be found in the R statistical package; that is, heterogeneous data tables with name indexing, time series operations, and auto-alignment of data. +xarray +------ + +`xarray `_ is similar to Pandas, but it +is intended for wrapping multidimensional scientific data. By labelling the +data with dimensions, coordinates, and attributes, it makes complex +multidimensional operations clearer and more intuitive. It also wraps +matplotlib for quick plotting, and can apply most operations in parallel using +`dask `_. + + Rpy2 ---- @@ -149,7 +160,7 @@ add-ons are available for academics and researchers. Canopy ------ -`Canopy `_ is another scientific +`Canopy `_ is another scientific Python distribution, produced by `Enthought `_. A limited 'Canopy Express' variant is available for free, but Enthought charges for the full distribution. Free licenses are available for academics. diff --git a/docs/scenarios/scrape.rst b/docs/scenarios/scrape.rst index 3c7493f42..527719200 100644 --- a/docs/scenarios/scrape.rst +++ b/docs/scenarios/scrape.rst @@ -28,7 +28,7 @@ lxml and Requests `lxml `_ is a pretty extensive library written for parsing XML and HTML documents very quickly, even handling messed up tags in the process. We will also be using the -`Requests `_ module instead of the +`Requests `_ module instead of the already built-in urllib2 module due to improvements in speed and readability. You can easily install both using ``pip install lxml`` and ``pip install requests``. @@ -87,8 +87,8 @@ Let's see what we got exactly: .. code-block:: python - print 'Buyers: ', buyers - print 'Prices: ', prices + print('Buyers: ', buyers) + print('Prices: ', prices) :: diff --git a/docs/scenarios/speed.rst b/docs/scenarios/speed.rst index 485872360..5dc0cd845 100644 --- a/docs/scenarios/speed.rst +++ b/docs/scenarios/speed.rst @@ -76,7 +76,7 @@ C Extensions Cython ------ -`Cython `_ implements a superset of the Python language +`Cython `_ implements a superset of the Python language with which you are able to write C and C++ modules for Python. Cython also allows you to call functions from compiled C libraries. Using Cython allows you to take advantage of Python's strong typing of variables and operations. @@ -168,25 +168,23 @@ What's the difference in speed? Let's try it! .. code-block:: python import time - #activate pyx compiler + # Activate pyx compiler import pyximport - pyximport.install() - #primes implemented with Cython - import primesCy - #primes implemented with Python - import primes - - print "Cython:" - t1= time.time() - print primesCy.primes(500) - t2= time.time() - print "Cython time: %s" %(t2-t1) - print "" - print "Python" - t1= time.time() - print primes.primes(500) - t2= time.time() - print "Python time: %s" %(t2-t1) + pyximport.install() + import primesCy # primes implemented with Cython + import primes # primes implemented with Python + + print("Cython:") + t1 = time.time() + print(primesCy.primes(500)) + t2 = time.time() + print("Cython time: %s" % (t2 - t1)) + print("") + print("Python") + t1 = time.time() + print(primes.primes(500)) + t2 = time.time() + print("Python time: %s" % (t2 - t1)) These lines both need a remark: @@ -448,14 +446,14 @@ Multiprocessing .. _`PyPy`: http://pypy.org -.. _`The GIL`: http://wiki.python.org/moin/GlobalInterpreterLock +.. _`The GIL`: https://wiki.python.org/moin/GlobalInterpreterLock .. _`guide`: http://www.dabeaz.com/python/UnderstandingGIL.pdf .. _`New GIL`: http://www.dabeaz.com/python/NewGIL.pdf -.. _`Special care`: http://docs.python.org/c-api/init.html#threads +.. _`Special care`: https://docs.python.org/c-api/init.html#threads .. _`David Beazley's`: http://www.dabeaz.com/GIL/gilvis/measure2.py .. _`concurrent.futures`: https://docs.python.org/3/library/concurrent.futures.html .. _`Future`: https://docs.python.org/3/library/concurrent.futures.html#concurrent.futures.Future .. _`threading`: https://docs.python.org/3/library/threading.html -.. _`stackoverflow post`: http://stackoverflow.com/questions/26688424/python-threads-are-printing-at-the-same-time-messing-up-the-text-output +.. _`Stack Overflow post`: https://stackoverflow.com/questions/26688424/python-threads-are-printing-at-the-same-time-messing-up-the-text-output .. _`data race`: https://en.wikipedia.org/wiki/Race_condition .. _`Lock`: https://docs.python.org/3/library/threading.html#lock-objects diff --git a/docs/scenarios/web.rst b/docs/scenarios/web.rst index c80b97ca5..a2c84818b 100644 --- a/docs/scenarios/web.rst +++ b/docs/scenarios/web.rst @@ -126,7 +126,7 @@ Pyramid focus on modularity. It comes with a small number of libraries ("batteries") built-in, and encourages users to extend its base functionality. A set of provided cookiecutter templates helps making new project decisions for users. -It powers one of the most important parts of python infrastucture +It powers one of the most important parts of python infrastructure `PyPI `_. Pyramid does not have a large user base, unlike Django and Flask. It's a @@ -155,7 +155,7 @@ and `Pydantic `_. FastAPI takes advantage of standard Python type declarations in function parameters to declare request parameters and bodies, perform data conversion (serialization, -parsing), data valdiation, and automatic API documentation with **OpenAPI 3** +parsing), data validation, and automatic API documentation with **OpenAPI 3** (including **JSON Schema**). It includes tools and utilities for security and authentication (including OAuth2 with JWT @@ -280,13 +280,6 @@ how to set up your first application. Heroku is the recommended PaaS for deploying Python web applications today. -Eldarion --------- - -`Eldarion `_ (formely known as Gondor) is a PaaS powered -by Kubernetes, CoreOS, and Docker. They support any WSGI application and have a -guide on deploying `Django projects `_. - ********** Templating diff --git a/docs/scenarios/xml.rst b/docs/scenarios/xml.rst index 91cafc5c4..24dab5869 100644 --- a/docs/scenarios/xml.rst +++ b/docs/scenarios/xml.rst @@ -43,7 +43,7 @@ untangle also supports loading XML from a string or a URL. xmltodict ********* -`xmltodict `_ is another simple +`xmltodict `_ is another simple library that aims at making XML feel like working with JSON. An XML file like this: @@ -81,3 +81,30 @@ and then you can access elements, attributes, and values like this: xmltodict also lets you roundtrip back to XML with the unparse function, has a streaming mode suitable for handling files that don't fit in memory, and supports XML namespaces. + +********** +xmlschema +********** + +`xmlschema `_ provides support for using XSD-Schemas in Python. +Unlike other XML libraries, automatic type parsing is available, so f.e. if the schema defines an element to be of type ``int``, the parsed ``dict`` will contain also an ``int`` value for that element. +Moreover the library supports automatic and explicit validation of XML documents against a schema. + +.. code-block:: python + + from xmlschema import XMLSchema, etree_tostring + + # load a XSD schema file + schema = XMLSchema("your_schema.xsd") + + # validate against the schema + schema.validate("your_file.xml") + + # or + schema.is_valid("your_file.xml") + + # decode a file + data = schmema.decode("your_file.xml") + + # encode to string + s = etree_tostring(schema.encode(data)) diff --git a/docs/shipping/freezing.rst b/docs/shipping/freezing.rst index 99dcba293..841fa2040 100644 --- a/docs/shipping/freezing.rst +++ b/docs/shipping/freezing.rst @@ -46,22 +46,23 @@ On Linux, an alternative to freezing is to Comparison of Freezing Tools **************************** +Date of this writing: Oct 5, 2019 Solutions and platforms/features supported: -=========== ======= ===== ==== ======== ======= ============= ============== ==== ===================== -Solution Windows Linux OS X Python 3 License One-file mode Zipfile import Eggs pkg_resources support -=========== ======= ===== ==== ======== ======= ============= ============== ==== ===================== -bbFreeze yes yes yes no MIT no yes yes yes -py2exe yes no no yes MIT yes yes no no -pyInstaller yes yes yes yes GPL yes no yes no -cx_Freeze yes yes yes yes PSF no yes yes no -py2app no no yes yes MIT no yes yes yes -=========== ======= ===== ==== ======== ======= ============= ============== ==== ===================== +=========== ======= ===== ==== ======== ======= ============= ============== ==== ===================== ===================== +Solution Windows Linux OS X Python 3 License One-file mode Zipfile import Eggs pkg_resources support Latest release date +=========== ======= ===== ==== ======== ======= ============= ============== ==== ===================== ===================== +bbFreeze yes yes yes no MIT no yes yes yes Jan 20, 2014 +py2exe yes no no yes MIT yes yes no no Oct 21, 2014 +pyInstaller yes yes yes yes GPL yes no yes no Jul 9, 2019 +cx_Freeze yes yes yes yes PSF no yes yes no Aug 29, 2019 +py2app no no yes yes MIT no yes yes yes Mar 25, 2019 +=========== ======= ===== ==== ======== ======= ============= ============== ==== ===================== ===================== .. note:: Freezing Python code on Linux into a Windows executable was only once supported in PyInstaller `and later dropped - `_. + `_. .. note:: All solutions need a Microsoft Visual C++ to be installed on the target machine, except py2app. @@ -139,7 +140,7 @@ Prerequisite is to install :ref:`Python on Windows `. The last 3. (Optionally) `include icon `_ -4. (Optionally) `one-file mode `_ +4. (Optionally) `one-file mode `_ 5. Generate :file:`.exe` into :file:`dist` directory: @@ -221,6 +222,45 @@ Linux bbFreeze ~~~~~~~~ +.. warning:: bbFreeze will ONLY work in Python 2.x environment, since it's no longer being maintained as stated by it's former maintainer. If you're interested in it, check the repository in `here `_. + +bbFreeze can be used with all distributions that has Python installed along with pip2 and/or easy_install. + +For pip2, use the following: + +.. code-block:: console + + $ pip2 install bbfreeze + +Or, for easy_install: + +.. code-block:: console + + $ easy_install bbfreeze + +With bbFreeze installed, you're ready to freeze your applications. + +Let's assume you have a script, say, "hello.py" and a module called "module.py" and you have a function in it that's being used in your script. +No need to worry, you can just ask to freeze the main entrypoint of your script and it should freeze entirely: + +.. code-block:: console + + $ bbfreeze script.py + +With this, it creates a folder called dist/, of which contains the executable of the script and required .so (shared objects) files linked against libraries used within the Python script. + +Alternatively, you can create a script that does the freezing for you. An API for the freezer is available from the library within: + +.. code-block:: python + + from bbfreeze import Freezer + + freezer = Freezer(distdir='dist') + freezer.addScript('script.py', gui_only=True) # Enable gui_only kwarg for app that uses GUI packages. + freezer() PyInstaller ~~~~~~~~~~~ +PyInstaller can be used in a similar fashion as in OS X. The installation goes in the same manner as shown in the OS X section. + +Don't forget to have dependencies such as Python and pip installed for usage. diff --git a/docs/shipping/packaging.rst b/docs/shipping/packaging.rst index 0f0ff04d1..34674cff2 100644 --- a/docs/shipping/packaging.rst +++ b/docs/shipping/packaging.rst @@ -48,7 +48,7 @@ On Linux, you may also want to consider For Python Developers ********************* -If you're writing an open source Python module, `PyPI `_ +If you're writing an open source Python module, `PyPI `_ , more properly known as *The Cheeseshop*, is the place to host it. @@ -56,8 +56,8 @@ If you're writing an open source Python module, `PyPI `_ Pip vs. easy_install -------------------- -Use `pip `_. More details -`here `_. +Use `pip `_. More details +`here `_. Personal PyPI @@ -83,7 +83,7 @@ Go to your command prompt and type: .. code-block:: console $ cd archive - $ python -m SimpleHTTPServer 9000 + $ python -m http.server 9000 This runs a simple HTTP server running on port 9000 and will list all packages (like **MyPackage**). Now you can install **MyPackage** using any Python @@ -105,7 +105,7 @@ I got fooled by that, one time. But if you feel that creating a folder called pypiserver ++++++++++ -`pypiserver `_ is a minimal PyPI +`pypiserver `_ is a minimal PyPI compatible server. It can be used to serve a set of packages to easy_install or pip. It includes helpful features like an administrative command (``-U``) which will update all its packages to their latest versions @@ -193,4 +193,4 @@ Useful Tools - `fpm `_ - `alien `_ -- `dh-virtualenv `_ (for APT/DEB omnibus packaging) +- `dh-virtualenv `_ (for APT/DEB omnibus packaging) diff --git a/docs/shipping/publishing.rst b/docs/shipping/publishing.rst new file mode 100644 index 000000000..4b480f801 --- /dev/null +++ b/docs/shipping/publishing.rst @@ -0,0 +1,66 @@ +.. _publishing-your-code-ref: + + +#################### +Publishing Your Code +#################### + +.. todo:: Replace this kitten with the photo we want. + +.. image:: https://placekitten.com/800/600 + +A healthy open source project needs a place to publish its code and project +management stuff so other developers can collaborate with you. This lets your +users gain a better understanding of your code, keep up with new developments, +report bugs, and contribute code. + +This development web site should include the source code history itself, a bug +tracker, a patch submission (aka "Pull Request") queue, and possibly additional +developer-oriented documentation. + +There are several free open source project hosting sites (aka "forges"). These +include GitHub, SourceForge, Bitbucket, and GitLab. GitHub is currently the best. +Use GitHub. + + +********************************* +Creating a Project Repo on GitHub +********************************* + +To publish your Python project on GitHub: + +1. Create a GitHub account if you don't already have one. + +2. Create a new repo for your project. + + 1. Click on the "+" menu next to your avatar in the upper right of the page and choose "New repository". + + 2. Name it after your project and give it an SEO-friendly description. + + 3. If you don't have an existing project repo, choose the settings to add a + README, `.gitignore`, and license. Use the Python `.gitignore` option. + +3. On the newly created repo page, click "Manage topics" and add the tags "python" and "python3" and/or "python2" as appropriate. + +4. Include a link to your new GitHub repo in your project's README file so people who just have the project distribution know where to find it. + +If this is a brand new repo, clone it to your local machine and start working: + +.. code-block:: console + + $ git clone https://github.com// + +Or, if you already have a project Git repo, add your new GitHub repo as a remote: + +.. code-block:: console + + $ cd + $ git remote add origin https://github.com// + $ git push --tags + +*********************** +When Your Project Grows +*********************** + +For more information about managing an open source software project, see the book +`Producing Open Source Software `_. diff --git a/docs/starting/install/linux.rst b/docs/starting/install/linux.rst index f0dc63950..4198be8be 100644 --- a/docs/starting/install/linux.rst +++ b/docs/starting/install/linux.rst @@ -38,7 +38,7 @@ it makes it much easier for you to use other third-party Python libraries. Setuptools & Pip **************** -The two most crucial third-party Python packages are `setuptools `_ and `pip `_. +The two most crucial third-party Python packages are `setuptools `_ and `pip `_. Once installed, you can download, install and uninstall any compliant Python software product with a single command. It also enables you to add this network installation @@ -75,6 +75,5 @@ manage your virtual environments. -------------------------------- -This page is a remixed version of `another guide `_, +This page is a remixed version of `another guide `_, which is available under the same license. - diff --git a/docs/starting/install/osx.rst b/docs/starting/install/osx.rst index 48e5bdfe9..4a8a8e03b 100644 --- a/docs/starting/install/osx.rst +++ b/docs/starting/install/osx.rst @@ -10,9 +10,10 @@ Installing Python 2 on Mac OS X .. note:: Check out our :ref:`guide for installing Python 3 on OS X`. -**Mac OS X comes with Python 2.7 out of the box.** +**Mac OS X comes with Python 2.7 out of the box between versions 10.8 and 12.3.** -You do not need to install or configure anything else to use Python. Having said +If your Mac OS X version is between the above versions, +you do not need to install or configure anything else to use Python. Having said that, I would strongly recommend that you install the tools and libraries described in the next section before you start building Python applications for real-world use. In particular, you should always install Setuptools, as it makes @@ -33,7 +34,7 @@ Let's install a real version of Python. Before installing Python, you'll need to install a C compiler. The fastest way is to install the Xcode Command Line Tools by running ``xcode-select --install``. You can also download the full version of -`Xcode `_ from the Mac App Store, or the +`Xcode `_ from the Mac App Store, or the minimal but unofficial `OSX-GCC-Installer `_ package. @@ -50,9 +51,9 @@ package. While OS X comes with a large number of Unix utilities, those familiar with Linux systems will notice one key component missing: a decent package manager. -`Homebrew `_ fills this void. +`Homebrew `_ fills this void. -To `install Homebrew `_, open :file:`Terminal` or +To `install Homebrew `_, open :file:`Terminal` or your favorite OS X terminal emulator and run .. code-block:: console @@ -129,5 +130,5 @@ To start using this and see more information: :ref:`Virtual Environments `_, +This page is a remixed version of `another guide `_, which is available under the same license. diff --git a/docs/starting/install/win.rst b/docs/starting/install/win.rst index e22837c8f..67f8885d6 100644 --- a/docs/starting/install/win.rst +++ b/docs/starting/install/win.rst @@ -13,7 +13,7 @@ Installing Python 2 on Windows First, download the `latest version `_ of Python 2.7 from the official website. If you want to be sure you are installing a fully up-to-date version, click the Downloads > Windows link from the home page of the -`Python.org web site `_ . +`Python.org web site `_ . The Windows version is provided as an MSI package. To install it manually, just double-click the file. The MSI package format allows Windows administrators to @@ -32,13 +32,13 @@ tedious, so add the directories for your default Python version to the :envvar:` Assuming that your Python installation is in :file:`C:\\Python27\\`, add this to your :envvar:`PATH`: -.. code-block:: console +.. code-block:: doscon C:\Python27\;C:\Python27\Scripts\ You can do this easily by running the following in ``powershell``: -.. code-block:: console +.. code-block:: powershell [Environment]::SetEnvironmentVariable("Path", "$env:Path;C:\Python27\;C:\Python27\Scripts\", "User") @@ -57,7 +57,7 @@ makes it much easier for you to use other third-party Python libraries. Setuptools + Pip **************** -The two most crucial third-party Python packages are `setuptools `_ and `pip `_. +The two most crucial third-party Python packages are `setuptools `_ and `pip `_. Once installed, you can download, install and uninstall any compliant Python software product with a single command. It also enables you to add this network installation @@ -68,9 +68,9 @@ pip by default. To see if pip is installed, open a command prompt and run -.. code-block:: console +.. code-block:: doscon - $ command -v pip + command -v pip To install pip, `follow the official pip installation guide `_ - this will automatically install the latest version of setuptools. @@ -92,5 +92,5 @@ To start using this and see more information: :ref:`Virtual Environments `_, +This page is a remixed version of `another guide `_, which is available under the same license. diff --git a/docs/starting/install3/linux.rst b/docs/starting/install3/linux.rst index 36b439ec2..b02204bc0 100644 --- a/docs/starting/install3/linux.rst +++ b/docs/starting/install3/linux.rst @@ -7,7 +7,7 @@ Installing Python 3 on Linux .. image:: /_static/photos/34435689480_2e6f358510_k_d.jpg -This document describes how to install Python 3.6 on Ubuntu Linux machines. +This document describes how to install Python 3.6 or 3.8 on Ubuntu Linux machines. To see which version of Python 3 you have installed, open a command prompt and run @@ -20,12 +20,12 @@ If you are using Ubuntu 16.10 or newer, then you can easily install Python 3.6 w $ sudo apt-get update $ sudo apt-get install python3.6 -If you're using another version of Ubuntu (e.g. the latest LTS release), we recommend using the `deadsnakes PPA `_ to install Python 3.6:: +If you're using another version of Ubuntu (e.g. the latest LTS release) or you want to use a more current Python, we recommend using the `deadsnakes PPA `_ to install Python 3.8:: $ sudo apt-get install software-properties-common $ sudo add-apt-repository ppa:deadsnakes/ppa $ sudo apt-get update - $ sudo apt-get install python3.6 + $ sudo apt-get install python3.8 If you are using other Linux distribution, chances are you already have Python 3 pre-installed as well. If not, use your distribution's package manager. @@ -37,8 +37,8 @@ For example on Fedora, you would use `dnf`: Note that if the version of the ``python3`` package is not recent enough for you, there may be ways of installing more recent versions as well, -depending on you distribution. For example installing the ``python36`` package -on Fedora 25 to get Python 3.6. If you are a Fedora user, you might want +depending on you distribution. For example installing the ``python3.9`` package +on Fedora 32 to get Python 3.9. If you are a Fedora user, you might want to read about `multiple Python versions available in Fedora`_. .. _multiple Python versions available in Fedora: https://developer.fedoraproject.org/tech/languages/python/multiple-pythons.html @@ -54,20 +54,20 @@ At this point, you may have system Python 2.7 available as well. $ python -This will launch the Python 2 interpreter. +This might launch the Python 2 interpreter. .. code-block:: console $ python3 -This will launch the Python 3 interpreter. +This will always launch the Python 3 interpreter. **************** Setuptools & Pip **************** -The two most crucial third-party Python packages are `setuptools `_ and `pip `_. +The two most crucial third-party Python packages are `setuptools `_ and `pip `_. Once installed, you can download, install and uninstall any compliant Python software product with a single command. It also enables you to add this network installation @@ -113,6 +113,5 @@ So, onward! To the :ref:`Pipenv & Virtual Environments -------------------------------- -This page is a remixed version of `another guide `_, +This page is a remixed version of `another guide `_, which is available under the same license. - diff --git a/docs/starting/install3/osx.rst b/docs/starting/install3/osx.rst index 9ffe20225..fa90fb93a 100644 --- a/docs/starting/install3/osx.rst +++ b/docs/starting/install3/osx.rst @@ -9,9 +9,10 @@ Installing Python 3 on Mac OS X .. image:: /_static/photos/34435689480_2e6f358510_k_d.jpg -**Mac OS X comes with Python 2.7 out of the box.** +**Mac OS X comes with Python 2.7 out of the box between versions 10.8 and 12.3.** -You do not need to install or configure anything else to use Python 2. These +If your Mac OS X version is between the above versions, +you do not need to install or configure anything else to use Python 2. These instructions document the installation of Python 3. The version of Python that ships with OS X is great for learning, but it's not @@ -27,7 +28,7 @@ Doing it Right Let's install a real version of Python. Before installing Python, you'll need to install GCC. GCC can be obtained -by downloading `Xcode `_, the smaller +by downloading `Xcode `_, the smaller `Command Line Tools `_ (must have an Apple account) or the even smaller `OSX-GCC-Installer `_ package. @@ -43,14 +44,14 @@ package. While OS X comes with a large number of Unix utilities, those familiar with Linux systems will notice one key component missing: a package manager. -`Homebrew `_ fills this void. +`Homebrew `_ fills this void. -To `install Homebrew `_, open :file:`Terminal` or +To `install Homebrew `_, open :file:`Terminal` or your favorite OS X terminal emulator and run .. code-block:: console - $ ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" + $ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)" The script will explain what changes it will make and prompt you before the installation begins. @@ -139,5 +140,5 @@ So, onward! To the :ref:`Pipenv & Virtual Environments -------------------------------- -This page is a remixed version of `another guide `_, +This page is a remixed version of `another guide `_, which is available under the same license. diff --git a/docs/starting/install3/win.rst b/docs/starting/install3/win.rst index 588d1ccb0..db78d9240 100644 --- a/docs/starting/install3/win.rst +++ b/docs/starting/install3/win.rst @@ -12,7 +12,7 @@ It's a community system packager manager for Windows 7+. (It's very much like Ho Once done, installing Python 3 is very simple, because Chocolatey pushes Python 3 as the default. -.. code-block:: console +.. code-block:: doscon choco install python @@ -24,12 +24,14 @@ Once you've run this command, you should be able to launch Python directly from Setuptools + Pip **************** -The two most crucial third-party Python packages are `setuptools `_ and `pip `_, +The two most crucial third-party Python packages are `setuptools `_ and `pip `_, which let you download, install and uninstall any compliant Python software product with a single command. It also enables you to add this network installation capability to your own Python software with very little work. -All supported versions of Python 3 include pip, so just make sure it's up to date:: +All supported versions of Python 3 include pip, so just make sure it's up to date: + +.. code-block:: doscon python -m pip install -U pip @@ -52,5 +54,5 @@ So, onward! To the :ref:`Pipenv & Virtual Environments -------------------------------- -This page is a remixed version of `another guide `_, +This page is a remixed version of `another guide `_, which is available under the same license. diff --git a/docs/starting/which-python.rst b/docs/starting/which-python.rst index d9dcc13ec..59d42352e 100644 --- a/docs/starting/which-python.rst +++ b/docs/starting/which-python.rst @@ -20,9 +20,9 @@ one might think. The basic gist of the state of things is as follows: -1. Most production applications today use Python 2.7. +1. Most production applications today use Python 3. 2. Python 3 is ready for the production deployment of applications today. -3. Python 2.7 will only receive necessary security updates until 2020 [#pep373_eol]_. +3. Python 2 reached the end of its life on January 1, 2020 [#pep373_eol]_. 4. The brand name "Python" encapsulates both Python 3 and Python 2. @@ -31,7 +31,7 @@ Recommendations *************** -.. note:: The use of **Python 3** is *highly* preferred over Python 2. Consider upgrading your applications and infrastructure if you find yourself *still* using Python 2 in production today. If you are using Python 3, congratulations — you are indeed a person of excellent taste. +.. note:: The use of **Python 3** is *highly* recommended over Python 2. Consider upgrading your applications and infrastructure if you find yourself *still* using Python 2 in production today. If you are using Python 3, congratulations — you are indeed a person of excellent taste. —*Kenneth Reitz* I'll be blunt: @@ -40,10 +40,6 @@ I'll be blunt: - If you're learning Python for the first time, familiarizing yourself with Python 2.7 will be very useful, but not more useful than learning Python 3. - Learn both. They are both "Python". -- Software that is already built often depends on Python 2.7. -- If you are writing a new open source Python library, it's best to write it for both Python 2 and 3 - simultaneously. Only supporting Python 3 for a new library you want to be widely adopted is a - political statement and will alienate many of your users. This is not a problem — slowly, over the next three years, this will become less the case. ********* @@ -58,8 +54,6 @@ Given such, only use Python 2 if you have a strong reason to, such as a pre-existing code-base, a Python 2 exclusive library, simplicity/familiarity, or, of course, you absolutely love and are inspired by Python 2. No harm in that. -Check out `Can I Use Python 3? `_ to see if any -software you're depending on will block your adoption of Python 3. `Further Reading `_ @@ -67,9 +61,7 @@ It is possible to `write code that works on Python 2.6, 2.7, and Python 3 `_. This ranges from trivial to hard depending upon the kind of software you are writing; if you're a beginner there are far more important things to -worry about. Note that Python 2.6 is end-of-life upstream, so you shouldn't -try to write 2.6-compatible code unless you're being paid specifically to -do that. +worry about. *************** @@ -135,7 +127,8 @@ expose Python code to other languages in the .NET framework. IronPython directly into the Visual Studio development environment, making it an ideal choice for Windows developers. -IronPython supports Python 2.7. [#iron_ver]_ +IronPython supports Python 2.7. [#iron_ver]_ IronPython 3 [#iron_ver3]_ +is being developed, but is not ready for use as of September 2020. PythonNet --------- @@ -151,16 +144,16 @@ installations on non-Windows operating systems, such as OS X and Linux, to operate within the .NET framework. It can be run in addition to IronPython without conflict. -Pythonnet supports from Python 2.6 up to Python 3.5. [#pythonnet_ver1]_ [#pythonnet_ver2]_ +Pythonnet is compatible with Python 2.7 and 3.5-3.8. [#pythonnet_ver1]_ -.. [#pypy_ver] http://pypy.org/compat.html +.. [#pypy_ver] https://pypy.org/compat.html .. [#jython_ver] https://hg.python.org/jython/file/412a8f9445f7/NEWS -.. [#iron_ver] http://ironpython.codeplex.com/releases/view/81726 +.. [#iron_ver] https://ironpython.net/download/ -.. [#pythonnet_ver1] https://travis-ci.org/pythonnet/pythonnet +.. [#iron_ver3] https://github.com/IronLanguages/ironpython3 -.. [#pythonnet_ver2] https://ci.appveyor.com/project/TonyRoberts/pythonnet-480xs +.. [#pythonnet_ver1] https://pythonnet.github.io/ .. [#pep373_eol] https://www.python.org/dev/peps/pep-0373/#id2 diff --git a/docs/writing/documentation.rst b/docs/writing/documentation.rst index c0d93d86c..27d85405a 100644 --- a/docs/writing/documentation.rst +++ b/docs/writing/documentation.rst @@ -45,7 +45,7 @@ Project Publication Depending on the project, your documentation might include some or all of the following components: -- An *introduction* should show a very short overview of what can be +- An *introduction* should give a very short overview of what can be done with the product, using one or two extremely simplified use cases. This is the thirty-second pitch for your project. @@ -85,7 +85,7 @@ structured and easily readable documentation for your project. for general project documentation. This Guide is built with Sphinx_ and is hosted on `Read The Docs`_ -.. _Sphinx: http://sphinx.pocoo.org +.. _Sphinx: https://www.sphinx-doc.org .. _Read The Docs: http://readthedocs.org .. _restructuredtext-ref: @@ -94,13 +94,13 @@ reStructuredText ~~~~~~~~~~~~~~~~ Most Python documentation is written with reStructuredText_. It's like -Markdown with all the optional extensions built in. +Markdown, but with all the optional extensions built in. The `reStructuredText Primer`_ and the `reStructuredText Quick Reference`_ should help you familiarize yourself with its syntax. .. _reStructuredText: http://docutils.sourceforge.net/rst.html -.. _reStructuredText Primer: http://sphinx.pocoo.org/rest.html +.. _reStructuredText Primer: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html .. _reStructuredText Quick Reference: http://docutils.sourceforge.net/docs/user/rst/quickref.html @@ -149,8 +149,8 @@ a project's documentation. Additionally, Doctest_ will read all embedded docstrings that look like input from the Python commandline (prefixed with ">>>") and run them, checking to see if the output of the command matches the text on the following line. This -allows developers to embed real examples and usage of functions alongside -their source code, and as a side effect, it also ensures that their code is +allows developers to embed real examples and usage of functions alongside +their source code. As a side effect, it also ensures that their code is tested and works. :: @@ -187,8 +187,8 @@ Docstrings are accessible from both the `__doc__` dunder attribute for almost every Python object, as well as with the built in `help()` function. While block comments are usually used to explain *what* a section of code is -doing, or the specifics of an algorithm, docstrings are more intended for -explaining to other users of your code (or you in 6 months time) *how* a +doing, or the specifics of an algorithm, docstrings are more intended towards +explaining other users of your code (or you in 6 months time) *how* a particular function can be used and the general purpose of a function, class, or module. @@ -214,7 +214,7 @@ In larger or more complex projects however, it is often a good idea to give more information about a function, what it does, any exceptions it may raise, what it returns, or relevant details about the parameters. -For more detailed documentation of code a popular style is the one used for the +For more detailed documentation of code a popular style used, is the one used by the NumPy project, often called `NumPy style`_ docstrings. While it can take up more lines than the previous example, it allows the developer to include a lot more information about a method, function, or class. :: diff --git a/docs/writing/gotchas.rst b/docs/writing/gotchas.rst index 677bdf823..f717858ca 100644 --- a/docs/writing/gotchas.rst +++ b/docs/writing/gotchas.rst @@ -7,13 +7,13 @@ Common Gotchas .. image:: /_static/photos/34435688380_b5a740762b_k_d.jpg For the most part, Python aims to be a clean and consistent language that -avoids surprises. However, there are a few cases that can be confusing to +avoids surprises. However, there are a few cases that can be confusing for newcomers. Some of these cases are intentional but can be potentially surprising. Some could arguably be considered language warts. In general, what follows is a collection of potentially tricky behavior that might seem strange at first -glance, but is generally sensible once you're aware of the underlying cause for +glance, but are generally sensible, once you're aware of the underlying cause for the surprise. @@ -53,8 +53,8 @@ isn't provided, so that the output is:: [12] [42] -What Does Happen -~~~~~~~~~~~~~~~~ +What Actually Happens +~~~~~~~~~~~~~~~~~~~~~ .. testoutput:: @@ -100,6 +100,7 @@ Late Binding Closures Another common source of confusion is the way Python binds its variables in closures (or in the surrounding global scope). + What You Wrote ~~~~~~~~~~~~~~ @@ -125,8 +126,8 @@ variable that multiplies their argument, producing:: 6 8 -What Does Happen -~~~~~~~~~~~~~~~~ +What Actually Happens +~~~~~~~~~~~~~~~~~~~~~ .. testoutput:: @@ -206,7 +207,7 @@ will automatically write a bytecode version of that file to disk, e.g. These ``.pyc`` files should not be checked into your source code repositories. Theoretically, this behavior is on by default for performance reasons. -Without these bytecode files present, Python would re-generate the bytecode +Without these bytecode files, Python would re-generate the bytecode every time the file is loaded. diff --git a/docs/writing/license.rst b/docs/writing/license.rst index 0a74f5405..820cc9a05 100644 --- a/docs/writing/license.rst +++ b/docs/writing/license.rst @@ -6,8 +6,8 @@ Choosing a License .. image:: /_static/photos/33907149294_82d7535a6c_k_d.jpg -Your source publication *needs* a license. In the US, if no license is -specified, users have no legal right to download, modify, or distribute. +Your source publication *needs* a license. In the US, unless a license is +specified, users have no legal right to download, modify, or distribute the product. Furthermore, people can't contribute to your code unless you tell them what rules to play by. Choosing a license is complicated, so here are some pointers: diff --git a/docs/writing/logging.rst b/docs/writing/logging.rst index 5ea058efc..b6110f7f7 100644 --- a/docs/writing/logging.rst +++ b/docs/writing/logging.rst @@ -10,6 +10,8 @@ The :mod:`logging` module has been a part of Python's Standard Library since version 2.3. It is succinctly described in :pep:`282`. The documentation is notoriously hard to read, except for the `basic logging tutorial`_. +As an alternative, `loguru `_ provides an approach for logging, nearly as simple as using a simple ``print`` statement. + Logging serves two purposes: - **Diagnostic logging** records events related to the application's @@ -57,7 +59,7 @@ using the ``__name__`` global variable: the :mod:`logging` module creates a hierarchy of loggers using dot notation, so using ``__name__`` ensures no name collisions. -Here is an example of best practice from the `requests source`_ -- place +Here is an example of the best practice from the `requests source`_ -- place this in your ``__init__.py``: .. code-block:: python @@ -70,9 +72,9 @@ this in your ``__init__.py``: Logging in an Application ************************* -The `twelve factor app `_, an authoritative reference +The `twelve factor app `_, an authoritative reference for good practice in application development, contains a section on -`logging best practice `_. It emphatically +`logging best practice `_. It emphatically advocates for treating log events as an event stream, and for sending that event stream to standard output to be handled by the application environment. @@ -81,7 +83,7 @@ application environment. There are at least three ways to configure a logger: - Using an INI-formatted file: - - **Pro**: possible to update configuration while running using the + - **Pro**: possible to update configuration while running, using the function :func:`logging.config.listen` to listen on a socket. - **Con**: less control (e.g. custom subclassed filters or loggers) than possible when configuring a logger in code. @@ -92,13 +94,13 @@ There are at least three ways to configure a logger: - **Con**: less control than when configuring a logger in code. - Using code: - **Pro**: complete control over the configuration. - - **Con**: modifications require a change to source code. + - **Con**: modifications require a change to the source code. Example Configuration via an INI File ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Let us say the file is named ``logging_config.ini``. +Let us say that the file is named ``logging_config.ini``. More details for the file format are in the `logging configuration`_ section of the `logging tutorial`_. @@ -192,9 +194,9 @@ Example Configuration Directly in Code logger.debug('often makes a very good meal of %s', 'visiting tourists') -.. _basic logging tutorial: http://docs.python.org/howto/logging.html#logging-basic-tutorial -.. _logging configuration: https://docs.python.org/howto/logging.html#configuring-logging -.. _logging tutorial: http://docs.python.org/howto/logging.html -.. _configuring logging for a library: https://docs.python.org/howto/logging.html#configuring-logging-for-a-library -.. _log record: https://docs.python.org/library/logging.html#logrecord-attributes +.. _basic logging tutorial: http://docs.python.org/3/howto/logging.html#logging-basic-tutorial +.. _logging configuration: https://docs.python.org/3/howto/logging.html#configuring-logging +.. _logging tutorial: http://docs.python.org/3/howto/logging.html +.. _configuring logging for a library: https://docs.python.org/3/howto/logging.html#configuring-logging-for-a-library +.. _log record: https://docs.python.org/3/library/logging.html#logrecord-attributes .. _requests source: https://github.com/kennethreitz/requests diff --git a/docs/writing/reading.rst b/docs/writing/reading.rst index ad67ea3cb..1e03a4def 100644 --- a/docs/writing/reading.rst +++ b/docs/writing/reading.rst @@ -43,7 +43,7 @@ reading. Each one of these projects is a paragon of Python coding. Requests is an Apache2 Licensed HTTP library, written in Python, for human beings. -- `Tablib `_ +- `Tablib `_ Tablib is a format-agnostic tabular dataset library, written in Python. diff --git a/docs/writing/structure.rst b/docs/writing/structure.rst index 842a44dd4..5d9645acd 100644 --- a/docs/writing/structure.rst +++ b/docs/writing/structure.rst @@ -18,7 +18,7 @@ the project? What features and functions can be grouped together and isolated? By answering questions like these you can begin to plan, in a broad sense, what your finished product will look like. -In this section we take a closer look at Python's module and import +In this section, we take a closer look at Python's modules and import systems as they are the central elements to enforcing structure in your project. We then discuss various perspectives on how to build code which can be extended and tested reliably. @@ -32,7 +32,7 @@ It's Important. ::::::::::::::: Just as Code Style, API Design, and Automation are essential for a -healthy development cycle, Repository structure is a crucial part of +healthy development cycle. Repository structure is a crucial part of your project's `architecture `__. @@ -54,13 +54,12 @@ documentation. Of course, first impressions aren't everything. You and your colleagues will spend countless hours working with this repository, eventually -becoming intimately familiar with every nook and cranny. The layout of -it is important. +becoming intimately familiar with every nook and cranny. The layout is important. Sample Repository ::::::::::::::::: -**tl;dr**: This is what `Kenneth Reitz `_ recommends. +**tl;dr**: This is what `Kenneth Reitz recommended in 2013 `__. This repository is `available on GitHub `__. @@ -126,7 +125,7 @@ If you aren't sure which license you should use for your project, check out `choosealicense.com `_. Of course, you are also free to publish code without a license, but this -would prevent many people from potentially using your code. +would prevent many people from potentially using or contributing to your code. Setup.py :::::::: @@ -157,8 +156,8 @@ should be placed at the root of the repository. It should specify the dependencies required to contribute to the project: testing, building, and generating documentation. -If your project has no development dependencies, or you prefer -development environment setup via ``setup.py``, this file may be +If your project has no development dependencies, or if you prefer +setting up a development environment via ``setup.py``, this file may be unnecessary. Documentation @@ -331,42 +330,42 @@ Easy structuring of a project means it is also easy to do it poorly. Some signs of a poorly structured project include: -- Multiple and messy circular dependencies: if your classes +- Multiple and messy circular dependencies: If the classes Table and Chair in :file:`furn.py` need to import Carpenter from :file:`workers.py` to answer a question such as ``table.isdoneby()``, and if conversely the class Carpenter needs to import Table and Chair to answer the question ``carpenter.whatdo()``, then you have a circular dependency. In this case you will have to resort to - fragile hacks such as using import statements inside + fragile hacks such as using import statements inside your methods or functions. -- Hidden coupling: each and every change in Table's implementation +- Hidden coupling: Each and every change in Table's implementation breaks 20 tests in unrelated test cases because it breaks Carpenter's code, - which requires very careful surgery to adapt the change. This means + which requires very careful surgery to adapt to the change. This means you have too many assumptions about Table in Carpenter's code or the reverse. -- Heavy usage of global state or context: instead of explicitly +- Heavy usage of global state or context: Instead of explicitly passing ``(height, width, type, wood)`` to each other, Table and Carpenter rely on global variables that can be modified and are modified on the fly by different agents. You need to - scrutinize all access to these global variables to understand why + scrutinize all access to these global variables in order to understand why a rectangular table became a square, and discover that remote template code is also modifying this context, messing with - table dimensions. + the table dimensions. - Spaghetti code: multiple pages of nested if clauses and for loops with a lot of copy-pasted procedural code and no proper segmentation are known as spaghetti code. Python's - meaningful indentation (one of its most controversial features) make - it very hard to maintain this kind of code. So the good news is that + meaningful indentation (one of its most controversial features) makes + it very hard to maintain this kind of code. The good news is that you might not see too much of it. - Ravioli code is more likely in Python: it consists of hundreds of similar little pieces of logic, often classes or objects, without - proper structure. If you never can remember if you have to use + proper structure. If you never can remember, if you have to use FurnitureTable, AssetTable or Table, or even TableNew for your - task at hand, you might be swimming in ravioli code. + task at hand, then you might be swimming in ravioli code. ******* @@ -384,13 +383,13 @@ in one file, and all low-level operations in another file. In this case, the interface file needs to import the low-level file. This is done with the ``import`` and ``from ... import`` statements. -As soon as you use `import` statements you use modules. These can be either +As soon as you use `import` statements, you use modules. These can be either built-in modules such as `os` and `sys`, third-party modules you have installed in your environment, or your project's internal modules. To keep in line with the style guide, keep module names short, lowercase, and be sure to avoid using special symbols like the dot (.) or question mark (?). -So a file name like :file:`my.spam.py` is one you should avoid! Naming this way +A file name like :file:`my.spam.py` is the one you should avoid! Naming this way will interfere with the way Python looks for modules. In the case of `my.spam.py` Python expects to find a :file:`spam.py` file in a @@ -398,10 +397,10 @@ folder named :file:`my` which is not the case. There is an `example `_ of how the dot notation should be used in the Python docs. -If you'd like you could name your module :file:`my_spam.py`, but even our -friend the underscore should not be seen often in module names. However, using other +If you like, you could name your module :file:`my_spam.py`, but even our trusty +friend the underscore, should not be seen that often in module names. However, using other characters (spaces or hyphens) in module names will prevent importing -(- is the subtract operator), so try to keep module names short so there is +(- is the subtract operator). Try to keep module names short so there is no need to separate words. And, most of all, don't namespace with underscores; use submodules instead. .. code-block:: python @@ -412,15 +411,15 @@ no need to separate words. And, most of all, don't namespace with underscores; u import library.foo_plugin Aside from some naming restrictions, nothing special is required for a Python -file to be a module, but you need to understand the import mechanism in order +file to be a module. But you need to understand the import mechanism in order to use this concept properly and avoid some issues. Concretely, the ``import modu`` statement will look for the proper file, which -is :file:`modu.py` in the same directory as the caller if it exists. If it is +is :file:`modu.py` in the same directory as the caller, if it exists. If it is not found, the Python interpreter will search for :file:`modu.py` in the "path" -recursively and raise an ImportError exception if it is not found. +recursively and raise an ImportError exception when it is not found. -Once :file:`modu.py` is found, the Python interpreter will execute the module in +When :file:`modu.py` is found, the Python interpreter will execute the module in an isolated scope. Any top-level statement in :file:`modu.py` will be executed, including other imports if any. Function and class definitions are stored in the module's dictionary. @@ -437,7 +436,7 @@ unwanted effects, e.g. override an existing function with the same name. It is possible to simulate the more standard behavior by using a special syntax of the import statement: ``from modu import *``. This is generally considered -bad practice. **Using** ``import *`` **makes code harder to read and makes +bad practice. **Using** ``import *`` **makes the code harder to read and makes dependencies less compartmentalized**. Using ``from modu import func`` is a way to pinpoint the function you want to @@ -493,20 +492,20 @@ modules, but with a special behavior for the :file:`__init__.py` file, which is used to gather all package-wide definitions. A file :file:`modu.py` in the directory :file:`pack/` is imported with the -statement ``import pack.modu``. This statement will look for an +statement ``import pack.modu``. This statement will look for :file:`__init__.py` file in :file:`pack` and execute all of its top-level statements. Then it will look for a file named :file:`pack/modu.py` and execute all of its top-level statements. After these operations, any variable, function, or class defined in :file:`modu.py` is available in the pack.modu namespace. -A commonly seen issue is to add too much code to :file:`__init__.py` +A commonly seen issue is adding too much code to :file:`__init__.py` files. When the project complexity grows, there may be sub-packages and sub-sub-packages in a deep directory structure. In this case, importing a single item from a sub-sub-package will require executing all :file:`__init__.py` files met while traversing the tree. -Leaving an :file:`__init__.py` file empty is considered normal and even a good +Leaving an :file:`__init__.py` file empty is considered normal and even good practice, if the package's modules and sub-packages do not need to share any code. @@ -520,45 +519,44 @@ Object-oriented programming *************************** Python is sometimes described as an object-oriented programming language. This -can be somewhat misleading and needs to be clarified. +can be somewhat misleading and requires further clarifications. In Python, everything is an object, and can be handled as such. This is what is meant when we say, for example, that functions are first-class objects. Functions, classes, strings, and even types are objects in Python: like any object, they have a type, they can be passed as function arguments, and they -may have methods and properties. In this understanding, Python is an -object-oriented language. +may have methods and properties. In this understanding, Python can be considered +as an object-oriented language. However, unlike Java, Python does not impose object-oriented programming as the main programming paradigm. It is perfectly viable for a Python project to not be object-oriented, i.e. to use no or very few class definitions, class inheritance, or any other mechanisms that are specific to object-oriented -programming. +programming languages. Moreover, as seen in the modules_ section, the way Python handles modules and namespaces gives the developer a natural way to ensure the encapsulation and separation of abstraction layers, both being the most common reasons to use object-orientation. Therefore, Python programmers have more -latitude to not use object-orientation, when it is not required by the business +latitude as to not use object-orientation, when it is not required by the business model. There are some reasons to avoid unnecessary object-orientation. Defining -custom classes is useful when we want to glue together some state and some -functionality. The problem, as pointed out by the discussions about functional +custom classes is useful when we want to glue some state and some +functionality together. The problem, as pointed out by the discussions about functional programming, comes from the "state" part of the equation. In some architectures, typically web applications, multiple instances of Python -processes are spawned to respond to external requests that can happen at the -same time. In this case, holding some state in instantiated objects, which +processes are spawned as a response to external requests that happen simultaneously. +In this case, holding some state in instantiated objects, which means keeping some static information about the world, is prone to concurrency problems or race conditions. Sometimes, between the initialization of the state of an object (usually done with the ``__init__()`` method) and the actual use of the object state through one of its methods, the world may have changed, and the retained state may be outdated. For example, a request may load an item in memory and mark it as read by a user. If another request requires the deletion -of this item at the same time, it may happen that the deletion actually occurs -after the first process loaded the item, and then we have to mark as read a -deleted object. +of this item at the same time, the deletion may actually occur after the first +process loaded the item, and then we have to mark a deleted object as read. This and other issues led to the idea that using stateless functions is a better programming paradigm. @@ -572,7 +570,7 @@ or deletes data in a global variable or in the persistence layer, it is said to have a side-effect. Carefully isolating functions with context and side-effects from functions with -logic (called pure functions) allow the following benefits: +logic (called pure functions) allows the following benefits: - Pure functions are deterministic: given a fixed input, the output will always be the same. @@ -675,7 +673,7 @@ by the ``with`` statement. CustomOpen is first instantiated and then its is finished executing, the ``__exit__`` method is then called. And now the generator approach using Python's own -`contextlib `_: +`contextlib `_: .. code-block:: python @@ -714,7 +712,7 @@ type. In fact, in Python, variables are very different from what they are in many other languages, specifically statically-typed languages. Variables are not a segment of the computer's memory where some value is written, they are 'tags' or 'names' pointing to objects. It is therefore possible for the variable 'a' to -be set to the value 1, then to the value 'a string', then to a function. +be set to the value 1, then the value 'a string', to a function. The dynamic typing of Python is often considered to be a weakness, and indeed it can lead to complexities and hard-to-debug code. Something named 'a' can be @@ -744,7 +742,7 @@ Some guidelines help to avoid this issue: def func(): pass # Do something -Using short functions or methods helps reduce the risk +Using short functions or methods helps to reduce the risk of using the same name for two unrelated things. It is better to use different names even for things that are related, @@ -790,7 +788,7 @@ compute x + 1, you have to create another integer and give it a name. my_list = [1, 2, 3] my_list[0] = 4 - print my_list # [4, 2, 3] <- The same list has changed + print(my_list) # [4, 2, 3] <- The same list has changed x = 6 x = x + 1 # The new x is another object @@ -824,7 +822,7 @@ most idiomatic way to do this. nums = "" for n in range(20): nums += str(n) # slow and inefficient - print nums + print(nums) **Better** @@ -834,7 +832,7 @@ most idiomatic way to do this. nums = [] for n in range(20): nums.append(str(n)) - print "".join(nums) # much more efficient + print("".join(nums)) # much more efficient **Best** @@ -842,11 +840,11 @@ most idiomatic way to do this. # create a concatenated string from 0 to 19 (e.g. "012..1819") nums = [str(n) for n in range(20)] - print "".join(nums) + print("".join(nums)) One final thing to mention about strings is that using ``join()`` is not always best. In the instances where you are creating a new string from a pre-determined -number of strings, using the addition operator is actually faster, but in cases +number of strings, using the addition operator is actually faster. But in cases like above or in cases where you are adding to an existing string, using ``join()`` should be your preferred method. @@ -890,5 +888,5 @@ Runners Further Reading *************** -- http://docs.python.org/2/library/ -- http://www.diveintopython.net/toc/index.html +- http://docs.python.org/3/library/ +- https://diveintopython3.net/ diff --git a/docs/writing/style.rst b/docs/writing/style.rst index 8f15a1b02..d8c096a05 100644 --- a/docs/writing/style.rst +++ b/docs/writing/style.rst @@ -8,7 +8,7 @@ Code Style .. image:: /_static/photos/33907150054_5ee79e8940_k_d.jpg If you ask Python programmers what they like most about Python, they will -often cite its high readability. Indeed, a high level of readability +often cite its high readability. Indeed, a high level of readability is at the heart of the design of the Python language, following the recognized fact that code is read much more often than it is written. @@ -65,9 +65,9 @@ it is bad practice to have two disjointed statements on the same line of code. .. code-block:: python - print 'one'; print 'two' + print('one'); print('two') - if x == 1: print 'one' + if x == 1: print('one') if and : # do something @@ -76,11 +76,11 @@ it is bad practice to have two disjointed statements on the same line of code. .. code-block:: python - print 'one' - print 'two' + print('one') + print('two') if x == 1: - print 'one' + print('one') cond1 = cond2 = @@ -226,7 +226,7 @@ but making a public property private might be a much harder operation. Returning values ~~~~~~~~~~~~~~~~ -When a function grows in complexity it is not uncommon to use multiple return +When a function grows in complexity, it is not uncommon to use multiple return statements inside the function's body. However, in order to keep a clear intent and a sustainable readability level, it is preferable to avoid returning meaningful values from many output points in the body. @@ -271,7 +271,7 @@ Idioms A programming idiom, put simply, is a *way* to write code. The notion of programming idioms is discussed amply at `c2 `_ -and at `Stack Overflow `_. +and at `Stack Overflow `_. Idiomatic Python code is often referred to as being *Pythonic*. @@ -357,9 +357,7 @@ Instead, use a list comprehension: .. code-block:: python - four_lists = [[] for __ in xrange(4)] - -Note: Use range() instead of xrange() in Python 3. + four_lists = [[] for __ in range(4)] Create a string from a list ~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -403,7 +401,7 @@ hand, the hash of the item will tell Python where in the set to look for a matching item. As a result, the search can be done quickly, even if the set is large. Searching in dictionaries works the same way. For more information see this -`StackOverflow `_ +`StackOverflow `_ page. For detailed information on the amount of time various common operations take on each of these data structures, see `this page `_. @@ -455,7 +453,7 @@ Also known as :pep:`20`, the guiding principles for Python's design. Namespaces are one honking great idea -- let's do more of those! For some examples of good Python style, see `these slides from a Python user -group `_. +group `_. ***** @@ -467,8 +465,7 @@ easy-to-read version of PEP 8 is also available at `pep8.org ` This is highly recommended reading. The entire Python community does their best to adhere to the guidelines laid out within this document. Some project -may sway from it from time to time, while others may -`amend its recommendations `_. +may sway from it from time to time, while others may amend its recommendations. That being said, conforming your Python code to PEP 8 is generally a good idea and helps make code more consistent when working on projects with other @@ -496,7 +493,15 @@ Then run it on a file or series of files to get a report of any violations. optparse.py:472:29: E221 multiple spaces before operator optparse.py:544:21: W601 .has_key() is deprecated, use 'in' -The program `autopep8 `_ can be used to +Auto-Formatting +~~~~~~~~~~~~~~~ + +There are several auto-formatting tools that can reformat your code, +in order to comply with PEP 8. + +**autopep8** + +The program `autopep8 `_ can be used to automatically reformat code in the PEP 8 style. Install the program with: .. code-block:: console @@ -513,6 +518,49 @@ Excluding the ``--in-place`` flag will cause the program to output the modified code directly to the console for review. The ``--aggressive`` flag will perform more substantial changes and can be applied multiple times for greater effect. +**yapf** + +While autopep8 focuses on solving the PEP 8 violations, `yapf `_ +tries to improve the format of your code aside from complying with PEP 8. +This formatter aims at providing as good looking code as a programmer who +writes PEP 8 compliant code. +It gets installed with: + +.. code-block:: console + + $ pip install yapf + +Run the auto-formatting of a file with: + +.. code-block:: console + + $ yapf --in-place optparse.py + +Similar to autopep8, running the command without the ``--in-place`` flag will +output the diff for review before applying the changes. + +**black** + +The auto-formatter `black `_ offers an +opinionated and deterministic reformatting of your code base. +Its main focus lies in providing a uniform code style without the need of +configuration throughout its users. Hence, users of black are able to forget +about formatting altogether. Also, due to the deterministic approach minimal +git diffs with only the relevant changes are guaranteed. You can install the +tool as follows: + +.. code-block:: console + + $ pip install black + +A python file can be formatted with: + +.. code-block:: console + + $ black optparse.py + +Adding the ``--diff`` flag provides the code modification for review without +direct application. *********** Conventions @@ -533,10 +581,10 @@ list of what is considered false. .. code-block:: python if attr == True: - print 'True!' + print('True!') if attr == None: - print 'attr is None!' + print('attr is None!') **Good**: @@ -544,15 +592,15 @@ list of what is considered false. # Just check the value if attr: - print 'attr is truthy!' + print('attr is truthy!') # or check for the opposite if not attr: - print 'attr is falsey!' + print('attr is falsey!') # or, since None is considered false, explicitly check for it if attr is None: - print 'attr is None!' + print('attr is None!') Access a Dictionary Element ~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -566,9 +614,9 @@ or pass a default argument to :py:meth:`dict.get`. d = {'hello': 'world'} if d.has_key('hello'): - print d['hello'] # prints 'world' + print(d['hello']) # prints 'world' else: - print 'default_value' + print('default_value') **Good**: @@ -576,24 +624,24 @@ or pass a default argument to :py:meth:`dict.get`. d = {'hello': 'world'} - print d.get('hello', 'default_value') # prints 'world' - print d.get('thingy', 'default_value') # prints 'default_value' + print(d.get('hello', 'default_value')) # prints 'world' + print(d.get('thingy', 'default_value')) # prints 'default_value' # Or: if 'hello' in d: - print d['hello'] + print(d['hello']) Short Ways to Manipulate Lists ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ `List comprehensions `_ -provide a powerful, concise way to work with lists. +provides a powerful, concise way to work with lists. `Generator expressions `_ -follow almost the same syntax as list comprehensions but return a generator -instead of a list. +follows almost the same syntax as list comprehensions but return a generator +instead of a list. Creating a new list requires more work and uses more memory. If you are just going to loop through the new list, prefer using an iterator instead. @@ -617,7 +665,7 @@ example if you need to use the result multiple times. If your logic is too complicated for a short list comprehension or generator -expression, consider using a generator function instead of returning a list. +expression, consider using a generator function instead of returning a list. **Good**: @@ -637,20 +685,20 @@ expression, consider using a generator function instead of returning a list. yield current_batch -Never use a list comprehension just for its side effects. +Never use a list comprehension just for its side effects. **Bad**: .. code-block:: python - [print(x) for x in seqeunce] + [print(x) for x in sequence] **Good**: .. code-block:: python for x in sequence: - print(x) + print(x) Filtering a list @@ -677,7 +725,7 @@ Don't make multiple passes through the list. **Good**: -Use a list comprehension or generator expression. +Use a list comprehension or generator expression. .. code-block:: python @@ -732,7 +780,7 @@ Use :py:func:`enumerate` keep a count of your place in the list. a = [3, 4, 5] for i, item in enumerate(a): - print i, item + print(i, item) # prints # 0 3 # 1 4 @@ -753,7 +801,7 @@ files for you. f = open('file.txt') a = f.read() - print a + print(a) f.close() **Good**: @@ -762,7 +810,7 @@ files for you. with open('file.txt') as f: for line in f: - print line + print(line) The ``with`` statement is better because it will ensure you always close the file, even if an exception is raised inside the ``with`` block. @@ -778,7 +826,7 @@ a white space added to the end of the line, after the backslash, will break the code and may have unexpected results. A better solution is to use parentheses around your elements. Left with an -unclosed parenthesis on an end-of-line the Python interpreter will join the +unclosed parenthesis on an end-of-line, the Python interpreter will join the next line until the parentheses are closed. The same behavior holds for curly and square braces. diff --git a/docs/writing/tests.rst b/docs/writing/tests.rst index 141c92971..28eb3260b 100644 --- a/docs/writing/tests.rst +++ b/docs/writing/tests.rst @@ -9,8 +9,8 @@ Testing Your Code Testing your code is very important. Getting used to writing testing code and running this code in parallel is now -considered a good habit. Used wisely, this method helps you define more -precisely your code's intent and have a more decoupled architecture. +considered a good habit. Used wisely, this method helps to define your +code's intent more precisely and have a more decoupled architecture. Some general rules of testing: @@ -201,7 +201,7 @@ the unittest module! Hypothesis ---------- -Hypothesis is a library which lets you write tests that are parametrized by +Hypothesis is a library which lets you write tests that are parameterized by a source of examples. It then generates simple and comprehensible examples that make your tests fail, letting you find more bugs with less work. @@ -248,35 +248,6 @@ simple INI-style configuration file. `tox `_ -Unittest2 ---------- - -unittest2 is a backport of Python 2.7's unittest module which has an improved -API and better assertions over the one available in previous versions of Python. - -If you're using Python 2.6 or below, you can install it with pip: - -.. code-block:: console - - $ pip install unittest2 - -You may want to import the module under the name unittest to make porting code -to newer versions of the module easier in the future - -.. code-block:: python - - import unittest2 as unittest - - class MyTest(unittest.TestCase): - ... - -This way if you ever switch to a newer Python version and no longer need the -unittest2 module, you can simply change the import in your test module without -the need to change any other code. - - `unittest2 `_ - - mock ---- @@ -323,6 +294,6 @@ always returns the same result (but only for the duration of the test). # get_search_results runs a search and iterates over the result self.assertEqual(len(myapp.get_search_results(q="fish")), 3) -Mock has many other ways you can configure it and control its behavior. +Mock has many other ways with which you can configure and control its behaviour. `mock `_ diff --git a/requirements.txt b/requirements.txt index c2886a7fe..4a246ac76 100644 --- a/requirements.txt +++ b/requirements.txt @@ -6,7 +6,7 @@ docutils==0.14 idna==2.7 imagesize==1.0.0 Jinja2==2.10 -MarkupSafe==1.0 +MarkupSafe==1.1.1 packaging==17.1 Pygments==2.2.0 pyparsing==2.2.0 diff --git a/runtime.txt b/runtime.txt index d70c8f8d8..cc1923a40 100644 --- a/runtime.txt +++ b/runtime.txt @@ -1 +1 @@ -3.6 +3.8