Python manual Module

Translation The Python tutorial#modules

6. Modules

If you exit from the Python interpreter and then re-enter, the previously defined names (functions and variables) are lost. Therefore, if you want to write a longer program, it is better to use a text editor to prepare the interpreter input, using the file as an alternative input. This is also known as creating a script . When the program is getting longer, you may split the program into several files for easy maintenance reasons. You might also want to use a very useful function in multiple programs without having to copy its definition into each program.

To support these requirements, Python provides a way to put definitions into a file and use them in script or interpreter interactive instances. Such a file is called a module , and the definition in the module can be imported into other modules or in the main module (a collection of variables that can be accessed in the scripts and calculation modes executed at the top level).

A module is a file that contains Python definitions and statements. The file name is the module name and has a .py suffix. In the module, the name of the module (as a string), as the value of the global variable __name__ , is available. For example, use your favorite text editor to create a file in the current directory with the fibo.py following content:

# Fibonacci numbers moduledef fib (n):    # write Fibonacci series up to Na, B = 0, 1while b < N:print (b, end= ")        A, B = B, A+bprint () def fib2 (n):   # return Fibonacci series up to Nresult = []    A, b = 0, 1while b < n:        ResU Lt.append (b)        A, B = b, a+breturn result

Enter the Python interpreter and import the module using the following command:

>>> Import Fibo

This operation does not import the name of the fibo function defined in the current symbol table, but only the name of the imported module fibo . The function can be accessed using the module name:

>>> Fibo.fib (+) 1 1 2 3 5 8 144 233 377 610 987>>> FIBO.FIB2 (100) [1, 1, 2, 3, 5, 8, 13, 89]>>> fibo.__name__ ' Fibo '

If you want to use a function frequently, you can assign it to a local name:

>>> fib = fibo.fib>>> fib (500) 1 1 2 3 5 8 13 21 34 55 89 144 233 377

6.1 More on Modules

Modules can contain both executable statements and function definitions. The executable statement is used to initialize the module. When the module name appears in the import statement, these executable statements are executed only once [1]. (If the file is a script, these executables will also execute)

Each module has its own private symbol table, which is used by all functions defined in the module as global symbol tables. Thus, the authors of the module can use these global variables without worrying about accidental name collisions with global variables. On the other hand, if you know what you're doing, you can use the same method as the reference function to refer to the global variables of the module modname.itemname .

Modules can refer to other modules. Placing all the import statements at the beginning of the module (or script) is a good habit, but it is not mandatory. The name of the module being imported will be placed in the global symbol table of the current module.

There is a variant method of importing a statement that imports the module's name directly into the symbol table of the current module. For example:

>>> from Fibo import fib, fib2>>> fib (500) 1 1 2 3 5 8 13 21 34 55 89 144 233 377

The above does not introduce the name of the module (which is not defined in the example above fibo ).

There is even a way to import all the names defined in the module:

>>> from Fibo import *>>> fib (500) 1 1 2 3 5 8 13 21 34 55 89 144 233 377

This method imports all _ names that do not begin with the underscore. In most cases, Python programmers do not use this method, as this will import unknown names into the interpreter, and may also mask some of the names already defined.

It is important to note that the name is usually imported from a module or package in practice, so the names are not encouraged, because they reduce the readability of the program. However, it is possible to use it in an interactive environment to reduce typing input.

Note: For performance reasons, each module in an interpreter session is imported only once. Therefore, if the module is changed, the interpreter must be restarted; If you only want to test a module interactively, use importlib.reload() , for example:import importlib; importlin.reload(modulename)

6.1.1 executing modules as scripts

When you run the Python module using the following command:

Python fibo.py <arguments>

The code in the module is executed as if it were imported, but at this point it is __name__ set to __main__ . This means that the following code is added to the end of the module:

if __name__ = = "__main__": Import sys    fib (int (sys.argv[1]))

