6. Modules — Python 3.10.7 documentation

In the simplest case, __init__.py can just be an empty file, but it can also execute initialization code for the package or set the __all__ variable, described ... Navigation index modules| next| previous| Python» 3.10.7Documentation» ThePythonTutorial» 6.Modules | 6.Modules¶ IfyouquitfromthePythoninterpreterandenteritagain,thedefinitionsyou havemade(functionsandvariables)arelost.Therefore,ifyouwanttowritea somewhatlongerprogram,youarebetteroffusingatexteditortopreparethe inputfortheinterpreterandrunningitwiththatfileasinputinstead.This isknownascreatingascript.Asyourprogramgetslonger,youmaywantto splititintoseveralfilesforeasiermaintenance.Youmayalsowanttousea handyfunctionthatyou’vewritteninseveralprogramswithoutcopyingits definitionintoeachprogram. Tosupportthis,Pythonhasawaytoputdefinitionsinafileandusethemina scriptorinaninteractiveinstanceoftheinterpreter.Suchafileiscalleda module;definitionsfromamodulecanbeimportedintoothermodulesorinto themainmodule(thecollectionofvariablesthatyouhaveaccesstoina scriptexecutedatthetoplevelandincalculatormode). AmoduleisafilecontainingPythondefinitionsandstatements.Thefilename isthemodulenamewiththesuffix.pyappended.Withinamodule,the module’sname(asastring)isavailableasthevalueoftheglobalvariable __name__.Forinstance,useyourfavoritetexteditortocreateafile calledfibo.pyinthecurrentdirectorywiththefollowingcontents: #Fibonaccinumbersmodule deffib(n):#writeFibonacciseriesupton a,b=0,1 whilea>>importfibo Thisdoesnotaddthenamesofthefunctionsdefinedinfibodirectlyto thecurrentnamespace(seePythonScopesandNamespacesformoredetails); itonlyaddsthemodulenamefibothere.Using themodulenameyoucanaccessthefunctions: >>>fibo.fib(1000) 01123581321345589144233377610987 >>>fibo.fib2(100) [0,1,1,2,3,5,8,13,21,34,55,89] >>>fibo.__name__ 'fibo' Ifyouintendtouseafunctionoftenyoucanassignittoalocalname: >>>fib=fibo.fib >>>fib(500) 01123581321345589144233377 6.1.MoreonModules¶ Amodulecancontainexecutablestatementsaswellasfunctiondefinitions. Thesestatementsareintendedtoinitializethemodule.Theyareexecutedonly thefirsttimethemodulenameisencounteredinanimportstatement.1 (Theyarealsorunifthefileisexecutedasascript.) Eachmodulehasitsownprivatenamespace,whichisusedastheglobalnamespace byallfunctionsdefinedinthemodule.Thus,theauthorofamodulecan useglobalvariablesinthemodulewithoutworryingaboutaccidentalclashes withauser’sglobalvariables.Ontheotherhand,ifyouknowwhatyouare doingyoucantouchamodule’sglobalvariableswiththesamenotationusedto refertoitsfunctions,modname.itemname. Modulescanimportothermodules.Itiscustomarybutnotrequiredtoplaceall importstatementsatthebeginningofamodule(orscript,forthat matter).Theimportedmodulenames,ifplacedatthetoplevelofamodule (outsideanyfunctionsorclasses),areaddedtothemodule’sglobalnamespace. Thereisavariantoftheimportstatementthatimportsnamesfroma moduledirectlyintotheimportingmodule’snamespace.Forexample: >>>fromfiboimportfib,fib2 >>>fib(500) 01123581321345589144233377 Thisdoesnotintroducethemodulenamefromwhichtheimportsaretakeninthe localnamespace(sointheexample,fiboisnotdefined). Thereisevenavarianttoimportallnamesthatamoduledefines: >>>fromfiboimport* >>>fib(500) 01123581321345589144233377 Thisimportsallnamesexceptthosebeginningwithanunderscore(_). InmostcasesPythonprogrammersdonotusethisfacilitysinceitintroduces anunknownsetofnamesintotheinterpreter,possiblyhidingsomethings youhavealreadydefined. Notethatingeneralthepracticeofimporting*fromamoduleorpackageis frownedupon,sinceitoftencausespoorlyreadablecode.However,itisokayto useittosavetypingininteractivesessions. Ifthemodulenameisfollowedbyas,thenthename followingasisbounddirectlytotheimportedmodule. >>>importfiboasfib >>>fib.fib(500) 01123581321345589144233377 Thisiseffectivelyimportingthemoduleinthesamewaythatimportfibo willdo,withtheonlydifferenceofitbeingavailableasfib. Itcanalsobeusedwhenutilisingfromwithsimilareffects: >>>fromfiboimportfibasfibonacci >>>fibonacci(500) 01123581321345589144233377 Note Forefficiencyreasons,eachmoduleisonlyimportedonceperinterpreter session.Therefore,ifyouchangeyourmodules,youmustrestartthe interpreter–or,ifit’sjustonemoduleyouwanttotestinteractively, useimportlib.reload(),e.g.importimportlib; importlib.reload(modulename). 6.1.1.Executingmodulesasscripts¶ WhenyourunaPythonmodulewith pythonfibo.py thecodeinthemodulewillbeexecuted,justasifyouimportedit,butwith the__name__setto"__main__".Thatmeansthatbyaddingthiscodeat theendofyourmodule: if__name__=="__main__": importsys fib(int(sys.argv[1])) youcanmakethefileusableasascriptaswellasanimportablemodule, becausethecodethatparsesthecommandlineonlyrunsifthemoduleis executedasthe“main”file: $pythonfibo.py50 0112358132134 Ifthemoduleisimported,thecodeisnotrun: >>>importfibo >>> Thisisoftenusedeithertoprovideaconvenientuserinterfacetoamodule,or fortestingpurposes(runningthemoduleasascriptexecutesatestsuite). 6.1.2.TheModuleSearchPath¶ Whenamodulenamedspamisimported,theinterpreterfirstsearchesfor abuilt-inmodulewiththatname.Thesemodulenamesarelistedin sys.builtin_module_names.Ifnotfound,itthensearchesforafile namedspam.pyinalistofdirectoriesgivenbythevariable sys.path.sys.pathisinitializedfromtheselocations: Thedirectorycontainingtheinputscript(orthecurrentdirectorywhenno fileisspecified). PYTHONPATH(alistofdirectorynames,withthesamesyntaxasthe shellvariablePATH). Theinstallation-dependentdefault(byconventionincludinga site-packagesdirectory,handledbythesitemodule). Note Onfilesystemswhichsupportsymlinks,thedirectorycontainingtheinput scriptiscalculatedafterthesymlinkisfollowed.Inotherwordsthe directorycontainingthesymlinkisnotaddedtothemodulesearchpath. Afterinitialization,Pythonprogramscanmodifysys.path.The directorycontainingthescriptbeingrunisplacedatthebeginningofthe searchpath,aheadofthestandardlibrarypath.Thismeansthatscriptsinthat directorywillbeloadedinsteadofmodulesofthesamenameinthelibrary directory.Thisisanerrorunlessthereplacementisintended.Seesection StandardModulesformoreinformation. 6.1.3.“Compiled”Pythonfiles¶ Tospeeduploadingmodules,Pythoncachesthecompiledversionofeachmodule inthe__pycache__directoryunderthenamemodule.version.pyc, wheretheversionencodestheformatofthecompiledfile;itgenerallycontains thePythonversionnumber.Forexample,inCPythonrelease3.3thecompiled versionofspam.pywouldbecachedas__pycache__/spam.cpython-33.pyc.This namingconventionallowscompiledmodulesfromdifferentreleasesanddifferent versionsofPythontocoexist. Pythonchecksthemodificationdateofthesourceagainstthecompiledversion toseeifit’soutofdateandneedstoberecompiled.Thisisacompletely automaticprocess.Also,thecompiledmodulesareplatform-independent,sothe samelibrarycanbesharedamongsystemswithdifferentarchitectures. Pythondoesnotcheckthecacheintwocircumstances.First,italways recompilesanddoesnotstoretheresultforthemodulethat’sloadeddirectly fromthecommandline.Second,itdoesnotcheckthecacheifthereisno sourcemodule.Tosupportanon-source(compiledonly)distribution,the compiledmodulemustbeinthesourcedirectory,andtheremustnotbeasource module. Sometipsforexperts: Youcanusethe-Oor-OOswitchesonthePythoncommand toreducethesizeofacompiledmodule.The-Oswitchremovesassert statements,the-OOswitchremovesbothassertstatementsand__doc__ strings.Sincesomeprogramsmayrelyonhavingtheseavailable,youshould onlyusethisoptionifyouknowwhatyou’redoing.“Optimized”moduleshave anopt-tagandareusuallysmaller.Futurereleasesmay changetheeffectsofoptimization. Aprogramdoesn’trunanyfasterwhenitisreadfroma.pyc filethanwhenitisreadfroma.pyfile;theonlythingthat’sfaster about.pycfilesisthespeedwithwhichtheyareloaded. Themodulecompileallcancreate.pycfilesforallmodulesina directory. Thereismoredetailonthisprocess,includingaflowchartofthe decisions,inPEP3147. 6.2.StandardModules¶ Pythoncomeswithalibraryofstandardmodules,describedinaseparate document,thePythonLibraryReference(“LibraryReference”hereafter).Some modulesarebuiltintotheinterpreter;theseprovideaccesstooperationsthat arenotpartofthecoreofthelanguagebutareneverthelessbuiltin,either forefficiencyortoprovideaccesstooperatingsystemprimitivessuchas systemcalls.Thesetofsuchmodulesisaconfigurationoptionwhichalso dependsontheunderlyingplatform.Forexample,thewinregmoduleisonly providedonWindowssystems.Oneparticularmoduledeservessomeattention: sys,whichisbuiltintoeveryPythoninterpreter.Thevariables sys.ps1andsys.ps2definethestringsusedasprimaryandsecondary prompts: >>>importsys >>>sys.ps1 '>>>' >>>sys.ps2 '...' >>>sys.ps1='C>' C>print('Yuck!') Yuck! C> Thesetwovariablesareonlydefinediftheinterpreterisininteractivemode. Thevariablesys.pathisalistofstringsthatdeterminestheinterpreter’s searchpathformodules.Itisinitializedtoadefaultpathtakenfromthe environmentvariablePYTHONPATH,orfromabuilt-indefaultif PYTHONPATHisnotset.Youcanmodifyitusingstandardlist operations: >>>importsys >>>sys.path.append('/ufs/guido/lib/python') 6.3.Thedir()Function¶ Thebuilt-infunctiondir()isusedtofindoutwhichnamesamodule defines.Itreturnsasortedlistofstrings: >>>importfibo,sys >>>dir(fibo) ['__name__','fib','fib2'] >>>dir(sys) ['__breakpointhook__','__displayhook__','__doc__','__excepthook__', '__interactivehook__','__loader__','__name__','__package__','__spec__', '__stderr__','__stdin__','__stdout__','__unraisablehook__', '_clear_type_cache','_current_frames','_debugmallocstats','_framework', '_getframe','_git','_home','_xoptions','abiflags','addaudithook', 'api_version','argv','audit','base_exec_prefix','base_prefix', 'breakpointhook','builtin_module_names','byteorder','call_tracing', 'callstats','copyright','displayhook','dont_write_bytecode','exc_info', 'excepthook','exec_prefix','executable','exit','flags','float_info', 'float_repr_style','get_asyncgen_hooks','get_coroutine_origin_tracking_depth', 'getallocatedblocks','getdefaultencoding','getdlopenflags', 'getfilesystemencodeerrors','getfilesystemencoding','getprofile', 'getrecursionlimit','getrefcount','getsizeof','getswitchinterval', 'gettrace','hash_info','hexversion','implementation','int_info', 'intern','is_finalizing','last_traceback','last_type','last_value', 'maxsize','maxunicode','meta_path','modules','path','path_hooks', 'path_importer_cache','platform','prefix','ps1','ps2','pycache_prefix', 'set_asyncgen_hooks','set_coroutine_origin_tracking_depth','setdlopenflags', 'setprofile','setrecursionlimit','setswitchinterval','settrace','stderr', 'stdin','stdout','thread_info','unraisablehook','version','version_info', 'warnoptions'] Withoutarguments,dir()liststhenamesyouhavedefinedcurrently: >>>a=[1,2,3,4,5] >>>importfibo >>>fib=fibo.fib >>>dir() ['__builtins__','__name__','a','fib','fibo','sys'] Notethatitlistsalltypesofnames:variables,modules,functions,etc. dir()doesnotlistthenamesofbuilt-infunctionsandvariables.Ifyou wantalistofthose,theyaredefinedinthestandardmodule builtins: >>>importbuiltins >>>dir(builtins) ['ArithmeticError','AssertionError','AttributeError','BaseException', 'BlockingIOError','BrokenPipeError','BufferError','BytesWarning', 'ChildProcessError','ConnectionAbortedError','ConnectionError', 'ConnectionRefusedError','ConnectionResetError','DeprecationWarning', 'EOFError','Ellipsis','EnvironmentError','Exception','False', 'FileExistsError','FileNotFoundError','FloatingPointError', 'FutureWarning','GeneratorExit','IOError','ImportError', 'ImportWarning','IndentationError','IndexError','InterruptedError', 'IsADirectoryError','KeyError','KeyboardInterrupt','LookupError', 'MemoryError','NameError','None','NotADirectoryError','NotImplemented', 'NotImplementedError','OSError','OverflowError', 'PendingDeprecationWarning','PermissionError','ProcessLookupError', 'ReferenceError','ResourceWarning','RuntimeError','RuntimeWarning', 'StopIteration','SyntaxError','SyntaxWarning','SystemError', 'SystemExit','TabError','TimeoutError','True','TypeError', 'UnboundLocalError','UnicodeDecodeError','UnicodeEncodeError', 'UnicodeError','UnicodeTranslateError','UnicodeWarning','UserWarning', 'ValueError','Warning','ZeroDivisionError','_','__build_class__', '__debug__','__doc__','__import__','__name__','__package__','abs', 'all','any','ascii','bin','bool','bytearray','bytes','callable', 'chr','classmethod','compile','complex','copyright','credits', 'delattr','dict','dir','divmod','enumerate','eval','exec','exit', 'filter','float','format','frozenset','getattr','globals','hasattr', 'hash','help','hex','id','input','int','isinstance','issubclass', 'iter','len','license','list','locals','map','max','memoryview', 'min','next','object','oct','open','ord','pow','print','property', 'quit','range','repr','reversed','round','set','setattr','slice', 'sorted','staticmethod','str','sum','super','tuple','type','vars', 'zip'] 6.4.Packages¶ PackagesareawayofstructuringPython’smodulenamespacebyusing“dotted modulenames”.Forexample,themodulenameA.Bdesignatesasubmodule namedBinapackagenamedA.Justliketheuseofmodulessavesthe authorsofdifferentmodulesfromhavingtoworryabouteachother’sglobal variablenames,theuseofdottedmodulenamessavestheauthorsofmulti-module packageslikeNumPyorPillowfromhavingtoworryabout eachother’smodulenames. Supposeyouwanttodesignacollectionofmodules(a“package”)fortheuniform handlingofsoundfilesandsounddata.Therearemanydifferentsoundfile formats(usuallyrecognizedbytheirextension,forexample:.wav, .aiff,.au),soyoumayneedtocreateandmaintainagrowing collectionofmodulesfortheconversionbetweenthevariousfileformats. Therearealsomanydifferentoperationsyoumightwanttoperformonsounddata (suchasmixing,addingecho,applyinganequalizerfunction,creatingan artificialstereoeffect),soinadditionyouwillbewritinganever-ending streamofmodulestoperformtheseoperations.Here’sapossiblestructurefor yourpackage(expressedintermsofahierarchicalfilesystem): sound/Top-levelpackage __init__.pyInitializethesoundpackage formats/Subpackageforfileformatconversions __init__.py wavread.py wavwrite.py aiffread.py aiffwrite.py auread.py auwrite.py ... effects/Subpackageforsoundeffects __init__.py echo.py surround.py reverse.py ... filters/Subpackageforfilters __init__.py equalizer.py vocoder.py karaoke.py ... Whenimportingthepackage,Pythonsearchesthroughthedirectorieson sys.pathlookingforthepackagesubdirectory. The__init__.pyfilesarerequiredtomakePythontreatdirectories containingthefileaspackages.Thispreventsdirectorieswithacommonname, suchasstring,unintentionallyhidingvalidmodulesthatoccurlater onthemodulesearchpath.Inthesimplestcase,__init__.pycanjustbe anemptyfile,butitcanalsoexecuteinitializationcodeforthepackageor setthe__all__variable,describedlater. Usersofthepackagecanimportindividualmodulesfromthepackage,for example: importsound.effects.echo Thisloadsthesubmodulesound.effects.echo.Itmustbereferencedwith itsfullname. sound.effects.echo.echofilter(input,output,delay=0.7,atten=4) Analternativewayofimportingthesubmoduleis: fromsound.effectsimportecho Thisalsoloadsthesubmoduleecho,andmakesitavailablewithoutits packageprefix,soitcanbeusedasfollows: echo.echofilter(input,output,delay=0.7,atten=4) Yetanothervariationistoimportthedesiredfunctionorvariabledirectly: fromsound.effects.echoimportechofilter Again,thisloadsthesubmoduleecho,butthismakesitsfunction echofilter()directlyavailable: echofilter(input,output,delay=0.7,atten=4) Notethatwhenusingfrompackageimportitem,theitemcanbeeithera submodule(orsubpackage)ofthepackage,orsomeothernamedefinedinthe package,likeafunction,classorvariable.Theimportstatementfirst testswhethertheitemisdefinedinthepackage;ifnot,itassumesitisa moduleandattemptstoloadit.Ifitfailstofindit,anImportError exceptionisraised. Contrarily,whenusingsyntaxlikeimportitem.subitem.subsubitem,eachitem exceptforthelastmustbeapackage;thelastitemcanbeamoduleora packagebutcan’tbeaclassorfunctionorvariabledefinedintheprevious item. 6.4.1.Importing*FromaPackage¶ Nowwhathappenswhentheuserwritesfromsound.effectsimport*?Ideally, onewouldhopethatthissomehowgoesouttothefilesystem,findswhich submodulesarepresentinthepackage,andimportsthemall.Thiscouldtakea longtimeandimportingsub-modulesmighthaveunwantedside-effectsthatshould onlyhappenwhenthesub-moduleisexplicitlyimported. Theonlysolutionisforthepackageauthortoprovideanexplicitindexofthe package.Theimportstatementusesthefollowingconvention:ifapackage’s __init__.pycodedefinesalistnamed__all__,itistakentobethe listofmodulenamesthatshouldbeimportedwhenfrompackageimport*is encountered.Itisuptothepackageauthortokeepthislistup-to-datewhena newversionofthepackageisreleased.Packageauthorsmayalsodecidenotto supportit,iftheydon’tseeauseforimporting*fromtheirpackage.For example,thefilesound/effects/__init__.pycouldcontainthefollowing code: __all__=["echo","surround","reverse"] Thiswouldmeanthatfromsound.effectsimport*wouldimportthethree namedsubmodulesofthesound.effectspackage. If__all__isnotdefined,thestatementfromsound.effectsimport* doesnotimportallsubmodulesfromthepackagesound.effectsintothe currentnamespace;itonlyensuresthatthepackagesound.effectshas beenimported(possiblyrunninganyinitializationcodein__init__.py) andthenimportswhatevernamesaredefinedinthepackage.Thisincludesany namesdefined(andsubmodulesexplicitlyloaded)by__init__.py.It alsoincludesanysubmodulesofthepackagethatwereexplicitlyloadedby previousimportstatements.Considerthiscode: importsound.effects.echo importsound.effects.surround fromsound.effectsimport* Inthisexample,theechoandsurroundmodulesareimportedinthe currentnamespacebecausetheyaredefinedinthesound.effectspackage whenthefrom...importstatementisexecuted.(Thisalsoworkswhen __all__isdefined.) Althoughcertainmodulesaredesignedtoexportonlynamesthatfollowcertain patternswhenyouuseimport*,itisstillconsideredbadpracticein productioncode. Remember,thereisnothingwrongwithusingfrompackageimport specific_submodule!Infact,thisistherecommendednotationunlessthe importingmoduleneedstousesubmoduleswiththesamenamefromdifferent packages. 6.4.2.Intra-packageReferences¶ Whenpackagesarestructuredintosubpackages(aswiththesoundpackage intheexample),youcanuseabsoluteimportstorefertosubmodulesofsiblings packages.Forexample,ifthemodulesound.filters.vocoderneedstouse theechomoduleinthesound.effectspackage,itcanusefrom sound.effectsimportecho. Youcanalsowriterelativeimports,withthefrommoduleimportnameform ofimportstatement.Theseimportsuseleadingdotstoindicatethecurrentand parentpackagesinvolvedintherelativeimport.Fromthesurround moduleforexample,youmightuse: from.importecho from..importformats from..filtersimportequalizer Notethatrelativeimportsarebasedonthenameofthecurrentmodule.Since thenameofthemainmoduleisalways"__main__",modulesintendedforuse asthemainmoduleofaPythonapplicationmustalwaysuseabsoluteimports. 6.4.3.PackagesinMultipleDirectories¶ Packagessupportonemorespecialattribute,__path__.Thisis initializedtobealistcontainingthenameofthedirectoryholdingthe package’s__init__.pybeforethecodeinthatfileisexecuted.This variablecanbemodified;doingsoaffectsfuturesearchesformodulesand subpackagescontainedinthepackage. Whilethisfeatureisnotoftenneeded,itcanbeusedtoextendthesetof modulesfoundinapackage. Footnotes 1 Infactfunctiondefinitionsarealso‘statements’thatare‘executed’;the executionofamodule-levelfunctiondefinitionaddsthefunctionnameto themodule’sglobalnamespace. TableofContents 6.Modules 6.1.MoreonModules 6.1.1.Executingmodulesasscripts 6.1.2.TheModuleSearchPath 6.1.3.“Compiled”Pythonfiles 6.2.StandardModules 6.3.Thedir()Function 6.4.Packages 6.4.1.Importing*FromaPackage 6.4.2.Intra-packageReferences 6.4.3.PackagesinMultipleDirectories Previoustopic 5.DataStructures Nexttopic 7.InputandOutput ThisPage ReportaBug ShowSource Navigation index modules| next| previous| Python» 3.10.7Documentation» ThePythonTutorial» 6.Modules |