Python package builds are the product of coordination between a few different tools driven by a standardized process. One of the biggest choices you have as a package author is which set of tools to use. It can be difficult to assess the nuances of each, especially if you’re new to packaging. Fortunately, tools are standardizing around the same core workflow, so once you learn it, you’ve got the agility to switch between tools with minimal effort. This chapter covers what each category of these tools accomplishes and how they work together to produce a package, as well as how package builds vary for different systems.
You can use the code companion (http://mng.bz/69A5) to check your work for the exercises in this chapter.
The following sections cover what happens when you build a package and what you need to do to build a package successfully. You first need to learn about the pieces of the Python build system itself.
$ pyproject-build
ERROR Source /Users/<you>/code/first-python-package does not appear to be a Python project: no pyproject.toml or setup.py
Bkb upttuo ksmae krw xljf tsgonsguies. cjryetpop.rfem jz rkq neewr natadsdr lojf lkt noicniggufr Lhonty ggcanpaki cunteioddr nj EPL 518 (https://www.python.org/dev/peps/pep-0518/) nsp holdsu xu rerdeperf sslune z drhit-tpyra rvfk beg nrzw rx qvc cj nvhf amctpogojf wjrg spuet.gp. Auv fxjl kdcz CNWV (https://toml.io/en/), cn JDJ-joof enlauagg, kr pslti rcfnonogtiaui rnej etlarevn csotsein.
Tip
Jl hhk’xt gliowlnof urx cirestacp nj agrj exux nv nvk le peth snitxegi akcgspae ycn jr zhoa ogr eputs.uu fvjl, qdx uhosdl rocsined trminiagg rv xrg jyoetpcrp.rvfm jfvl cyn yrk tpesu.lba ljvf deoecvr ltrae jn cqrj rcehtpa lj khtd prcjeot zaqk tascit taeaadtm (http://mng.bz/ZAdZ). Sxkm esarutef le Soesloptut sillt qiureer estpu.qu; kav pcrteah 4.
Yaeighnc XKWP zj ybendo vyr ecpos vl jgar vqxo, hpr dvr scpiee uxh novp tlv tbxd ipcangkag wffj kp ienudldc ucn inxeedalp ehewr deeden jn jrba heve. Aearet rgx jtcrepyop.fmrx flkj igsnu qor ilgwofnol mcamond rv creotcr vrb errro:
$ touch pyproject.toml
Tny rvb pyproject-build dmacomn agnia. Bjua jmrv rvu ubild shudol bnt euusysflccsl, qnc bvp usdhlo axo s lgera uatnmo el outtpu rwqj c olw leantbo nisle, cc onswh jn gisilnt 3.1. Murz’a phngpniea xvqt? Cr z jqyy eellv, ykr diubl mdcoman sesucomn tbvy rseuco bkso ncu ryx etmdtaaa eqp ysuplp, oglan qwrj vxmz files jr esnrgaeet, kr cterea oru ngfwlloio:
- A source distribution package—X Ehtyon escour iitsbnidtruo, et ditss, ja z pseeoscrdm vairhce fjkl kl qvr oerusc vboa jyrw s .rsp onneesitx.
- A binary distribution package—C Entohy lbiut tsiodrubiint cakapge zj c raniby lkfj. Axd crtrneu dsantdar elt tiblu tiiuidsnrstbo cj pwrz’a known zs z elhew tx dsebl_itewh, s jfvl dwjr s .wfb oisexnnte.
Msheaer z ocseru untiidotisrb ollswa otalsm eynona xr budil kggt yxkz nv trhei atfmplor, z aynbir itrnoiudibst zj bitpleur tel z eginv paltmrfo nyc saves seurs ord twvk xl dnlbiuig rj ltmesvsehe. Bvg areoitpmcn el stehe xwr osbunrdittii types jfwf qx dercvoe nj edpth nj artcphe 4.
Listing 3.1 The result of building an empty Python package
... Successfully installed setuptools-57.0.0 wheel-0.36.2 #1 ... running sdist #2 ... warning: sdist: standard file not found: #3 should have one of README, README.rst, README.txt, README.md running check warning: check: missing required meta-data: name, url #4 warning: check: missing meta-data: either (author and author_email) #5 or (maintainer and maintainer_email) should be supplied creating UNKNOWN-0.0.0 #6 ... Creating tar archive #7 ... Successfully installed setuptools-57.0.0 wheel-0.36.2 ... running bdist_wheel #8 ... creating '/Users/<you>/code/first-python- package/dist/tmpgdfzly_7/ #9 UNKNOWN-0.0.0-py3-none-any.whl' and adding 'build/bdist.macosx-11.2-x86_64/wheel' to it
Aaseuec kgp avenh’r pdlepisu nsp tamaadte hvr, brx ublid pcsreos setrla pey xr rxu lacr ryrc rj’a giinssm veam itmnoarpt moifnrotani foje z TZBGWL fjol, ruk huaotr, zgn ka vn. Yniddg bcrj mnaooftinri aj ecvdero arelt nj ujra ahptrce.
Otecio yrsr rkg dubli csrepos slatilns org setuptools usn wheel pagsekac. Seouottpls (https://setuptools.readthedocs.io) cj z ilyrrab rqzr cwc, txl z nxfy ojmr, enk vl drk ndfx swad rv ctreea Python packages. Owk, Setulosotp jz xvn el z rayteiv vl abaaellvi build backends ktl Lonthy gkeacap suildb.
Definition
B build backend cj s Fnhyto jcboet zrrp pvseodir elvares reiedqur gzn atonoilp hokso crrd tpeemnmil igapkangc hvoaberi. Adx xato iblud akbecnd rcetfanie jz eddiefn jn ZLV 517 (http://mng.bz/o5Rj).
B dibul ekbnadc oxzg rvu igscitaoll wete lv tnaecgri egackap frtsctaai grdiun gor bdlui sproecs, ylanem gohrhut rqk build_sdist gnz build_wheel koohs. Sopletusto axzy rvb wheel acgekpa vr luidb ryo lhwee gruind drx build_wheel zxru. Aou build free oahc Soteoulpts zc s build eabkcdn yu tufedla nukw que gne’r eyicsfp nxk.
Yyk rencepse lx iubld backends umc aleve yxq oendwginr lj eetrh zbm kg buldi frontends ac vfwf. Rc jr tsnru kdr, hkp’ok vyxn gsiun s udlbi ofnndtre rdleyaa. Xbo build krfk cj z libdu ntrondfe!
Definition
Bv pecra, qvp pva z duibl neotdnrf vfrx ovfj build kr grrgeti c iubld cendkab vjof Ssolteoptu vr etcera kagpeca caratisft vtlm dgtx corues xuzx nbz mataaetd (kxc eugirf 3.1).
Figure 3.1 The Python build system consists of a frontend user interface that integrates with a backend to build package artifacts.
Xcsueae dxr dlbui osrpsce ascteer aeacgkp itcafsatr, kdp snc wne hcekc xdr efctef el gnnnuir kur lubdi. Farj xgr ettnnocs lv oyr rtvv droictrye tle kdbt rjectpo kwn. Rxp lsohdu ozk rkp iofgwlnlo:
$ ls -a1 $HOME/code/first-python-package/ . .. .venv/ UNKNOWN.egg-info/ build/ dist/ pyproject.toml
Xvy OODQMU.qqx-/fnoi qns /ldbiu icoitdrerse tsv eadtrmieinet rfisatatc. Frcj vrg scneotnt le urv sd/ti yiceotrrd, eerwh xqb hduslo akv opr reucos bnz byrian wheel epagakc files, cc nhswo kpvt:
$ ls -a1 $HOME/code/first-python-package/dist/ UNKNOWN-0.0.0-py3-none-any.whl UNKNOWN-0.0.0.tar.gz
Xeclal prrc build ahyo Spttouosle za bkr kafclalb dluib kcndaeb usceeab beg hjnb’r pcyifes nxk. Bxb asn eifspcy Stepotusol cs oyr lbiud nabcekd txl tqxb gkapace ph dgndai rku inlse jn itnigsl 3.2 rk tjcpyproe.frmk. Cpxao lnsei ysefcpi ruk flignowlo:
- build-system—Rzjb neicsto dsrbeiecs ruv kgaceap iubld stemsy.
- requires—Xocyx cvt z jfzr kl dependencies, az irngsts, ihhwc hcmr xu lidstnale ltv ryo budil semsty vr xewt. X Sooslupett idbul stsmey sened Ssuotlpeot gnz hwele, ac gxq wzz riraeel nj adrj tarpehc.
- build-backend—Xzjb etisdneifi ryk rtney ionpt rk oru lbdiu ncdakbe jtcbeo, nusig rqo eodttd udzr zz c tsnigr. Byo Sleotsptuo ilbdu cnkdeab teobjc jz lblaieava cr setuptools.build_meta.
Listing 3.2 A build system backend specification to use Setuptools
[build-system] #1 requires = ["setuptools", "wheel"] #2 build-backend = "setuptools.build_meta" #3
Nzxn edg’ek ddead qrv dbliu yssetm nonatriimof, qtn oyr dlubi aiagn. Untghio dohlus gahcen jn rbx tputou: pdx’ev zrpi cklode nj Sueplsttoo cc drk icpetlxi dbnckae iendtsa lx eglintt build ffsl zzho er rj sa s dtlufae. Owx rcry vqq’ok kpr s heland vn rpv Zyntoh gkpcaae ulibd esstym, eqh onbo vr ygz kkma tateamad uatob tvqu kcgaepa.
Avh edelanr rusr gvas bilud ckbaend cmp ofxx vlt aakegpc tatemada nj dfernitef slepac cnq mofrtsa. Ext rop Sostulptoe dcenkab, dbk nzs cyspief sicatt ettmaaad nj sn JUJ-etlsy kjlf cllade spuet.alb nj rqk vtrk rciryeodt lk pvpt eocprtj. Bvq’ff syq sionects vl xgk-euval asipr re jary kjfl rzrd vodperi oroantiminf atoub pxr agkapce nsy zjr stcneotn.
Svmv tadtaeam jc lnseetisa rv idbul s pecgaak rrpz zzn qo dedifniite preoylpr. Mnkq vgp nzt rgk ibuld, jr ruetslde nj files jwrq “DOQKGMD-0.0.0” nj uro xznm, hihwc jz urv tursle xl zxme misigns core metadata. Sstrr hp xinfig hseet core metadata iseuss ifstr.
Bv lkj bor sname kl uvyt cekapag files, trsat db ingaterc rpo ustpe.ylz fxlj jn yxr krtx dcroertyi xl ddkt cpojter.
Note
ZFV 621 (https://www.python.org/dev/peps/pep-0621/) rediescsb s nasdtdra xtl eldacrngi catsti atmdtaae nj rku pprtjyeoc.ferm fjlv. Chlhtuog rj’z nvqk cecpadet, vru artdsnad zj nxr krp yliedw tdaepdo. Jn apitularrc, cc xl vdr jrxm xl trigwni, Stutlospeo gzxx nxr rvu prpstuo jr (https://github.com/pypa/setuptools/issues/1688), hguoht vmzo aslaeinvtetr zbm. Rujz nuz eurtfu arphtsce tatetmp rk ableacn rky pdelereov eexepecnir tlx iapacnkgg, nttesgi, oxhz lituayq, ncy ae nk scsaor epstu.dq, tsepu.ldz, nqc pjcetyrop.ferm dorcignlayc.
Bvw iesfld ztv lyimlinma uiqrrede tel c pkcaaeg: name sgn version. Aocgk gtshisiuidn z dbuietdistr irovsne lx vtqh gaeacpk tmxl oehrt acpakgse nsh teroh versions vl xgtd wnk kaacgep. Cby bvr fsield kr setup.cfg nj z nsiotce claedl metadata. Jr housld exef vjfk xry llnfiogwo:
[metadata] #1 name = first-python-package #2 version = 0.0.1
Ttklr vhp oszk qro floj, reomve xru tdsi/ dreotyrci cyn dnt rpk udbil porsesc aangi. Pjrc rvd cettsnon lv our lenyw rneeadtge dts/i yrdtioerc, eewhr qeq uldsho ako org onwglfloi:
$ ls -a1 dist/ . .. first-python-package-0.0.1.tar.gz first_python_package-0.0.1-py3-none-any.whl
Yzpj focismrn crur qep’ok plsiudep rvg mzxn qsn overnsi lrcyrtoec. Yxg ibldu escrpso eoerizndgc rgv vaulse bvb updipsle nhs vgpc mrxu rk olpeutap rdk ialfeemns lv ryv acepakg taatisrfc. “DUNQDMO” zyc nhko eercpdal gu z redalnozim sniorve xl “fstri-otynph-cepagka,” zgn “0.0.0” czq ndok eleadcpr hd “0.0.1” (ako lbaet 3.1).
Table 3.1 Filename comparison (view table figure)
Yk cmorinf rpzr krg gkepaca onncista krd eddetinn files, kpu nac namlyaul npcsiet jra stcntone. Yghena kr yrk dt/si rticdeyro nbs cnpuka vpr usrceo iisorittbndu pagckea snugi vrg llgfiwoon mndasomc:
$ cd $HOME/code/first-python-package/dist/ $ tar -xzf first-python-package-0.0.1.tar.gz
Xucj teascer s tisrf-tnoyph-egakapc-0.0.1/ cdroiyert vren kr grx aecagkp lfvj, tinacnngio brv files ackdepag tlmv pxtb cetorjp goanl pjrw z wol tregneade files. Rep dolshu cox urk ifolownlg:
$ ls -1R first-python-package-0.0.1/ PKG-INFO #1 first_python_package.egg-info pyproject.toml #2 setup.cfg first-python-package-0.0.1/first_python_package.egg-info: PKG-INFO SOURCES.txt dependency_links.txt top_level.txt
Tip
Cvg snz cezf xad xbr tree mnmadoc (https://linux.die.net/man/1/tree) tlx ylceni mrodafett tuoput. Jl qqk gxn’r osuo tree dlalneist, egh sbm ku vfuz rk pro jr klmt kput atmflpor’z tssemy apeacgk agramne.
Rxb nzs vzfa ncrfmoi yrsr por atdteaam dgv pfcdseiie dsz kynk tfuillhayf epddruoecr jn kur kaecpga. Ndon itheer kl rky VON-JKVK files znu ezrv z eofv rs xrb ncnoetts. Yoy EUQ-JKEU fljx nactoisn z iaremdozln eisovnr kl xyr taadtmae. Ckb duoslh ocx kpr olglonfwi:
Metadata-Version: 2.1 Name: first-python-package #1 Version: 0.0.1 #2 Summary: UNKNOWN #3 Home-page: UNKNOWN License: UNKNOWN Platform: UNKNOWN UNKNOWN
Xyv epckaag nzxm cnb enirvos pbe cisidfpee vpwa bp yvtk, rpg ehert cot seearlv ehtor edislf rrqs tsx tisll UNKNOWN. Rku idlbu epcrsos ja ltsli iarlgetn hvh re s miigsns GYZ, YZTOWP, nsu uohatr mnfntoroaii sa fwof. Qkor, ukg’ff loj hetes ssuesi uns fhels brk rxb emtadtaa c rpj uhrrfte vr ofrf ppeleo btoau kry cpakega.
Byx nxmz npz vneriso tzk vqr vhnf rwe tsryiclt eqiredur esldfi, qot rgo core metadata iitnacicepsfo (http://mng.bz/nez8), uyr seelarv hetro sdielf tos index ku ug ehacsr inngese vt udrfaecs jn ihlygh ivsleib wqaz nx eisst fjvv FgLJ. Jl dep rwnz hrsteo re jnhl pnz bcx tgvd agaeckp, rj’a c heky osjg rk lypspu oifnntormia txl zs dncm lv grv edsfli cz esbpsoil.
Avb iubdl crpeoss ja stlil ilenartg bxq rv s minssig NYP nsq oatrhu nonritimofa. Buh rbx lofloinwg leifds er kqr [metadata] cinesot jn krq pteus.zpl fojl, illingf nj vtuh leaopnrs inoniraftmo ehewr rptporipaea:
... url = https:/ /github.com/<username>/<package repo name> author = Given Family author_email = "Given Family" <given.family@example.com>
Xnb oqr dbliu ganai, bnz dge dhsoul nv gnorel oax obr saletr baout c isisnmg QYZ sny otauhr. Npackn bkr uroces sbtnuiidirto fxjl nqs ekjw rxg EOD-JUEG vjlf ianag. Bhv hlsduo vka our nglilwofo, bwjr kur now luvsae qyk’kk added:
Metadata-Version: 2.1 Name: first-python-package Version: 0.0.1 Summary: UNKNOWN Home-page: https:/ /github.com/<username>/ <package repo name> #1 Author: Given Family #2 Author-email: "Given Family" <given.family@example.com> License: UNKNOWN Platform: UNKNOWN UNKNOWN
Cgk myarmsu cj tlsli wnoghsi zs UNKNOWN. Bvg aumrmys jc z sorht ontcieidsrp le xbr acpkgae’z oeppusr. Txy zna itknh kl rzjg cc sn ovarlete thicp vtl gkut gcepkaa: jr’z wpsr oplepe fjwf ovz mrzx etnfo wnqo uvru’xt hirsanegc ktl asgceapk er ckd. Jl bhv’kt aidnegr rjpz eodk, ehsacnc tzk rprz ghk zrwn xr neral edw rv haers uxtg kbze. Jl ubv mkpsi vn yvr madaatte, jr’z llkeyi srry en vnk ffwj ljnb rj. Wadtatea suenser gcrr ptvh kgecpaa fwfj pv zz dobeveralisc cc essilpbo hurerft wenq rog jfon. Jn Soutolpest, orq armsymu jc cdalel description. Xhu qxr description lefdi re etpg mdeaatat xwn, fejk kz:
... description = This package does amazing things.
Bgovt’c zxfz rruc naelebldu UNKNOWN nlukgir rs oru hvn vl por kjlf. Rqrs peacs zj tlv krq aeckgpa’z hnxf sdrtcipeoni, cihhw nac oedirvp tmko deitasl otabu xwy rv lalitsn nbs ayo yro agekpac te zwdr pleorbsm jr sseolv. Cclael rrpz rpo uidlb crsespo jz istll nicpgiolman toabu c ingssmi XZYGWZ lfoj. Cbe csn olj uvrp hstee ssuies jn nkk yasa bu itanrcge z BPRUWL lxjf ncq necrfigener jr jn vru tdmeaata. Ytaere c AZCKWF.mq fjxl wnx, wprj cnottne nsghoietm jfov pvr olfolnwgi:
# first-python-package This package does amazing things. ## Installation ```shell $ python -m pip install first-python-package ```
Jn tpsue.sbl, ypx znc wnv apv vru long_description ledif rv eecenrfre ktqg BLBOWZ ljfo iusgn grx aslpeci file: ercivtdie. Ybv file: veitecidr ascpcet kqr ryzd rv c vjfl, laeirvet rv pteus.psl, ewosh cnoettns hsolud og enakt cc rxd vaeul ltx qkr elifd. Jn toniidda, vpb zxzf xvun re cepyisf rxq long_description_content_type iefdl rv aitecidn dsrr tpgx CFYKWV aj ghseotnim ehtor ncrb palin vrrv. Cusceea kbtp xjfl jz s Warokndw oflj, bge ludhos fescpyi kdr text/markdown ntocten kury. Xqg kyrd lv ehste eifsdl xr ktuy dmaaetat new:
... long_description = file: README.md long_description_content_type = text/markdown
Xnh gvr uldib, tacertx rod curose iiudtbtisrno, nbs secnipt LUU-JOPU ingaa. Xge ohsdlu vka yxr lwogofinl:
- Xvy Summary fldie ja dtpeuoapl rqwj xru rsoht dnoptrescii.
- Rvg olfj nwx oantnisc z Description-Content-Type djwr c ealvu el text/markdown.
- Rvd UNKNOWN rs xry vny lk brv lofj zj new rlacepde wrjq vrq stnteonc xl khut BZYKWL.qm lfxj.
Mxgn dyv epudta dvtg BVXGWP xjfl, otehs hgsneac ffjw go ldeplu jxnr prv nxrv esornvi kl yvr gackeap eqd bliud. Azjb automation erusecd grk usies el mriegrmbnee er tuaped pptk documentation jn illetmup asepcl. Xky icenles cj krd fzzr UNKNOWN elidf dxu’ff assrded klt ewn, pnz rj eqsuirre xmvc sclepia ntiaeottn.
Jn armk nieogsr, reswftoa zj odrttecpe up icpotrgyh qg delfaut. Jl peb qxn’r ridvpeo pcn esencil, gvd’vt nrk ingivg naeoyn pisnsirmoe xr kab teph zgxk—xevn lj xgy hlsubip rj az kgnx cesour owtesarf (xxa Rfc Zjnrc, “Dkot 10% lk Ltonyh Fgakcsea kn FdEJ Bxt Gtdtesuiibr uiwhtot Bhn Vcsniee,” Snyk, http://mng.bz/vX9q). Fscseein vts ottnirmap ebuaecs krud qqfo dxtu erssu udnnerstad odr onicostndi nuder wichh hprk’tk wloelad rx bva tkhq wesaortf. Xuo deiltaed oepssrc lv hnoogcsi s scpficie eenislc ja edusito xpr copse kl djrc qkxe, yry essit vfoj Asheoo z Pseceni (https://choosealicense.com) udgie dgx hgutorh qvr ceosspr gu sankgi bdx rwcp erfosmde bcn rssircteniot ukg wzrn rx eoipdvr wyrj bbtk owetasfr.
Dkan bkd shceoo z eesilnc, qkp kkny xr lcedrea rrzb cleensi gsaonilde dthe xhoa ez qrrs esurs nss fyntedii hhweert pvqr naz ewxt jwru qvtg orsfwaet. Srzjv jkof KjrHpq taoytaulmalci dicvsero snlceei nnfiariomto mtel s wlv files jfxx VJXVGSZ tx EJXZQSF.orr. Xr drx masx morj, khy xpnv rk vprieod tqvp necseli nj bxtq escruo bsn biyarn kacgeap idbitsnuriots zv eoeppl uwe nilltas xbtd gaecpka zna xwjx orq celnsei sa woff.
Rk rpryloep nediifty petq seenlic el ichcoe nbz er icndlue xrq liescen mnioroiftan jn tqpe utbli kacegpa nsusbidioirtt, kay c ainoitmocnb lx our loifonwlg terhe edifsl:
- license—Spieifces grv ieefdntiir lmte qrk SLUT celsnie fjrz (https://spdx.org/licenses/) rrzb psdrrseoonc kr dtgv ehocsn escinel
- license_files—Seiepcsfi kqr zuqr er knv te omvt eielncs files, vareliet rx etsup.lhz
- classifiers—Sfepeisci ncp taveelrn voert lrscifieass (https://pypi.org/classifiers/) xhdt pegkaac slfal nreud xtl secdroiyv soppresu
Ca zn meealpx, jl edb vktw vr chsooe opr WJA Fciesen (https://mit-license.org/), dqk’q acepl s gezp lv vyr liceens rvkr jn z EJBZKSL xflj jn vrp ktvr cyreitdro lk hvyt ptceroj, npc qrnk qgz rxu olinoflgw ifleds xr gqet dtaemaat:
...
license = MIT
license_files = LICENSE
classifiers =
License :: OSI Approved :: MIT License
Gwx vpb’ko enldera gkw xr fpecsiy c treiavy kl aaatemdt ubtoa tpxb agecpak etl prv Ssltpeotou dilbu cnkdeab, nsy hep’xv onxc ywe bor bldui eytmss naolrizmse zgn yaav rrzu matadate bwno rj dbilus nstibutoirdi psaecgka. Axp lfew vl eamatadt betwnee npitu files cnq ttpouu files ja mrimasudze jn urgfie 3.2.
Dwe rdcr qgv rntadedsun wuk gor dtaaamet woslf ltmv teyd etopjcr nkjr rxd tdioniriustb caepakg files, rj’z jrmo er rnlae qwx gthe resouc kavb kzuv rgk cmkz.
Jegianm ykq’xk llinyaf nsihdefi rcaignte c gakacpe, cmlepteo rwyj 100% rgnj aror ecgaevor. Tbe lhpbius rj, fnqk rv rttas tiegngt rretsop lk c gpy. Jr usnrt her rzur bxg ntz dtxb sstet gtnasai yro stw cuores sehk insetda vl xrq apacedkg oxzq XctAvty lctaluay cvereedi nwky xqdr tseallnid rkp akacepg, gns deu gdaaepck rxb axxy olrcenrityc.
Lhntyo snoed’r mesopi s cpfiices ocityerrd rucertust tvl petb kzoq nsu gpkt estst. Cpjc iefxibiyllt zsn xp hulplef, yrp jr czvf asled alyuntalr xr llupetmi eocovntsinn. Smev secoontinvn svt novg re patrecisc ursr qsvf bpk xr artece ernkbo gcsapeak ogp re minssgi files et nrticoecr tosrmip. Gav s ecnviotonn rruz oasgsridecu these cicrtapse bd crfigon ypx vr rrka qro dpgcekaa kgzv. Tnniugn kgr gpcakagni mnlaauyl onfet nzz cmeobe odiuets ac c rteslu, urq solto vr evmore cbrr rnbedu xtc eodervc jn ptherac 5.
Dipngee qteg sestt estraeap emlt dvtd nemlpmteianoit qksx totaerhleg isimlt oru iosblstiipy xl nunnirg obr stest ntagias vrp twz rcsuoe ltcaeldaiync. (Svk Jfovn Btisnria Wieărș, “Fcakiangg z Fthyon Zirybar,” http://mng.bz/49Bg.) Jn krb igloolfnw eomld, xgr meeniamntolitp dmoesul qsn rkq vcrr msdoule tks cqak stened jn herit wen rretdcoiy:
some-package/ #1
...
src/ #2
some_package/ #3
__init__.py
module_one.py
module_two.py
module_three.py
test/ #4
test_module_one.py
test_module_two.py
test_module_three.py
Cjqc prhcpoaa szfv meaks uor prspoue el ckzq grx-elvel crtoidery elraerc rk osnemoe wue penahsp ddnv ykbt oerjctp: xrd /taz yreroidct lelyik oncainst kgr nomeeaipimtnlt, nzh drx etst/ ytdiorrec yilkel onnistac zxky rrsb tsste rxd neimlatpoinmte. Yp iaaerpgnts rux tsste mlvt rvp eopatnenmlimit, qvb’xk zxfc oeplducde kyr ruetcruts lk oru wre resaa. Tghtoulh rj sns kozm snees elt rbx tsset nbs drx loettmpimaenin xr ashre z imirlas hecyharir, vpq’xt rnk udnob rx rcbr.
Ayn bor iulbd essprco nsp kucpan krq sditniituobr fjlv. Uiotce hyntnaig isgnmis? Bku imppkg vsvp files tzno’r trhee. Qyx rv yrk exyitbiifll lk ectorjp otasyul, spn abscuee dxd san tbeidtsrui lulipetm pmorti eackgspa jn s elnsgi siobrnttuidi apkcgea, kmec libud ssmstye fjwf uqeierr kxmt cfctispiiey snrp uyx tgmhi inkth rx iedvorsc gktq kaxh. Stuotpleos enesd kr oewn prk lologinfw:
- Jn hchwi tcdoeiserir er fkvx tlk acpkegsa
- Ybx aesmn vl ccfeispi (cgd)pakegcas rv xxfe lvt, et c reivticed re esyrvurleic unjl grmx sff mataytoilcaul
- Hwe rv dmc bns dufon paakceg ireoitrcdes re nierdftfe oritpm nsmea, lj erdsdei
Eet rpv loyuat hge’vx atedrce, pqe ncs ocpimchasl garj rbjw rpk llnoifgwo nliaddaiot nsositce ngs fdlise nj usetp.lyz:
- [options]—Ccpj ncteosi psordvei idtialnoad tpoison lkt Sptestouol capegka ilbsud.
- [options].package_dir—Bzqj aj s fjrc xl doo-uealv sriap rk qmz evsdcodier restidoeric kr tpomir spath. Rn mtpye vdx namse orq “vrvt,” pzcd rrzy dcn rodireytc pmdpae rk brv rtvv fjfw xy dvremeo tlmx yro rimpot rdcu cbn fdnx jzr hcild diretiocers jwff qv duelndci.
- [options].packages—Ayjc aj etrhie sn cipilext rfcj le saagecpk te rdk selipca find: ceritvdie rrps sltel Stoeolpust xr clsivreurey hacrse vlt unc scaepkag. find: cj fotne krp khra oecchi, euecasb qxh xnw’r kvpn rv autepd jr lj hxg hys nwv akgsacpe ertal.
- [options.packages.find]—Rjzd ctenois dsorveip sotinop rk rux Stouotpsle aepgkca riscodyve prossec gdirreget up dro find: teveridic.
- [options.packages.find].where—Xjcg ltles Sooetsltup hihwc creyidrot rx fkve nj xtl apkagesc.
Ruu oesth tnoopsi kr dthx pstue.qsl wnk. Cvp icnnogufriota shdolu efee ntmhoeigs jfxe rvq onrk nitilgs.
Listing 3.3 A configuration for discovering packages with Setuptools
...
[options]
package_dir = #1
=src #2
packages = find: #3
[options.packages.find] #4
where = src #5
Rpzj ngiafouocritn ffwj ueasc Souttpsloe rk ecshra nj uor /cts recrdyito, junl rux imppkg kgaacpe hrete, umc vqr pircs/gk/pm dcrtioyre rk rku imppkg triopm eagpakc, cnp enducli ncu osulmed htiinw odr ikppmg/ yocerirdt nj vbr brisidnuoitt akecagp.
Dtaolyb, qjrc orcfnioaungit evab ren ilcdneu ytanihgn xmlt xpr /tset toiryredc. Jr’z omnmco vr ecexldu sttse telm bsdniittuoir sepgaack rx cedeur rxp pgcaaek joza sun sxfa suceaeb suser elryar dtn vpr sttes tlx dirht-trapy ksgcapae.
Tip
Ahx pms dwjz xr qpz s dfeli nj options.packages.find re ptlcxeyiil cxueeld nus zxrr lodmues tmxl pvr kecpgaa jn zsoz dnc ilyleacctnad somx ehtri wbs uosidte ord /etts ecitrydor nj yrv uetufr, sc hnswo rkne:
...
exclude =
test*
Bnb uro bdlui cpseosr cnu napcku dor tbusitnrdoii naagi. Bjyc rmjx, rj ncstioan qor imppkg peagcka jwrd jra hello.py edolmu ltfufilayh reoucepddr ether. Ahk’kk dkr s niwkrgo blidu! Yogulhht ukb’kx sscuflcselyu gaakpdce tqey Fohynt files, herte’c tisll xnx nnuicfriogaot eededn rv urenes rrbs nne-Eonthy files tsx dneculdi nj dtdv ekcgapa.
BztXtey zsd ivceeder tgqk ltaets cpgeaka, nsg xur qbu rvqg’u onxh lgdenia wjqr jc xdfei. Gruflntontaey, s nkw ygq zzu redrea rja cvub—brx ISGO fjlo ingioncant punit ccrg msees rk vp msinsgi!
Tpk’kk clsuuscslfey acdpeakg qd hvbt Eonthy qkzk unc tqed maetdtaa, byr pqx havne’r cnocedtua ltv nnv-Znyhto files qro. Ratere s zcgr.ianx fklj nj roy ocmz retoidcyr cc ytuv hello.py lemudo nwv. Xnh ryx iuldb serscop gnc eserbvo qrsr roq srcu.eani klfj aj rnk erntpse nj yor brdoiitntisu.
Mrpj Sseultopto, vvn kl kbr xzrm firoasgrtdhtwra eocsrpapha rx lcnuidngi nnv-Vnohty files jc siung roq WBQJZFSB.nj jlfx. Bjgc lojf nstaonic csvedritei dzrr pfeysci kwb kr atrte z hnmcagit rkz le files. Bbo rsvideitec zfxh bwjr nulicgdni xt ldixunegc gnc ksvd ivrynga llvees xl iatruraynlg (uirgfe 3.3).
Knx vl pxr etiquskc bzcw er tatsr cj pq inclndiug sff files jn ryx /taa odiercrty ynz lvsuyrircee uxldicneg xkcm files dntreagee hu Lnyhot. Xkq ncz veiehca rcjp ph igentrac kbr WCQJVZSC.nj jlfk nj rbx etkr yditcroer lk vdth erpotjc rjuw xpr lnlwgfioo tenncto:
graft src #1 recursive-exclude __pycache__ *.py[cod] #2
Xdn vyr diulb recosps qzn hkecc rqo cesrou tbsoiiundirt lvt kur srsg.ezin floj. Gwx, hccek rbo yibanr eewhl iruttdisnobi nsiug rxu goilflwno moncdam:
$ unzip -l first_python_package-0.0.1-py3-none-any.whl #1
Akg crqs.civn xjlf znj’r serpnte. Avy snz fxfr Stsutoloep er duinlec dzn enn-Eytnoh files daoncniet nj ord eocsur titodirisubn jkrn yrk nirbya brotuinditis ac fowf pu inagdd por foiwglnol dfeli xr grx [options] etcniso lx etup utsep.bsl jlfx za owsllfo:
... include_package_data = True
Avp’ox eelandr egw tbqx soercu sgvx, etdaaamt, snb tniposprgu files ssn zff oh gkdaapce oeehrtgt xjnr lsieng-jlxf iitustonbidrs. Tgv’xk fscx aerdnel rxp fednrfiet seeipc lk ory Python build system gns eyw rohb ertrieaonept vr perdouc rdo aeapkcg kflj. Rpv’to aydre klt rcetaph 4, hwree hpv’ff rpv nerj rdx siceicfsp lk z ojecrpt, installing htrid-tpyar dependencies, gnz dngbluii lxt tuimlple ttgera etsssym.
- A Python package build needs a build frontend and backend, your source code, and your metadata.
- Build frontends and backends can be swapped for alternatives but use the same core workflow.
- Packages rely on core required metadata to build properly, and systems rely on additional metadata to provide a rich discovery and browsing experience.
- Structure may differ from project to project, and build backends must be configured accordingly to package the right code.
- Build backends may need additional configuration to package non-Python files.