The module is executed as a script or as a module, because mian the code that parses the command line executes only when the module executes as a file:

$ python fibo.py 501 1 2 3 5 8 13 21 34

If the module is imported, the code does not execute:

>>> Import fibo>>>

This can be used to provide a user interface for a module using a convention or as a test (the module executes a test case as a script)

6.1.2 The Module Search Path

When spam the module is imported, the interpreter first searches for the built-in module. If not found, the interpreter searches for the sys.path file named in the list of paths provided by the variable spam.py . sys.pathinitialize from the following locations:

• The directory containing the input script (or the current directory if no files are specified)

• PYTHONPATH(The directory name collection, similar to the shell environment variable PATH , is also an environment variable)

• Install default directory

Note: In a file system that supports symbolic links, the directory that contains the input scripts is the directory to which the symbolic links are directed. This means that directories containing symbolic links are not added to the search path.

After initialization, the Python program can be modified sys.path . The directory containing the execution script is placed at the beginning of the search path, before the standard library path. This means that the script in the directory will be loaded, and the module with the same name in the standard library directory will not be loaded. This throws an error unless the module is intended to replace the standard library. Read the standard modules for more information. The custom module should not have the same name as the standard module, otherwise the standard module will be overwritten. )

6.1.3 "Compiled" Python files

To speed up module loading, Python __pycache__ caches the compiled version of each module in the directory, the cache file is named module.version.pyc , the version of the compiled file is encoded, and the version Python version number is usually included. For example, in CPython release 3.3 , the spam.py compiled version of the file is cached as __pycache__/spam.cpython-33.pyc . This naming convention allows modules from different Python releases to coexist.

Python checks the modified date of the source file with the compiled version to determine whether the compiled version expires and whether it needs to be recompiled. This is a fully automated process. In addition, the compilation module is platform independent, so heterogeneous systems can share the same library.

Python does not check for caches in both environments. First, Python is always recompiled, and the results of modules loaded directly from the command line are not stored. Second, if there is no source module, Python does not check the cache. To support the distribution of passive files (only compiled versions), the compiled module must be placed in the source file directory, and the source module needs not exist.

Advice to experts:

• You can use the command line -O or -OO switch to reduce the size of the compilation module. -Oparameter removes assert the statement, and the -OO parameter removes both the assert statement and the __doc__ string. Because some programs rely on these variables, you can only use them if you confirm that you want to do so. The "optimized" module has a opt- label and is usually smaller. The future hairstyle version may change the effect of optimization.

• .pyca program that reads from a file will not .py run faster than a program read from a file, .pyc where the file is fast enough to load.

• compileallThe module can create files for all modules in the directory .pyc .

• More information about this in PEP 3147, including a decision-making process

6.2 Standard Modules

Python provides a library of standard modules, described in separate documents, named Python Library Reference (hereafter called Library Reference ). There are modules embedded in the interpreter, which are not part of the language core, but they are embedded, both for performance and for accessing the native interface of the operating system as a system call. These collection of modules depend on the configuration options of the underlying platform. For example winreg , modules are available only in Windows systems. A special module is worth noting: sys This module is embedded in all Python interpreters. Variables sys.ps1 and sys.ps2 strings that define the main prompt and the secondary prompt:

>>> import sys>>> sys.ps1 ' >>> >>> sys.ps2 ' ... ' >>> sys.ps1 = ' c> ' c> print (' yuck! ') yuck! C>

These two variables are defined only when the interpreter is running in interactive mode.

sys.pathA variable is a list of characters that determines the path of the Interpreter module search. The variable is initialized from the environment variable PYTHONPATH , or the built-in default path ( PYTHONPATH when unspecified). You can list modify its value using the standard operation:

>>> Import sys>>> sys.path.append ('/ufs/guido/lib/python ')

6.3 The Dir () Function

Inline functions dir() are used to search for the name of a module definition. Returns a list of ordered strings:

