Introduction
Mar 08, 2017 This video explains how to install Python 3 in a Mac OS X, both Mavericks and Yosemite. As the Python website says, 'Python 2.x is legacy, Python 3.x is the present and future of the language. Pythonのimport文で標準ライブラリやpipでインストールしたパッケージ、自作のパッケージなどをインポートするときに探索されるパス(ディレクトリ)をモジュール検索パス(Module Search Path)と呼ぶ。6. モジュール (module) モジュール検索パス — Python 3.6.5 ドキュメント 自作のパッケージや.
The import
statement is usually the first thing you see at the top of anyPython file. We use it all the time, yet it is still a bit mysterious tomany people. This tutorial will walk through how import works and howto view and modify the directories used for importing.
If you want to learn how to import a module by using a string variablename to reference the module, check out my tutorial on Import Python Module by String Name
Also check out my Python Virtual Environments Tutorial to learn moreabout isolated Python environments.
Modules versus packages
First, let's clarify the difference between modules and packages.They are very closely related, and often confused.They both serve the same purpose which is to organize code,but they each provide slightly different ways of doing that.
- A module is a single
.py
file with Python code. - A package is a directory that can contains multiple Python modules.
A module can be thought of as a self-contained package, and a packageis like a module that is separated out across multiple files.It really depends on how you want to organize your code and how largeyour project is. I always start with a module and turn it in to a packageif needed later.
How import works
The import
keyword in Python is used to load other Python source code filesin to the current interpreter session. This is how you re-use code and share itamong multiple files or different projects.
There are a few different ways to use import
. For example, if we wantedto use the function join()
that lives in the path
module of the os
package.Its full name would be os.path.join()
. We have a few ways of importingand using the function. Read more about the os
package athttps://docs.python.org/3/library/os.path.html.
Import versus from
There are a few different ways you can import a package or a module.You can directly call import
or use from x import y
format.The from
keyword tells Python what package or module to look infor the name specified with import
. Here are a few example that allaccomplish the same end goal.
Different ways to import and execute os.path.join()
:
As you can see, you can import the whole package, a specific module withina package, a specific function from within a module. The *
wildcard meansload all modules and functions. I do not recommend using the wildcard becauseit is too ambiguous. It is better to explicitly list each import so you canidentify where it came from. A good IDE like PyCharm will help you managethese easily.
When you call import
in the Python interpreter searches through a set ofdirectories for the name provided.The list of directories that it searches is stored in sys.path
and can bemodified during run-time. To modify the paths before starting Python,you can modify the PYTHONPATH
environment variable. Both sys.path
andPYTHONPATH
are covered more below.
Import by string
If you want to import a module programmatically, you can use importlib.import_module()
.This function is useful if you are creating a plugin system where modulesneed to be loaded at run-time based on string names.
This method is not commonly used, and is only useful in special circumstances.For example, if you are building a plugin system where you want to load every filein a directory as a module based on the filepath string.
How __init__ and __main__ work
Names that start and end with double underscores, often called 'dunders',are special names in Python.Two of them are special names related to modules and packages: __init__
and __main__
.Depending on whether you are organizing your code as a package or a module,they are treated slightly differently.
We will look at the difference between a module and a package in a moment,but the main idea is this:
- When you import a package it runs the
__init__.py
file inside the package directory. - When you execute a package (e.g.
python -m my_package
) it executes the__main__.py
file. - When you import a module it runs the entire file from top to bottom.
- When you execute a module ir runs the entire file from top-to-bottom and sets the
__name__
variable to the string'__main__'
.
In a package
In a Python package (a directory), you can have a module named __init__.py
andanother named __main__.py
.
Here is an example structure of a package:
If a package is invoked directly (e.g. python -m my_package
), the __main__.py
module is executed.The __init__.py
file is executed when a package is imported (e.g. import my_package
).
In a module
In the previous section, we saw how a package can have separate files for __init__.py
and __main__.py
.In a module (a single .py file) the equivalent of __init__
and __main__
arecontained in the single file. The entire itself essentially becomes both the __init__.py
and the __main__.py
.
When a module is imported, it runs the whole file, loading any functions defined.
When a module is invoked directly, for example, python my_module.py
orpython -m my_module
, then it does the same thing as importing it, but alsosets the __name__
variable to the string '__main__'
.
You can take advantage of this and execute a section of code only ifthe module is invoked directly, and not when it is imported. To do this,you need to explicitly check the __name__
variable, and see if it equals __main__
.If it is set to the string __main__
, then you know the module was invokeddirectly, and not simply imported.
Take this example. Create a file named my_module.py
with the following contents:
Try out a few different things to understand how it works:
- Run the file directly with Python:
python my_module.py
- Invoke the module with
-m
flag:python -m my_module
- Import the module from another Python file:
python -c 'import my_module'
- Import and call the function defined:
python -c 'import my_module; my_module.my_function()'
Manage import paths
sys.path
When you start a Python interpreter, one of the things it creates automaticallyis a list that contains all of directories it will use to search for modules when importing.This list is available in a variable named sys.path
.Here is an example of printing out sys.path
.Note that the empty '
entry means the current directory.
You are allowed to modify sys.path
during run-time.Just be sure to modify it before you call import
.It will search the directories in order stopping at the first place itfinds the specified modules.
PYTHONPATH
PYTHONPATH
is related to sys.path
very closely. PYTHONPATH
is anenvironment variable that you set before running the Python interpreter.PYTHONPATH
, if it exists, should contain directories that should be searchedfor modules when using import
. If PYTHONPATH
is set, Python will include the directories in sys.path
for searching.Use a semicolon to separate multiple directories.
Here is an example of setting the environment variable in Windows and listingthe paths in Python:
And in Linux and Mac you can do the equivalent like this:
So, in order to import modules or packages, they need to reside in one of the paths listed in sys.path
.You can modify the sys.path
list manually if needed from within Python.It is just a regular list
so it can be modified in all the normal ways.For example, you can append to the end of the list using sys.path.append()
or to insert in an arbitrary position using sys.path.insert()
.For more help, refer to https://docs.python.org/3/tutorial/datastructures.html
The site module
You can also use the site
module to modify sys.path
.See more at https://docs.python.org/3/library/site.html.
Example output:
You can also direclty invoke the site module to get a list of default paths:
Example run:
PYTHONHOME
The PYTHONHOME
environment variable is similar to PYTHONPATH
except itshould define where the standard libraries are. If PYTHONHOME
is set,it will assume some default paths relative to the home, which can be supplemented with PYTHONPATH
.
This is particularly relevant if you embedded Python in to a C applicationand it is trying to determine the path of Python using the PYTHONHOME
environment variable.
Just for reference, here is a quick example of how you wouldbuild a C application with Python embedded in it.
Conclusion
After reading this, you should have a better understanding of how Python'simport
statement works and how the PYTHONPATH
environment variableand sys.path
affect import
. You should also understand the differencesand similarities between modules and packages, the dunders __init__
and__main__
and how to use them effectively.
References
Introduction
The import
statement is usually the first thing you see at the top of anyPython file. We use it all the time, yet it is still a bit mysterious tomany people. This tutorial will walk through how import works and howto view and modify the directories used for importing.
If you want to learn how to import a module by using a string variablename to reference the module, check out my tutorial on Import Python Module by String Name
Also check out my Python Virtual Environments Tutorial to learn moreabout isolated Python environments.
Modules versus packages
First, let's clarify the difference between modules and packages.They are very closely related, and often confused.They both serve the same purpose which is to organize code,but they each provide slightly different ways of doing that.
- A module is a single
.py
file with Python code. - A package is a directory that can contains multiple Python modules.
A module can be thought of as a self-contained package, and a packageis like a module that is separated out across multiple files.It really depends on how you want to organize your code and how largeyour project is. I always start with a module and turn it in to a packageif needed later.
How import works
The import
keyword in Python is used to load other Python source code filesin to the current interpreter session. This is how you re-use code and share itamong multiple files or different projects.
There are a few different ways to use import
. For example, if we wantedto use the function join()
that lives in the path
module of the os
package.Its full name would be os.path.join()
. We have a few ways of importingand using the function. Read more about the os
package athttps://docs.python.org/3/library/os.path.html.
Import versus from
There are a few different ways you can import a package or a module.You can directly call import
or use from x import y
format.The from
keyword tells Python what package or module to look infor the name specified with import
. Here are a few example that allaccomplish the same end goal.
Different ways to import and execute os.path.join()
:
As you can see, you can import the whole package, a specific module withina package, a specific function from within a module. The *
wildcard meansload all modules and functions. I do not recommend using the wildcard becauseit is too ambiguous. It is better to explicitly list each import so you canidentify where it came from. A good IDE like PyCharm will help you managethese easily.
When you call import
in the Python interpreter searches through a set ofdirectories for the name provided.The list of directories that it searches is stored in sys.path
and can bemodified during run-time. To modify the paths before starting Python,you can modify the PYTHONPATH
environment variable. Both sys.path
andPYTHONPATH
are covered more below.
Import by string
If you want to import a module programmatically, you can use importlib.import_module()
.This function is useful if you are creating a plugin system where modulesneed to be loaded at run-time based on string names.
This method is not commonly used, and is only useful in special circumstances.For example, if you are building a plugin system where you want to load every filein a directory as a module based on the filepath string.
How __init__ and __main__ work
Names that start and end with double underscores, often called 'dunders',are special names in Python.Two of them are special names related to modules and packages: __init__
and __main__
.Depending on whether you are organizing your code as a package or a module,they are treated slightly differently.
We will look at the difference between a module and a package in a moment,but the main idea is this:
- When you import a package it runs the
__init__.py
file inside the package directory. - When you execute a package (e.g.
python -m my_package
) it executes the__main__.py
file. - When you import a module it runs the entire file from top to bottom.
- When you execute a module ir runs the entire file from top-to-bottom and sets the
__name__
variable to the string'__main__'
.
In a package
In a Python package (a directory), you can have a module named __init__.py
andanother named __main__.py
.
Here is an example structure of a package:
If a package is invoked directly (e.g. python -m my_package
), the __main__.py
module is executed.The __init__.py
file is executed when a package is imported (e.g. import my_package
).
In a module
In the previous section, we saw how a package can have separate files for __init__.py
and __main__.py
.In a module (a single .py file) the equivalent of __init__
and __main__
arecontained in the single file. The entire itself essentially becomes both the __init__.py
and the __main__.py
.
When a module is imported, it runs the whole file, loading any functions defined.
When a module is invoked directly, for example, python my_module.py
orpython -m my_module
, then it does the same thing as importing it, but alsosets the __name__
variable to the string '__main__'
.
You can take advantage of this and execute a section of code only ifthe module is invoked directly, and not when it is imported. To do this,you need to explicitly check the __name__
variable, and see if it equals __main__
.If it is set to the string __main__
, then you know the module was invokeddirectly, and not simply imported.
Take this example. Create a file named my_module.py
with the following contents:
Try out a few different things to understand how it works:
- Run the file directly with Python:
python my_module.py
- Invoke the module with
-m
flag:python -m my_module
- Import the module from another Python file:
python -c 'import my_module'
- Import and call the function defined:
python -c 'import my_module; my_module.my_function()'
Manage import paths
sys.path
When you start a Python interpreter, one of the things it creates automaticallyis a list that contains all of directories it will use to search for modules when importing.This list is available in a variable named sys.path
.Here is an example of printing out sys.path
.Note that the empty '
entry means the current directory.
You are allowed to modify sys.path
during run-time.Just be sure to modify it before you call import
.It will search the directories in order stopping at the first place itfinds the specified modules.
PYTHONPATH
PYTHONPATH
is related to sys.path
very closely. PYTHONPATH
is anenvironment variable that you set before running the Python interpreter.PYTHONPATH
, if it exists, should contain directories that should be searchedfor modules when using import
. If PYTHONPATH
is set, Python will include the directories in sys.path
for searching.Use a semicolon to separate multiple directories.
Here is an example of setting the environment variable in Windows and listingthe paths in Python:
And in Linux and Mac you can do the equivalent like this:
So, in order to import modules or packages, they need to reside in one of the paths listed in sys.path
.You can modify the sys.path
list manually if needed from within Python.It is just a regular list
so it can be modified in all the normal ways.For example, you can append to the end of the list using sys.path.append()
or to insert in an arbitrary position using sys.path.insert()
.For more help, refer to https://docs.python.org/3/tutorial/datastructures.html
The site module
Osx Add To Path
You can also use the site
module to modify sys.path
.See more at https://docs.python.org/3/library/site.html.
Example output:
You can also direclty invoke the site module to get a list of default paths:
Example run:
PYTHONHOME
The PYTHONHOME
environment variable is similar to PYTHONPATH
except itshould define where the standard libraries are. If PYTHONHOME
is set,it will assume some default paths relative to the home, which can be supplemented with PYTHONPATH
.
Python Add Library Path Mac Os Download
This is particularly relevant if you embedded Python in to a C applicationand it is trying to determine the path of Python using the PYTHONHOME
environment variable.
Python Add Library Path Mac Os Download
Just for reference, here is a quick example of how you wouldbuild a C application with Python embedded in it.
Conclusion
After reading this, you should have a better understanding of how Python'simport
statement works and how the PYTHONPATH
environment variableand sys.path
affect import
. You should also understand the differencesand similarities between modules and packages, the dunders __init__
and__main__
and how to use them effectively.