>>> import Fibo, sys>>> dir (Fibo) [' __name__ ', ' fib ', ' Fib2 ']>>> dir (sys) [' __displayhook__ ' , ' __doc__ ', ' __excepthook__ ', ' __loader__ ', ' __name__ ', ' __package__ ', ' __stderr__ ', ' __stdin__ ', ' __stdout__ ', ' _ Clear_type_cache ', ' _current_frames ', ' _debugmallocstats ', ' _getframe ', ' _home ', ' _mercurial ', ' _xoptions ', ' Abiflags ', ' api_version ', ' argv ', ' base_exec_prefix ', ' base_prefix ', ' 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 ', ' getcheckinterval ', ' getdefaultencoding ', ' Getdlopenflags ', ' getfilesystemencoding ', ' getobjects ', ' getprofile ', ' getrecursionlimit ', ' getrefcount ', ' Getsizeof ', ' getswitchinterval ', ' gettotalrefcount ', ' gettrace ', ' hash_info ', ' hexversion ', ' implementation ', ' Int_ Info ', ' intern ', ' maxsize ', ' maxunicode ', ' meta_path ', ' modules ', ' path ', ' path_hooks ', ' Path_importEr_cache ', ' platform ', ' prefix ', ' ps1 ', ' setcheckinterval ', ' setdlopenflags ', ' setprofile ', ' setrecursionlimit ', ' Setswitchinterval ', ' settrace ', ' stderr ', ' stdin ', ' stdout ', ' thread_info ', ' Version ', ' Version_info ', ' warnoptions '

Using dir() a function without parameters lists all the names of the current scope:

>>> a = [1, 2, 3, 4, 5]>>> import fibo>>> fib = fibo.fib>>> dir () [' __builtins__ ', ' __n Ame__ ', ' a ', ' fib ', ' Fibo ', ' sys ']

Be aware that the function lists all types of names: variables, modules, functions, and so on.

dir()The names of inline functions and variables are not listed. If you wish to list, these names are defined in the standard module builtins :

>>> Import builtins>>> 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 ', ' fo Rmat ', ' frozenset ', ' getattr ', ' globals ', ' hasattr ', ' hash ', ' help ', ' hex ', ' id ', ' input ', ' int ', ' isinstance ', ' Issubclas '  S ', ' 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 ', ' Staticmet ' Hod ', ' str ', ' Sum ', ' super ', ' tuple ', ' type ', ' vars ', ' Zip '] 

6.4 Packages

A package is a way to structure the Python module namespace using the DOT module name. For example, the module name A.B represents A a sub-module in a package B . Just as the module allows authors of different modules to avoid worrying about the global name of each module, the use of the DOT module name makes it possible for authors of multi-module packages (such as NumPy or Python image libraries) to avoid worrying about the names of each module.

Suppose you need to design a collection of modules (packages) for the processing of unified audio files and audio data. There are many different audio file formats (usually identified by extension, such as .wav, .aiff, .au ), so you need to create and maintain a continuously growing collection of modules for the transformations of different file formats. There are also many different operations on the audio data (such as mixing, adding echoes, adding equalizer functions, creating a faux stereoscopic effect), so you need to write an extra number of modules that perform these operations. The following is the possible structure of the package (represented in a hierarchical file structure):

sound/                          top-level package      __init__.py Initialize The sound package      formats/                  subpackage for file Format Conversions              __init__.py              wavread.py              wavwrite.py              aiffread.py              aiffwrite.py              auread.py              auwrite.py ...      effects/                  subpackage for sound effects              __init__.py              echo.py              surround.py              reverse.py              ...      filters/                  subpackage for filters              __init__.py              equalizer.py vocoder.py karaoke.py              ...

When the package is imported, the Python search sys.path provides a path to find the Bun directory.

In order for Python to consider a generic directory as a package, the directory must contain __init__.py files. This is done in order to avoid the unconscious concealment of common directory names (such as string ) that would later appear in the module's search path in a valid module. In the simplest case, __init__.py it can be an empty file, but it can also contain executable initialization package code or set __all__ variables, which are described later.

The user of the package can import a separate module from the package:

Import Sound.effects.echo

This is added to the Submodule sound.effects.echo . You must use the full name reference:

Sound.effects.echo.echofilter (input, output, delay=0.7, atten=4)

Optional ways to import Submodules:

From sound.effects import Echo

The above also loads echo the submodule, does not use the package prefix to refer to the module, so it can be used as follows:

Echo.echofilter (input, output, delay=0.7, atten=4)

The other way is to directly import the required functions or variables:

From Sound.effects.echo import Echofilter

Again, this will add echo to the submodule, but make the function echofilter() available directly:

Echofilter (input, output, delay=0.7, atten=4)

Note When used from package import item , item you can make a submodule (a child package), or it can be another name defined within a package, such as a function, class, or variable. The import statement first tests whether the item to be imported exists in the package, and if it does not, Python assumes that the item is a module and tries to load it. If the last search fails, the ImportError exception is thrown.

In contrast, when used, each item must be a package except for the last item, and the import item.subitem.subsubitem last item can be either a module or a package but not a class, function, or variable defined in the preceding item.

6.4.1 Importing * from a package

from sound.effects import *What happens when you use it? Ideally, you always expect to find all the submodules in the file system and import them all. All imports take a long time, and importing submodules can have undesirable side effects that should occur during explicit import.

The only solution is for the package author to provide an explicit index of a package. importstatement follows the convention: If a __init__.py variable named is defined in the package's code __all__ , from package import * all modules specified by that variable are imported when used. When a new version of a package is released, the package author is responsible for updating the list __all__ . If the package author does not want to be able to use from package import * the module in the import package, it may not be supported __all__ . For example, the file sound/effects/__init__.py might contain the following code:

__all__ = ["echo", "surround", "reverse"]

This means that from sound.effects import * sound the three modules specified in the package are imported.

If __all__ not defined, the statement from sound.effects import * does not sound.effects pour all of the submodule in the package into the current namespace, only guarantees that the package sound.effects is imported (potentially running __init__.py initialization code) and imports any names defined in the package. Include __init__.py any name defined in the (and explicitly loaded submodule). It will also include import any stuffed bun modules that were explicitly loaded by the preceding statement. Consider the following code:

Import sound.effects.echoimport sound.effects.surroundfrom sound.effects Import *

In this example, echo and the surround modules are imported into the current namespace because they are defined from... import in the package when they are executed sound.effects . ( __all__ same as valid when defined)

Although import * only names that conform to a particular pattern are exported, they are not recommended for use in production code.

Remember, use form Package import specific_submodle no errors. In fact, this is the recommended method unless the current module needs to use a module of the same name in another package.

6.4.2 Intra-package References

When a package contains a child package structure (as in the case of a sound package), you can refer to the submodule in the sibling package using an absolute import. For example, if sound.filters.vocoder a module needs to use sound.effects a module in a package echo , you can use the from sound.effects import echo .

You can also use from modul import name statements to import modules relative to each other. This method uses points . to indicate the parent package that is involved in the current package and relative imports. Take the surround module as an example:

From. Import Echofrom. Import Formatsfrom. Filters Import Equalizer

Relative imports are based on the name of the current module. Because the name of the main module is always __main__ , the module to use as the Python Application Master module must always use the absolute import method.

6.4.3 Packages in multiple directories

The package also supports a special property __path__ . __init__.pybefore the code executes, the property __path__ is initialized to a list that contains the path to the directory where the __init__.py file is held. This variable can be modified to affect future searches of modules and sub-packages within the package.

However, this feature is not always required, it can be used to extend the module collection of the package

Footnotes

[1] In practice, function definitions are also "statements" that can be "executed"; function execution at the module level places the name of the function in the global symbol table of the module